Install and Run Without Docker

The Safety Core ships as Debian packages and as a container image. The image is built from the same packages. Install the runtime package on every host that runs the launcher, a decision maker or a command receiver, even when the rest of the Safety Core runs in the container. Install the development package where you build your own decision maker or event source.

Packages

None of the packages declares a dependency, so dpkg does not install the libraries the binaries need. Install them yourself; see Runtime libraries.

Download

The packages are NGC resources. Each package is one version of the resource nvidia/halos-outside-in/outside-in-safety, named by the release, the platform, the build and the package name.

# x86-64
ngc registry resource download-version "nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-x86-lin64-release-6b92731-psf-desktop"
ngc registry resource download-version "nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-x86-lin64-release-6b92731-psf-desktop-dev"
# IGX Thor (aarch64)
ngc registry resource download-version "nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-aarch64-release-6b92731-psf-tegra"
ngc registry resource download-version "nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-aarch64-release-6b92731-psf-tegra-dev"

psf-tegra-fsi is nvidia/halos-outside-in/outside-in-safety:nv-psf-halos-1.4-aarch64-release-6b92731-psf-tegra-fsi, and needs a separate sign-up.

Install

On x86-64:

sudo dpkg -i <download-dir>/psf-desktop.deb
sudo dpkg -i <download-dir>/psf-desktop-dev.deb    # only where you build

On IGX Thor:

sudo dpkg -i <download-dir>/psf-tegra.deb
sudo dpkg -i <download-dir>/psf-tegra-dev.deb      # only where you build
sudo dpkg -i <download-dir>/psf-tegra-fsi.deb      # only for an SDM on the FSI

To cross-compile for IGX Thor on an x86-64 host, extract the packages instead of installing them:

dpkg -x <download-dir>/psf-tegra.deb <extraction-path>
dpkg -x <download-dir>/psf-tegra-dev.deb <extraction-path>

Reinstall, upgrade and remove

• Same version. Every build of a package carries the same version string. dpkg -i replaces the installed files even when the version is unchanged, so a reinstall does install the new build. Confirm it by the file times, not the version:

  ls -l /opt/nvidia/psf/bin/nvpss_daemon /opt/nvidia/psf/bin/nvpsd_gateway

• Edited configuration is overwritten. The packages mark no configuration files. A reinstall or upgrade replaces nvpss.conf, sensor_pipelines_config.conf, thresholds.cfg and pcm_monitor.cfg in /opt/nvidia/psf/bin, and the rsyslog rule, with the shipped versions, and empties /var/log/psf/pss.log. Copy your edited files elsewhere first, and keep your own configuration under names the package does not ship (for example sensor_config.conf, which ships only as sensor_config.conf.sample). Learned baselines are not package files and are kept. SAIM refuses its baselines from an earlier release, so learn them again after upgrading; see Baselines.

• Remove. dpkg --purge removes the package files and, for the runtime package, the three socket files in /run/nvpsf. It leaves the /run/nvpsf directory.

  # x86-64
  sudo dpkg --purge psf-desktop-dev psf-desktop
  # IGX Thor
  sudo dpkg --purge psf-tegra-fsi psf-tegra-dev psf-tegra

Install paths

Configuration files in /opt/nvidia/psf/bin:

Runtime libraries

On Ubuntu 24.04:

sudo apt-get update
sudo apt-get install -y librdkafka1 libprotobuf32t64

Ubuntu 22.04’s protobuf package provides libprotobuf.so.23, not libprotobuf.so.32, so it does not satisfy mdx_client or nv_perception_monitor. The container image is based on Ubuntu 24.04 and already contains the libraries its platform needs, except the driver’s.

Check that nothing is missing:

ldd /opt/nvidia/psf/apps/mdx-client/mdx_client /opt/nvidia/psf/bin/nv_perception_monitor \
    /opt/nvidia/psf/bin/safety_monitor | grep "not found"

Expected result: no output.

