Copilot instructions for loramodem

Repository at a glance

Project: LoRa KISS modem (Zephyr RTOS)
Purpose: Bridge a KISS serial interface to a LoRa radio (two threads: serial → LoRa, LoRa → serial).
Key components: app/ (Zephyr application), drivers/lora/lr11xx (Semtech LR11xx driver), boards/ (board overlays).

Quick commands

Build for a board (recommended): west build -b app Example: west build -b heltec_wifi_lora32_v3 app
Flash the built image: west flash
Open Zephyr menuconfig: west build -b app -t menuconfig
CMake alternative (repo root): cmake -S app -B build && cmake --build build

Testing & lint

Testing strategy (from CLAUDE.md): unit tests run on host (arm64/x86) with a mocked HAL; integration tests run on target hardware. No repo-level test runner or lint targets are present by default — look for a tests/ or scripts/ directory if added.

High-level architecture (big picture)

app/ contains the Zephyr application (app/src/*.c). main.c starts two cooperative threads:
- kiss_rx_thread: reads bytes from the KISS UART, decodes frames (kiss.c), handles SetHardware commands, and calls lora_modem_send().
- lora_rx_thread: polls lora_modem_recv() with a finite timeout and writes received payloads as KISS frames to the UART.
KISS protocol implementation: app/src/kiss.c, kiss.h — encoder/decoder and SetHardware sub-command definitions.
Radio abstraction: app/src/lora_modem.c, lora_modem.h — stores runtime params (g_params) protected by a mutex and snapshots params at send/recv time so changes take effect on the next call.
HW driver: drivers/lora/lr11xx implements Zephyr's lora_driver_api. Hardware-specific SPI/GPIO HAL pieces live in lr11xx_hal.c.
Build integration: app/CMakeLists.txt registers drivers/lora/lr11xx as an extra Zephyr module (ZEPHYR_EXTRA_MODULES).

Key repository conventions and patterns

Chosen nodes and aliases:
- The KISS UART is resolved from a chosen node: loramodem_kiss_uart (board overlay must define it).
- LoRa device is expected as DT alias lora0 (DEVICE_DT_GET(DT_ALIAS(lora0))).
Kconfig / defaults:
- app/prj.conf contains project defaults (frequency, SF, BW, TX power, stack sizes, heap pool setting used by the app).
- Runtime radio params are read from Kconfig at init (lora_modem_init) and stored in g_params.
Radio parameter updates:
- lora_modem_set_params() validates values and updates g_params under mutex; changes take effect when lora_modem_send() or lora_modem_recv() is next called (thread-safe snapshotting).
KISS SetHardware mapping:
- See kiss.h for sub-commands (SET_FREQ, GET_PARAMS, etc.) and main.c for how responses are encoded and sent.
Board overlays and confs:
- Overlays live in boards/ or board-specific .overlay files. App-level overrides can live in app.overlay or per-board .conf files.
Memory & testing notes (from CLAUDE.md):
- Target memory budget and testing strategy are documented in CLAUDE.md (unit tests on host, integration on target).

Files to read first when exploring code

app/src/main.c, app/src/kiss.c/h, app/src/lora_modem.c/h, drivers/lora/lr11xx/{.c,.h}, app/prj.conf, app/CMakeLists.txt, CLAUDE.md

AI & editor configs found

CLAUDE.md contains project constraints and test strategy; consult it for memory and testing guidance.
.vscode/settings.json points the CMake source directory to app/ in the original developer setup.
.claude/settings.local.json contains allowed webfetch domains for the Claude assistant.

If you (the user) want, Copilot sessions should:

Prefer reading the files listed above first.
Respect chosen DT nodes (loramodem_kiss_uart, alias lora0) and Kconfig defaults in app/prj.conf.
When suggesting code changes, keep stack/heap and RAM budgets in CLAUDE.md in mind.