SEI Configuration (nvpss.conf)

The SEI daemon, nvpss_daemon, reads nvpss.conf once at startup. It never re-reads the file, so every change needs a daemon restart. This page lists every key the daemon accepts, which keys are mandatory, and exactly what happens when a value is missing or invalid.

When they start the control plane, the launchers read three of the same keys. deploymentMode selects the identity file of the MDX client. required_safety_monitor and required_perception_monitor are checked against the launcher’s --saim-mode and --pcm-mode. The launchers never change the file. See Monitor modes.

File location

The Debian package installs the shipped file at /opt/nvidia/psf/bin/nvpss.conf.

nvpss_daemon accepts only --conf <path> and -h/--help. Any other argument prints error: unexpected argument (see --help), and the daemon exits with status 1.

File format

• One key = value per line. Whitespace around the key, the = and the value is ignored.
• A line whose first non-blank character is # is a comment. Blank lines are ignored.
• A # after a value starts a comment, and the daemon ignores it. The launchers do not: they read deploymentMode with any trailing comment and then refuse it as unrecognised. Keep the deploymentMode line free of comments.
• Keys are case-sensitive. deploymentMode and enableFusion accept their values in either case.
• The daemon does not report unknown keys. A misspelt optional key is ignored, and its default applies.
• A non-comment line without =, or with an empty key, makes the whole file unreadable. The daemon prints Warning: Invalid config line (missing '='): <line> and Error parsing line <n>: <line>, then refuses to start.
• If a key appears more than once, the last line wins. The exceptions are deploymentMode, enableFusion, required_safety_monitor, required_perception_monitor and required_mdx_instances: for these five keys a repeat is fatal.

Key reference

The tables give the value in the shipped file and, for optional keys, the value the daemon uses when the key is absent (“Code default”). A mandatory key has no default: the daemon refuses to start without it.

Mandatory in every deployment

Mandatory when enableFusion = true

With enableFusion = false these keys are neither required nor read. If any of them is present, the daemon logs enableFusion=false: fusion-only keys present and ignored with the key names.

alpha + beta + gamma must be within 0.01 of 1.0. If it is not, the daemon logs Weight sum (alpha + beta + gamma = <sum>) should be close to 1.0; changing to default value and sets all three weights to 0.33. The daemon still starts, so check the log after you edit weights.

A fusion key whose value is not a number at all falls back to its code default (fusionThreshold 0.5, alpha 0.35, beta 0.45, gamma 0.20, temporalTolerance 5 ms), and the daemon prints Error: Invalid float value for key '<key>' or Error: Invalid milliseconds value for key '<key>'. For a value that starts with a number, the daemon reads the leading number and ignores the rest.

If fusion cannot be initialised with the final values, the daemon refuses to start with enableFusion=true but the fusion pipeline failed to initialise; refusing to start.

Optional fusion keys

These are read only when enableFusion = true.

Mandatory when deploymentMode = 3D

In 3D the daemon also refuses to start when any of these holds:

The shipped file has maxPipelines = 3, and the shipped camera list uses pipelineId 1 to 3. A 3D group therefore needs a fourth pipelineId, and maxPipelines must be raised to at least that value.

Optional, bounded

For these keys an empty value means “use the code default”. A value that is not a whole number is replaced by the code default, with the warning Invalid <key> value (expected integer <min>..<max>); using default <default>. A value outside the range is clamped to the nearest bound, with the warning <key> value <v> clamped to <bound>.

pss_to_psd_retry_budget × pss_to_psd_response_timeout_ms must not exceed 6000 ms. If it does, the daemon logs PSS-to-PSD retry window out of range; falling back to default retry budget and timeout and uses 3 attempts and 2000 ms.

Retired keys

Behaviour of the main settings

Required safety sources

required_safety_monitor, required_perception_monitor and required_mdx_instances declare which safety sources the deployment runs.

• Parsing. The value must be plain decimal digits (at most three) within the range. Anything else is fatal: <key> is defined more than once, <key> is not a plain decimal integer or <key> is out of range. stderr also shows the value and the accepted range.
• What the launchers do with them. The monitors are started by their launcher modes, --saim-mode and --pcm-mode, not by these keys. When launch_hoisa.sh or the container entrypoint starts the control plane, it reads required_safety_monitor and required_perception_monitor as strictly as the daemon does, and stops before starting anything unless each is 1 for a monitor in active and 0 for a monitor in learn or skip: Error: --<saim|pcm>-mode <mode> conflicts with <key> = <n> in <file>. A learning run, with no monitor in active and not both skipped, starts no daemon and does not read the file. The launchers never change the file.
• Tracking. The daemon tracks every monitor and every numbered MDX client instance that registers, required or not. If one stops (hang, crash, orderly exit or heartbeat loss), every SDM latches, and no release is accepted until that source is registered and heartbeating again.
• Never registered. A required source that has not registered within 6.5 s + (max_hb_failures − 1) × 5 s of daemon start is reported lost with reason=never_registered, and every SDM latches. With the shipped max_hb_failures = 50, that is about 4 minutes 12 seconds.

At startup the daemon logs a record containing PSS required sources, followed by the three values.

Heartbeat fail-safe

The daemon checks client heartbeats every 5 s. A client counts as stale once 6.5 s have passed since its last heartbeat, and each check while it is still stale adds one miss. Let M be max_hb_failures.

The SW_FAIL names the lost source: cause 15 for SAIM, 17 for PCM, 18 for an MDX client instance, and cause 8 for any other client. See Causes and records. Detection takes about 5 × M seconds after the last heartbeat: about 50 s at M = 10, and about 4 minutes at the shipped M = 50.

