# 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](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

```bash
# 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](docs/known-issues.md)** first — it
> lists every reproduction blocker and the deployed layout the binary expects.

## Documentation

| Document | Contents |
|----------|----------|
| [docs/architecture.md](docs/architecture.md) | System overview, threading model, end-to-end data flow, capture state machine |
| [docs/build-and-setup.md](docs/build-and-setup.md) | Toolchain, dependencies, build, serial/MQTT setup, directory layout |
| [docs/configuration.md](docs/configuration.md) | `config.ini` keys, CLI flags, console command grammar |
| [docs/mqtt-api.md](docs/mqtt-api.md) | MQTT topic catalog, payloads, QoS/retain, ControlCode semantics |
| [docs/modules-reference.md](docs/modules-reference.md) | Per-file reference and key data structures |
| [docs/known-issues.md](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.