Launchers and command-line options

The Safety Core is started in one of three ways:

The Deployment Guide starts the container directly, with the SDMs inside it; see Container options. launch_hoisa.sh runs the SDMs on the host instead; see What runs where.

Both launchers take the mode of each AI monitor on the command line, --saim-mode and --pcm-mode. When they start the control plane, they check those modes against required_safety_monitor and required_perception_monitor in nvpss.conf, and they read the deployment topology from deploymentMode. They never change nvpss.conf. See Monitor modes and SEI Configuration.

launch_hoisa.sh

sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode <learn|active|skip> --pcm-mode <learn|active|skip> [options]

Requirements

• Root or passwordless sudo. The launcher uses sudo -n to create /var/log/psf, its log files, the baseline directories of a learning monitor and /run/nvpsf, and to start the host processes of a control-plane run. Without it the launcher stops with Error: cannot create /var/log/psf; run as root or configure passwordless sudo.

• Docker access for --runtime docker (the default). A control-plane run checks that Docker is installed, that a docker group exists and that the user can reach the Docker daemon, and stops with Error: docker is not installed or not in PATH, Error: 'docker' group does not exist or Error: cannot connect to the Docker daemon (is the user in the 'docker' group?). A learning run checks only that Docker is installed.

• A readable nvpss.conf in a control-plane run, with deploymentMode, required_safety_monitor and required_perception_monitor. The launcher parses the two required-monitor keys as strictly as the daemon does, before it starts anything. A learning run does not read the file.

• /run/nvpsf, in a control-plane run. The launcher creates it if it is missing and sets mode 1777. It refuses a symlink and a directory it cannot write. Under --runtime docker the directory must also be writable by other users, because the container writes to it as a different user. A mode other than 1777 is a warning only.

• One primary group for every Safety Core process (see Shared process group). With --runtime host every connecting process runs as root. With --runtime docker the launcher starts the SDMs and fsicom-agent with the container user’s group; see Host processes and the container’s group. For that, a control-plane run with --runtime docker also needs:

  • setpriv, from util-linux, runnable through passwordless sudo, or the launcher stops with Error: 'sudo -n setpriv' is not available; install util-linux and allow setpriv for passwordless sudo, so host PSF processes can start with the container's group;
  • Docker without user-namespace remapping and not in rootless mode, or the launcher stops with Error: Docker user-namespace remapping/rootless mode is not supported: host PSF processes must share the container's GID. It reads this from docker info, and stops with Error: cannot read the Docker security options (docker info) if it cannot.

  The launcher checks both before it starts anything.

• Kernel socket buffers large enough for the gateway link. See Kernel socket buffers.

• For --sdm-target fsi: the FSI firmware flashed and the nvFsiCom daemon running. The launcher does not start nvFsiCom. See SDM on FSI.

Monitor modes

--saim-mode and --pcm-mode are both required, and each selects one monitor only.

The two modes together decide what kind of run it is:

Required sources. A monitor in learn or skip reports nothing to the SEI daemon, so the daemon must not require it. In a control-plane run the launcher checks:

A mismatch stops the launcher before anything starts, for example:

Error: --pcm-mode skip conflicts with required_perception_monitor = 1 in /opt/nvidia/psf/bin/nvpss.conf.
       Set required_perception_monitor = 0 for this mode, or select the mode matching the deployment's required sources.

A missing key gives Error: <key> is missing from <file>., a repeated key Error: <key> is defined more than once in <file>. Keep exactly one., and any value other than 0 or 1 Error: <key> = '<value>' in <file> is not 0 or 1. When the keys match, the launcher prints Required sources: safety_monitor=<n> perception_monitor=<n> (from <file>). To change what a site requires, edit the file named by --nvpss-conf; the launcher never rewrites it.

Missing or invalid mode. Error: --saim-mode is required and must be learn, active, or skip, or the same with --pcm-mode.

Options

