From 2439852573d554c0b4f8184ce1751af927aa0d1d Mon Sep 17 00:00:00 2001 From: Michael Heimpold Date: Thu, 30 Oct 2025 10:20:08 +0100 Subject: [PATCH 1/4] Update DBC and generated UART frame documentation Signed-off-by: Michael Heimpold --- docs/source/safety_protocol.rst | 126 +++++++++---- docs/source/utils/uart_com.dbc | 308 +++++++++++++++++--------------- 2 files changed, 258 insertions(+), 176 deletions(-) diff --git a/docs/source/safety_protocol.rst b/docs/source/safety_protocol.rst index 231a402..ab3c262 100644 --- a/docs/source/safety_protocol.rst +++ b/docs/source/safety_protocol.rst @@ -7,7 +7,7 @@ ChargeControl1 **Description**: This message shall be sent from the host processor to the safety controller to control the peripherals connected to the safety controller. -**Senders**: Default_HostController +**Senders**: chargeSOM_HostController .. list-table:: Signals in ChargeControl1 :widths: 30 6 6 10 7 7 7 6 30 @@ -58,6 +58,15 @@ ChargeControl1 - 0 - - 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. + * - CC_Contactor3State + - 18 + - 1 + - + - No + - 1 + - 0 + - + - 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. **Bitfield Layout** @@ -70,7 +79,7 @@ ChargeControl1 +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 1| | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 2| | | | | | | CC_Contactor2State | CC_Contactor1State | + 2| | | | | | CC_Contactor3State | CC_Contactor2State | CC_Contactor1State | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 3| | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ @@ -92,7 +101,7 @@ ChargeState1 **Description**: 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. -**Senders**: Safety Controller +**Senders**: chargeSOM_SafetyController .. list-table:: Signals in ChargeState1 :widths: 30 6 6 10 7 7 7 6 30 @@ -116,6 +125,15 @@ ChargeState1 - 0 - % - The current duty cycle between 0.0% and 100.0%. If the PWM is not aczive this signal is 0 + * - CS_SafeStateActive + - 3 + - 2 + - + - No + - 1 + - 0 + - + - This signal reports, if the controller is in safeState or not. * - CS_PWM_Active - 7 - 1 @@ -169,34 +187,25 @@ ChargeState1 - 1 - 0 - - - Is set when the contactor is closed - * - CS_Contactor1Error - - 34 - - 1 - - - - No - - 1 - - 0 - - - - Is set when an error in the contactor is detected + - State of contactor 1 * - CS_Contactor2State - - 36 + - 35 - 2 - - No - 1 - 0 - - - Is set when the contactor is closed - * - CS_Contactor2Error + - State of contactor 2 + * - CS_Contactor3State - 37 - - 1 + - 2 - - No - 1 - 0 - - - Is set when an error in the contactor is detected + - State of contactor 3 * - CS_HV_Ready - 38 - 1 @@ -233,9 +242,24 @@ ChargeState1 - 0 - - *No description available* + * - CS_SafeStateReason + - 55 + - 8 + - + - No + - 1 + - 0 + - + - This signal describes in which module a fault was detected, why the controller went into safeState **Value Descriptions** +- **CS_SafeStateActive** + + - 0x0 = NormalState + - 0x1 = SafeState + - 0x3 = SNA + - **CS_CurrentCpState** - 0x0 = Unknown @@ -260,14 +284,23 @@ ChargeState1 - **CS_Contactor1State** - - 0x0 = OPEN - - 0x1 = CLOSE + - 0x0 = UNDEFINED + - 0x1 = OPEN + - 0x2 = CLOSE - 0x3 = NotConfigured - **CS_Contactor2State** - - 0x0 = OPEN - - 0x1 = CLOSE + - 0x0 = UNDEFINED + - 0x1 = OPEN + - 0x2 = CLOSE + - 0x3 = NotConfigured + +- **CS_Contactor3State** + + - 0x0 = UNDEFINED + - 0x1 = OPEN + - 0x2 = CLOSE - 0x3 = NotConfigured - **CS_Estop1ChargingAbort** @@ -288,6 +321,28 @@ ChargeState1 - 0x1 = TRUE - 0x3 = NotConfigured +- **CS_SafeStateReason** + + - 0x0 = NoStop + - 0x1 = InternalError + - 0x2 = ComTimeout + - 0x3 = Temp1_Malfunction + - 0x4 = Temp2_Malfunction + - 0x5 = Temp3_Malfunction + - 0x6 = Temp4_Malfunction + - 0x7 = Temp1_Overtemp + - 0x8 = Temp2_Overtemp + - 0x9 = Temp3_Overtemp + - 0xA = Temp4_Overtemp + - 0xB = PP_Malfunction + - 0xC = CP_Malfunction + - 0xD = CP_ShortCircuit + - 0xE = CP_DiodeFault + - 0xF = HVSW_Malfunction + - 0x10 = EmergencyInput1 + - 0x11 = EmergencyInput2 + - 0x12 = EmergencyInput3 + **Bitfield Layout** :: @@ -295,7 +350,7 @@ ChargeState1 +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 0| CS_PWM_Active | | | | | |CS_CurrentDutyCycle | | + 0| CS_PWM_Active | | | | CS_SafeStateActive | |CS_CurrentDutyCycle | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 1| | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ @@ -303,11 +358,11 @@ ChargeState1 +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 3| | | | | | CS_CurrentPpState | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| | CS_HV_Ready | CS_Contactor2Error | CS_Contactor2State | | CS_Contactor1Error | CS_Contactor1State | | + 4| | CS_HV_Ready | CS_Contactor3State | | CS_Contactor2State | | CS_Contactor1State | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 5| | |CS_Estop3ChargingAbo| |CS_Estop2ChargingAbo| |CS_Estop1ChargingAbo| | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 6| | | | | | | | | + 6| CS_SafeStateReason | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 7| | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ @@ -321,7 +376,7 @@ PT1000State **Description**: This message shall be sent from safety controller to host processor for indicating the state of the connected temperature sensors -**Senders**: Safety Controller +**Senders**: chargeSOM_SafetyController .. list-table:: Signals in PT1000State :widths: 30 6 6 10 7 7 7 6 30 @@ -496,7 +551,7 @@ FirmwareVersion **Description**: This message provides information about the type and version of the flashed firmware -**Senders**: Safety Controller +**Senders**: chargeSOM_SafetyController .. list-table:: Signals in FirmwareVersion :widths: 30 6 6 10 7 7 7 6 30 @@ -556,6 +611,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** @@ -585,9 +649,9 @@ FirmwareVersion +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 3| PlatformType | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 4| ApplicationType | | | | | | | | + 4| ParameterVersion | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ - 5| | | | | | | | | + 5| ParameterVersion | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ 6| | | | | | | | | +--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+ @@ -603,7 +667,7 @@ GitHash **Description**: This message provides information about the GIT hash, written in the firmware -**Senders**: Safety Controller +**Senders**: chargeSOM_SafetyController .. list-table:: Signals in GitHash :widths: 30 6 6 10 7 7 7 6 30 @@ -661,7 +725,7 @@ InquiryPacket **Description**: This packet is used to request a special message from the safety controller -**Senders**: Default_HostController, CCY_HostController +**Senders**: chargeSOM_HostController, CCY_HostController .. list-table:: Signals in InquiryPacket :widths: 30 6 6 10 7 7 7 6 30 diff --git a/docs/source/utils/uart_com.dbc b/docs/source/utils/uart_com.dbc index 6769525..07284e9 100644 --- a/docs/source/utils/uart_com.dbc +++ b/docs/source/utils/uart_com.dbc @@ -1,4 +1,4 @@ -VERSION "0.0.1" +VERSION "0.0.3" NS_ : @@ -33,165 +33,177 @@ NS_ : BS_: -BU_: Default_HostController Default_SafetyController CCY_HostController CCY_SafetyController - - -BO_ 255 InquiryPacket: 8 Default_HostController - SG_ PacketId : 7|8@0+ (1,0) [0|0] "" CCY_SafetyController,Default_SafetyController - -BO_ 0 DigitalOutput: 4 Default_HostController - SG_ DO_SAFETY_HVSW3_PRECHARGE : 9|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_CP_INVERT : 3|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_CP_Dutycycle : 31|8@0+ (1,0) [0|0] "%" Default_SafetyController - SG_ DO_PP_SAE_IEC : 15|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_CP_STATE_C : 18|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_GPIO_EXP : 12|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_IMD_OD_EN : 11|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_MOTOR_OUT2 : 5|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_MOTOR_OUT1 : 6|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_HVSW2_HS : 13|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_SAFETY_HVSW1_HS : 14|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_PT1000_CTRLEN4 : 10|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_PT1000_CTRLEN3 : 19|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_PT1000_CTRLEN2 : 20|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ DO_PT1000_CTRLEN1 : 21|1@0+ (1,0) [0|0] "" Default_SafetyController +BU_: chargeSOM_HostController chargeSOM_SafetyController CCY_HostController CCY_SafetyController + + +BO_ 255 InquiryPacket: 8 chargeSOM_HostController + SG_ PacketId : 7|8@0+ (1,0) [0|0] "" CCY_SafetyController,chargeSOM_SafetyController + +BO_ 0 DigitalOutput: 8 chargeSOM_HostController + SG_ DO_SAFETY_HVSW3_PRECHARGE : 9|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_CP_INVERT : 3|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_CP_Dutycycle : 31|8@0+ (1,0) [0|0] "%" chargeSOM_SafetyController + SG_ DO_PP_SAE_IEC : 15|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_SAFETY_CP_STATE_C : 18|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController,CCY_SafetyController + SG_ DO_SAFETY_GPIO_EXP : 12|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_SAFETY_IMD_OD_EN : 11|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_SAFETY_MOTOR_OUT2 : 5|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_SAFETY_MOTOR_OUT1 : 6|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_SAFETY_HVSW2_HS : 13|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_SAFETY_HVSW1_HS : 14|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController + SG_ DO_PT1000_CTRLEN4 : 10|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController,CCY_SafetyController + SG_ DO_PT1000_CTRLEN3 : 19|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController,CCY_SafetyController + SG_ DO_PT1000_CTRLEN2 : 20|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController,CCY_SafetyController + SG_ DO_PT1000_CTRLEN1 : 21|1@0+ (1,0) [0|0] "" chargeSOM_SafetyController,CCY_SafetyController + SG_ DO_CE_S3 : 23|1@0+ (1,0) [0|0] "" CCY_SafetyController BO_ 18 DiagnosticMeasurements2: 8 CCY_SafetyController SG_ DM_ID_ADC_VAL : 23|16@0+ (1,0) [0|0] "" CCY_HostController SG_ DM_CE_ADC_VAL : 7|16@0+ (1,0) [0|0] "" CCY_HostController -BO_ 5 AnalogInput04: 8 Default_SafetyController - SG_ AI_INT_REFVOLT : 39|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_INT_TEMP : 23|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_PT1000_CFB3_4 : 7|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - -BO_ 4 AnalogInput03: 8 Default_SafetyController - SG_ AI_SAFETY_HS2_CFB : 39|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_SAFETY_HS1_CFB : 23|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_SAFETY_PRECHARGE_CFB : 7|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_PT1000_CFB1_2 : 55|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - -BO_ 3 AnalogInput02: 8 Default_SafetyController - SG_ AI_SAFETY_U_IN_ADC : 55|16@0+ (1,0) [0|0] "" Default_HostController - SG_ AI_PP_VALUE_ADC : 39|16@0+ (1,0) [0|0] "" Default_HostController - SG_ AI_CP_BUFFERED_POS_ADC : 23|16@0+ (1,0) [0|0] "" Default_HostController - SG_ AI_CP_BUFFERED_NEG_ADC : 7|16@0+ (1,0) [0|0] "" Default_HostController - -BO_ 2 AnalogInput01: 8 Default_SafetyController - SG_ AI_PT1000_LEAD1_4 : 55|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_PT1000_LEAD1_3 : 39|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_PT1000_LEAD1_2 : 23|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController - SG_ AI_PT1000_LEAD1_1 : 7|16@0+ (1,0) [0|0] "" CCY_HostController,Default_HostController +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_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 + SG_ AI_SAFETY_U_IN_ADC : 55|16@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ AI_PP_VALUE_ADC : 39|16@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ AI_CP_BUFFERED_POS_ADC : 23|16@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ AI_CP_BUFFERED_NEG_ADC : 7|16@0+ (1,0) [0|0] "" chargeSOM_HostController + +BO_ 19 AnalogInput05: 8 CCY_SafetyController + SG_ AI_HV_READY : 39|16@0+ (1,0) [0|0] "" CCY_HostController + SG_ AI_CE_ADC : 23|16@0+ (1,0) [0|0] "" CCY_HostController + SG_ AI_ID_ADC : 7|16@0+ (1,0) [0|0] "" CCY_HostController + +BO_ 2 AnalogInput01: 8 chargeSOM_SafetyController + SG_ AI_PT1000_LEAD1_4 : 55|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController + SG_ AI_PT1000_LEAD1_3 : 39|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController + SG_ AI_PT1000_LEAD1_2 : 23|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController + SG_ AI_PT1000_LEAD1_1 : 7|16@0+ (1,0) [0|0] "" CCY_HostController,chargeSOM_HostController BO_ 17 ChargeControl2: 8 CCY_HostController SG_ CC_ControllerReset : 3|2@0+ (1,0) [0|0] "" CCY_SafetyController SG_ CC_CCSReady : 7|4@0+ (1,0) [0|0] "" CCY_SafetyController BO_ 16 ChargeState2: 8 CCY_SafetyController + SG_ CS_SafeStateActive : 23|2@0+ (1,0) [0|0] "" CCY_HostController SG_ CS_EStop_Reason : 15|8@0+ (1,0) [0|0] "" CCY_HostController SG_ CS_ID_State : 3|4@0+ (1,0) [0|0] "" CCY_HostController SG_ CS_CE_State : 7|4@0+ (1,0) [0|0] "" CCY_HostController -BO_ 7 ChargeState1: 8 Default_SafetyController - SG_ CS_Estop1ChargingAbort : 41|2@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_Estop2ChargingAbort : 43|2@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_Estop3ChargingAbort : 45|2@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_Contactor1State : 33|2@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_Contactor2State : 36|2@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_Contactor1Error : 34|1@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_Contactor2Error : 37|1@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_HV_Ready : 38|1@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_CurrentPpState : 26|3@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_CurrentCpState : 18|3@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_CpShortCircuit : 19|1@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_DiodeFault : 20|1@0+ (1,0) [0|0] "" Default_HostController - SG_ CS_CurrentDutyCycle : 1|10@0+ (0.1,0) [0|0] "%" Default_HostController - SG_ CS_PWM_Active : 7|1@0+ (1,0) [0|0] "" Default_HostController - -BO_ 6 ChargeControl1: 8 Default_HostController - SG_ CC_Contactor1State : 16|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ CC_Contactor2State : 17|1@0+ (1,0) [0|0] "" Default_SafetyController - SG_ CC_TargetDutyCycle : 1|10@0+ (0.1,0) [0|0] "%" Default_SafetyController - SG_ CC_PWM_Active : 7|1@0+ (1,0) [0|0] "" Default_SafetyController - -BO_ 10 FirmwareVersion: 8 Default_SafetyController - SG_ MajorVersion : 7|8@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ MinorVersion : 15|8@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ BuildVersion : 23|8@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PlatformType : 31|8@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ ApplicationType : 39|8@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - -BO_ 11 GitHash: 8 Default_SafetyController - SG_ HashSignal : 7|64@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - -BO_ 14 ErrorMessage: 8 Default_SafetyController - SG_ ErrorAddData2 : 55|16@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ ErrorAddData1 : 39|16@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ ErrorModule : 6|15@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ ErrorReason : 23|16@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ ErrorActive : 7|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - -BO_ 9 DiagnosticMeasurements: 8 Default_SafetyController - SG_ DM_PP_Voltage : 39|16@0- (1,0) [0|0] "" Default_SafetyController,Default_HostController - SG_ DM_CP_VoltagePositiveSide : 23|16@0- (1,0) [0|0] "" Default_SafetyController,Default_HostController - SG_ DM_CP_VoltageNegativeSide : 7|16@0- (1,0) [0|0] "" Default_SafetyController,Default_HostController - -BO_ 8 PT1000State: 8 Default_SafetyController - SG_ PT4_Temperature : 55|14@0- (0.1,0) [0|0] "°C" Default_HostController,CCY_HostController - SG_ PT4_SelftestFailed : 57|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT4_ChargingStopped : 56|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT3_Temperature : 39|14@0- (0.1,0) [0|0] "°C" Default_HostController,CCY_HostController - SG_ PT3_SelftestFailed : 41|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT3_ChargingStopped : 40|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT2_Temperature : 23|14@0- (0.1,0) [0|0] "°C" Default_HostController,CCY_HostController - SG_ PT2_SelftestFailed : 25|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT2_ChargingStopped : 24|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT1_Temperature : 7|14@0- (0.1,0) [0|0] "°C" Default_HostController,CCY_HostController - SG_ PT1_SelftestFailed : 9|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ PT1_ChargingStopped : 8|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - -BO_ 1 DigitalInput: 3 CCY_SafetyController - SG_ DI_SAFETY_CP_STATE_C : 19|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_MOTOR_OUT1 : 6|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_MOTOR_OUT2 : 5|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_MOTOR_FAULT : 4|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_HVSW2_HS : 13|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_HVSW1_HS : 14|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_HVSW3_PRECHARGE : 9|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_PP_SAE_IEC : 15|1@0+ (1,0) [0|0] "" Default_HostController - SG_ DI_SAFETY_DEV_1 : 0|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_SAFETY_DEV_2 : 1|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_EV_CP_EDGE : 2|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_CP_INVERT : 3|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_SAFETY_K1_IN : 7|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_PT4_EN : 10|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_PT3_EN : 20|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_PT2_EN : 21|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_PT1_EN : 22|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_SAFETY_IMD_OD_EN : 11|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_SAFETY_GPIO_EXP : 12|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_ESTOP3 : 16|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_ESTOP2 : 17|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_ESTOP1 : 18|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - SG_ DI_SAFETY_K2_IN : 8|1@0+ (1,0) [0|0] "" Default_HostController,CCY_HostController - -BO_TX_BU_ 255 : CCY_HostController,Default_HostController; -BO_TX_BU_ 5 : CCY_SafetyController,Default_SafetyController; -BO_TX_BU_ 4 : CCY_SafetyController,Default_SafetyController; -BO_TX_BU_ 2 : CCY_SafetyController,Default_SafetyController; -BO_TX_BU_ 10 : CCY_SafetyController,Default_SafetyController; -BO_TX_BU_ 14 : CCY_SafetyController,Default_SafetyController; -BO_TX_BU_ 8 : CCY_SafetyController,Default_SafetyController; -BO_TX_BU_ 1 : Default_SafetyController,CCY_SafetyController; +BO_ 7 ChargeState1: 8 chargeSOM_SafetyController + SG_ CS_SafeStateReason : 55|8@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ CS_SafeStateActive : 3|2@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ CS_Estop1ChargingAbort : 41|2@0+ (1,0) [0|0] "" chargeSOM_HostController + 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 : 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 + SG_ CS_CpShortCircuit : 19|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ CS_DiodeFault : 20|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ CS_CurrentDutyCycle : 1|10@0+ (0.1,0) [0|0] "%" chargeSOM_HostController + SG_ CS_PWM_Active : 7|1@0+ (1,0) [0|0] "" chargeSOM_HostController + +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 + +BO_ 10 FirmwareVersion: 8 chargeSOM_SafetyController + SG_ MajorVersion : 7|8@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ MinorVersion : 15|8@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + 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 + +BO_ 14 ErrorMessage: 8 chargeSOM_SafetyController + SG_ ErrorAddData2 : 55|16@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ ErrorAddData1 : 39|16@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ ErrorModule : 6|15@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ ErrorReason : 23|16@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ ErrorActive : 7|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + +BO_ 9 DiagnosticMeasurements: 8 chargeSOM_SafetyController + SG_ DM_PP_Voltage : 39|16@0- (1,0) [0|0] "" chargeSOM_SafetyController,chargeSOM_HostController + SG_ DM_CP_VoltagePositiveSide : 23|16@0- (1,0) [0|0] "" chargeSOM_SafetyController,chargeSOM_HostController + SG_ DM_CP_VoltageNegativeSide : 7|16@0- (1,0) [0|0] "" chargeSOM_SafetyController,chargeSOM_HostController + +BO_ 8 PT1000State: 8 chargeSOM_SafetyController + SG_ PT4_Temperature : 55|14@0- (0.1,0) [0|0] "°C" chargeSOM_HostController,CCY_HostController + SG_ PT4_SelftestFailed : 57|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT4_ChargingStopped : 56|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT3_Temperature : 39|14@0- (0.1,0) [0|0] "°C" chargeSOM_HostController,CCY_HostController + SG_ PT3_SelftestFailed : 41|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT3_ChargingStopped : 40|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT2_Temperature : 23|14@0- (0.1,0) [0|0] "°C" chargeSOM_HostController,CCY_HostController + SG_ PT2_SelftestFailed : 25|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT2_ChargingStopped : 24|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT1_Temperature : 7|14@0- (0.1,0) [0|0] "°C" chargeSOM_HostController,CCY_HostController + SG_ PT1_SelftestFailed : 9|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ PT1_ChargingStopped : 8|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + +BO_ 1 DigitalInput: 8 CCY_SafetyController + SG_ DI_SAFETY_CP_STATE_C : 19|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ DI_SAFETY_MOTOR_OUT1 : 6|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_MOTOR_OUT2 : 5|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_MOTOR_FAULT : 4|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_HVSW2_HS : 13|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_HVSW1_HS : 14|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_HVSW3_PRECHARGE : 9|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_PP_SAE_IEC : 15|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_DEV_1 : 0|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_DEV_2 : 1|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_EV_CP_EDGE : 2|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_CP_INVERT : 3|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_K1_IN : 7|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_PT4_EN : 10|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ DI_PT3_EN : 20|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ DI_PT2_EN : 21|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ DI_PT1_EN : 22|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ DI_SAFETY_IMD_OD_EN : 11|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_SAFETY_GPIO_EXP : 12|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_ESTOP3 : 16|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_ESTOP2 : 17|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_ESTOP1 : 18|1@0+ (1,0) [0|0] "" chargeSOM_HostController,CCY_HostController + SG_ DI_SAFETY_K2_IN : 8|1@0+ (1,0) [0|0] "" chargeSOM_HostController + SG_ DI_CE_S3 : 23|1@0+ (1,0) [0|0] "" CCY_HostController + +BO_TX_BU_ 255 : CCY_HostController,chargeSOM_HostController; +BO_TX_BU_ 5 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 4 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 2 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 10 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 11 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 14 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 8 : CCY_SafetyController,chargeSOM_SafetyController; +BO_TX_BU_ 1 : chargeSOM_SafetyController,CCY_SafetyController; CM_ BO_ 255 "This packet is used to request a special message from the safety controller"; CM_ SG_ 255 PacketId "The ID, which message shall be requested. Supported values are described below."; +CM_ SG_ 16 CS_SafeStateActive "This signal reports, if the controller is in safeState or not."; 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_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_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 "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"; @@ -202,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"; @@ -210,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"; @@ -232,14 +246,18 @@ BA_DEF_DEF_ "BusType" ""; BA_ "BusType" "J1708"; VAL_ 255 PacketId 10 "FirmwareVersion" 11 "GitHash" ; VAL_ 17 CC_CCSReady 2 "CCS_EmergencyStop" 1 "CCS_Ready" 0 "CCS_NotReady" ; -VAL_ 16 CS_EStop_Reason 13 "HVReady_Malfunction" 12 "CE_Malfunction" 11 "ID_Malfunction" 10 "Temp4_Overtemp" 9 "Temp3_Overtemp" 8 "Temp2_Overtemp" 7 "Temp1_Overtemp" 6 "Temp4_Malfunction" 5 "Temp3_Malfunction" 4 "Temp2_Malfunction" 3 "Temp1_Malfunction" 2 "ComTimeout" 1 "EmergencyInput" 0 "NoStop" ; -VAL_ 16 CS_ID_State 15 "SNA" 14 "Invalid" 1 "Connected" 0 "Not_Connected" ; -VAL_ 16 CS_CE_State 15 "SNA" 7 "Invalid" 6 "B0" 5 "EC" 4 "E" 3 "D" 2 "C" 1 "B" 0 "A" ; +VAL_ 16 CS_SafeStateActive 3 "SNA" 1 "SafeState" 0 "NormalState" ; +VAL_ 16 CS_EStop_Reason 14 "EmergencyInput" 13 "HVReady_Malfunction" 12 "CE_Malfunction" 11 "ID_Malfunction" 10 "Temp4_Overtemp" 9 "Temp3_Overtemp" 8 "Temp2_Overtemp" 7 "Temp1_Overtemp" 6 "Temp4_Malfunction" 5 "Temp3_Malfunction" 4 "Temp2_Malfunction" 3 "Temp1_Malfunction" 2 "ComTimeout" 1 "InternalError" 0 "NoStop" ; +VAL_ 16 CS_ID_State 3 "Invalid" 2 "Connected" 1 "Not Connected" 0 "Unknown" ; +VAL_ 16 CS_CE_State 7 "Invalid" 6 "EC" 5 "E" 4 "C" 3 "B" 2 "B0" 1 "A" 0 "Unknown" ; +VAL_ 7 CS_SafeStateReason 18 "EmergencyInput3" 17 "EmergencyInput2" 16 "EmergencyInput1" 15 "HVSW_Malfunction" 14 "CP_DiodeFault" 13 "CP_ShortCircuit" 12 "CP_Malfunction" 11 "PP_Malfunction" 10 "Temp4_Overtemp" 9 "Temp3_Overtemp" 8 "Temp2_Overtemp" 7 "Temp1_Overtemp" 6 "Temp4_Malfunction" 5 "Temp3_Malfunction" 4 "Temp2_Malfunction" 3 "Temp1_Malfunction" 2 "ComTimeout" 1 "InternalError" 0 "NoStop" ; +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" ; From aa72c933db46efe078d15a6af7e91bc7bd79377e Mon Sep 17 00:00:00 2001 From: Michael Heimpold Date: Thu, 30 Oct 2025 11:24:43 +0100 Subject: [PATCH 2/4] Adapt parameter block documentation to safety fw v0.2.6 Signed-off-by: Michael Heimpold --- .../safety_controller_parameterization.rst | 67 +++++++++++++++---- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/source/safety_controller_parameterization.rst b/docs/source/safety_controller_parameterization.rst index de6a6ad..b57d1aa 100644 --- a/docs/source/safety_controller_parameterization.rst +++ b/docs/source/safety_controller_parameterization.rst @@ -32,15 +32,21 @@ To make the handling of parameters human-friendly, all parameters can be put tog .. code-block:: yaml + version: 1 pt1000s: - - 75.0 °C - - 85.0 °C - - disabled + - abort-temperature: 75.0 °C + resistance-offset: 0.85 Ω + - abort-temperature: 85.0 °C + resistance-offset: 1.042 Ω + - 80.0 °C - disabled contactors: + - type: without-feedback + close-time: 100 ms + open-time: 100 ms - without-feedback - - without-feedback + - disabled estops: - active-low @@ -52,35 +58,64 @@ To make the handling of parameters human-friendly, all parameters can be put tog 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 -either a temperature threshold in °C at which the safety controller stops and/or prevents charging. -In a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled` +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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The safety controller allows to control up to 2 high-voltage contactors and can monitor corresponding mirror contacts. -The mirror contacts need to have `Normally Closed` semantic. In the YAML parameterization, it is possible to -specify whether the safety controller should actually switch the corresponding output pin and whether to monitor -the feedback input pins. +The safety controller allows to control up to 3 high-voltage contactors and can monitor corresponding mirror contacts. +The mirror contacts support `Normally Closed` and `Normally Open` semantic, but customer must follow chargebyte's +Charge SOM's EVB reference design otherwise the logic might be inverted. +In the YAML parameterization, it is possible to specify whether the safety controller should actually switch the +corresponding output pin and whether to monitor the feedback input pins. When using the feedback, it is usually also +required to specify the open and closing times of the used contactor. These times are expected in milliseconds and +used by the Safety Firmware to check after the given time whether the feedback pin has expected level. If the level +differs from the expectation, then Safety Firmware assumes a malfunction and thus enters safe state. -Possible parameter values are: +The example YAML file above shows all allowed variants how to parameterize a contactor. +Possible values for the `type` are: - `disabled` - `without-feedback` -- `with-feedback` +- `with-feedback-normally-open` +- `with-feedback-normally-closed` + +Since the open/close timings make no sense in case of `disabled` or `without-feedback`, it is possible to use these +tokens directly as array item (actually, it is also possible to use the `with-feedback...` ones, but then the timings +are considered zero). + +Both `close-time` and `open-time` accept integer values in the range 0 to 2550 ms, however the given value is +divided by 10 before it is actually stored internally. Emergency Input Configuration @@ -105,15 +140,19 @@ The following session transcript shows how the install procedure works: # create a YAML file on-the-fly $ cat < /tmp/my-parameters.yaml + version: 1 pt1000s: - - 75.0 °C - - 85.0 °C + - abort-temperature: 85.0 °C + resistance-offset: 0.85 Ω + - abort-temperature: 75.0 °C + resistance-offset: 1.1 Ω - disabled - disabled contactors: - without-feedback - without-feedback + - disabled estops: - active-low From 9b7d3a0f7b917e133c247d3906a22cac62e7097d Mon Sep 17 00:00:00 2001 From: Michael Heimpold Date: Mon, 3 Nov 2025 16:59:36 +0100 Subject: [PATCH 3/4] Add reference/example circuit for contactor feedback signal Signed-off-by: Michael Heimpold --- .../charge_som_contactor_feedback_evb-circuit.drawio.svg | 4 ++++ docs/source/safety_controller_parameterization.rst | 9 ++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg diff --git a/docs/source/_static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg b/docs/source/_static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg new file mode 100644 index 0000000..af5f680 --- /dev/null +++ b/docs/source/_static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg @@ -0,0 +1,4 @@ + + + +
Safety MCU
Safety MCU
Charge SOM
Charge SOM
SAFETY_HVSW1_FB
SAFETY_HVSW1_FB
5V
5V
10k
1...
EVB
EVB
PSU
12 V
PSU...
−
−
+
+
1
1
2
2
3
3
4
4
5
5
6
6
7
7
8
8
X19
X19
GND
GND
DC +
DC +Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/source/safety_controller_parameterization.rst b/docs/source/safety_controller_parameterization.rst index b57d1aa..6524323 100644 --- a/docs/source/safety_controller_parameterization.rst +++ b/docs/source/safety_controller_parameterization.rst @@ -96,6 +96,12 @@ Contactor and Contactor Feedback Configuration The safety controller allows to control up to 3 high-voltage contactors and can monitor corresponding mirror contacts. The mirror contacts support `Normally Closed` and `Normally Open` semantic, but customer must follow chargebyte's Charge SOM's EVB reference design otherwise the logic might be inverted. + +.. figure:: _static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg + :width: 800px + + Simplified Reference Circuit used on Charge SOM's EVB for Contactor Feedback Signal + In the YAML parameterization, it is possible to specify whether the safety controller should actually switch the corresponding output pin and whether to monitor the feedback input pins. When using the feedback, it is usually also required to specify the open and closing times of the used contactor. These times are expected in milliseconds and @@ -112,10 +118,11 @@ Possible values for the `type` are: Since the open/close timings make no sense in case of `disabled` or `without-feedback`, it is possible to use these tokens directly as array item (actually, it is also possible to use the `with-feedback...` ones, but then the timings -are considered zero). +are considered zero which will result in an error due to the latency in the contactor). Both `close-time` and `open-time` accept integer values in the range 0 to 2550 ms, however the given value is divided by 10 before it is actually stored internally. +(This division by 10 is necessary because the safety controller operates with internal time slots of 10 ms.) Emergency Input Configuration From c00a5116a1502a50a48b1e73873b9d5a0edb081c Mon Sep 17 00:00:00 2001 From: Michael Heimpold Date: Tue, 4 Nov 2025 12:51:04 +0100 Subject: [PATCH 4/4] Reword the feedback open/close time description Signed-off-by: Michael Heimpold --- .../safety_controller_parameterization.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/safety_controller_parameterization.rst b/docs/source/safety_controller_parameterization.rst index 6524323..60145fb 100644 --- a/docs/source/safety_controller_parameterization.rst +++ b/docs/source/safety_controller_parameterization.rst @@ -93,8 +93,8 @@ The range for `resistance-offset` is -32.0 Ω ... 32.0 Ω and these values are s Contactor and Contactor Feedback Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The safety controller allows to control up to 3 high-voltage contactors and can monitor corresponding mirror contacts. -The mirror contacts support `Normally Closed` and `Normally Open` semantic, but customer must follow chargebyte's +The safety controller allows to control up to 3 high-voltage contactors and can monitor corresponding feedback contacts. +The feedback contacts support `Normally Closed` and `Normally Open` semantic, but customer must follow chargebyte's Charge SOM's EVB reference design otherwise the logic might be inverted. .. figure:: _static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg @@ -103,10 +103,10 @@ Charge SOM's EVB reference design otherwise the logic might be inverted. Simplified Reference Circuit used on Charge SOM's EVB for Contactor Feedback Signal In the YAML parameterization, it is possible to specify whether the safety controller should actually switch the -corresponding output pin and whether to monitor the feedback input pins. When using the feedback, it is usually also -required to specify the open and closing times of the used contactor. These times are expected in milliseconds and -used by the Safety Firmware to check after the given time whether the feedback pin has expected level. If the level -differs from the expectation, then Safety Firmware assumes a malfunction and thus enters safe state. +corresponding output pin and whether to monitor the feedback input pins. When using the feedback, it is also +required to specify the opening and closing times of the used contactor. These times are expected in milliseconds and +used by the safety firmware to check after the given time whether the feedback pin has the expected level. If the level +differs from the expectation, then the safety firmware assumes a malfunction and thus enters safe state. The example YAML file above shows all allowed variants how to parameterize a contactor. Possible values for the `type` are: @@ -118,11 +118,11 @@ Possible values for the `type` are: Since the open/close timings make no sense in case of `disabled` or `without-feedback`, it is possible to use these tokens directly as array item (actually, it is also possible to use the `with-feedback...` ones, but then the timings -are considered zero which will result in an error due to the latency in the contactor). +are considered zero which will result in an error due to the physical latency in the contactor). -Both `close-time` and `open-time` accept integer values in the range 0 to 2550 ms, however the given value is -divided by 10 before it is actually stored internally. -(This division by 10 is necessary because the safety controller operates with internal time slots of 10 ms.) +Both `close-time` and `open-time` accept integer values in the range 10 to 2550 ms. Internally, the +safety controller operates with time slots of 10 ms, so the last digit of the given integer is just discarded. +(In other words, the given integer is integer-divided by 10 before it is stored in the parameter block.) Emergency Input Configuration