max_hb_failures also sets how long the daemon waits for a required source at startup (see above). The NvPSD Gateway has its own --max_hb_failures option for the SDM link, and does not read nvpss.conf.

Delivery to the NvPSD Gateway

The daemon sends each DecisionRequest up to pss_to_psd_retry_budget times and waits up to pss_to_psd_response_timeout_ms for each response. When every attempt fails, it logs PSS_TO_PSD_DELIVERY_FAILURE and marks the following requests ERROR. The gateway turns ERROR into a SW_FAIL with cause 12 for every SDM. The daemon returns to NORMAL only after an ERROR-marked request has been acknowledged, and then logs PSS_TO_PSD_DELIVERY_RECOVERED.

Status interval

Every status_noop_interval_ms the daemon sends a status DecisionRequest (PSS_STATUS_NOOP). It carries the source-presence report and re-sends every standing SENSOR_INVALID and AI_PIPELINE_INVALID verdict, so an SDM that restarts latches again within one interval. Each accepted request also refreshes the SDM’s decision-freshness timer, which defaults to 7000 ms. Keep the interval below that timeout, or every SDM latches whenever no events flow.

Staging queues

psd_operational_queue_depth and psd_critical_queue_depth size the queues in which events wait for delivery. Size them against the number of events one camera frame can produce, not against the event rate, because perception reports a burst of events for each frame. Each new high-water mark is logged as PSD_STAGING_QUEUE_HIGH_WATER. A DecisionRequest still carries at most 8 events, so these keys change only the daemon’s memory use, at about 261 bytes per slot.

When the critical queue is full, a fault or trust report displaces an event from a distrusted source. If there is nothing to displace, the daemon reports ERROR until the queue has drained to half its depth. The records it writes are listed in Causes and records.

Processing health and rejected reports

• fusion_failure_error_ms. A processing stage that fails once is only logged. A stage that fails without interruption for this long makes the daemon report ERROR, which the gateway forwards to every SDM as a SW_FAIL with cause 12.
• client_reject_error_threshold. A report is rejected for a bad CRC or schema, a client id that does not match the connection, a confidence below threshold, an unresolved sensor, or an unauthorised client type. After this many consecutive rejections from one required source, the daemon raises a SW_FAIL with cause 13 that names the source. An accepted report resets the count.

Startup failures

The daemon checks the file in this order and exits with status 1 at the first failure. Each failure is written to the SEI log and to stderr.

Other invalid values do not stop the daemon. It replaces them as described above and logs One or more configuration parameters were invalid; default or bounded values were applied (see prior messages).

When the daemon does not start, no client can register. The container entrypoint then stops with Error: Failed to start /opt/nvidia/psf/bin/nvpss_daemon, and launch_hoisa.sh --runtime host stops with Error: failed to start nvpss_daemon.

Where the messages appear

Startup records to check

After a change, confirm these records in the SEI log:

Examples

2D, as shipped

Comments are omitted.

max_hb_failures = 50
pss_to_psd_retry_budget = 3
pss_to_psd_response_timeout_ms = 2000
status_noop_interval_ms = 5000
psd_operational_queue_depth = 32
psd_critical_queue_depth = 32
fusion_failure_error_ms = 1000
client_reject_error_threshold = 50
required_safety_monitor = 1
required_perception_monitor = 1
required_mdx_instances = 1
deploymentMode = 2D
enableFusion = true
timeWindowSize = 400
fusionThreshold = 0.4
alpha = 0.4
beta = 0.4
gamma = 0.2
temporalTolerance = 10
trajectoryCount = 4
maxPipelines = 3
bypassFusionEvents = SW_FAIL
sensorConfig = /opt/nvidia/psf/bin/sensor_config.conf

3D (BEV)

Three cameras (pipelineId 1 to 3) form one group with pipelineId 4. Only the lines that differ from the 2D file are shown. The fusion keys can stay in the file: the daemon ignores them and names them in the log.

deploymentMode = 3D
enableFusion = false
sensorGroupConfig = /opt/nvidia/psf/bin/sensor_group_config.conf
maxPipelines = 4

A site without the Perception Monitor

required_perception_monitor = 0

Start the launcher with --pcm-mode skip; with this value it refuses --pcm-mode active. The daemon does not expect PCM. A PCM that registers anyway is still tracked: if it later stops, every SDM latches.

Tuning guidelines

These apply with enableFusion = true, except where noted.

• Latency. A smaller timeWindowSize (200–250 ms) shortens the correlation window. It also marks events stale sooner, in either fusion mode.
• Variable ingestion delay. A larger timeWindowSize (1000–5000 ms) stops events from a delayed source from being marked stale and dropped by the SDMs. This applies in either fusion mode.
• Fast objects or unsynchronised cameras. Raise temporalTolerance to 10–25 ms.
• Long, curved paths. Raise trajectoryCount to 6–8.
• Fewer false fusions in a well-calibrated multi-camera site: raise fusionThreshold to 0.70–0.80. Lower it to 0.35–0.45 to keep sensitivity, at the cost of more fused events.
• Weights. When you raise one of alpha, beta or gamma, lower another by the same amount, so that the sum stays within 0.01 of 1.0. Otherwise all three are reset to 0.33.
• Fault-detection time, in either fusion mode. A max_hb_failures of 3–5 detects a lost client in about 15–25 s, but is more sensitive to host load. A value of 30–100 tolerates stalls, but takes 2.5–8 minutes, and delays the never-registered check by the same amount.