“Applies to” names the runs in which the option has an effect. A control-plane run and a learning run are defined in Monitor modes.

Every option that takes a value rejects a missing value, or a value starting with --, with Error: <option> requires an argument. An unknown option prints Error: unknown option '<option>' and the usage text, and the launcher exits with status 1. An option ignored in a learning run prints a warning of the form Warning: <option> is ignored in learn mode.

The environment variables PCM_BASELINE_CONFIG (its directory part) and PCM_MONITOR_CONFIG, when set in the launcher’s environment, replace the defaults of --pcm-baseline-dir and --pcm-config.

Options with no effect

--gateway-ip and --gateway-port are parsed, and --gateway-port is range-checked, but neither value reaches any process. The NvPSD Gateway listens on no IP address or UDP port: every SDM connects to it through /run/nvpsf/nvpsd_gateway. A non-default value makes the launcher print a warning that mentions a “preflight UDP port check”; no such check runs. Leave both options out.

Applications

All the SDMs of one launch share one NvPSD Gateway and one MDX client. Any other value is refused with Error: unsupported app '<value>'. launch_hoisa.sh has no atl_proximity value; the combined forklift and proximity application is started through the container entrypoint only. Multi-SDM values are refused with --sdm-target fsi: Error: multi-SDM combinations support --sdm-target ccplex only.

SDM configuration files

Every CCPLEX ATL and Proximity SDM needs a configuration file that binds its situations to event codes. The package installs editable templates in /opt/nvidia/psf/bin/:

Copy a template, edit it, and pass the copy with --sdm-config. The event codes must match the output_event values of the mapping the MDX client runs. The launcher checks that each file is readable (Error: SDM <n> config '<path>' is not a readable file), that the list has one entry per SDM (Error: --sdm-config needs <n> value(s), in the same order as --app), and that two SDMs do not share an event code (Error: SDM configs overlap on EVENT_<n>; use distinct application event codes). The SDM binary validates the keys inside each file at startup; see Binary command lines. In a learning run with PCM, an unreadable file gives Error: PCM SDM config '<path>' is not readable.

What runs where

Under --runtime docker, a learning run starts one container in the foreground, with --rm, for both learning monitors, and the launcher returns when that container exits. A control-plane run starts the container in the background; the monitors start inside it after its control plane. Under --runtime host, a learning monitor needs write access to its baseline directory as the user running the launcher, or the launcher stops with Error: <SAIM|PCM> baseline dir '<dir>' is not writable for LEARN; grant write access or run LEARN under sudo.

Every host process that the launcher starts with sudo -n runs as root. Under --runtime host they run with group ID 0, and every connecting process is such a host process, so they all share one primary group. Under --runtime docker the processes in the container run as the container user nvidia, with that user’s group, and the launcher starts the SDMs and fsicom-agent on the host with that group; see Host processes and the container’s group.

Host processes and the container’s group

In a control-plane run with --runtime docker, once the container is running and before it starts any SDM or fsicom-agent, the launcher reads the group ID of the container user with docker exec <container-name> id -g nvidia and prints:

Host PSF processes run with the container's GID <gid> (user nvidia in <container-name>)

It then starts each SDM, or fsicom-agent, as sudo -n setpriv --regid <gid> --keep-groups -- env .... The process keeps root’s user ID and supplementary groups; only its primary group changes. --runtime host is unchanged: it starts the control plane, the SDMs or fsicom-agent, and a monitor in active with sudo -n env ..., and a monitor in learn as the user running the launcher. A learning run with --runtime docker starts no process on the host.

The launcher stops, and removes the container, before any host process starts, if it cannot use the group ID:

It then checks whether host accounts share the container user’s IDs, and warns without stopping:

Warning: GID <gid> of the Safety Core container is also used on this host by a group with <m> member(s) and as the primary group of <k> user(s).
         Accounts that can run with GID <gid> can connect to, or stand in for,
         the Safety Core sockets in /run/nvpsf. List them with: getent group <gid>; getent passwd | awk -F: '$4 == <gid>'
