fwt_software/docs/known-issues.md

Known Issues & Reproduction Blockers

This page lists everything that stands between a freshly-copied checkout and a running system, plus a few correctness/robustness notes. These are documentation only — no code has been changed. Each entry notes a recommended fix if you choose to act on it later.

Reproduction blockers

1. Hardcoded config path (will fail on this machine)

main.cpp line 66 reads the config from an absolute path owned by user ggs:

ini_parse("/home/ggs/projects/Fire_Gimbal_Control/bin/x64/Release/config.ini", handler, &config)

On this machine (user pedro, repo at ~/code/Fire_Gimbal_Control_staeffelsberg) that file does not exist, so the program prints Can't load config.ini file! and exits.

To run as-is: create the expected tree and place a config there:

mkdir -p /home/ggs/projects/Fire_Gimbal_Control/bin/x64/Release
cp bin/x64/Release/config.ini /home/ggs/projects/Fire_Gimbal_Control/bin/x64/Release/

(Or run under a ggs user / adjust the path.) Recommended fix: make the config path a CLI argument or resolve it relative to the executable / $HOME.

2. Hardcoded image output path

Camera.cpp line 348 writes images under:

$HOME/projects/Fire_Gimbal_Control/bin/x64/Release/<RGB|ACR|NIR>/<unix_ms>.jxl

This uses $HOME (so it follows the running user) but a fixed projects/Fire_Gimbal_Control/... subtree, not the repo location. The directories are created on demand, so this mainly matters for knowing where images land and for free-space planning. Recommended fix: derive the output root from config.

3. Startup scripts point at the deployed tree

bin/x64/Release/startup_gimbal.sh and startup_gimbal_with_init.sh invoke:

~/projects/Fire_Gimbal_Control/bin/x64/Release/Fire_Gimbal_Control.out ...

i.e. the deployed ~/projects/... layout, not ~/code/Fire_Gimbal_Control_staeffelsberg. To use the scripts unchanged, deploy the built binary + config into that tree; otherwise edit the scripts to point at your build output.

4. Proprietary SDK required — Allied Vision Vimba X

VmbC/VmbCPP are not installable via any package manager. Without the Vimba X SDK the project will not compile or link (-lVmbC -lVmbCPP, headers VmbC/VmbC.h, VmbCPP/VmbCPP.h). Download from Allied Vision and add the SDK include/lib paths — see build-and-setup.md. Camera IDs in config.ini must match the transport: GigE IPs (192.168.11.10x, host NIC on that subnet) or USB IDs (DEV_...).

5. Hardware + broker needed for a full run

A complete run needs all of:

• the motor controller MCU enumerated at /dev/ttyACM0 (115200 8N1), user in dialout;
• the cameras reachable by Vimba X;
• a reachable MQTT broker at zkms_server_ip with the configured credentials.

If serial open fails it is caught and logged (the program continues but has no telemetry). If MQTT does not connect, the program exits (main.cpp lines 162-165).

Demo mode is not a no-hardware path. --demo 1 skips JXL encoding (copies test_smoke.jxl instead), but VimbaHandler's constructor still starts the Vimba system and calls Open() on each configured camera, so cameras must still be present. There is no flag to bypass cameras entirely.

Correctness / robustness notes

6. Telemetry field order (humid before temp)

The serial parser maps values[9] → humid and values[10] → temp (Serial.h lines 99-100). The motor-controller firmware must emit fields in that order. If temperature/humidity look swapped, this is why.

7. Trigger gated on is_moving == 1

In the capture state machine the actual TriggerCamera() call happens only while act_info.is_moving == 1 (main.cpp lines 305-306 and 328-329), i.e. it triggers while the gimbal still reports moving rather than after it has stopped. Documented as-is; verify against the firmware's is_moving semantics if captured frames look motion-blurred.

8. Plaintext MQTT credentials

mqtt_user / mqtt_pw are stored in plaintext in config.ini and printed paths/values go to stdout. Recommended: restrict file permissions and/or source credentials from the environment or a secrets store.

9. MQTTClient::run() busy-waits

After connecting, the MQTT thread spins on while (running) ; (MQTT.cpp lines 97-98), pegging a CPU core. Functionally harmless but wasteful. Recommended: replace with a condition variable / sleep, or simply let the thread exit since Paho's own threads handle delivery.

10. SerialPort::parser() missing return on non-$ lines

parser() returns nothing when the first character isn't $ (Serial.h lines 74-109) — undefined behaviour for a non-void function. In practice the result is ignored, but compile with -Wall -Wreturn-type (already -Wall) and consider adding an explicit return false;.

11. Console grammar limits on set motorctl

The Boost.Spirit grammar expects command device option <double> with alphabetic tokens (Parser.h lines 52-62). Raw motor commands that are numeric or multi-token may not land in the option field as intended. Verify any set motorctl <cmd> you rely on actually parses (watch the echoed command/device/option/value line).

12. Two divergent config.ini files

config.ini (root: Rietschen, 3 GigE cameras) and bin/x64/Release/config.ini (Staeffelsberg, 1 USB camera) differ, and neither is at the path the binary reads (issue #1). Decide which is authoritative for this deployment and place it at the expected path.

Minimal local bring-up checklist

1. Install non-proprietary deps + Vimba X SDK; make succeeds. (build-and-setup.md)
2. Put a valid config.ini at /home/ggs/projects/Fire_Gimbal_Control/bin/x64/Release/config.ini (issue #1), with zkms_server_ip = 127.0.0.1 and a local broker running (e.g. Mosquitto).
3. Ensure at least one configured camera is visible to Vimba X and on the right subnet/USB.
4. Connect the motor MCU on /dev/ttyACM0 (or expect telemetry-less operation).
5. Run ./Fire_Gimbal_Control.out --start 1 and watch GGS/FWT/<tower>/CamEvent over MQTT and the <RGB|ACR|NIR>/ image folders.