PATH and LD_LIBRARY_PATH

The Safety Core executables carry no library search path of their own. The runtime package registers /opt/nvidia/psf/lib with the dynamic linker through /etc/ld.so.conf.d/nvidia-psf.conf and runs ldconfig, so after dpkg -i no LD_LIBRARY_PATH is needed. The binaries are not added to PATH; call them by their full path, or:

export PATH=/opt/nvidia/psf/bin:"${PATH}"

If you extracted the packages with dpkg -x instead of installing them, the linker configuration is not in place. Set the library path to the extracted tree:

export LD_LIBRARY_PATH=<extraction-path>/opt/nvidia/psf/lib:"${LD_LIBRARY_PATH}"

What the runtime package sets up

Kernel socket buffers

The transport sizes the gateway-to-SDM link for 516 decision packets, because a packet the gateway cannot send burns a sequence number and the SDM latches on the gap. When the gateway and each SDM open the link, they request receive and send buffers for 516 messages, read back what the kernel granted, and refuse to continue if it is less. Linux caps the grant at net.core.rmem_max (receive) and net.core.wmem_max (send), and the stock limits are lower than the request.

Set both limits on the host that runs these processes. The container uses the host’s network namespace and shares the host’s limits. Do not lower a larger value that is already set.

Files in /etc/sysctl.d/ apply in name order, and a later file overrides an earlier one. The file names below are chosen against the VSS settings file (99-vss.conf), which sets both limits to 5242880.

On a host with CCPLEX SDMs only, the file sorts before the VSS file, so a larger VSS value still wins:

printf 'net.core.rmem_max = 836436\nnet.core.wmem_max = 836436\n' | sudo tee /etc/sysctl.d/60-nvpsf.conf
sudo sysctl --system

On an IGX Thor that runs fsicom-agent, the file sorts after the VSS file, because the agent needs more than VSS sets:

printf 'net.core.rmem_max = 5283840\nnet.core.wmem_max = 5283840\n' | sudo tee /etc/sysctl.d/99-zz-nvpsf-fsi.conf
sudo sysctl --system

Check:

sysctl net.core.rmem_max net.core.wmem_max

What happens when a limit is too low:

The requested size is twice the payload because Linux reports buffer sizes with its own accounting overhead included. The check is in provisionSocketBuffer() of the transport library. The transport also honours an environment variable, NVPSF_MIN_QUEUE_DEPTH, that lowers the 516-packet floor for test machines and prints a warning when set. Do not set it in production: a lower floor re-opens the drop that the floor exists to prevent.

Running without Docker

Every Safety Core process can run directly on the host.

Before you start

1. Install the runtime package and the runtime libraries.
2. Raise the kernel socket buffers.
3. Check that /run/nvpsf exists with mode 1777 (ls -ld /run/nvpsf). The package creates it at every boot. Without the package, create it after every boot, because /run is cleared: sudo mkdir -p /run/nvpsf && sudo chmod 1777 /run/nvpsf.
4. Create /opt/nvidia/psf/bin/sensor_config.conf from sensor_config.conf.sample, or point sensorConfig in nvpss.conf at your file. The daemon reads the file named by sensorConfig, not the one you pass to the launcher or to mdx_client, so all three must name the same file.
5. Check sensor_pipelines_config.conf against your cameras (2D) or your BEV group (3D).
6. Copy the SDM configuration from its .sample and edit it.
7. For SAIM in active mode, make sure /opt/nvidia/psf/bin/saim_baseline holds a baseline for every camera, learned (<camera>_baseline.cfg) or shipped (<camera>_baseline.cfg.default).
8. For PCM in active mode, make sure /opt/nvidia/psf/bin/pcm_baseline holds a baseline learned with the same event mapping and SDM configurations as the active run (see Learning by hand), and that /opt/nvidia/psf/bin/pcm_monitor.cfg lists the perception containers of this host.

With the launcher

