diff --git a/docs/source/everest_charging_stack.rst b/docs/source/everest_charging_stack.rst index a39c78c..5536769 100644 --- a/docs/source/everest_charging_stack.rst +++ b/docs/source/everest_charging_stack.rst @@ -22,7 +22,7 @@ An overview of the EVerest modules is shown in the next section. .. include:: ../../includes/everest_overview_of_everest_modules.inc -**DCSupplySimulator** (`view on GitHub `__) +**DCSupplySimulator** (`view on GitHub `__) This module simulates a DC power supply device. diff --git a/docs/source/safety_controller.rst b/docs/source/safety_controller.rst index 469ac62..c38578b 100644 --- a/docs/source/safety_controller.rst +++ b/docs/source/safety_controller.rst @@ -88,6 +88,8 @@ This state can only be left by a reset. .. figure:: _static/images/safety_controller_states.svg :width: 1000pt +.. include:: safety_controller_parameterization.rst + .. include:: safety_controller_uart.rst .. include:: everest_bsp.rst diff --git a/docs/source/safety_controller_parameterization.rst b/docs/source/safety_controller_parameterization.rst new file mode 100644 index 0000000..51056a7 --- /dev/null +++ b/docs/source/safety_controller_parameterization.rst @@ -0,0 +1,162 @@ +.. _safety_controller_parameterization.rst: + +Safety Controller Parameterization +---------------------------------- + + +Overview +^^^^^^^^ + +The safety controller can or must be parameterized to a certain extent. For example, it is required to know +which temperature channels are actually in use and at which temperature thresholds the charging process needs to +be stopped to avoid injuries to users and/or prevent damage to the EVSE itself. +It also supports an emergency input channel which can be disabled when not connected/required in +the actual customer setup. + +These safety controller parameters are stored as a binary parameter block, directly in the safety controller's flash. +When shipped from factory, there is a default parameter block installed which allows easy evaluation of the product, +but is not intended for production usage in the field. +Customers are encouraged to adjust the parameters to their requirements/needs during deployment of the board into +an actual charger. + +To adjust the parameters, some small command line tools are included in the shipped Linux firmware which allow +to create/modify the parameters on the board itself. However, it is also possible to use these tools on a Linux +host system (e.g. in a virtual machine) and then to transfer the created parameter block to each board +and install it. + +The mentioned tools are part of the `ra-utils repository `__ on Github. + +To make the handling of parameters human-friendly, all parameters can be put together using a YAML text file. + +.. code-block:: yaml + + version: 1 + pt1000s: + - abort-temperature: 75.0 °C + resistance-offset: 0.85 Ω + - abort-temperature: 85.0 °C + resistance-offset: 1.042 Ω + - 80.0 °C + - disabled + + contactors: + - with-feedback-normally-open + - disabled + - disabled + + estops: + - active-low + - disabled + - disabled + +.. important:: + + The YAML file is required to be encoded in UTF-8. While most parameters are ASCII only, temperature thresholds require + trailing `°C` suffix which has a special UTF-8 encoding sequence. This might be displayed incorrectly in the editor + when editing on the device itself and/or finally stored wrong in the YAML file. + The same applies to the resistance offsets in Ohm. + When unsure, adapt/create the YAML file on your Linux host system with your preferred editor and transfer it + to the board via Ethernet network (e.g. SCP/SFTP). + +Such a YAML file must be converted to a binary parameter block file afterwards. And this binary parameter block file +must finally be flashed to the safety controller's flash memory, see below. + +.. important:: + + The YAML file allows to specify a numeric parameter block version. This version is used internally by the + safety controller firmware to detect the binary structure of the parameter block. It must thus match the + safety firmware's expectation, otherwise the safety controller will refuse to work and enters safe state directly. + + +Temperature Channel (PT1000) Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The safety controller supports up to 4 PT1000 temperature channels. Thus the YAML file expects for each channel +a temperature threshold in °C at which the safety controller stops and/or prevents charging. Also for each channel, +an offset value in Ohm can be specified. This offset depends on the actual physical wiring and must be determined +in the specific customer setup. +If a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled` +instead of a temperature value. +The example YAML file above shows that the PT1000 configuration is an array with up to 4 items. Each item can either +be a single temperature threshold, the special token `disabled` or it is a key-value list. Valid keys are +`abort-temperature` and `resistance-offset`. If no `resistance-offset` is given, then it is assumed to be zero. + +The accepted value range for `abort-temperature` is -80.0 °C to 200.0 °C and it is stored with one decimal digit. + +The range for `resistance-offset` is -32.0 Ω ... 32.0 Ω and these values are stored with three decimal digits internally. + + +Contactor and Contactor Feedback Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On Charge Control Y, the high-voltage contactors are not controlled directly by the safety controller firmware. +Please do not modify the shipped factory settings as there are board revision specific differences. + + +Emergency Input Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The safety controller can monitor up to 3 emergency inputs, however on Charge Control Y only one physical +emergency input is available. So the second and third inputs must kept disabled. + +Possible configuration values for the first one are: + +- `disabled` +- `active-low` + + +Installing a Parameter Block +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once the YAML file is created and fits your charger setup, it is required to convert it to a binary parameter block file. +In the mentioned repository, there exists a tool `ra-pb-create` to generate such a binary file from the YAML file. +The following session transcript shows how the install procedure works: + +.. code-block:: sh + + # create a YAML file on-the-fly + $ cat < /tmp/my-parameters.yaml + version: 1 + pt1000s: + - abort-temperature: 75.0 °C + resistance-offset: 0.85 Ω + - abort-temperature: 85.0 °C + resistance-offset: 1.042 Ω + - 80.0 °C + - disabled + + contactors: + - with-feedback-normally-open + - disabled + - disabled + + estops: + - active-low + - disabled + - disabled + EOL + + # convert YAML to binary + ra-pb-create -i /tmp/my-parameters.yaml -o /tmp/my-parameters.bin + + # stop EVerest - to have exclusive access to safety controller + systemctl stop everest + + # flash the parameter block + ra-update -a data flash /tmp/my-parameters.bin + + # restart EVerest + systemctl start everest + + +Checking the Installed Parameter Block +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To check which settings are currently used by the safety controller firmware, it is possible to read back the parameter block. + +.. code-block:: sh + + systemctrl stop everest + ra-update -a data dump | ra-pb-dump + +This will print the current settings in YAML format on stdout. diff --git a/docs/source/safety_protocol.rst b/docs/source/safety_protocol.rst index 269392a..25bbbc4 100644 --- a/docs/source/safety_protocol.rst +++ b/docs/source/safety_protocol.rst @@ -53,25 +53,31 @@ ChargeControl2 :: - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| CC_CCSReady | | | | CC_ControllerReset | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 1| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 3| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 7| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ + Bit + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + 0 |<-------------x|<-----x| | | + +---+---+---+---+---+---+---+---+ + | +-- CC_ControllerReset + +-- CC_CCSReady + +---+---+---+---+---+---+---+---+ + 1 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + B 2 | | | | | | | | | + y +---+---+---+---+---+---+---+---+ + t 3 | | | | | | | | | + e +---+---+---+---+---+---+---+---+ + 4 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 5 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 6 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 7 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + + ChargeState2 ^^^^^^^^^^^^ @@ -182,25 +188,35 @@ ChargeState2 :: - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| CS_CE_State | | | | CS_ID_State | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 1| CS_EStop_Reason | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| CS_SafeStateActive | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 3| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 7| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ + Bit + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + 0 |<-------------x|<-------------x| + +---+---+---+---+---+---+---+---+ + | +-- CS_ID_State + +-- CS_CE_State + +---+---+---+---+---+---+---+---+ + 1 |<-----------------------------x| + +---+---+---+---+---+---+---+---+ + +-- CS_EStop_Reason + +---+---+---+---+---+---+---+---+ + B 2 |<-----x| | | | | | | + y +---+---+---+---+---+---+---+---+ + t +-- CS_SafeStateActive + e +---+---+---+---+---+---+---+---+ + 3 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 4 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 5 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 6 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 7 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + + PT1000State ^^^^^^^^^^^ @@ -357,25 +373,43 @@ PT1000State :: - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| PT1_Temperature | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 1| PT2_Temperature | | | | | | PT1_SelftestFailed |PT1_ChargingStopped | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| PT2_Temperature | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 3| PT3_Temperature | | | | | | PT2_SelftestFailed |PT2_ChargingStopped | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| PT3_Temperature | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| PT4_Temperature | | | | | | PT3_SelftestFailed |PT3_ChargingStopped | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| PT4_Temperature | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 7| | | | | | | PT4_SelftestFailed |PT4_ChargingStopped | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ + Bit + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + 0 |<------------------------------| + +---+---+---+---+---+---+---+---+ + 1 |----------------------x|<-x|<-x| + +---+---+---+---+---+---+---+---+ + | | +-- PT1_ChargingStopped + | +-- PT1_SelftestFailed + +-- PT1_Temperature + +---+---+---+---+---+---+---+---+ + 2 |<------------------------------| + +---+---+---+---+---+---+---+---+ + 3 |----------------------x|<-x|<-x| + +---+---+---+---+---+---+---+---+ + | | +-- PT2_ChargingStopped + B | +-- PT2_SelftestFailed + y +-- PT2_Temperature + t +---+---+---+---+---+---+---+---+ + e 4 |<------------------------------| + +---+---+---+---+---+---+---+---+ + 5 |----------------------x|<-x|<-x| + +---+---+---+---+---+---+---+---+ + | | +-- PT3_ChargingStopped + | +-- PT3_SelftestFailed + +-- PT3_Temperature + +---+---+---+---+---+---+---+---+ + 6 |<------------------------------| + +---+---+---+---+---+---+---+---+ + 7 |----------------------x|<-x|<-x| + +---+---+---+---+---+---+---+---+ + | | +-- PT4_ChargingStopped + | +-- PT4_SelftestFailed + +-- PT4_Temperature + + FirmwareVersion ^^^^^^^^^^^^^^^ @@ -446,6 +480,15 @@ FirmwareVersion - 0 - - The type of firmware. See possible values below + * - ParameterVersion + - 47 + - 16 + - Big Endian + - No + - 1 + - 0 + - + - Version of the parameter file **Value Descriptions** @@ -464,25 +507,40 @@ FirmwareVersion :: - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| MajorVersion | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 1| MinorVersion | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| BuildVersion | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 3| PlatformType | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| ApplicationType | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 7| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ + Bit + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + 0 |<-----------------------------x| + +---+---+---+---+---+---+---+---+ + +-- MajorVersion + +---+---+---+---+---+---+---+---+ + 1 |<-----------------------------x| + +---+---+---+---+---+---+---+---+ + +-- MinorVersion + +---+---+---+---+---+---+---+---+ + 2 |<-----------------------------x| + +---+---+---+---+---+---+---+---+ + +-- BuildVersion + B +---+---+---+---+---+---+---+---+ + y 3 |<-----------------------------x| + t +---+---+---+---+---+---+---+---+ + e +-- PlatformType + +---+---+---+---+---+---+---+---+ + 4 |<-----------------------------x| + +---+---+---+---+---+---+---+---+ + +-- ApplicationType + +---+---+---+---+---+---+---+---+ + 5 |<------------------------------| + +---+---+---+---+---+---+---+---+ + 6 |------------------------------x| + +---+---+---+---+---+---+---+---+ + +-- ParameterVersion + +---+---+---+---+---+---+---+---+ + 7 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + + GitHash ^^^^^^^ @@ -522,25 +580,29 @@ GitHash :: - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| HashSignal | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 1| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 3| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 7| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ + Bit + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + 0 |<------------------------------| + +---+---+---+---+---+---+---+---+ + 1 |-------------------------------| + +---+---+---+---+---+---+---+---+ + 2 |-------------------------------| + +---+---+---+---+---+---+---+---+ + B 3 |-------------------------------| + y +---+---+---+---+---+---+---+---+ + t 4 |-------------------------------| + e +---+---+---+---+---+---+---+---+ + 5 |-------------------------------| + +---+---+---+---+---+---+---+---+ + 6 |-------------------------------| + +---+---+---+---+---+---+---+---+ + 7 |------------------------------x| + +---+---+---+---+---+---+---+---+ + +-- HashSignal + + InquiryPacket ^^^^^^^^^^^^^ @@ -587,23 +649,28 @@ InquiryPacket :: - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| PacketId | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 1| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 3| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 7| | | | | | | | | - +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ + Bit + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + 0 |<-----------------------------x| + +---+---+---+---+---+---+---+---+ + +-- PacketId + +---+---+---+---+---+---+---+---+ + 1 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + B 2 | | | | | | | | | + y +---+---+---+---+---+---+---+---+ + t 3 | | | | | | | | | + e +---+---+---+---+---+---+---+---+ + 4 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 5 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 6 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + 7 | | | | | | | | | + +---+---+---+---+---+---+---+---+ + + diff --git a/docs/source/utils/.gitignore b/docs/source/utils/.gitignore new file mode 100644 index 0000000..bee8a64 --- /dev/null +++ b/docs/source/utils/.gitignore @@ -0,0 +1 @@ +__pycache__ diff --git a/docs/source/utils/dbc_to_rst.py b/docs/source/utils/dbc_to_rst.py index ccf8178..0d0829a 100644 --- a/docs/source/utils/dbc_to_rst.py +++ b/docs/source/utils/dbc_to_rst.py @@ -1,20 +1,10 @@ import cantools +from cantools.subparsers.dump import formatting +from dbc_to_rst_config import * # Load the DBC file db = cantools.database.load_file("uart_com.dbc") -# Messages you want to document -target_msgs = ["ChargeControl2", "ChargeState2", "PT1000State", "FirmwareVersion", "GitHash", "InquiryPacket"] - -# Sender name mapping -sender_name_map = { - "CCY_SafetyController": "Safety Controller", - "CCY_Linux": "Linux Processor" -} - -# Senders to exclude from display -excluded_senders = {"Default_SafetyController"} - # Extract a signal row as a list of strings def signal_row(signal): def safe(value): @@ -42,50 +32,14 @@ def safe(value): ] def format_bit_matrix(msg): - bit_width = 20 - byte_label_width = 3 - bitfield = [None] * (msg.length * 8) - - for signal in msg.signals: - if signal.byte_order == "little_endian": - bit_indices = list(range(signal.start, signal.start + signal.length)) - else: - bit_indices = list(range(signal.start, signal.start - signal.length, -1)) - - for idx in bit_indices: - if 0 <= idx < len(bitfield): - bitfield[idx] = signal.name - - total_bits = msg.length * 8 - num_rows = total_bits // 8 - lines = [] - - # Header with byte index - border = " +" + "+".join(["-" * bit_width] * 8) + "+" - header = " |" + "|".join([f"{7 - i:^{bit_width}}" for i in range(8)]) + "|" - lines.extend([border, header, border]) - - for row in range(num_rows): - base = row * 8 - seen = set() - row_cells = [] - for i in range(8): - bit_index = base + (7 - i) - label = bitfield[bit_index] - if label and label not in seen: - cell = label[:bit_width].center(bit_width) - seen.add(label) - else: - cell = " " * bit_width - row_cells.append(cell) - lines.append(f"{row:>3}|" + "|".join(row_cells) + "|") - lines.append(border) - rst = "\n**Bitfield Layout**\n\n::\n\n" - rst += "\n".join(lines) + "\n" + rst += '\n'.join([ + (' ' + line).rstrip() + for line in formatting.layout_string(msg).splitlines() + ]) + rst += "\n\n\n" return rst - # Format one message block as RST def format_message_rst(msg): rst = f"{msg.name}\n{'^' * len(msg.name)}\n\n" diff --git a/docs/source/utils/dbc_to_rst_config.py b/docs/source/utils/dbc_to_rst_config.py new file mode 100644 index 0000000..1470747 --- /dev/null +++ b/docs/source/utils/dbc_to_rst_config.py @@ -0,0 +1,11 @@ +# Messages you want to document +target_msgs = ["ChargeControl2", "ChargeState2", "PT1000State", "FirmwareVersion", "GitHash", "InquiryPacket"] + +# Sender name mapping +sender_name_map = { + "CCY_SafetyController": "Safety Controller", + "CCY_Linux": "Linux Processor" +} + +# Senders to exclude from display +excluded_senders = {"Default_SafetyController"} diff --git a/docs/source/utils/uart_com.dbc b/docs/source/utils/uart_com.dbc index 4ac0ecd..07284e9 100644 --- a/docs/source/utils/uart_com.dbc +++ b/docs/source/utils/uart_com.dbc @@ -1,4 +1,4 @@ -VERSION "0.0.2" +VERSION "0.0.3" NS_ : @@ -65,9 +65,9 @@ BO_ 5 AnalogInput04: 8 chargeSOM_SafetyController SG_ AI_PT1000_CFB3_4 : 7|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController BO_ 4 AnalogInput03: 8 chargeSOM_SafetyController - SG_ AI_SAFETY_HS2_CFB : 39|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController - SG_ AI_SAFETY_HS1_CFB : 23|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController - SG_ AI_SAFETY_PRECHARGE_CFB : 7|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController + SG_ AI_SAFETY_HVSW2_FB : 39|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController + SG_ AI_SAFETY_HVSW1_FB : 23|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController + SG_ AI_SAFETY_HVSW3_FB : 7|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController SG_ AI_PT1000_CFB1_2 : 55|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController BO_ 3 AnalogInput02: 8 chargeSOM_SafetyController @@ -104,9 +104,8 @@ BO_ 7 ChargeState1: 8 chargeSOM_SafetyController SG_ CS_Estop2ChargingAbort : 43|2@0+ (1,0) [0|0] "" chargeSOM_HostController SG_ CS_Estop3ChargingAbort : 45|2@0+ (1,0) [0|0] "" chargeSOM_HostController SG_ CS_Contactor1State : 33|2@0+ (1,0) [0|0] "" chargeSOM_HostController - SG_ CS_Contactor2State : 36|2@0+ (1,0) [0|0] "" chargeSOM_HostController - SG_ CS_Contactor1Error : 34|1@0+ (1,0) [0|0] "" chargeSOM_HostController - SG_ CS_Contactor2Error : 37|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ CS_Contactor2State : 35|2@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ CS_Contactor3State : 37|2@0+ (1,0) [0|0] "" chargeSOM_HostController SG_ CS_HV_Ready : 38|1@0+ (1,0) [0|0] "" chargeSOM_HostController SG_ CS_CurrentPpState : 26|3@0+ (1,0) [0|0] "" chargeSOM_HostController SG_ CS_CurrentCpState : 18|3@0+ (1,0) [0|0] "" chargeSOM_HostController @@ -118,6 +117,7 @@ BO_ 7 ChargeState1: 8 chargeSOM_SafetyController BO_ 6 ChargeControl1: 8 chargeSOM_HostController SG_ CC_Contactor1State : 16|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController SG_ CC_Contactor2State : 17|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ CC_Contactor3State : 18|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController SG_ CC_TargetDutyCycle : 1|10@0+ (0.1,0) [0|0] "%" chargeSOM_SafetyController SG_ CC_PWM_Active : 7|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController @@ -127,6 +127,7 @@ BO_ 10 FirmwareVersion: 8 chargeSOM_SafetyController SG_ BuildVersion : 23|8@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController SG_ PlatformType : 31|8@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController SG_ ApplicationType : 39|8@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ ParameterVersion : 47|16@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController BO_ 11 GitHash: 8 chargeSOM_SafetyController SG_ HashSignal : 7|64@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController @@ -200,10 +201,9 @@ CM_ SG_ 16 CS_SafeStateActive "This signal reports, if the controller is in safe CM_ BO_ 7 "This message shall be sent from safety controller to host processor for indicating the state of the charging session as well as the state of connected peripherals."; CM_ SG_ 7 CS_SafeStateReason "This signal describes in which module a fault was detected, why the controller went into safeState"; CM_ SG_ 7 CS_SafeStateActive "This signal reports, if the controller is in safeState or not."; -CM_ SG_ 7 CS_Contactor1State "Is set when the contactor is closed"; -CM_ SG_ 7 CS_Contactor2State "Is set when the contactor is closed"; -CM_ SG_ 7 CS_Contactor1Error "Is set when an error in the contactor is detected"; -CM_ SG_ 7 CS_Contactor2Error "Is set when an error in the contactor is detected"; +CM_ SG_ 7 CS_Contactor1State "State of contactor 1"; +CM_ SG_ 7 CS_Contactor2State "State of contactor 2"; +CM_ SG_ 7 CS_Contactor3State "State of contactor 3"; CM_ SG_ 7 CS_HV_Ready "This is the state of the HV ready or State C output. This output is high, if the chargeSOM dont see any errors and CP is at state C. Otherwise it is low."; CM_ SG_ 7 CS_CurrentPpState "State of the proximity pin. For fixed cables at CCS2, this value is 0x0: No Cable detected"; CM_ SG_ 7 CS_CurrentCpState "Current state of the control pilot. See value mappings below"; @@ -214,6 +214,7 @@ CM_ SG_ 7 CS_PWM_Active "Feedback if PWM is active. 0 means not active, 1 means CM_ BO_ 6 "This message shall be sent from the host processor to the safety controller to control the peripherals connected to the safety controller."; CM_ SG_ 6 CC_Contactor1State "Request to close the contactor state. A value of 0 means open contactor, a value of 1 means closed contactor. The contactors are only closed if the system has no errors and is in state C."; CM_ SG_ 6 CC_Contactor2State "Request to close the contactor state. A value of 0 means open contactor, a value of 1 means closed contactor. The contactors are only closed if the system has no errors and is in state C."; +CM_ SG_ 6 CC_Contactor3State "Request to close the contactor state. A value of 0 means open contactor, a value of 1 means closed contactor. The contactors are only closed if the system has no errors and is in state C."; CM_ SG_ 6 CC_TargetDutyCycle "Duty cycle between 0.0 and 100.0%. Values above 100.0% are set as 100%. Only valid if the signal CC_PWM_Active is 1"; CM_ SG_ 6 CC_PWM_Active "This flag indicates if the PWM should be activated. At a value of 0, the CP level is also 0V. At a value of 1, the CP level is dependant of the duty cycle"; CM_ BO_ 10 "This message provides information about the type and version of the flashed firmware"; @@ -222,6 +223,7 @@ CM_ SG_ 10 MinorVersion "Minor version of the firmware"; CM_ SG_ 10 BuildVersion "Build or patch version of the firmware"; CM_ SG_ 10 PlatformType "This firmware can be used for several products with minor changes in the build process. The platform type describes the used platform"; CM_ SG_ 10 ApplicationType "The type of firmware. See possible values below"; +CM_ SG_ 10 ParameterVersion "Version of the parameter file"; CM_ BO_ 11 "This message provides information about the GIT hash, written in the firmware"; CM_ SG_ 11 HashSignal "First 8 byte of the 160 bit (SHA-1) GIT hash"; CM_ BO_ 8 "This message shall be sent from safety controller to host processor for indicating the state of the connected temperature sensors"; @@ -253,8 +255,9 @@ VAL_ 7 CS_SafeStateActive 3 "SNA" 1 "SafeState" 0 "NormalState" ; VAL_ 7 CS_Estop1ChargingAbort 0 "FALSE" 1 "TRUE" 3 "NotConfigured" ; VAL_ 7 CS_Estop2ChargingAbort 0 "FALSE" 1 "TRUE" 3 "NotConfigured" ; VAL_ 7 CS_Estop3ChargingAbort 0 "FALSE" 1 "TRUE" 3 "NotConfigured" ; -VAL_ 7 CS_Contactor1State 0 "OPEN" 1 "CLOSE" 3 "NotConfigured" ; -VAL_ 7 CS_Contactor2State 0 "OPEN" 1 "CLOSE" 3 "NotConfigured" ; +VAL_ 7 CS_Contactor1State 0 "UNDEFINED" 1 "OPEN" 2 "CLOSE" 3 "NotConfigured" ; +VAL_ 7 CS_Contactor2State 0 "UNDEFINED" 1 "OPEN" 2 "CLOSE" 3 "NotConfigured" ; +VAL_ 7 CS_Contactor3State 0 "UNDEFINED" 1 "OPEN" 2 "CLOSE" 3 "NotConfigured" ; VAL_ 7 CS_CurrentPpState 7 "Error" 6 "Type1_ConnectedButtonPressed" 5 "Type1_Connected" 4 "63/70A" 3 "32A" 2 "20A" 1 "13A" 0 "NoCableDetected" ; VAL_ 7 CS_CurrentCpState 0 "Unknown" 7 "Invalid" 6 "F" 5 "E" 4 "D" 3 "C" 2 "B" 1 "A" ; VAL_ 10 PlatformType 129 "chargeSOM" 130 "CCY" ;