# Module Reference

Per-file reference for the source tree, plus the key in-memory data structures (this project's "data model").

## Source files

### [main.cpp](../main.cpp) — entry point & control loop
- `handler()` — inih callback flattening INI keys to `Section.name`.
- `readInput()` — stdin thread; reads lines, forwards to the `Parser`, handles `exit`.
- `main()` — loads config, parses CLI flags, constructs `SerialPort`, `MQTTClient`, `VimbaHandler`; starts the
  serial I/O thread and stdin thread; optionally runs the init sequence; runs the 10 ms control loop
  (command eval → telemetry poll → MQTT poll → capture state machine); cleans up on exit.
- Global state lives at file scope (`running`, `imagerate`, `ctl_code`, `mqtt_hdg`, `mqtt_client`,
  `camera_id_vec`, …).

### [Serial.h](../Serial.h) — motor controller link
- `struct motor_info` — telemetry snapshot (see below).
- `class SerialPort` — opens the port (115200 8N1, no parity/flow), async read-until `\n`, async write.
  - `parser()` — splits a `$`-prefixed `;`-delimited line into 12 fields and stores a `motor_info`.
  - `set_controller_info()` / `get_controller_info()` — mutex-guarded accessors.
  - `sendCommand()` — async-write a command string.
  - `run()` / `stop()` — drive the Boost.Asio `io_service`.

### [MQTT.h](../MQTT.h) / [MQTT.cpp](../MQTT.cpp) — MQTT client
- `struct mqtt_sub_data` — latest remote control state + "available" flags (see below).
- `class MQTTCallback` — Paho callback/listener: subscribes on connect, parses inbound messages, auto-reconnects
  on loss; `get_sub_data()` returns + clears the available flags.
- `class MQTTClient` — owns the `async_client`, connect options (auth, keep-alive, clean session); `publish()`
  sends QoS 1 retained messages. See [mqtt-api.md](mqtt-api.md) for the topic catalog.

### [Camera.h](../Camera.h) / [Camera.cpp](../Camera.cpp) — camera pipeline (Vimba X)
- `struct image_store_8bit` — owns a deep copy of one frame's pixel buffer + metadata (see below).
- `class FrameObserver` (in .cpp) — Vimba `IFrameObserver`; dumps the first 3 frames after each trigger
  (`settle`), enqueues complete frames, re-queues buffers to the camera.
- `class VimbaHandler` — starts up the Vimba system, opens cameras by ID, manages the per-camera bounded
  queues and the saver thread.
  - `Start()`/`Stop()` — begin/end continuous acquisition + saver thread.
  - `EnqueueToStoreStruct()` — copy a received frame into the queue (reuse oldest if at 100).
  - `SaveImage()` — saver loop: rotate 90° CCW, optionally display, encode JXL (or copy `test_smoke.jxl` in
    demo), write file, publish CamEvent.
  - `TriggerCamera()` / `TriggerSettle()` — fire `TriggerSoftware` ×4 with settle reset.
  - `ChangeFramerate()`, `evaluateCommand()`, `SetTowerName()`.

### [JPEG_XL.h](../JPEG_XL.h) — `class JPEGXL`
Wraps libjxl. Constructor encodes an 8-bit interleaved buffer (1 or 3 channels) into an in-memory JXL
codestream using a thread-parallel runner; `q == 0` → lossless, otherwise `q` is the frame distance; `e` is the
effort level. `WriteFile()` flushes the codestream to disk.

### [Parser.h](../Parser.h) — console command parsing
- `enum InputCommands` — command kinds (`startcamera`, `stopcamera`, `setcamera`, `setimagerate`,
  `setmotorcontrol`, `setdebug`, `no_cmd`, `setgimbal`).
- `struct parser_data` — parsed tokens (see below).
- `struct Parser` — Boost.Spirit Qi grammar splitting input into `command device option value`; mutex-guarded.
- `struct CMD_eval` — maps `parser_data` to an `InputCommands` value. See [configuration.md](configuration.md).

### [timing.h](../timing.h) — time helpers
- `class Timer` — high-resolution stopwatch (`Reset`, `Elapsed`, `ElapsedMillis`) plus string/file timestamp
  helpers; used for loop pacing and profiling.
- `class NanoUnixTimer` — Unix-epoch **millisecond** timestamps (`Stamp_longlong`, `Stamp_string`) used for
  image filenames and CamEvent `time`.
- `class ScopedTimer` — RAII timer that logs elapsed time on destruction.

### [ini.c](../ini.c) / [ini.h](../ini.h) — third-party `inih`
Minimal INI parser (`ini_parse`). Unmodified vendored library.

### Other files
- [cxxopts.hpp](../cxxopts.hpp) — third-party CLI parser, **included but unused** (the live CLI parsing uses
  Boost.Program_options; the cxxopts block in `main.cpp` is commented out).
- [Log.h](../Log.h) — empty stub (`#pragma once` only).

## Data structures (the in-memory "data model")

### `motor_info` ([Serial.h](../Serial.h) lines 6-19)
Telemetry from the motor controller, parsed from a 12-field `$`-line.

| Field | Type | Meaning | Source field index |
|-------|------|---------|---------------------|
| `Xenc` | int | Encoder position | 1 |
| `Xerr` | int | Encoder error | 2 |
| `sgt_val` | int | StallGuard value | 3 |
| `sgt_stat` | int | StallGuard status | 4 |
| `is_moving` | int | Movement flag | 5 |
| `control_status` | int | Driver/controller status | 6 |
| `hdg` | float | Heading (degrees) | 7 |
| `deviation_warn` | int | Deviation warning | 8 |
| `humid` | int | Humidity | **9** |
| `temp` | int | Temperature | **10** |
| `fan_pwm` | int | Fan PWM (0-255) | 11 |

> Field 0 is the literal `$` marker. Note the order: index 9 → `humid`, index 10 → `temp` (see
> [known-issues.md](known-issues.md) so the firmware emits them in this order).

### `mqtt_sub_data` ([MQTT.h](../MQTT.h) lines 7-21)
Latest remote-control state.

| Field | Type | Meaning |
|-------|------|---------|
| `ctl_avail` | bool | A new ControlCode arrived since last read |
| `hdg_avail` | bool | A new target heading arrived since last read |
| `target_heading` | string | Target heading (kept as string, forwarded as `kd<heading>`) |
| `control_code` | int | 0 = auto sweep, 1 = directed |

### `parser_data` ([Parser.h](../Parser.h) lines 21-26)
One parsed console command: `command`, `device`, `option` (strings) and `command_val` (double).

### `image_store_8bit` ([Camera.h](../Camera.h) lines 14-63)
One captured frame held in the queue: a `std::vector<VmbUchar_t>` pixel buffer plus `width`, `height`,
`pixelFormat`, a Unix-ms `timestamp`, and `cam_id`. Provides `equal()`/`setData()` so the queue can reuse the
oldest buffer in place when full.

## On-disk artifacts

| Artifact | Path | Format |
|----------|------|--------|
| Captured images | `$HOME/projects/Fire_Gimbal_Control/bin/x64/Release/<RGB\|ACR\|NIR>/<unix_ms>.jxl` | JPEG XL, rotated 90° CCW |
| Demo placeholder | `bin/x64/Release/test_smoke.jxl` | JPEG XL (copied verbatim in demo mode) |

There is no other persistence: state lives in memory and diagnostics go to stdout/stderr only (no log files).