fwt_software/docs/modules-reference.md

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 — 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 — 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.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 for the topic catalog.

Camera.h / 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 — 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 — 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.

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.h — third-party inih

Minimal INI parser (ini_parse). Unmodified vendored library.

Other files

• 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 — empty stub (#pragma once only).

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

motor_info (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 so the firmware emits them in this order).

mqtt_sub_data (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 lines 21-26)

One parsed console command: command, device, option (strings) and command_val (double).

image_store_8bit (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).