Documentation Index
Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt
Use this file to discover all available pages before exploring further.
Supported Hardware
The Ground Agent runs on any Linux ARM single-board computer that can host a USB WiFi adapter in monitor mode. The bench build uses a Raspberry Pi 4B. Production builds target Radxa CM3 and CM4 boards.
Required components
Every ground station needs these three things:
- A Linux SBC with at least 1 GB RAM, USB 2.0, and a 64-bit ARM processor
- An RTL8812EU USB WiFi adapter for WFB-ng receive on 5 GHz
- A USB-C power source that can sustain the required output under radio load
Everything else (OLED, buttons, HDMI, 4G modem) is optional but recommended.
Bench build (Raspberry Pi 4B)
This is the fastest way to get a ground station running. Every part is commodity hardware available globally.
| Part | Role |
|---|
| Raspberry Pi 4B (2 GB or 4 GB) | Ground SBC |
| 32 GB SD card (A2 class) | Boot and logs |
| LB-LINK BL-M8812EU2 (RTL8812EU) | WFB-ng radio receiver |
| 2x 5 dBi SMA dual-band antenna | Signal reception |
| USB-C data cable (1 m) | Tether to laptop |
| 5V / 3A USB-C power supply or USB-C PD power bank | Bench or field power |
Physical UI (recommended)
| Part | Role |
|---|
| SSD1306 128x64 I2C OLED (0.96” or 1.3”) | Status display |
| 4x tactile pushbuttons (6mm) | Menu navigation |
| Dupont jumper wires (M-F, 20 pack) | GPIO wiring |
| Protoboard or JST-XH housing | Wire management |
Standalone flight add-ons (optional)
| Part | Role |
|---|
| Micro-HDMI to HDMI cable (1.5 m) | Display output |
| 7” HDMI monitor (1024x600) | Pilot display |
| USB gamepad (Logitech F310 or similar) | Pilot input |
4G modem (optional)
| Part | Role |
|---|
| SIM7600G-H 4G LTE USB modem | Cellular uplink |
| SIM card with data plan | Cellular service |
Production tiers
- Radxa CM3 (RK3566) on a baseboard
- Single RTL8812EU radio
- OLED + 4 buttons on the front panel
- HDMI output
- WiFi AP on the onboard radio
- Compact palm-sized enclosure
Good for field pilots, bench engineers, and single-drone operations.
- Radxa CM4 (RK3588S2) on a baseboard
- Two RTL8812EU radios for antenna diversity
- OLED + 4 buttons on the front panel
- HDMI output
- Internal M.2 slot for 4G modem
- WiFi AP on the onboard radio
- Rugged field enclosure
Good for fleet operators, long-range operations, and commercial use.RTL8812EU details
The RTL8812EU chipset is required for WFB-ng monitor mode reception. It supports 5 GHz operation at up to 29 dBm TX power (800 mW+), though the ground side only uses RX mode.
Not all USB WiFi adapters work. The adapter must use the RTL8812EU or RTL8812AU chipset. Generic “WiFi 6” or “AC1200” adapters almost certainly use a different chipset that does not support monitor mode. The LB-LINK BL-M8812EU2 is the tested reference adapter.
install.sh script handles this automatically. If DKMS build fails (missing kernel headers), the install script reports the error and retries on the next boot after an apt upgrade.
OLED display
Any SSD1306-based or SH1106-based 128x64 I2C OLED works. The agent probes I2C address 0x3C (some clones use 0x3D). The display connects with four wires: SDA, SCL, VCC (3.3 V), and GND.
The 1.3” size is better for field use. The 0.96” size works fine on the bench.
Four tactile momentary pushbuttons wired between GPIO pins and GND. The agent enables internal pull-ups, so no external resistors are needed for the bench build.
| Button | Pi 4B GPIO | Header pin |
|---|
| B1 (Up / Record) | GPIO 5 | Pin 29 |
| B2 (Down / WiFi toggle) | GPIO 6 | Pin 31 |
| B3 (Select / Pair) | GPIO 13 | Pin 33 |
| B4 (Back / Factory reset) | GPIO 19 | Pin 35 |
On boards other than the Pi 4B, the GPIO pin numbers are defined in the HAL board profile YAML. The agent reads the profile at boot and maps buttons accordingly.
Gamepad support
Any USB HID gamepad works for standalone HDMI flight. The Web Gamepad API in Chromium handles mapping. Tested controllers:
- Logitech F310 (USB, reference controller)
- Xbox Series controller (USB or Bluetooth)
- PS4 DualShock (USB or Bluetooth)
- PS5 DualSense (USB or Bluetooth)
- 8BitDo Pro 2 (USB or Bluetooth)
Bluetooth gamepads pair through the setup webapp or the OLED menu.
Power source
The Ground Agent does not require an internal battery. Power it from a wall adapter on the bench or a USB-C PD power bank in the field.
| Operating mode | Planning draw | Power source guidance |
|---|
| Direct/headless node | ~7.5 W | 5 V / 2 A minimum, stronger source preferred on Pi-class boards |
| HDMI kiosk, dual-radio, or uplink-heavy node | ~9-11 W | 5 V / 3 A or equivalent USB-C PD source |
| Supply ceiling | 15 W | Use for margin and brownout prevention |
Mesh role hardware
If you plan to deploy this node as a relay or receiver in a multi-node mesh, you need one extra item beyond the bench build:
| Item | Default | Notes |
|---|
| Second RTL8812EU USB adapter | Yes | The default mesh carrier. Same chip as the primary for inventory simplicity and matched 29 dBm TX power. Plug into a different USB port from the primary. Runs 802.11s for batman-adv on UNII-1 (channel 36 or 40), ~100 MHz guard band from the primary WFB-ng radio on UNII-3. |
| MT7612U USB adapter (e.g. ALFA AWUS036ACM) | Alternative | Mainline mt76 driver. 20 dBm TX power. Good fit when mainline kernel coverage is preferred on the mesh side. |
| MT7921AU USB adapter (e.g. Brostrend AX9L) | Alternative | Mainline mt7921u driver. WiFi 6. 20-23 dBm TX power. Good fit when mesh scales to 3+ nodes and OFDMA helps. |
direct-mode node does not need a second adapter.
Read more about mesh hardware planning in the Local Mesh page.
What is next
