pss_protocol.h | NVIDIA Halos Outside-In Safety Blueprint

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.

#include "pss_protocol.h"

Types

TrajectoryCoordinates

struct TrajectoryCoordinates

Field	Declaration	Description
`x`	`float x`
`y`	`float y`

EventFusionMetadata

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

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

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

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

struct SensorData

Structure for sensor data summary.

Field	Declaration	Description
`clientID`	`uint32_t clientID`
`isHealthy`	`bool isHealthy`
`isTrustedSource`	`bool isTrustedSource`
`event`	`FusedSafetyEvent event`

SystemStatus

struct SystemStatus

Structure for system status.

Field	Declaration	Description
`hardwareErrorFlag`	`bool hardwareErrorFlag`
`softwareErrorFlag`	`bool softwareErrorFlag`
`mode`	`OperationalMode mode`

DecisionRequest

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

struct DecisionResponse

Structure for decision response.

Field	Declaration	Description
`decisionId`	`uint32_t decisionId`
`action`	`RecommendedAction action`
`confidenceLevel`	`float confidenceLevel`

EventType

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

enum RecommendedAction

Value	Initializer	Description
`ESTOP`
`AUDIO_WARNING`
`VISUAL_WARNING`
`IMPLEMENT_SAFETY_CONTROL`
`NO_ACTION_REQUIRED`

ObjectType

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

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

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

enum OperationalMode

Value	Initializer	Description
`NORMAL`
`DEGRADED`
`ERROR`

SafetyEventStatus

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`