launch_hoisa.sh --runtime host starts every process on the host, in the right order. It runs them as root through sudo -n, so they all have the same primary group; run it as root or with passwordless sudo.

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 <cmd-rx-port>

To learn the baselines first, run the same command with --saim-mode learn --pcm-mode learn and without the two --cmd-rx options. Every option is on Launcher. The launcher does not start the command receiver; start it first, as in step 4 below.

By hand

Start the processes in this order. The constraints that force it are:

These steps start the forklift safety function (ATL) in 2D. Run steps 1 to 3 and 5 to 8 in one root shell (sudo -i), so that every Safety Core process runs as root with the same primary group (see Shared process group). Run step 4 in its own terminal, because the receiver reads release commands from its standard input; the receiver does not use the AF_UNIX links, so it can run as any user.

1. Prepare the log files:

   mkdir -p /var/log/psf && cd /var/log/psf
   touch psf.log atl_sdm.log saim.log pcm.log && chmod 666 psf.log atl_sdm.log saim.log pcm.log

2. Start the SEI daemon, then wait for its socket:

   /opt/nvidia/psf/bin/nvpss_daemon --conf /opt/nvidia/psf/bin/nvpss.conf >> /var/log/psf/psf.log 2>&1 &
   sleep 1 && ls -l /run/nvpsf/nvpssd /run/nvpsf/nvpssd_to_psd

   Expected result: both sockets are listed.

3. Start the gateway and the MDX client:

   /opt/nvidia/psf/bin/nvpsd_gateway >> /var/log/psf/psf.log 2>&1 &
   /opt/nvidia/psf/apps/mdx-client/mdx_client \
       --config /opt/nvidia/psf/apps/atl/event_mapping_atl.pb.txt \
       --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
       --instance-id 1 --broker <kafka-broker> >> /var/log/psf/psf.log 2>&1 &

   In 3D, replace --sensor-config /opt/nvidia/psf/bin/sensor_config.conf with --sensor-pipelines-config /opt/nvidia/psf/bin/sensor_pipelines_config.conf.

4. In a separate terminal, on the PLC side, start the command receiver:

   /opt/nvidia/psf/apps/atl/atl_sdm_cmd_receiver -p <cmd-rx-port> --sdm_ip <sdm-host-ip>

   Expected result: ATL UDP Command Receiver listening on port <cmd-rx-port>.

5. Start the SDM:

   /opt/nvidia/psf/apps/atl/atl_sdm \
       --config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
       --log_file /var/log/psf/atl_sdm.log \
       --cmd_rx_ip <cmd-rx-ip> --cmd_rx_port <cmd-rx-port> \
       --decision_interval_ms 0 >> /var/log/psf/psf.log 2>&1 &

6. Start SAIM from its baseline directory, if required_safety_monitor = 1:

   (cd /opt/nvidia/psf/bin/saim_baseline && /opt/nvidia/psf/bin/safety_monitor --mode ACTIVE \
       --sensor-config /opt/nvidia/psf/bin/sensor_config.conf \
       --threshold-config /opt/nvidia/psf/bin/thresholds.cfg >> /var/log/psf/saim.log 2>&1 &)

7. Start PCM, if required_perception_monitor = 1, with the same event mapping and SDM configuration as the SDM:

   /opt/nvidia/psf/bin/nv_perception_monitor --mode ACTIVE \
       --event-mapping /opt/nvidia/psf/apps/atl/event_mapping_atl.pb.txt \
       --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
       --kafka-broker <kafka-broker> >> /var/log/psf/pcm.log 2>&1 &

   PCM reads /opt/nvidia/psf/bin/pcm_monitor.cfg and the baseline in /opt/nvidia/psf/bin/pcm_baseline. Check that it loaded both checks with grep 'checks: container_health=' /var/log/psf/pcm.log | tail -n 1; the line should show data_validation=on.

