75 lines
4.5 KiB
Markdown
75 lines
4.5 KiB
Markdown
# 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.
|