# Configuration & Commands

Three layers control behaviour: the **`config.ini`** file (read once at startup), **command-line flags**, and
**interactive console commands** typed on stdin while running.

## `config.ini`

Parsed by the `inih` library ([ini.c](../ini.c)). Keys are flattened to `Section.name` and stored in a
`std::map<std::string,std::string>` ([main.cpp](../main.cpp) lines 35-40, 64-95).

> **Important:** the binary reads from a **hardcoded absolute path**, not the file next to the binary:
> `/home/ggs/projects/Fire_Gimbal_Control/bin/x64/Release/config.ini` ([main.cpp](../main.cpp) line 66).
> See [known-issues.md](known-issues.md).

### Keys

| Section | Key | Type | Used as | Notes |
|---------|-----|------|---------|-------|
| `General` | `tower_name` | string | Tower identity; substituted into all MQTT topics and CamEvent payloads | e.g. `Rietschen`, `Staeffelsberg` |
| `General` | `image_interval` | int | Seconds between captures; converted to `imagerate = 1/interval` | Required (parsed with `stoi`) |
| `General` | `debug` | int (0/1) | Sets `motorctl_info_out`; when on, prints full telemetry each tick | |
| `Network` | `zkms_server_ip` | string | MQTT broker address the client connects to | "ZKMS" = the ground-station server |
| `Network` | `mqtt_user` | string | MQTT username | Plaintext |
| `Network` | `mqtt_pw` | string | MQTT password | Plaintext |
| `Camera` | `id_Cam1`..`id_Cam4` | string | Camera IDs; non-empty ones are added in order | GigE IP (`192.168.11.101`) or USB ID (`DEV_1AB22C0AADED`) |

Camera index → output folder mapping is by **position** (first configured camera = index 0):
`0 → RGB`, `1 → ACR`, `2 → NIR` ([Camera.cpp](../Camera.cpp) lines 342-347).

### Two config files exist (and differ)

| File | tower_name | interval | broker | cameras |
|------|-----------|----------|--------|---------|
| [config.ini](../config.ini) (repo root) | `Rietschen` | 5 | `10.11.12.13` | 3× GigE IPs `192.168.11.101-103` |
| [bin/x64/Release/config.ini](../bin/x64/Release/config.ini) | `Staeffelsberg` | 3 | `127.0.0.1` | 1× USB `DEV_1AB22C0AADED` |

The Release copy is the Staeffelsberg deployment. Neither sits at the hardcoded path the binary actually reads —
see [known-issues.md](known-issues.md).

### Example

```ini
[General]
tower_name = Staeffelsberg
image_interval = 3
debug = 0

[Network]
zkms_server_ip = 127.0.0.1
mqtt_user = fwt_gimbal
mqtt_pw = aeroaero

[Camera]
id_Cam1 = DEV_1AB22C0AADED
```

## Command-line flags

Parsed by Boost.Program_options ([main.cpp](../main.cpp) lines 104-153). All take a `bool` value
(presence + value); the code treats *presence* of the option as "on" regardless of the value.

| Flag | Short | Value | Effect |
|------|-------|-------|--------|
| `--help` | `-h` | — | Print options and exit |
| `--init` | `-i` | bool | Run the endstop-finding init sequence before the main loop |
| `--start` | `-s` | bool | Start camera capture automatically (no `start` console command needed) |
| `--demo` | `-d` | bool | Demo/simulation mode: copy `test_smoke.jxl` instead of encoding real frames |

Usage: `./Fire_Gimbal_Control.out --init 1 --start 1`

### Init sequence (`--init`)

When `--init` is set, before entering the loop the program sends to the motor controller, with delays
([main.cpp](../main.cpp) lines 220-241): `r` → `e` → `q` → *(wait 60 s)* → `y` → `ud56` ("set number of
intervals per turn" = 56). This finds endstops and configures the sweep resolution.

## Interactive console commands

While running, lines typed on stdin are parsed by [Parser.h](../Parser.h) (Boost.Spirit Qi) into up to four
tokens: `command device option value`. The grammar expects alphabetic tokens separated by spaces and an
optional trailing number. `CMD_eval` then maps them to actions ([main.cpp](../main.cpp) lines 244-273).

| Type this | Meaning |
|-----------|---------|
| `start` | Start camera acquisition + saver thread |
| `stop` | Stop camera acquisition |
| `debug` | Toggle telemetry printout (`motorctl_info_out`) |
| `set camera fps <value>` | Change camera acquisition frame rate (`AcquisitionFrameRate`) |
| `set camera jxlq <value>` | Set JPEG XL quality/distance (0 = lossless; higher = lossier) |
| `set camera jxle <value>` | Set JPEG XL effort (libjxl effort level) |
| `set camera display <0\|1>` | Toggle live OpenCV preview window |
| `set fps <value>` | Set the **capture interval rate** `imagerate` (images per second logic), not camera fps |
| `set motorctl <cmd>` | Forward a raw command string to the motor controller over serial |
| `exit` | Stop the program (sets `running = false`) |

Notes:
- `set camera ...` options are handled in `VimbaHandler::evaluateCommand` ([Camera.cpp](../Camera.cpp) lines
  241-251); only `fps`, `jxlq`, `jxle`, `display` are recognized.
- Because the grammar tokenizes on spaces with a trailing number, commands like `set motorctl <cmd>` rely on the
  `<cmd>` landing in the `option` field. Numeric-only motor commands and multi-token strings may not parse as
  expected — see [known-issues.md](known-issues.md).

## Raw motor-controller command reference (observed)

These short strings are sent over serial (`sendCommand`) by the program or via `set motorctl`. They are
interpreted by the **motor controller firmware** (not in this repo); listed here for reference of what the
software emits:

| Command | Sent when | Apparent meaning |
|---------|-----------|------------------|
| `r`, `e`, `q` | init sequence | endstop/homing steps |
| `y` | init sequence | (post-home step) |
| `ud56` | init sequence | set intervals-per-turn = 56 |
| `p` | ControlCode 0 capture | stop / advance to next interval |
| `kd<heading>` | ControlCode 1 capture | drive to target heading `<heading>` |