Software setup

Development environment

  1. Install pixi package manager.

  2. Install sandbox:

mkdir -p ~/sarcam/ws/src
cd ~/sarcam/ws/src
git clone https://gitlab.com/sar-eye/HorizonScanner/
cd HorizonScanner
git lfs install && git lfs pull  # pull binary libs and training data
pixi run setup   # clone external repository deps (gscam, nmea_navsat_driver)

  1. Build the sandbox:

pixi run build   # builds the sarcam codebase and its ROS2 parts

Next: How to develop if you just want to run the system as a developer.

Experimental features

Note

Only recommended if you really know what you do!

Zenoh shared memory (SHM)

scripts/pixi_ros_activate.sh points rmw_zenoh at the SHM-enabled configs in scripts/zenoh/ so large topics (e.g. ~11 MB raw camera frames) pass between local nodes via shared memory instead of being copied per subscriber, keeping the RGB pipeline at full fps. It is auto-disabled in CI, when /dev/shm is too small, and when the locked-memory limit is too low — otherwise nodes fail to allocate their shm segment and abort.

Each node mlocks an SHM pool at startup, so the locked-memory limit (ulimit -l) must be high enough or you get OS error 12 / RCLBadAlloc on startup, or — more subtly — large messages are silently dropped while small ones keep flowing. A process locks its own pool plus every peer pool it maps, so the requirement is (1 + peers) × pool. pixi_ros_activate.sh sets ZENOH_SHM_ALLOC_SIZE to 32 MB (down from rmw_zenoh’s 48 MB default; still holds 2–3 ~12 MB frames) to keep this bounded. Allow 256 MB per process (own pool + several peers, with headroom); the common 8 MB default is why SHM is skipped out of the box.

Raise it depending on your session type, then re-login and confirm with ulimit -l. Use this bounded value rather than infinity/unlimited, so a runaway process can’t lock all RAM:

  • systemd desktop (graphical login + its terminals): limits.d is ignored — set DefaultLimitMEMLOCK=256M in /etc/systemd/system.conf and /etc/systemd/user.conf, then reboot (the running managers only read it at startup).

  • SSH / TTY: add to /etc/security/limits.d/99-sarcam-rtprio.conf (replace sarcam; value in KB):

sarcam  -  memlock  262144   # 256 MB (own + several 32 MB peer pools)
sarcam  -  rtprio   98       # optional: silences the harmless watchdog priority warnings
sarcam  -  nice    -20       # optional

After changing limits, confirm with ulimit -l in the same terminal you launch the app from.

Deployment on ship

Note

Following steps are not needed as a generic developer!

Currently we run the development environment also on ships for usage for SAR.

The deployment assumes following things:

  • a user called sarcam with a home directory.

  • repo cloned to /home/sarcam/sarcam/ws/src/HorizonScanner

Note

A software package for easy install will follow later.

Desktop icon

  1. Copy src/sarcam_bringup/script/sarcam-main.sh to /home/sarcam/sarcam/ws/sarcam-main.sh and adjust for your deployment needs.

Tip

You can e.g. adjust the recording path to a external harddisk.

bash src/sarcam_bringup/services/install-services.sh

Copies sarcam-main.desktop to ~/Desktop. Click it to launch the sarcam-main.sh script in a terminal.

Window taskbar icons

Each GTK UI window (RGB cam, Thermal cam, Virtual Gamepad) gets a distinct taskbar icon with an emoji overlay (🌈 / 🔥 / 🕹️). Run this once after a fresh clone, and again whenever the base icon (sarcam_ui/ui/images/icon.png) changes:

pixi run generate-icons

This installs composited PNGs into ~/.local/share/icons/hicolor/256x256/apps/ and matching .desktop files into ~/.local/share/applications/, then refreshes the GNOME icon cache. The UI nodes load the icons from there at startup; if the files are missing they fall back to the system default and log a warning.

Next: How to develop.