Warning: UID <uid> of the Safety Core container belongs to <j> host account(s).
         They own the Safety Core sockets in /run/nvpsf on this host and can
         delete them. List them with: getent passwd <uid>

The first warning names only the clauses that apply: a host group with the ID, users whose primary group it is, or both. A group count it cannot compute is shown as ?. If the user ID cannot be read, the launcher prints Warning: cannot read the UID of user nvidia in container <container-name>; UID overlap not checked. The warnings give counts and lookup commands, never account or group names. What the overlap allows, and how to remove it, is described in Host accounts with the container’s group.

In a control-plane run the launcher starts, in order: the container (or, with --runtime host, the SEI daemon, then the NvPSD Gateway, then the MDX client), the SDMs or fsicom-agent, and, with --runtime host, the monitors that are not skipped. It waits 1 s after each SDM and each host control-plane process and stops with Error: failed to start <process> if the process has already exited. It waits 2 s after starting the container and stops with Error: Docker container <name> failed to start, followed by the container’s output, if the container is no longer running. Under --runtime docker it then prints Monitors run inside <name>: SAIM=<mode>, PCM=<mode>. A host monitor prints <SAIM|PCM> started in <LEARN|ACTIVE> mode with PID <pid>, or Skipping <SAIM|PCM> (--<saim|pcm>-mode skip). The MDX client is started as instance 1. In 2D it gets the camera list; in 3D it gets the reviewed sensor set.

With --sdm-target fsi the launcher starts fsicom-agent as:

fsicom-agent --heartbeat --relay-fsi-resp --ip <cmd-rx-ip> --port <cmd-rx-port> \
    --cmd-identifier <0xA2 for atl, 0xA5 for pxc>

What it mounts into the container

Control-plane run, --runtime docker:

The container arguments are --app <app>, then, for ATL and Proximity applications, --sdm-external --cmd_rx_port <ports>, then --cmd_rx_ip <ip>, --sensor-config /opt/nvidia/psf/bin/sensor_config.conf, --saim-mode <mode> --pcm-mode <mode> --learn-duration <seconds>, plus --event-mapping, --sdm-config, --broker, --pcm-baseline-dir, --baseline-dir and --gpu when they apply. SAIM and PCM therefore do not cross the container boundary; the SDMs and fsicom-agent on the host do, through /run/nvpsf, with the container user’s group (see Host processes and the container’s group).

Learning run, --runtime docker: the launcher runs the container in the foreground with --rm, and --network=host. For a learning SAIM it adds the GPU arguments above, the camera list, the SAIM baseline directory (writable) and saim.log. For a learning PCM it adds the PCM baseline directory (writable) and pcm.log, and, when PCM records event bindings, the event mapping as /opt/nvidia/psf/bin/pcm_event_mapping.pb.txt and each SDM configuration as /opt/nvidia/psf/bin/pcm_sdm_<n>.conf, all read-only. It passes --saim-mode <mode> --pcm-mode <mode> --learn-duration <seconds> and the matching container paths. A learning run mounts neither nvpss.conf nor the Docker socket, and prints Launching learners: SAIM=<mode>, PCM=<mode> (Docker).

The container does not receive sensor_pipelines_config.conf or the 3D sensor group file. See Known Limitations.

Logs

All files are under /var/log/psf/. The launcher creates psf.log and the SDM logs in a control-plane run, and saim.log and pcm.log for each monitor that is not skipped, all with mode 0666. SAIM and PCM output is appended to saim.log and pcm.log across runs.

With --runtime docker, docker logs <container-name> also shows the container’s syslog stream and the console output of every process in the container, including SAIM and PCM. The launcher removes the container when it stops, and its output with it; the files above remain.

Supervision, shutdown and exit status

While a control-plane run is up, the launcher checks every 2 s that each host process and each host monitor is alive and, under --runtime docker, that the container is still running. The first failure stops the run:

