feat: RAK/SX1303 HAL guard, UART onboard GPS, and operator docs

[iceice400]

Summary

Hardens concentrator startup for RAK/SenseCap Pi gateways (SX1302/SX1303), wires onboard UART GPS for the RAK Pi HAT, and documents the sx1261_check_status / lgw_start() failure mode seen on bare-metal RAK V2 installs.

HAL / radio

• Clears non-empty radio.sx1261_spi_path when radio.carrier_type is rak or sensecap_m1 before SX1261 init (prevents got:0x00 expected:0x22 → lgw_start() failed on Pi-invisible SX1261 wiring).
• SPI preflight: missing /dev/spidev0.0 raises a clear error (raspi-config / spi group hints).
• Best-effort sx1302_get_model_id() when the HAL exposes it; startup logs e.g. Concentrator model ID: 0x12 (SX1303).
• meshpoint setup persists radio.carrier_type when a concentrator is detected.

GPS / location

• Implements location.source: uart via UartSource + existing GpsReader (NMEA GGA on /dev/ttyAMA0).
• Config: location.uart_path, location.uart_baud; API + Configuration → GPS UART fieldset.
• Wizard offers live UART GPS when the hardware probe gets a fix.
• GpsReader uses pyserial first for /dev/* device nodes.

Docs

• COMMON-ERRORS, CONFIGURATION, HARDWARE-MATRIX, CHANGELOG (Unreleased), README troubleshooting for SX1261 and UART GPS.

Why

Fleet/support logs from RAK V2 + SX1303 (chip version 0x12) showed fatal startup when Advanced config set sx1261_spi_path on hardware where the SX1261 is not Pi-reachable. Separately, v0.7.5 shipped gpsd + skyplot but left UartSource as a placeholder despite install.sh already enabling /dev/ttyAMA0 for the RAK HAT GPS.

Type

• Bug fix
• Feature
• Docs
• Refactor
• UI
• Installer
• Region support
• Hardware change

Testing

• Local only
• Tested on hardware
• Dashboard tested
• Docs only (doc sections in this PR)

Unit tests (local):

python -m unittest \
  tests.test_sx1302_wrapper_hal_guard \
  tests.test_sx1302_wrapper \
  tests.test_uart_location_source \
  tests.test_location_static_uart_sources \
  tests.test_location_config

All 46 tests in the above set pass locally; HAL tests use mocked ctypes.CDLL.

Manual on device (recommended before merge):

1. radio.sx1261_spi_path: "" and radio.carrier_type: rak → service reaches Application startup complete; journal shows SX1261 spi_path empty or path cleared with warning.
2. location.source: uart, outdoor sky view → Configuration → GPS shows live lat/lon and satellite count.
3. Deliberately set sx1261_spi_path: "/dev/spidev0.1" on RAK → path cleared at startup, service still starts.

Hardware:

• Pi: (awaiting maintainer validation)
• Concentrator: RAK-class HAT, SX1303 (0x12) reported in original issue
• Node/radio: —
• Region: US915
• OS: Raspberry Pi OS Lite aarch64

Impact

• Parsing
• Relay
• TX
• Radio driver
• Region logic
• UI only (GPS card UART fieldset)
• Installer only

Risks: Low for RX/TX path — SX1261 guard only skips/clears config; UART GPS is isolated to the location pipeline. New HAL calls are behind hasattr(lib, "sx1302_get_model_id"). Upgrade requires pip install -r requirements.txt for new pyserial dependency.

Not in scope: HAL lgw_gps_* / PPS timestamp sync (follow-up issue).

Operator notes (post-merge)

# /opt/meshpoint/config/local.yaml
radio:
  sx1261_spi_path: ""
  carrier_type: rak   # from meshpoint setup

location:
  source: uart
  uart_path: /dev/ttyAMA0
  uart_baud: 9600

cd /opt/meshpoint
sudo /opt/meshpoint/venv/bin/pip install -r requirements.txt
sudo systemctl restart meshpoint
meshpoint logs | grep -iE 'SX1261|Concentrator model|LOCATION|concentrator started'

Skyplot az/el/SNR still requires gpsd + USB GPS; UART provides fix + satellite count from GGA.

AI-assisted?

• Yes

Implemented with AI assistance; unit tests run locally; hardware validation offered on RAK V2 + SX1303 SPI.