> This page is for version 1.4.0 (Latest) (default). > For other versions, use one of these documentation indexes: > - 1.4.0 (Latest) (default): https://docs.nvidia.com/halos/outside-in-safety/1.4.0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/halos/outside-in-safety/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/halos/outside-in-safety/_mcp/server. # pss_protocol.h > Generated reference for pss_protocol.h: The safety messages and their vocabulary: SafetyEvent, DecisionRequest, event types, event causes, presence bits and the protocol schema version. The safety messages and their vocabulary: `SafetyEvent`, `DecisionRequest`, event types, event causes, presence bits and the protocol schema version. Part of the SEI client interface. Generated from the header published in `safety-core/`, release 1.3-26.07.5. The development packages install it in `/opt/nvidia/psf/include`. ```c #include "pss_protocol.h" ``` ## Types ### TrajectoryCoordinates ```c struct TrajectoryCoordinates ``` | Field | Declaration | Description | | ----- | ----------- | ----------- | | `x` | `float x` | | | `y` | `float y` | | ### EventFusionMetadata ```c struct EventFusionMetadata ``` Structure containing metadata for event fusion. | Field | Declaration | Description | | ------------- | --------------------------------------------------------------- | ----------- | | `coordinates` | `TrajectoryCoordinates coordinates[MAX_TRAJECTORY_COORDINATES]` | | | `pipelineID` | `uint8_t pipelineID` | | | `clientID` | `uint8_t clientID` | | | `objectType` | `ObjectType objectType[2]` | | | `speed` | `float speed` | | | `objectID` | `uint32_t objectID[2]` | | ### MessageIntegrity ```c struct MessageIntegrity ``` End-of-message integrity trailer for `SafetyEvent` and `DecisionRequest`. Must be the **last** member of every top-level wire struct. CRC-32 (ISO 3309 / IEEE, polynomial 0xEDB88320 reflected) is computed over all bytes of the enclosing struct from offset 0 up to, but not including, the crc32 field (i.e. sizeof(struct) - sizeof(uint32_t) bytes). | Field | Declaration | Description | | --------------- | ------------------------ | ----------- | | `schemaVersion` | `uint16_t schemaVersion` | | | `crc32` | `uint32_t crc32` | | ### SafetyEvent ```c struct SafetyEvent ``` Structure for safety event data with fusion support. | Field | Declaration | Description | | ------------------ | ----------------------------------------------- | ----------- | | `id` | `uint32_t id` | | | `sensorIdentifier` | `char sensorIdentifier[MAX_INDENTIFIER_LENGTH]` | | | `type` | `EventType type` | | | `timestamp` | `uint64_t timestamp` | | | `confidenceLevel` | `float confidenceLevel` | | | `processed` | `bool processed` | | | `fusionMetadata` | `EventFusionMetadata fusionMetadata` | | | `cause` | `EventCause cause` | | | `integrity` | `MessageIntegrity integrity` | | ### FusedSafetyEvent ```c struct FusedSafetyEvent ``` Structure for fused safety events from dual pipelines. | Field | Declaration | Description | | ------------------ | ----------------------------------------------- | ----------- | | `id` | `uint32_t id` | | | `sensorIdentifier` | `char sensorIdentifier[MAX_INDENTIFIER_LENGTH]` | | | `type` | `EventType type` | | | `cause` | `EventCause cause` | | | `severity` | `SeverityLevel severity` | | | `timestamp` | `uint64_t timestamp` | | | `confidenceLevel` | `float confidenceLevel` | | | `status` | `SafetyEventStatus status` | | | `fusionMetadata` | `EventFusionMetadata fusionMetadata` | | ### SensorData ```c struct SensorData ``` Structure for sensor data summary. | Field | Declaration | Description | | ----------------- | ------------------------ | ----------- | | `clientID` | `uint32_t clientID` | | | `isHealthy` | `bool isHealthy` | | | `isTrustedSource` | `bool isTrustedSource` | | | `event` | `FusedSafetyEvent event` | | ### SystemStatus ```c struct SystemStatus ``` Structure for system status. | Field | Declaration | Description | | ------------------- | ------------------------ | ----------- | | `hardwareErrorFlag` | `bool hardwareErrorFlag` | | | `softwareErrorFlag` | `bool softwareErrorFlag` | | | `mode` | `OperationalMode mode` | | ### DecisionRequest ```c struct DecisionRequest ``` Structure for decision request. | Field | Declaration | Description | | ----------------------- | ------------------------------------------------------------- | ----------- | | `requestId` | `uint32_t requestId` | | | `sensorDataSummarySize` | `uint8_t sensorDataSummarySize` | | | `sensorDataSummary` | `SensorData sensorDataSummary[MAX_SENSORS_DATA_SUMMARY_SIZE]` | | | `pssStatus` | `SystemStatus pssStatus` | | | `integrity` | `MessageIntegrity integrity` | | ### DecisionResponse ```c struct DecisionResponse ``` Structure for decision response. | Field | Declaration | Description | | ----------------- | -------------------------- | ----------- | | `decisionId` | `uint32_t decisionId` | | | `action` | `RecommendedAction action` | | | `confidenceLevel` | `float confidenceLevel` | | ### EventType ```c enum EventType ``` Enumeration for detected safety event type. | Value | Initializer | Description | | --------------------- | ----------- | ----------- | | `EVENT_0` | `0` | | | `EVENT_1` | | | | `EVENT_2` | | | | `EVENT_3` | | | | `EVENT_4` | | | | `EVENT_5` | | | | `EVENT_6` | | | | `EVENT_7` | | | | `EVENT_8` | | | | `EVENT_9` | | | | `EVENT_10` | | | | `EVENT_11` | | | | `EVENT_12` | | | | `EVENT_13` | | | | `EVENT_14` | | | | `EVENT_15` | | | | `EVENT_16` | | | | `EVENT_17` | | | | `EVENT_18` | | | | `EVENT_19` | | | | `EVENT_20` | | | | `EVENT_21` | | | | `EVENT_22` | | | | `EVENT_23` | | | | `SW_FAIL` | | | | `EVENT_UNKNOWN` | | | | `SENSOR_INVALID` | | | | `SENSOR_VALID` | | | | `AI_PIPELINE_INVALID` | | | | `AI_PIPELINE_VALID` | | | | `PSS_STATUS_NOOP` | | | ### RecommendedAction ```c enum RecommendedAction ``` | Value | Initializer | Description | | -------------------------- | ----------- | ----------- | | `ESTOP` | | | | `AUDIO_WARNING` | | | | `VISUAL_WARNING` | | | | `IMPLEMENT_SAFETY_CONTROL` | | | | `NO_ACTION_REQUIRED` | | | ### ObjectType ```c enum ObjectType ``` Enumeration for detected object type. | Value | Initializer | Description | | --------- | ----------- | ----------- | | `TYPE_0` | `0` | | | `TYPE_1` | | | | `TYPE_2` | | | | `TYPE_3` | | | | `TYPE_4` | | | | `TYPE_5` | | | | `TYPE_6` | | | | `PERSON` | | | | `VEHICLE` | | | | `OBJECT` | | | ### Enumeration: OPERATIONAL, CRITICAL ```c enum { OPERATIONAL, CRITICAL } ``` | Value | Initializer | Description | | ------------- | ----------- | ----------- | | `OPERATIONAL` | `0U` | | | `CRITICAL` | `1U` | | ### Enumeration: CAUSE_NONE, CAUSE_SAIM_INIT, CAUSE_SAIM_INPUT_DEGRADED, CAUSE_SAIM_INTERNAL_ERROR, CAUSE_SAIM_STREAM_DISCONNECT, CAUSE_SAIM_FRAME_DROP, CAUSE_SAIM_UNKNOWN, CAUSE_SAIM_SENSOR_HEALTHY, CAUSE_HEARTBEAT_FAULT, CAUSE_GATEWAY_SEQUENCE_GAP, CAUSE_PSS_REQUEST_SEQUENCE_GAP, CAUSE_PSS_REQUEST_ID_INVALID, CAUSE_PSS_ERROR, CAUSE_CLIENT_INPUT_UNUSABLE, CAUSE_PSS_COMM_RECOVERED, CAUSE_SAFETY_MONITOR_LOST, CAUSE_SOURCE_PRESENCE, CAUSE_PERCEPTION_MONITOR_LOST, CAUSE_MDX_CLIENT_LOST, CAUSE_COUNT ```c enum { CAUSE_NONE, CAUSE_SAIM_INIT, CAUSE_SAIM_INPUT_DEGRADED, CAUSE_SAIM_INTERNAL_ERROR, CAUSE_SAIM_STREAM_DISCONNECT, CAUSE_SAIM_FRAME_DROP, CAUSE_SAIM_UNKNOWN, CAUSE_SAIM_SENSOR_HEALTHY, CAUSE_HEARTBEAT_FAULT, CAUSE_GATEWAY_SEQUENCE_GAP, CAUSE_PSS_REQUEST_SEQUENCE_GAP, CAUSE_PSS_REQUEST_ID_INVALID, CAUSE_PSS_ERROR, CAUSE_CLIENT_INPUT_UNUSABLE, CAUSE_PSS_COMM_RECOVERED, CAUSE_SAFETY_MONITOR_LOST, CAUSE_SOURCE_PRESENCE, CAUSE_PERCEPTION_MONITOR_LOST, CAUSE_MDX_CLIENT_LOST, CAUSE_COUNT } ``` | Value | Initializer | Description | | -------------------------------- | ----------- | ----------- | | `CAUSE_NONE` | `0U` | | | `CAUSE_SAIM_INIT` | `1U` | | | `CAUSE_SAIM_INPUT_DEGRADED` | `2U` | | | `CAUSE_SAIM_INTERNAL_ERROR` | `3U` | | | `CAUSE_SAIM_STREAM_DISCONNECT` | `4U` | | | `CAUSE_SAIM_FRAME_DROP` | `5U` | | | `CAUSE_SAIM_UNKNOWN` | `6U` | | | `CAUSE_SAIM_SENSOR_HEALTHY` | `7U` | | | `CAUSE_HEARTBEAT_FAULT` | `8U` | | | `CAUSE_GATEWAY_SEQUENCE_GAP` | `9U` | | | `CAUSE_PSS_REQUEST_SEQUENCE_GAP` | `10U` | | | `CAUSE_PSS_REQUEST_ID_INVALID` | `11U` | | | `CAUSE_PSS_ERROR` | `12U` | | | `CAUSE_CLIENT_INPUT_UNUSABLE` | `13U` | | | `CAUSE_PSS_COMM_RECOVERED` | `14U` | | | `CAUSE_SAFETY_MONITOR_LOST` | `15U` | | | `CAUSE_SOURCE_PRESENCE` | `16U` | | | `CAUSE_PERCEPTION_MONITOR_LOST` | `17U` | | | `CAUSE_MDX_CLIENT_LOST` | `18U` | | | `CAUSE_COUNT` | | | ### OperationalMode ```c enum OperationalMode ``` | Value | Initializer | Description | | ---------- | ----------- | ----------- | | `NORMAL` | | | | `DEGRADED` | | | | `ERROR` | | | ### SafetyEventStatus ```c enum SafetyEventStatus ``` Enumeration for `SafetyEvent` Fusion status. | Value | Initializer | Description | | ------------- | ----------- | ----------- | | `FUSED` | | | | `PASSTHROUGH` | | | | `STALE` | | | | `UNKNOWN` | | | ### Type aliases | Name | Definition | Description | | --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SeverityLevel` | `typedef uint8_t SeverityLevel` | Fixed-width downstream event severity for PSS daemon-built `FusedSafetyEvent` entries. Client `SafetyEvent` messages do not carry severity. PSS daemon assigns one of these values when constructing `DecisionRequest` payloads for PSD/SDM routing. | | `EventCause` | `typedef uint8_t EventCause` | Why an event was reported, orthogonal to what it reports. `type` says what happened; `EventCause` says why. Fixed width for wire stability, following the same shape as SeverityLevel and SafetyEventStatus. On the failed-sensor path, exactly one value is not diagnostic. CAUSE_SAIM_INIT marks SAIM's pre-frame fail-safe seed, which every sensor emits during startup; SDMs leave the sensor's failed bit unchanged for it, so it does not contribute to the all-safety-relevant-sensors-failed latch. **Every other value that reaches that path, including one an SDM does not recognise, is treated as a genuine failure and latches.** That asymmetry is deliberate and fails closed. CAUSE_PSS_COMM_RECOVERED is not an exception to the rule above: it rides a PSS_STATUS_NOOP, and updateSensorHealthFromDecisionRequest() skips PSS_STATUS_NOOP outright, so it never reaches the failed-sensor path at all. ADDING A VALUE IS NOT FREE, despite what an earlier version of this comment claimed. It is safe for SDM *latch* logic an unrecognised cause latches. It is NOT safe for the *validator*: validateCommonEventFields() rejects cause >= CAUSE_COUNT against the RECEIVING build's bound, and a rejected `DecisionRequest` is dropped before freshness is refreshed. A peer built before the value existed therefore misses the fault the event carried and, if the condition repeats, latches on a spurious freshness timeout. Every validating runtime must be rebuilt together, which is already required for a release. CAUSE_NONE and CAUSE_SAIM_UNKNOWN are behaviourally identical both latch. They differ only in what they record: nothing set a cause, versus SAIM had a missing or contradictory one. Do not collapse them. | ## Macros | Macro | Value | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `MAX_SENSORS_DATA_SUMMARY_SIZE` | `8` | | | `MAX_TRAJECTORY_COORDINATES` | `10` | | | `MAX_INDENTIFIER_LENGTH` | `64` | | | `MAX_SUPPORTED_PIPELINES` | `8` | | | `PSS_SCHEMA_VERSION` | `5U` | Protocol schema version. Increment on any wire-incompatible change to `SafetyEvent`, `FusedSafetyEvent`, or `DecisionRequest`. v5: dropped ROI_ENTRY/ROI_EXIT/TW_CROSSING_ENTRY/TW_CROSSING_EXIT and added EVENT_23. Every enumerator from SW_FAIL onwards shifts down by 3, so a v4 peer reads `SW_FAIL(27)` as SENSOR_VALID and `SENSOR_INVALID(29)` as AI_PIPELINE_VALID a failure report seen as a health report, in the dangerous direction. The version check in validateSafetyEvent / validateDecisionRequest is the only thing that catches this, so it is the bump rather than the enum edit that makes the change safe: without it two incompatible layouts both stamp 4 and the check passes. All PSF components must therefore be rebuilt AND redeployed together. A peer built from v4 sources validates this field and will reject every request rather than act on a misread one. | | `PSS_PRESENCE_SAFETY_MONITOR` | `0x00000001U` | | | `PSS_PRESENCE_PERCEPTION_MONITOR` | `0x00000002U` | | | `PSS_PRESENCE_MDX_MASK` | `0x0000FF00U` | | | `PSS_PRESENCE_MDX_INSTANCE(k)` | `(((uint32_t)(k) >= 1U && (uint32_t)(k) <= 8U) ? (0x00000100U << ((uint32_t)(k) - 1U)) : 0U)` | | | `PSS_INPUT_ANONYMOUS_CLIENT` | `0x00000004U` | | | `PSS_INPUT_STATE_MASK` | `(PSS_PRESENCE_SAFETY_MONITOR \| PSS_PRESENCE_PERCEPTION_MONITOR \| \ PSS_INPUT_ANONYMOUS_CLIENT \| PSS_PRESENCE_MDX_MASK)` | | | `PSS_INPUT_STATE_SHIFT` | `16U` | |