Added the protocol

README.rst

@@ -26,7 +26,7 @@ Building the documentation locally:
 To build the documentation locally, you need to have Python and pip installed on your system.
 You can install the required dependencies by running the following command:
 
-pip install -r requirements.txt
+pip install -r docs/requirements.txt
 
 After installing the dependencies, you can build the documentation by running the following command:
 

docs/source/hardware.rst

@@ -99,11 +99,114 @@ in the following table.
 | Stopbits        | 1           |
 +-----------------+-------------+
 
+System Architecture
+===================
+.. figure:: _static/images/system_architecture.svg
+    :width: 1000pt
+
+    Figure: Simplified system architecture for the safety controller on the chargeSOM
+
+The safety controller manages the Control Pilot (CP) line, acting as a critical interface for monitoring and controlling the high-voltage (HV) system in accordance with EV safety standards. Its core function is to **enforce safe operating states** based on system diagnostics and environmental conditions.
+
+Fault Detection & Safety Response
+---------------------------------
+
+When an error is detected—such as a fault in the system, a triggered emergency input, or a thermal violation—the controller transitions to **State F**, a fail-safe state that prevents further system operation to protect both the hardware and the user.
+
+HV Ready Enablement
+-------------------
+
+The controller verifies that **no system errors are present** and that the CP line is in **State C**. Only under these safe conditions does it enable the HV Ready signal, which may be used to energize the HV interlock or permit charging/operation.
+
+Emergency  Inputs
+----------------------------------
+
+The simplified system architecture shows only one emergency input. In the real system, there are 3 independent emergency input signals available: SAFETY_ESTOP1, SAFETY_ESTOP2 and SAFETY_ESTOP3. The inputs are active low. This means an emergency stop needs to pull the input to Gnd. The emergency inputs can be parameterized out.
+
+
+Temperature Monitoring
+----------------------------------
+
+The simplified system architecture shows only one temperature input. In the real system, there are 4 independent temperature measurement circuits for PT1000 sensors. The safety software monitors the temperature circuit for hardware errors and for overtemperaure. The temperature threshold can be parameterized.
+
+HV Connector Control
+--------------------
+
+If State C is confirmed and all safety criteria are met, the controller is also capable of closing HV connectors to complete the high-voltage path. Therefore it enables the 2 connectors SAFETY_HVSW1_HS and SAFETY_HVSW2_HS under the condition that State C is detected, the system is HV-ready and the host processor commands to close the contactors. 
+
+
+Reset Behaviour and Controller states
+=====================================
+The safety controller starts in an initialization state, to give the peripherals time to reach an defined state. It leaves the initialization state to a running state, after the reception of the first UART message from the host. Only periodic messages leaves the init state. With the reception of inquiriy messages, the safety controller stays in initialization. This gives the option to fetch version information in an init state. In running state, it monitors the peripherals and sends out UART messages. If any error occurs, the system goes into safe state. This state can only be left by a reset.
+
+.. figure:: _static/images/safety_controller_states.svg
+    :width: 1000pt
+
+
 
 Safety Controller Communication Protocol
 ========================================
 
-TBD
+Packet format descriptions
+--------------------------
+
+Data packet format
+
+Data packets contain payload and can be sent out from host to safety controller or vice versa. Data packets from safety controller to host can be transmitted periodically or by request via an inquiry packet. Only one inquiry packet can be requested before requesting the next one.
+
++--------+--------+--------+-------------------+
+| Symbol | Size   | Code   | Description       |
++========+========+========+===================+
+| SOF    | 1 byte | 0xA5   | Start of frame    |
++--------+--------+--------+-------------------+
+| ID     | 1 byte |        | Packet Identifier |
++--------+--------+--------+-------------------+
+| Data   | 8 byte |        | Payload           |
++--------+--------+--------+-------------------+
+| CRC    | 1 byte |        | CRC checksum      |
++--------+--------+--------+-------------------+
+| EOF    | 1 byte | 0x03   | End of frame      |
++--------+--------+--------+-------------------+
+
+
+Packet Identifier (ID)
+----------------------
+
+The values of the packet identifier (PacketId) are mapped to the messages as summarized below.
+
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+| PacketId | Description               | Communication Dir.  | Periodicity                                                 | Triggered by Inquiry |
++==========+===========================+=====================+=============================================================+======================+
+| 0x06     | Charge Control            | Host → Safety       | periodically, every 100ms OR immediately if changes occur   | No                   |
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+| 0x07     | Charge State              | Safety → Host       | periodically, every 100ms                                   | No                   |
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+| 0x08     | PT1000 State              | Safety → Host       | periodically, every 100ms                                   | No                   |
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+| 0x0A     | Firmware Version          | Safety → Host       | no, only upon request via inquiry packet                    | Yes                  |
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+| 0x0B     | GIT Hash                  | Safety → Host       | no, only upon request via inquiry packet                    | Yes                  |
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+| 0xFF     | Inquiry packet            | Host → Safety       | no, only to trigger inquiries                               | No                   |
++----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
+
+CRC checksum field
+------------------
+
+The checksum is defined over:
+
+::
+
+    Width       = 8
+    Poly        = 0x1d
+    XorIn       = 0xff
+    ReflectIn   = False
+    XorOut      = 0xff
+    ReflectOut  = False
+    Algorithm   = table-driven
+    Name        = CRC8 SAE J1850
+
+.. include:: safety_protocol.rst
 
 
 EVerest Board Support Package Module