fwt_software/docs/build-and-setup.md

# Build & Setup

This guide covers building the binary and the host setup needed to run it. For the things that will stop a
clean reproduction on a fresh machine, read [known-issues.md](known-issues.md) alongside this page.

## Toolchain

- **g++** with **C++17** (`-std=c++17`), GNU Make. The C file `ini.c` is compiled with **gcc**.
- Linux. Developed/deployed on a tower PC (LattePanda Sigma) running Linux; serial device is `/dev/ttyACM0`.

See [Makefile](../Makefile) — `CXXFLAGS := -std=c++17 -g -Wall -I.`

## Dependencies

The link line in the [Makefile](../Makefile) is:

```
-lpaho-mqttpp3 -lpaho-mqtt3a -lopencv_core -lopencv_highgui -ljxl -ljxl_threads -lboost_program_options -lVmbC -lVmbCPP
```

| Dependency | Libraries linked | Headers used | Typical source |
|------------|------------------|--------------|----------------|
| **Eclipse Paho MQTT C++** | `paho-mqttpp3`, `paho-mqtt3a` | `mqtt/async_client.h` | `libpaho-mqttpp-dev` / build from source (also needs Paho MQTT C) |
| **OpenCV** | `opencv_core`, `opencv_highgui` | `opencv2/opencv.hpp` | `libopencv-dev` |
| **libjxl (JPEG XL)** | `jxl`, `jxl_threads` | `jxl/encode.h`, `jxl/encode_cxx.h`, `jxl/thread_parallel_runner*.h` | `libjxl-dev` / build from source |
| **Boost** | `boost_program_options` | `boost/asio.hpp`, `boost/program_options.hpp`, `boost/spirit/include/qi.hpp`, `phoenix.hpp` | `libboost-all-dev` (or at least program_options, system, and the header-only Asio/Spirit) |
| **Allied Vision Vimba X SDK** | `VmbC`, `VmbCPP` | `VmbC/VmbC.h`, `VmbCPP/VmbCPP.h` | **Proprietary** — download from Allied Vision (see below) |

`cxxopts.hpp` is bundled but **not used** (the active CLI parser is Boost.Program_options); it does not need to
be installed.

### Debian/Ubuntu package hint

The non-proprietary dependencies are roughly:

```bash
sudo apt install build-essential libboost-all-dev libopencv-dev libjxl-dev \
                 libpaho-mqttpp-dev libpaho-mqtt-dev
```

Package names vary by distro/version; `libjxl-dev` and the Paho C++ packages may not exist on older releases and
then have to be built from source. This machine is **Manjaro/Arch** — use `pacman`/AUR equivalents
(`boost`, `opencv`, `libjxl`, `paho-mqtt-c`, `paho-mqtt-cpp`).

### Allied Vision Vimba X SDK (proprietary — required)

`VmbC`/`VmbCPP` are **not** available through any package manager. Download and install the Vimba X SDK from
Allied Vision (<https://www.alliedvision.com/en/products/software/vimba-x-sdk/>). After install you typically
need to:

- Make the SDK headers visible to the compiler (add `-I<vimbax>/api/include`) and the libs to the linker
  (`-L<vimbax>/api/lib`), and/or add the lib dir to `LD_LIBRARY_PATH` / an `ld.so.conf.d` entry at runtime.
- Run the SDK's transport-layer setup so cameras are discoverable (GenICam GenTL producers).

The current [Makefile](../Makefile) assumes the headers/libs are already on the default include/link paths; on
a fresh machine you will likely need to extend `CXXFLAGS`/`LDFLAGS` with the SDK paths.

## Build

```bash
make            # compiles ini.c, main.cpp, MQTT.cpp, Camera.cpp → bin/Fire_Gimbal_Control.out
make clean      # removes object files and the binary
```

- Object files land in `obj/` (the Makefile uses `OBJDIR := obj`).
- The output binary is `bin/Fire_Gimbal_Control.out`.

> Note: the committed build artifacts live under `bin/x64/Release/` and `obj/x64/Release/`, but the current
> Makefile writes to `bin/` and `obj/`. The `x64/Release/` layout is the *deployed* layout the running binary
> expects for config and image output (see below and [known-issues.md](known-issues.md)).

## Directory layout (build vs. deployed)

```
<repo>/
├── obj/                         ← Makefile object output
├── bin/Fire_Gimbal_Control.out  ← Makefile binary output
└── bin/x64/Release/             ← deployed/runtime directory
    ├── Fire_Gimbal_Control.out  ← deployed binary
    ├── config.ini               ← runtime config (differs from repo-root config.ini)
    ├── startup_gimbal.sh        ← launches with --start 1
    ├── startup_gimbal_with_init.sh ← launches with --init 1 --start 1
    ├── test_smoke.jxl           ← demo-mode placeholder image
    ├── RGB/  (ACR/  NIR/)       ← image output folders (created on demand)
    └── crash_genicam.txt        ← captured GenICam trigger error log (reference)
```

`compile_commands.json` is present for editor/clangd integration.

## Host setup to run

1. **Serial device** — the motor controller must enumerate as `/dev/ttyACM0` at 115200 8N1. Add your user to
   the `dialout` group (or set a udev rule) for non-root access:
   ```bash
   sudo usermod -aG dialout "$USER"   # log out/in afterward
   ```
2. **Cameras** — connect the Allied Vision cameras and confirm Vimba X can see them (vendor `VimbaXViewer` /
   `ListCameras`). The camera IDs in `config.ini` must match (GigE IPs like `192.168.11.101` or USB
   `DEV_...` IDs). For GigE, configure the host NIC on the `192.168.11.x` subnet.
3. **MQTT broker** — a broker must be reachable at the `zkms_server_ip` from `config.ini` with the configured
   username/password. **The program exits immediately if it cannot connect** ([main.cpp](../main.cpp) lines
   162-165). For local testing run e.g. Mosquitto and point `zkms_server_ip` at `127.0.0.1`.
4. **Paths** — the binary reads config from a hardcoded absolute path and writes images under
   `$HOME/projects/Fire_Gimbal_Control/...`. See [known-issues.md](known-issues.md) for the exact paths and how
   to satisfy them.

## Run

```bash
# from the deployed directory
./Fire_Gimbal_Control.out --help          # show options
./Fire_Gimbal_Control.out --start 1       # connect, start camera capture immediately
./Fire_Gimbal_Control.out --init 1 --start 1   # find endstops, then start
./Fire_Gimbal_Control.out --demo 1        # demo mode (copies test_smoke.jxl instead of encoding)
```

Type `exit` on the console (or send EOF) to stop. See [configuration.md](configuration.md) for all CLI flags
and the interactive console commands.