A learning monitor that exits with status 0 prints <SAIM|PCM> completed LEARN successfully and the run continues. A host learning run that succeeds prints All selected monitors completed LEARN successfully.

SIGINT (Ctrl-C) or SIGTERM stops the host monitors and every host process with SIGTERM, waits up to 10 s, sends SIGKILL to any that remain, then stops and removes the container. The launcher prints Cleanup complete last.

Default baselines (running active mode without learn)

SAIM. The package installs three SAIM baseline templates in /opt/nvidia/psf/bin/saim_baseline, tuned for the loading-dock reference scene: Camera_baseline.cfg.default, Camera_01_baseline.cfg.default and Camera_02_baseline.cfg.default.

In active mode SAIM looks, for each camera, for <sensorName>_baseline.cfg in its working directory (the baseline directory). If that file is missing, it uses <sensorName>_baseline.cfg.default and prints Notice: baseline '<file>' not found for sensor '<name>'; falling back to default '<file>.default'. If neither exists, SAIM stops with Error: baseline file '<file>' (or '<file>.default') not found for sensor '<name>'. The fallback matches sensorName exactly, so a site whose camera names differ from the three above must learn SAIM baselines. The templates were learned at 1920×1080, so they also need cameras of that size, and they are tied to the release: under the Docker runtime the container reads the host’s templates, so install the package of the same release as the image.

When SAIM is active, the launcher checks, before it starts anything, that the baseline directory holds at least one *_baseline.cfg or *_baseline.cfg.default file: Error: no SAIM baselines found in '<dir>'; run --saim-mode learn first. The container entrypoint checks again before it starts SAIM: Error: no SAIM baselines (*_baseline.cfg or *_baseline.cfg.default) found in '<dir>'.

PCM. A learning PCM writes one pcm_baseline.cfg into --pcm-baseline-dir. Besides the cameras it saw on mdx-frames and their timing, the file records the decision contract: the ROI and proximity rules of the event mapping that the SDM configurations select. With --app but no SDM configuration, as for --sdm-target fsi, PCM records every rule of the application’s mapping. With none of --app, --sdm-config and --event-mapping, it records cameras and timing only.

An active PCM compares the recorded contract with the contract of its own run and does not use a baseline whose contract differs, logging DVM: decision mapping changed for <camera>; baseline not used, re-run LEARN. When the run has a contract, as an ATL or Proximity application does, a pcm_baseline.cfg record learned without one is not used either; older per-camera baseline files are still used. With no usable baseline PCM runs without its data check; it does not report the AI pipeline invalid for this. Learn PCM baselines with the same --app, --sdm-config (or --atl-zone*-conf) and --event-mapping as the active run.

The package installs reference templates in /opt/nvidia/psf/bin/pcm_baseline: pcm_Camera_baseline.cfg.default, pcm_Camera_01_baseline.cfg.default and pcm_Camera_02_baseline.cfg.default. They were learned on the loading-dock reference scene with proximity_event_mapping.pb.txt, atl_sdm_zone1.conf and pxc_sdm_forklift.conf, so they fit --app atl,pxc with unchanged copies of those two configurations, on the reference cameras, and only while no learned pcm_baseline.cfg is in the directory. Any other application needs a learning run. How PCM chooses between the learned file and the templates is described in Perception Monitor.

PCM logs what it loaded at startup, as DVM: baseline loaded, cameras=<n>, decision-data profiles=<n> (from <dir>) and checks: container_health=<on|off> (...) data_validation=<on|off> (...).

Examples

Learn both monitors in the container, then run the forklift safety function with the control plane and the monitors in the container and the SDM on the host:

sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode learn --pcm-mode learn --app atl \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
    --docker-image nvcr.io/nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-6b92731 \
    --learn-duration 300
sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode active --pcm-mode active --app atl \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
    --docker-image nvcr.io/nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-6b92731 \
    --cmd-rx-ip <cmd-rx-ip> --cmd-rx-port 12345

