119 lines
6.6 KiB
Markdown
119 lines
6.6 KiB
Markdown
# 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).
|