HOISA Launcher Script - `launch_hoisa.sh`#

1. Overview#

launch_hoisa.sh is the reference launcher for the full HOISA Safety Core stack. It orchestrates:

The Safety Core Docker container (running the NvPSD Gateway, the SEI daemon, and the event-ingestion pipeline).
The Safety Decision Maker on the host — either the CCPLEX SDM binary (atl_sdm / proximity_sdm) or the fsicom-agent bridge when SDM is offloaded to the FSI.
The Safety AI Monitor (safety_monitor) on the host in either LEARN or ACTIVE mode.

It also prepares the filesystem state the stack depends on — the /var/log/psf/ log directory, the runtime IPC directory used for host ↔ container communication, the threshold configuration at a stable well-known path, and the bind-mount of nvpss.conf into the container.

The launcher is installed by the psf-desktop / psf-tegra Debian packages at:

/opt/nvidia/psf/bin/launch_hoisa.sh

The recommended execution directory is /opt/nvidia/psf/bin. SAIM baseline files are created and read relative to the launcher’s process working directory, so run the script from that directory:

cd /opt/nvidia/psf/bin
sudo ./launch_hoisa.sh ...

2. Operating Modes#

The launcher has three mutually exclusive modes selected via --mode <learn|active|skip>:

launch_hoisa.sh modes#
Mode	What runs	When to use
learn	`safety_monitor` only, in `LEARN` mode.	One-time baseline-learning pass. Installs the supplied threshold config to `/opt/nvidia/psf/bin/thresholds.cfg` so subsequent `active` runs pick it up automatically. Run from `/opt/nvidia/psf/bin` so baseline files are written to the expected directory.
active	Safety Core container + host SDM + `safety_monitor` (ACTIVE).	Full production stack. Default deployment. Reads the SAIM baseline files from the launcher working directory.
skip	Safety Core container + host SDM. No SAIM.	AI-trust path validated separately, or no GPU/decoder budget available for SAIM. Useful for event-ingestion-only deployments.

3. Command-Line Interface#

3.1 Required Arguments#

Argument	Description
`--mode <learn\|active\|skip>`	Operating mode (see Section 2).
`--sensor-config <file>`	Sensor configuration file in CSV form (`pipelineId, sensorName, rtspUrl` — one sensor per line). Consumed by `safety_monitor` and, in `active` / `skip` modes, bind-mounted into the Safety Core container. Each `rtspUrl` must be directly playable by `ffprobe` or `gst-launch-1.0`; VST registration or online status alone does not prove the stream is usable by HOISA.

3.2 Arguments Required in `active` / `skip` Modes#

Argument	Description
`--app <atl\|pxc>`	Application flavor. `atl` = forklift safety function control; `pxc` = proximity monitoring. Default: `atl`.
`--docker-image <image:tag>`	Fully-qualified image reference for the Safety Core container.
`--cmd-rx-ip <ip>`	IP address of the SDM command receiver (PLC or reference command receiver application).
`--cmd-rx-port <port>`	UDP port of the SDM command receiver.

3.3 Optional Arguments#

Argument	Default	Description
`--sdm-target <ccplex\|fsi>`	`ccplex`	`ccplex` launches the CCPLEX SDM binary on the host. `fsi` launches `fsicom-agent` instead; the SDM itself runs on the Functional Safety Island (see Section 5).
`--threshold-config <file>`	`/opt/nvidia/psf/bin/thresholds.cfg`	SAIM threshold configuration. In `learn` mode, if the file is not already at the default path, the launcher installs it there. In `active` mode, the launcher reads the default path unless overridden.
`--learn-duration <seconds>`	300	LEARN-mode duration. Accepted range: `[1, 3600]`.
`--gpu <id>`	unset	Pin all SAIM streams to this GPU index. Without this flag, SAIM distributes streams across visible GPUs.
`--kafka-broker <address>`	unset	Kafka broker endpoint for the event-ingestion client inside the container. Meaningful only in `active` / `skip` modes.
`--container-name <name>`	`nv-psf`	Docker container name. Change when running multiple instances side-by-side.
`--decision_interval_ms <ms>`	0 (off)	CCPLEX-SDM periodic decision-repeat interval in milliseconds. `0` disables periodic repeats (decisions remain event-driven). Non-zero values must be in `[100, 36000]`. Not applicable when `--sdm-target fsi`.
`--nvpss-conf <file>`	`/opt/nvidia/psf/bin/nvpss.conf`	Host path to the SEI daemon configuration. Bind-mounted read-only into the container. Use this to point at a per-site variant without editing the default.
`-h`, `--help`	—	Show the inline usage banner and exit.

Note

In learn mode, arguments that apply only to active / skip (--docker-image, --cmd-rx-ip, --cmd-rx-port, --kafka-broker, --sdm-target, --decision_interval_ms, --nvpss-conf) are accepted but ignored, and the launcher emits a “Warning: … is ignored in learn mode” line for transparency.

4. Runtime State and Logs#

4.1 Logs#

All logs are written to /var/log/psf/:

File	Contents
`/var/log/psf/psf.log`	Safety Core container components (gateway, SEI daemon, event-ingestion client).
`/var/log/psf/saim.log`	`safety_monitor` (LEARN or ACTIVE).
`/var/log/psf/atl_sdm.log`	ATL SDM (`--app atl`).
`/var/log/psf/pxc_sdm.log`	Proximity SDM (`--app pxc`).

To follow logs live:

tail -f /var/log/psf/psf.log
tail -f /var/log/psf/saim.log
tail -f /var/log/psf/atl_sdm.log   # or pxc_sdm.log

4.2 Privilege Requirements#

The launcher must be run as root, or the invoking user must have sudo privileges for the launcher. Elevated privileges are required to prepare the runtime log and IPC directories and to launch the host-side SDM / SAIM processes.

Membership in the docker group is additionally required to launch the Safety Core container (active / skip modes).

5. SDM on FSI#

When --sdm-target fsi is supplied, the launcher does not start the CCPLEX SDM binary. Instead it starts fsicom-agent on the CCPLEX, which bridges the FSI-hosted SDM to the NvPSD Gateway.

Prerequisites (unchanged from the manual deployment flow — see Safety Core Guide §2.2.2 / §2.3.2):

IGX-Thor BSP + Safety Extension Package flashed on the target.
HOISA-specific FSI firmware reflashed onto the FSI.
nvFsiCom daemon running on the CCPLEX. The launcher does not start nvFsiCom; it must be started before launch_hoisa.sh.

Example:

cd /opt/nvidia/psf/bin
sudo /opt/nvidia/ccplex_sf/fsi_ccplex_com/nvFsiCom &

sudo ./launch_hoisa.sh --mode active --app atl --sdm-target fsi \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --docker-image <PSF_DOCKER_IMAGE> \
    --cmd-rx-ip <IP> --cmd-rx-port <Port>

SDM logs are observable on the FSI UART shell (use tcu_muxer to discover the device node). /var/log/psf/atl_sdm.log / pxc_sdm.log carry only the fsicom-agent bridge output in this mode.

Note

--decision_interval_ms is applicable only to the CCPLEX SDM binary. The launcher warns if a non-default value is combined with --sdm-target fsi.

6. SEI Daemon Configuration (`nvpss.conf`)#

The SEI daemon reads its configuration from nvpss.conf. The launcher bind-mounts the host’s nvpss.conf read-only into the container so operator edits on the host are authoritative without rebuilding the image.

Default host source: /opt/nvidia/psf/bin/nvpss.conf (populated by the Debian package).
Override: --nvpss-conf /etc/psf/site-a/nvpss.conf to use a per-site variant without editing the default file.

The launcher validates that the host file exists and is readable before starting the container.

Full parameter reference: see Safety Event Integrator - Configuration.

7. Shutdown and Exit Status#

Sending SIGINT (Ctrl-C) or SIGTERM to the launcher triggers a graceful shutdown of all managed processes followed by removal of the Safety Core container. Any process that does not exit gracefully within a short grace period is force-terminated.

Exit codes:

0 — normal shutdown via Ctrl-C / SIGTERM.
1 — configuration or prerequisite validation failure, or one of the supervised processes died unexpectedly.
130 — process interrupted by SIGINT.
143 — process terminated by SIGTERM.

8. Troubleshooting#

8.1 Permission error preparing `/var/log/psf`#

The invoking user does not have the privileges required to create the log directory. Re-run the launcher as root, or configure sudo for the invoking user.

8.2 Safety Core container fails to start#

The launcher dumps the container’s initial logs to stderr. Common causes:

Docker image not available locally and not reachable on the registry.
Another container already bound to the same name.
nvpss.conf removed between validation and container start.

8.3 Host process exits immediately after launch#

If atl_sdm / proximity_sdm / safety_monitor exit within a second of starting, the launcher aborts with Error: failed to start <label>. Inspect the corresponding log in /var/log/psf/ for the root cause.

8.4 `safety_monitor` exits with baseline file not found#

Run launch_hoisa.sh from /opt/nvidia/psf/bin. The SAIM baseline files are resolved from the launcher working directory, and active mode expects the baseline files generated by learn mode to be present there.

cd /opt/nvidia/psf/bin
sudo ./launch_hoisa.sh --mode learn \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
    --threshold-config /opt/nvidia/psf/bin/thresholds.cfg \
    --learn-duration 300

If the baseline files are missing, rerun learn mode before starting active mode.

8.5 VST RTSP URL returns `DESCRIBE` or `PLAY` 404#

Validate the exact rtspUrl value from sensor_config.conf before launching HOISA:

ffprobe -rtsp_transport tcp <rtsp_url>
# or
gst-launch-1.0 rtspsrc location=<rtsp_url> ! fakesink

If the VST sensor is online but the configured /live/<sensor-id> URL does not play, refresh or recreate the VST proxy sensor and update sensor_config.conf with the new RTSP URL. Re-run the validation command before starting learn or active mode.

HOISA Launcher Script - launch_hoisa.sh#