The same run with every process on the host:

sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode active --pcm-mode active --runtime host --app atl \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
    --cmd-rx-ip <cmd-rx-ip> --cmd-rx-port 12345

Forklift safety function and Proximity Monitoring together, on the host. On the reference cameras, with unchanged copies of the templates and no learned pcm_baseline.cfg, PCM uses the reference baselines:

sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode active --pcm-mode active --runtime host --app atl,pxc \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf,/opt/nvidia/psf/bin/pxc_sdm_forklift.conf \
    --cmd-rx-ip <cmd-rx-ip> --cmd-rx-port 12345,12346

Forklift safety function with the SDM on the FSI, on the host:

sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode active --pcm-mode active --runtime host --app atl --sdm-target fsi \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --cmd-rx-ip <cmd-rx-ip> --cmd-rx-port 12345

Forklift safety function without PCM, on the host, where <nvpss-conf> is a copy of nvpss.conf with required_perception_monitor = 0:

sudo /opt/nvidia/psf/bin/launch_hoisa.sh --saim-mode active --pcm-mode skip --runtime host --app atl \
    --nvpss-conf <nvpss-conf> \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
    --cmd-rx-ip <cmd-rx-ip> --cmd-rx-port 12345

<cmd-rx-ip> is the address of the host running the command receiver. The configuration files named here are copies of the .sample templates.

Container options

The Safety Core image runs tini, then an entrypoint that starts cron and rsyslog as root, then runs /opt/nvidia/psf/bin/launch_psf.sh as the container user nvidia with the arguments given to docker run.

Container environment

Every process in the container runs as the container user nvidia, with that user’s primary group. Its group ID is set when the image is built; read it with docker run --rm --entrypoint id nvcr.io/nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-6b92731 -g nvidia. A Safety Core process on the host that connects to the container (fsicom-agent with --sdm-on-fsi, or the SDMs with --sdm-external) must run with that group ID as its primary group, for example sudo setpriv --regid <gid> --keep-groups -- <command>, and the container must mount the host’s /run/nvpsf with -v /run/nvpsf:/run/nvpsf. See Shared process group.

Options

An unknown option prints Error: Unknown option '<option>' and the usage text, and the container exits with status 1. The container has no --mode option.

The entrypoint has no option for these files. Mount your own copy over the path in the image:

Container applications

In a control-plane run the entrypoint reads deploymentMode from /opt/nvidia/psf/bin/nvpss.conf and checks required_safety_monitor and required_perception_monitor against the monitor modes, as described in Monitor modes, before it starts anything. In 3D it checks that /opt/nvidia/psf/bin/sensor_pipelines_config.conf is readable. A learning run reads neither file and starts only the learning monitors.

The SDMs started in the container get --decision_interval_ms 0. The MDX client is started as instance 1, with --sensor-config in 2D or with --sensor-pipelines-config /opt/nvidia/psf/bin/sensor_pipelines_config.conf in 3D.

PCM is started with --baseline-config <pcm-baseline-dir>/pcm_baseline.cfg, with --kafka-broker when --broker is given, and, for the ATL and Proximity applications and in a learning run that has them, with the event mapping and each SDM configuration. A PCM in active reaches the host’s Docker daemon through /var/run/docker.sock when it is mounted. The switch to the nvidia user drops the groups that docker run --group-add adds, so when that user cannot read and write the socket, the entrypoint starts PCM with the socket’s group added (sudo -n setpriv ... --groups <groups>,<socket gid>). Without the socket mount, PCM’s container check stays off and PCM logs Docker socket unreachable; container health is NOT checked until Docker answers again.

The entrypoint supervises what it started. If a control-plane process exits, or a monitor fails as described in Supervision, shutdown and exit status, it stops the others (SIGTERM, then SIGKILL after 10 s) and the container exits with status 1. In a learning run it prints All selected monitors completed LEARN successfully and exits with status 0 when every learning monitor succeeded.

