fwt_software/docs/build-and-setup.md

Build & Setup

The project builds with CMake (≥ 3.20) and a C++17 compiler. The build is split so the SDK-independent core and the development (mock) build work on any machine; the proprietary/heavy dependencies are optional.

Build options

Option	Default	Effect
WITH_VIMBA	ON	Build the Allied Vision Vimba X camera source. OFF → mock cameras only (no SDK needed).
WITH_MQTT	ON	Build the Eclipse Paho MQTT channel (fetched via FetchContent). OFF → null channel only.
BUILD_TESTING	OFF	Build the doctest unit tests (fetches doctest).

# Full build (requires Vimba X SDK installed + network for Paho)
cmake -B build
cmake --build build                    # -> build/fire_gimbal_control

# Development build: no proprietary SDKs, no broker
cmake -B build -DWITH_VIMBA=OFF -DWITH_MQTT=OFF
cmake --build build

# With tests
cmake -B build -DWITH_VIMBA=OFF -DWITH_MQTT=OFF -DBUILD_TESTING=ON
cmake --build build && ctest --test-dir build --output-on-failure

CMake exports compile_commands.json into the build dir for clangd/IDEs.

Dependencies

Dependency	Needed for	How it's provided
CMake ≥ 3.20, g++/clang with C++17	always	system package (cmake, official repo)
OpenCV (core, highgui, imgproc)	image rotate/display	find_package(OpenCV) — system package
libjxl (libjxl, libjxl_threads)	JPEG XL encoding	pkg-config — system package
Boost (program_options; header-only Asio)	CLI parsing, serial I/O	find_package(Boost CONFIG) — system package
Threads	concurrency	system
Eclipse Paho MQTT C/C++	MQTT (WITH_MQTT=ON)	FetchContent from official upstream (no AUR / system install)
Allied Vision Vimba X SDK	cameras (WITH_VIMBA=ON)	proprietary, install manually (see below)

On Arch/Manjaro the system deps are roughly:

sudo pacman -S cmake opencv libjxl boost

(Debian/Ubuntu equivalents: cmake build-essential libopencv-dev libjxl-dev libboost-all-dev.)

Eclipse Paho MQTT (FetchContent, no AUR)

When WITH_MQTT=ON, CMake downloads and builds Paho MQTT C and C++ from the official Eclipse repos (cmake/Paho.cmake), pinned by tag. This keeps the dependency off the AUR. For maximum integrity, pin PAHO_C_TAG/PAHO_CPP_TAG to a commit SHA or switch to a hash-verified release tarball. The first configure needs network access.

Allied Vision Vimba X SDK (proprietary)

VmbC/VmbCPP are not in any package manager. Download the Vimba X SDK from Allied Vision (https://www.alliedvision.com/en/products/software/vimba-x-sdk/) and point CMake at it:

cmake -B build -DVMB_HOME=/opt/VimbaX_2024-1
# or: export VIMBA_X_HOME=/opt/VimbaX_2024-1

cmake/FindVmb.cmake locates the headers/libs and creates Vmb::VmbC / Vmb::VmbCPP. If the SDK is absent, build with -DWITH_VIMBA=OFF to get a mock-only binary.

Host setup (for a real run)

1. Serial device — the motor controller must appear at the configured [Serial] device (default /dev/ttyACM0) at the configured baud. Add your user to dialout for non-root access:

   sudo usermod -aG dialout "$USER"   # re-login afterwards
   

   If the port can't be opened the program logs an error and continues (degraded, no telemetry).
2. Cameras — connect the Allied Vision cameras and confirm Vimba X sees them. Camera IDs in config.ini must match (GigE IP like 192.168.11.101, host NIC on that subnet; or USB DEV_...).
3. MQTT broker — reachable at [Network] zkms_server_ip with the credentials (from $FGC_MQTT_USER/ $FGC_MQTT_PW or the config). Unlike the old version, the program no longer exits if MQTT is unavailable — it logs a warning and continues. Use --no-mqtt to skip MQTT entirely.

Run

scripts/run.sh --start                                   # real deployment
scripts/run.sh --init --start                            # find endstops, then start
scripts/run.sh --mock-serial --mock-camera --no-mqtt --start   # dev, no hardware

scripts/run.sh locates the binary relative to itself, and scripts/fire-gimbal-control.service is a systemd unit template (uses WorkingDirectory + FGC_CONFIG, so no paths are hardcoded in the binary).

Directory layout

build/                 CMake build output (gitignored)
include/fgc/, src/     headers and implementations (see modules-reference.md)
tests/                 unit tests
config/config.example.ini   template (copy to config.ini)