Fire Gimbal Control (Staeffelsberg)

Real-time control software for an automated fire-watch gimbal. A single C++17 binary runs on a tower-mounted PC, rotates a pan gimbal carrying up to four industrial cameras, captures a 360° panorama for wildfire detection, compresses each frame to JPEG XL, and reports to a ground station over MQTT.

This is the deployment for the Staeffelsberg fire-watch tower (FWT). The same codebase is used across towers; the tower identity comes from config.ini.

State is held in memory (mutex-guarded structs), configuration is read once from an INI file, images are written to the filesystem as .jxl, and telemetry flows over MQTT. See docs/architecture.md for the full picture.

What it does (at a glance)

 motor controller (MCU)            this program (Fire_Gimbal_Control.out)             ground station
 ┌───────────────────┐  serial    ┌──────────────────────────────────────┐  MQTT   ┌──────────────┐
 │  gimbal + sensors │ ─────────▶ │  read telemetry → decide when to stop │ ──────▶ │ broker / ZKMS │
 │  /dev/ttyACM0     │ ◀───────── │  send move/stop commands              │ ◀────── │  control UI   │
 └───────────────────┘            │  trigger cameras → encode JXL → save  │         └──────────────┘
                                  └──────────────┬───────────────────────┘
              Vimba X (GigE/USB)                 │  files
                  cameras  ───────────────────▶  ▼  RGB/ACR/NIR/<unix_ms>.jxl

Quick start

# 1. Install dependencies (see docs/build-and-setup.md for details + Vimba X SDK)
# 2. Build
make                       # produces bin/Fire_Gimbal_Control.out
# 3. Run (requires camera(s), motor MCU on /dev/ttyACM0, and a reachable MQTT broker)
./bin/Fire_Gimbal_Control.out --start 1          # auto-start capture
./bin/Fire_Gimbal_Control.out --init 1 --start 1 # also find endstops first

Before it will run on this machine, several paths are hardcoded to /home/ggs/projects/Fire_Gimbal_Control/... and the program exits if MQTT can't connect. Read docs/known-issues.md first — it lists every reproduction blocker and the deployed layout the binary expects.

Documentation

Document	Contents
docs/architecture.md	System overview, threading model, end-to-end data flow, capture state machine
docs/build-and-setup.md	Toolchain, dependencies, build, serial/MQTT setup, directory layout
docs/configuration.md	config.ini keys, CLI flags, console command grammar
docs/mqtt-api.md	MQTT topic catalog, payloads, QoS/retain, ControlCode semantics
docs/modules-reference.md	Per-file reference and key data structures
docs/known-issues.md	Reproduction blockers and recommended follow-ups

Repository layout

.
├── main.cpp            Entry point: config, CLI args, threads, main control loop
├── Serial.h            SerialPort + motor_info telemetry parser (Boost.Asio)
├── MQTT.h / MQTT.cpp   MQTTClient + callbacks (Eclipse Paho C++)
├── Camera.h / Camera.cpp  VimbaHandler: acquisition, queue, JXL save (Vimba X + OpenCV)
├── JPEG_XL.h           JPEG XL encoder wrapper (libjxl)
├── Parser.h            Console command parser (Boost.Spirit Qi) + command evaluator
├── timing.h            Timer / timestamp helpers
├── ini.c / ini.h       inih INI parser (third-party)
├── cxxopts.hpp         Third-party CLI parser (legacy/unused — Boost is used instead)
├── Log.h               Empty stub
├── config.ini          Configuration (also a separate copy under bin/x64/Release/)
├── Makefile            Build definition
└── bin/x64/Release/    Deployed/runtime directory (binary, config, startup scripts, image folders)

License / ownership

Internal tooling for the GGS fire-watch tower network. No license file is present in the repository.