Inside the container, SAIM output goes to /var/log/psf/saim.log and PCM output to /var/log/psf/pcm.log, and both also to the container output. The SDMs started in the container write their own logs to /var/log/psf/<app>_sdm.log. The syslog records of the SEI daemon, the NvPSD Gateway and the MDX client go to /var/log/psf/psf.log. Everything also appears in docker logs <container>.

Plain docker run examples

Forklift safety function with the SDM, SAIM, PCM and the control plane in the container, on x86-64. Every Safety Core process then runs with the container user’s group, so the container needs no /run/nvpsf mount:

docker run -d --name nv-psf --network=host --gpus all \
    -e NVIDIA_DRIVER_CAPABILITIES=compute,utility,video \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /opt/nvidia/psf/bin/sensor_config.conf:/opt/nvidia/psf/bin/sensor_config.conf:ro \
    -v /opt/nvidia/psf/bin/nvpss.conf:/opt/nvidia/psf/bin/nvpss.conf:ro \
    -v /opt/nvidia/psf/bin/atl_sdm_zone1.conf:/opt/nvidia/psf/bin/atl_sdm_zone1.conf:ro \
    -v /opt/nvidia/psf/bin/pcm_monitor.cfg:/opt/nvidia/psf/bin/pcm_monitor.cfg:ro \
    -v /opt/nvidia/psf/bin/saim_baseline:/opt/nvidia/psf/bin/saim_baseline:ro \
    -v /opt/nvidia/psf/bin/pcm_baseline:/opt/nvidia/psf/bin/pcm_baseline:ro \
    nvcr.io/nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-6b92731 \
    --app atl --saim-mode active --pcm-mode active \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
    --cmd_rx_ip <cmd-rx-ip> --cmd_rx_port 12345

The PCM baselines in the mounted directory must have been learned with the same --app and --sdm-config. To learn them with the container, run it in the foreground; it exits when both monitors have finished:

docker run --rm --name nv-psf-learn --network=host --gpus all \
    -e NVIDIA_DRIVER_CAPABILITIES=compute,utility,video \
    -v /opt/nvidia/psf/bin/sensor_config.conf:/opt/nvidia/psf/bin/sensor_config.conf:ro \
    -v /opt/nvidia/psf/bin/atl_sdm_zone1.conf:/opt/nvidia/psf/bin/atl_sdm_zone1.conf:ro \
    -v /opt/nvidia/psf/bin/saim_baseline:/opt/nvidia/psf/bin/saim_baseline \
    -v /opt/nvidia/psf/bin/pcm_baseline:/opt/nvidia/psf/bin/pcm_baseline \
    nvcr.io/nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-6b92731 \
    --saim-mode learn --pcm-mode learn --learn-duration 300 --app atl \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf

On aarch64, replace --gpus all with --runtime nvidia -e NVIDIA_VISIBLE_DEVICES=all. The entrypoint gives SAIM the groups of the GPU and PVA device nodes itself, so --group-add is not needed. Add --broker <host:port> to either command when Kafka is not at localhost:9092. Follow the output with docker logs -f nv-psf. The mounted nvpss.conf must require the monitors that run, as described in Monitor modes.

Logs on the host. Without a log mount the logs stay in the container and are lost when it is removed. To keep them, add -v /var/log/psf:/var/log/psf, and first create on the host every log file the container writes, with mode 666: psf.log, saim.log and pcm.log, and each SDM log (see Applications). The container user can write to those files but cannot create files in the host directory; a missing file stops the container with Error: monitor log is not writable: /var/log/psf/<saim|pcm>.log or Error: cannot create SDM log '<file>'. Quick Deployment uses this mount.

A process on the host. With --sdm-on-fsi or --sdm-external, add -v /run/nvpsf:/run/nvpsf and start the process on the host as described in Container environment. The procedures are in Decision maker on the host and SDM on FSI.

fsicom-agent

