Cap-LoRa-1262

LoRa chat application for M5Stack CardputerZero and the SX1262 radio built into the Cap LoRa-1262 accessory.

Features

• Send and receive LoRa text messages
• Show radio status, RSSI/SNR, SPI probe results, and initialization diagnostics
• Use an SDL desktop display for UI development without Cap hardware

Dependencies

Run the bootstrap script once after cloning this repository:

./bootstrap.sh

It fetches lvgl, spdlog, smooth_ui_toolkit, RadioLib, and pigweed under dependencies/. RadioLib supplies the SX1262 driver. Device builds compile Pigweed's pw_spi_linux, pw_i2c_linux, and pw_digital_io_linux Linux userspace drivers (with their Pigweed dependencies) into the binary; SDL builds do not use Pigweed. SDL builds require SDL2 development files.

Build

For SDL desktop testing:

cmake -S . -B build/sdl -DCAP_LORA_USE_SDL=ON
cmake --build build/sdl -j8

For a native CardputerZero build:

cmake -S . -B build/cp0 -DCAP_LORA_USE_SDL=OFF
cmake --build build/cp0 -j8

The desktop and device binaries are written to dist/sdl/ and dist/device/ respectively.

Run the SDL tests locally with:

cmake -S . -B build/tests -DCAP_LORA_USE_SDL=ON -DBUILD_TESTING=ON
cmake --build build/tests -j8
ctest --test-dir build/tests --output-on-failure

GitHub Actions runs only the device test suite (CAP_LORA_USE_SDL=OFF) and builds the Debian package. SDL builds and tests are reserved for local development.

Startup and shutdown logs are flushed immediately so they survive the forced shutdown deadline. LVGL warnings and assertion failures include their source location. The shutdown signal test enables SPDLOG_LEVEL=debug to log each main-loop phase and prints the process exit code and captured logs on failure. Set SPDLOG_LEVEL=debug when running manually to collect the same diagnostics.

Usage

Run the SDL build with:

LV_SDL_ZOOM=2 ./dist/sdl/Cap-LoRa-1262

Key controls:

• Z/C or Left/Right: switch between Messages and Info
• F/X or Up/Down: select a message or scroll Info; Fn+F/Fn+X selects messages
• Enter: compose a message or reply to the selected message
• Ctrl+C/Ctrl+V: copy the selected message or paste into the editor
• Fn+H (H on desktop): open Help; Esc closes it
• Esc: close a dialog or exit

The SDL build displays the complete LoRa UI and uses a simulated backend for initialization, send, and receive/echo testing. It does not access SPI, GPIO, or I2C; real hardware initialization is performed only by a device build on a CardputerZero with the Cap attached.

Hardware

The device build initializes the Cap's SX1262 over SPI and controls reset, busy, IRQ, and power through the CardputerZero GPIO/I2C interfaces. The backend accepts these optional environment-variable overrides (the defaults match the CardputerZero Cap wiring):

Variable	Purpose
LORA_SPI_DEV	Explicit SPI device path (otherwise probes /dev/spidev0.1, then /dev/spidev0.0)
LORA_RST_CHIP, LORA_RST_OFFSET	GPIO chip and line for SX1262 reset
LORA_BUSY_CHIP, LORA_BUSY_OFFSET	GPIO chip and line for SX1262 BUSY
LORA_IRQ_CHIP, LORA_IRQ_OFFSET	GPIO chip and line for SX1262 IRQ
HAT_5VOUT_CHIP, HAT_5VOUT_OFFSET	Explicit active-low GPIO override for the 5V rail; both values must be set

The Debian package launches the app as the APPLaunch user. That user must be a member of the video, input, gpio, spi, and i2c groups, as configured by the CardputerZero image. A package udev rule grants the gpio group write access only to ext_5v_out/brightness; the UI and radio protocol code do not run as root.

Radio initialization errors and SPI/GPIO diagnostics are shown in the app.

Package

The executable is installed below /usr/share/Cap-LoRa-1262/. The package installs its icon in APPLaunch's shared image directory and its desktop entry under /usr/share/APPLaunch/applications/; these are the paths used by the CardputerZero launcher for dynamic applications. Keeping only these launcher integration files in APPLaunch preserves separation from the LoRa source and executable.

When removing the legacy built-in LoRa page from APPLaunch, keep the launcher's lora display-order token. The desktop entry uses Name=LoRa, and that token keeps this external application in the same position as the former built-in entry. Disable APPLaunch's CONFIG_CP0_LVGL_INIT_LORA (and its RadioLib component if no other consumer remains) before deleting the shared cp0 LoRa sources.

Build the CardputerZero arm64 Debian package on an x86 Linux or WSL2 host with the Docker wrapper:

./packaging/docker/package_deb.sh

The Docker packager downloads the CardputerZero BSP over HTTPS and verifies the published SHA-256 for v0.0.4. For another BSP release, set both BSP_VERSION/BSP_URL and its 64-character BSP_SHA256 before running the wrapper. An unverified archive is refused by default; only a trusted local mirror should use CAP_LORA_ALLOW_UNVERIFIED_BSP=1.

To package natively on a CardputerZero instead, run:

./packaging/deb/package_deb.sh

The generated package is written to dist/:

dist/m5cardputerzero-cap-lora-1262_<version>_m5stack1_arm64.deb

See THIRD_PARTY_NOTICES.md for dependency licenses.