Skip to content

Configuration Reference

OWTS configuration is primarily device-local and persisted via NVS (firmware).

Device mode

The device runs in one of two modes:

  • aircraft
  • winch

Mode affects which radio path is active and which API routes are meaningful. See:

Radio RF settings (frequency + TX power)

If built with CONFIG_OWTS_RADIO_USE_SX1262, OWTS exposes RF settings via /api/radio and the on-device UI (Config page).

  • Defaults and band rules: see main/radio/owts_radio_settings.h (EU868-style target, FLARM avoidance band, grid snapping, ERP hints). GET /api/radio exposes the effective limits and modem_backend as "gfsk" or "lora".
  • SRD profiles: NVS stores srd_profile_id (index into allowed_srd_profiles in GET /api/radio). Each profile lists frequency segment, duty cap (duty_cycle_max_ppm), power cap, and modem compatibility; the UI shows overlap warnings (e.g. FLARM).
  • FLARM avoidance window: firmware rejects configured centre frequencies that fall in the blocked band (see header constants).
  • Frequency stepping: frequency_hz_step in GET /api/radio matches the compiled PHY (GFSK RX bandwidth or LoRa BW) so the grid stays consistent with validation.

The firmware persists RF settings in NVS. Validation happens both for hardware limits and for the compiled-in regulatory hints (EU-DE SRD band).

Aircraft SRD duty (RAM): per-packet on-air intervals (modem TX start → TX_DONE) are accumulated in 1 s buckets over a 3600 s sliding window and compared to the active profile’s duty_cycle_max_ppm unless duty_cycle_lab_override (NVS) is set for bench use. See Firmware → Radio.

Modem backend (compile-time, not NVS)

GFSK vs LoRa is chosen with OWTS_RADIO_USE_LORA_BACKEND in main/radio/owts_radio_settings.h (rebuild both aircraft and winch with the same value). REST payloads and protobuf on-air framing are shared; only the PHY modem configuration differs.

Aircraft pre-TX listen (always on)

With SX1262 enabled, the aircraft task always runs a channel check before each telemetry slot in a burst. Timing and RSSI threshold are compile-time constants in main/radio/owts_radio_settings.h (OWTS_RADIO_LBT_* for GFSK; LoRa uses CAD via OWTS_RADIO_LORA_CAD_*).

See Firmware → Radio (SX1262) for behaviour and log lines.

Winch WS2812 LED strip

When enabled at build time (CONFIG_OWTS_WINCH_USE_WS2812), the winch mode can drive a WS2812/WS2812B LED strip as a speed indicator.

  • GPIO (build-time): CONFIG_OWTS_WINCH_WS2812_GPIO (default: GPIO42)
  • Runtime settings (NVS + API): GET/PATCH /api/winch/led
  • count (3..100)
  • brightness (0..1) — active speed segment
  • dim_below_factor (0..1) — brightness scale for segments below current IAS
  • reversed (bool)
  • color_order (rgb, grb, brg, rbg, bgr, gbr)

Notes:

  • Default color order: most WS2812B strips are GRB, so firmware defaults to grb.
  • Boot self-test (winch mode): the strip shows RED → BLUE → GREEN for ~500 ms each. Green is kept on during boot, then the strip is turned off right before continuous RX is armed.
  • Reboot semantics: PATCH /api/winch/led persists settings and then reboots the device (frontend warns about this).

Frontend proxy (local dev)

For local UI development against a device, configure frontend/.env as described in:

  • frontend_readme.md