fsicom-agent runs on the CCPLEX when the SDM runs on the Functional Safety Island. It connects to the NvPSD Gateway like an SDM, forwards each DecisionRequest to the FSI over the FSI communication channel, and relays the FSI SDM’s commands to the command receiver over UDP. It is installed by the psf-tegra-fsi package at /opt/nvidia/psf/bin/fsicom-agent, and must run as root with the nvFsiCom daemon already running.

sudo /opt/nvidia/psf/bin/fsicom-agent --heartbeat --relay-fsi-resp \
    --ip <cmd-rx-ip> --port <cmd-rx-port> --cmd-identifier <0xA2|0xA5>

fsicom-agent accepts both --option value and --option=value.

--gw-transport, --gw-socket, --gw-ip and --gw-port are retired. Passing one prints an “unrecognized option” error and the usage text, and the agent exits with status 1. The link to the NvPSD Gateway is always /run/nvpsf/nvpsd_gateway.

Behaviour.

• Gateway link. If the gateway is not up yet, the agent logs [GW] Awaiting NvPSDGateway (UNIX_SOCKET)... and retries every 500 ms without limit, so it can start before or after the Safety Core. It registers for EVENT_0 to EVENT_23 and SW_FAIL, and re-registers every 30 s. A refusal is logged once per reason: [GW] The gateway refused this agent's registration; reason=<reason> -- not registered, no decisions will reach the FSI SDM.
• Gateway heartbeat. If no gateway heartbeat arrives for 8 s, the agent logs [GW-WD] PSDGateway heartbeat lost for <ms> ms. It takes no other action; the FSI SDM detects the loss through its own decision-freshness check.
• Command receiver. With --relay-fsi-resp, the agent sends a heartbeat command to the receiver every 5 s. It forwards a safe-release request to the FSI only when the request comes from the exact --ip and --port, carries the --cmd-identifier, and has a valid CRC, and at most once per second.
• Socket buffers. The agent’s gateway socket needs net.core.rmem_max and net.core.wmem_max of at least 5283840 bytes. While they are lower, every connection attempt fails with nvpsf_transport: SO_RCVBUF granted <n> bytes but <m> are required ...; raise net.core.rmem_max, and the agent keeps retrying.
• FSI channel. The device tree must have the nvidia,tegra-fsicom-bufdemo-10k node with channelid_list = <6>; otherwise the agent stops with [ERROR] Reading channel configuration failed. If FSI communication cannot be initialised, the agent prints [ERROR] FSI COM initialization failed: <code> with hints and stops. When nvFsiCom is not running, the agent does not get past [INIT] Initializing FSI communication....

A healthy start prints these lines, in order:

[INIT] ✓ FSI communication initialized
[TRANSPORT] gateway upstream: UNIX_SOCKET
[GW] Connected to gateway 127.0.0.1:50000 — link established (first packet received)
[HB] First keepalive received (seq=<n>) — FSI heartbeat link up
[HB] First pong received (seq=<n>) — FSI responding to pings

The address in the [GW] Connected to gateway line is a leftover and is not used: the link is the local socket.

The agent logs to stdout and stderr only. launch_hoisa.sh appends both to the first SDM log (atl_sdm.log or pxc_sdm.log). The SDM on the FSI logs to the FSI UART; use the tcu_muxer utility to find its device node.

Binary command lines

All binaries except fsicom-agent take options only in the form --option value: --option=value is rejected as an unknown option. Each binary prints its usage text with -h or --help, except safety_monitor, which has no help option.

nvpss_daemon (SEI)

Any other argument: error: unexpected argument (see --help), exit status 1.

nvpsd_gateway (NvPSD Gateway)

All options are optional. Both launchers start the gateway with none, so the defaults apply.

