112 lines
5.5 KiB
Markdown
112 lines
5.5 KiB
Markdown
# Fire Gimbal Control (Staeffelsberg)
|
|
|
|
Real-time control software for an automated **fire-watch gimbal**. A C++17 program 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 serves all towers;
|
|
the tower identity comes from `config.ini`.
|
|
|
|
The code is organized around an **SDK-independent core** (`fgc_core`: config, logging, capture scheduler,
|
|
parsers) and **swappable I/O implementations** behind three interfaces — motor controller, control channel,
|
|
and camera source — each with a real and a mock/null version. This makes the system deployable on any machine
|
|
and runnable **without hardware or an MQTT broker** for development.
|
|
|
|
State is held in memory (mutex-guarded), configuration is read once from an INI file, images are written to
|
|
the filesystem as `.jxl`, and telemetry flows over MQTT. There is no database.
|
|
|
|
## Architecture at a glance
|
|
|
|
```
|
|
┌──────────────────────── fgc_core (no SDKs) ─────────────────────────┐
|
|
│ Config · Logger · CaptureScheduler · TelemetryParser · CommandParser │
|
|
└───────▲─────────────────▲──────────────────▲────────────────────────┘
|
|
│ IMotorController │ IControlChannel │ ICameraSource
|
|
┌───────────┴──────┐ ┌────────┴─────────┐ ┌──────┴────────────────┐
|
|
real │ SerialMotorCtrl │ │ MqttControlChannel│ │ VimbaCameraSource │ (WITH_VIMBA/WITH_MQTT)
|
|
mock │ MockMotorCtrl │ │ NullControlChannel│ │ MockCameraSource │
|
|
└──────────────────┘ └──────────────────┘ └──────────┬────────────┘
|
|
frames
|
|
▼
|
|
ImagePipeline → .jxl + CamEvent
|
|
```
|
|
|
|
See [docs/architecture.md](docs/architecture.md) for the full design.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
cmake -B build # configure (needs the Vimba X SDK + Paho for a full build)
|
|
cmake --build build # -> build/fire_gimbal_control
|
|
|
|
# Development build with NO proprietary SDKs (mocks only):
|
|
cmake -B build -DWITH_VIMBA=OFF -DWITH_MQTT=OFF
|
|
cmake --build build
|
|
```
|
|
|
|
Dependencies and the Vimba X SDK setup are in [docs/build-and-setup.md](docs/build-and-setup.md).
|
|
|
|
## Run
|
|
|
|
```bash
|
|
# Real deployment (needs cameras, motor MCU on the configured serial port, MQTT broker):
|
|
scripts/run.sh --start
|
|
scripts/run.sh --init --start # find endstops first
|
|
|
|
# Development, no hardware or broker:
|
|
scripts/run.sh --mock-serial --mock-camera --no-mqtt --start --log-level debug
|
|
```
|
|
|
|
Config is resolved from `--config <path>`, then `$FGC_CONFIG`, `./config.ini`, the executable's directory, and
|
|
`$XDG_CONFIG_HOME/fire_gimbal_control/config.ini`. Copy the template to get started:
|
|
|
|
```bash
|
|
cp config/config.example.ini config.ini # then edit
|
|
```
|
|
|
|
Type `exit` (or Ctrl-D) to stop. See [docs/configuration.md](docs/configuration.md) for all options.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
cmake -B build -DWITH_VIMBA=OFF -DWITH_MQTT=OFF -DBUILD_TESTING=ON
|
|
cmake --build build
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
The unit tests cover the core (config, paths, telemetry/command parsers, capture scheduler) and need no SDKs.
|
|
|
|
## Documentation
|
|
|
|
| Document | Contents |
|
|
|----------|----------|
|
|
| [docs/architecture.md](docs/architecture.md) | Components, interfaces, threading, data flow, capture state machine |
|
|
| [docs/build-and-setup.md](docs/build-and-setup.md) | CMake, dependencies, options, Vimba X / Paho, host setup |
|
|
| [docs/configuration.md](docs/configuration.md) | `config.ini` keys, CLI flags, console commands |
|
|
| [docs/mqtt-api.md](docs/mqtt-api.md) | MQTT topic catalog and payloads |
|
|
| [docs/modules-reference.md](docs/modules-reference.md) | Per-file reference and data structures |
|
|
| [docs/known-issues.md](docs/known-issues.md) | Status of past issues + remaining caveats |
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
CMakeLists.txt Build (options: WITH_VIMBA, WITH_MQTT, BUILD_TESTING)
|
|
cmake/ FindVmb.cmake (Vimba X), Paho.cmake (FetchContent)
|
|
config/ config.example.ini (real config.ini is gitignored)
|
|
include/fgc/ Public headers: interfaces, Config, Logger, scheduler, impls
|
|
mock/ Mock/null implementations
|
|
src/
|
|
core/ Config, Logger, Paths, parsers, CaptureScheduler, Application
|
|
serial/ SerialMotorController
|
|
mqtt/ MqttControlChannel
|
|
camera/ VimbaCameraSource, ImagePipeline, JpegXlEncoder
|
|
main.cpp Thin entry point (CLI -> Application)
|
|
tests/ doctest unit tests
|
|
scripts/ run.sh + systemd unit template
|
|
ini.c / ini.h Bundled inih INI parser
|
|
```
|
|
|
|
## Ownership
|
|
|
|
Internal tooling for the GGS fire-watch tower network. No license file is present in the repository.
|