8. Check that the SDM registered and is receiving decisions:

   grep -E "sent registration|received DecisionRequest" /var/log/psf/atl_sdm.log | tail -3

   Expected result: a SDM: sent registration (7 event types) to gateway line, followed by SDM: received DecisionRequest from psdGateway lines at least every 5 seconds. The receiver’s console shows the latch and release events.

For PXC, use /opt/nvidia/psf/apps/proximity/proximity_event_mapping.pb.txt, proximity_sdm --config /opt/nvidia/psf/bin/pxc_sdm_forklift.conf --log_file /var/log/psf/pxc_sdm.log, the same two files for PCM, and proximity_sdm_cmd_receiver.

To stop, send SIGTERM to every process; the gateway and the SDMs shut down cleanly on it:

pkill -TERM -f '^/opt/nvidia/psf/'

Learning by hand

Learn mode needs no SEI daemon: neither monitor registers with it. Run both in one root shell, against the normal, unobstructed scene, with <kafka-broker> as in By hand. Each stops after --learn-duration seconds (1–3600, default 300). PCM exits with status 1 when it could not write its baseline.

(cd /opt/nvidia/psf/bin/saim_baseline && /opt/nvidia/psf/bin/safety_monitor --mode LEARN \
    --sensor-config /opt/nvidia/psf/bin/sensor_config.conf --learn-duration 300 >> /var/log/psf/saim.log 2>&1) &
/opt/nvidia/psf/bin/nv_perception_monitor --mode LEARN --learn-duration 300 \
    --event-mapping /opt/nvidia/psf/apps/atl/event_mapping_atl.pb.txt \
    --sdm-config /opt/nvidia/psf/bin/atl_sdm_zone1.conf \
    --kafka-broker <kafka-broker> >> /var/log/psf/pcm.log 2>&1 &
wait

Expected result: one <camera>_baseline.cfg per camera in /opt/nvidia/psf/bin/saim_baseline, and /opt/nvidia/psf/bin/pcm_baseline/pcm_baseline.cfg. PCM logs DVM: baseline: published <n> camera(s) in /opt/nvidia/psf/bin/pcm_baseline/pcm_baseline.cfg; bbox/confidence/occupancy are not fault baselines. Give PCM the same --event-mapping and --sdm-config values in learn and active mode; an active PCM does not use a baseline learned with other values. See PCM baselines.

Building the reference applications

The development package installs:

examples is /opt/nvidia/psf/examples/apps/metropolis after dpkg -i, or the same path under <extraction-path> after dpkg -x.

Command receivers

The receivers need only their own source and packet header. On x86-64:

E=/opt/nvidia/psf/examples/apps/metropolis
g++ -std=c++11 -o atl_sdm_cmd_receiver $E/atl/udp_cmd_receiver/cmd_rx.cpp \
    -I $E/atl/include -lpthread
g++ -std=c++11 -o proximity_sdm_cmd_receiver $E/proximity/udp_cmd_receiver/cmd_rx.cpp \
    -I $E/proximity/include -lpthread

For IGX Thor, cross-compile on an x86-64 host with aarch64-linux-gnu-g++ and E=<extraction-path>/opt/nvidia/psf/examples/apps/metropolis.

Decision makers

A reference SDM is built from these inputs:

The shared SDM headers are sdm_decision_request_state.h, sdm_decision_freshness.hpp, sdm_gateway_decision_sequence.hpp and sdm_reviewed_sensor_set.hpp. The sensor-config parser is sensor_config_parser.h and sensor_config_parser.cpp.

FSI package

psf-tegra-fsi is for IGX Thor only. Install it on the Thor, with psf-tegra.

fsicom-agent needs libnvpsf_transport.so from psf-tegra, and the NvFsiCom and EPL libraries of the IGX Safety Extension Package, which the Safety Core packages do not include. It also needs the larger kernel socket buffers. Flashing the firmware and running the agent are covered in Custom Deployment; the agent’s options are on Launcher; its contract with the gateway is on Writing a decision maker.