# 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](../main.cpp) line 66 reads the config from an absolute path owned by user `ggs`:

```cpp
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:
```bash
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](../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](../bin/x64/Release/startup_gimbal.sh) and
[startup_gimbal_with_init.sh](../bin/x64/Release/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](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](../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](../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](../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](../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](../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](../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](../config.ini) (root: `Rietschen`, 3 GigE cameras) and
[bin/x64/Release/config.ini](../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](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.