--transport, --sdm_socket, --sdm_ip, --sdm_port and --sdm_allow are retired: they get error: unknown option (see --help) and exit status 1. A missing or out-of-range value prints an error: line and exits with status 1. The gateway opens no TCP or UDP port; SDMs connect to /run/nvpsf/nvpsd_gateway. At startup it connects to the SEI daemon (60 attempts, 500 ms apart) and exits with status 1 if that fails.

mdx_client (MDX client)

Giving both -s and -g prints error: -s/--sensor-config and -g/--sensor-pipelines-config are mutually exclusive; supply exactly one. Giving neither prints error: a sensor identity file is required: -s/--sensor-config for 2D, or -g/--sensor-pipelines-config for 3D/BEV. Both exit with status 1. The client logs to syslog with the tag nv_mdx_client. If 10 consecutive heartbeats to the SEI daemon fail (about 50 s), it logs PSS heartbeat ACK failure limit reached — PSS presumed dead, exiting and exits.

atl_sdm (forklift safety function)

The --config file is validated strictly: a missing, repeated, unknown or invalid key stops the SDM with error: --config <path>: <reason>. A safety_pipelines line from an earlier release is rejected by name; the reviewed sensor set comes from --sensor_pipelines_config. --events is retired and rejected by name. --gateway_ip and --gateway_port are not accepted (error: unknown option (see --help)). Command-line errors exit with status 1; a startup failure after parsing (for example an unloadable reviewed sensor set) exits with status 255.

proximity_sdm (Proximity Monitoring)

proximity_sdm takes the same options as atl_sdm, with these differences:

atl_proximity_sdm (forklift safety function with forklift–person proximity)

Started only by the container entrypoint with --app atl_proximity, next to an atl_sdm. It takes no --config, --log_file or instance option, and always logs to atl_proximity_sdm.log in its working directory.

Command receivers

atl_sdm_cmd_receiver, proximity_sdm_cmd_receiver and atl_proximity_sdm_cmd_receiver are the reference PLC endpoints. They take the same options:

• Heartbeat watchdog. The receiver counts a miss once 5 s pass without an SDM heartbeat, and one more every 5.5 s after that. At --max_hb_failures misses (about 54.5 s at 10) it prints cmd_rx: upstream CMD_HEARTBEAT fault latched (tier 3) — local fail-safe, no PSS — stopping and exits with status 0. The watchdog starts when the receiver starts, so a receiver whose SDM never comes up also stops.
• Release on first contact. 500 ms after the first valid packet from the SDM, the receiver sends one safe-release request, logged as Startup: peer connected — sending safe-release to clear any pre-existing latch. The SDM still denies it while a fault is active.
• Interactive release. After the SDM reports a latched safe state, typing release (or r, safe-release, y, yes) sends a safe-release request.
• If the receiver cannot bind its port, it prints Error binding socket: <error> and exits with status 0.

safety_monitor (SAIM)

SAIM reads and writes its baselines as <sensorName>_baseline.cfg in its working directory; see Default baselines. The accelerator backend is fixed at build time: the GPU on x86-64, and the PVA in the shipped aarch64 build. SAIM tries to register with the SEI daemon 6 times, 5 s apart, then exits with Failed to register with PSS daemon after 6 attempts. Exiting. It logs to stdout and stderr only. An unknown argument prints Error: unknown argument: <argument>, and SAIM exits with status 1.

nv_perception_monitor (PCM)

In active mode PCM reads /opt/nvidia/psf/bin/pcm_monitor.cfg (or $PCM_MONITOR_CONFIG), whose [monitors] section enables container_health and data_validation. Both are on by default. PCM reaches Docker through /var/run/docker.sock. It registers with the SEI daemon in 6 attempts, 5 s apart, and exits if that fails. An argument error, an unusable pcm_monitor.cfg in active mode, or an event mapping or SDM configuration it cannot use exits with status 2. PCM logs to stdout and stderr only, as lines starting [<date> <time>] [PCM][INFO|WARNING|ERR]; both launchers copy both streams to /var/log/psf/pcm.log. The checks and the configuration keys are on Perception Monitor.