Hardware & boards

Reference target: Seeed XIAO ESP32S3 + Wio-SX1262

The first-class development target (and what CI’s firmware build pins). Pin map (verified against Meshtastic’s variants/esp32s3/seeed_xiao_s3/variant.h):

Signal	GPIO
LORA_SCK	7
LORA_MISO	8
LORA_MOSI	9
LORA_CS	41
LORA_RESET	42
SX126X_BUSY	40
SX126X_DIO1 (IRQ + sleep wake)	39
SX126X_RXEN (RF switch RX enable)	38
SX126X_TXEN	not wired (DIO2 drives TX path)
User button	21
LED	48

Radio init facts that will destroy hardware or sensitivity if wrong:

DIO2 is the RF switch TX control (setDio2AsRfSwitch(true)), RXEN is GPIO 38 via setRfSwitchPins(38, RADIOLIB_NC). RadioLib then guarantees the LNA/PA paths are switched before any TX/RX — never drive these manually.
TCXO on DIO3 at 1.8 V (tcxoVoltage = 1.8 in begin()); a wrong voltage here can cook the TCXO on some modules.
DC-DC regulator mode (useRegulatorLDO = false).
On deep sleep, hold LORA_CS high (parasitic current + floating-CS bus garbage — Meshtastic learned this the hard way, sleep.cpp:303).
Remote signed Admin may force tx.enabled off only. It persists the same receive-only master switch as the local tx off console command and clears queued RF frames; remote TX enablement, PA power, frequency-window, and retune enablement remain unsupported. Stored non-anchor lane.plan rows become active only after the local lane retune on console opt-in on this reviewed SX1262 target, and TX still requires the separate local tx on antenna/siting check.

firmware/variants/xiao_wio_sx1262.h encodes all of the above; new boards get a new variant header, never inline #ifdefs in logic code.

Routing-redesign ERB/RACK or TX-contention work also inherits the Phase 4 RF validation checklist in docs/research/routing-redesign/PHASE4_RF_VALIDATION_PLAN.md; CI and agents can prepare that evidence path, but only measured radio evidence plus human sign-off can close it.

Variant contract

A variant header must define: SPI pins, CS/RESET/BUSY/DIO1, RF-switch topology (one of RFSW_DIO2, RFSW_RXEN_TXEN, RFSW_NONE — the enum forces new boards to state their switch wiring explicitly; omitting it is a compile error, because an unstated RF switch is how PAs die), TCXO voltage or 0.0f for XTAL, regulator mode, battery sense pin/divider or none, PSRAM expectation, and the USB stack flavor (S3 native / nRF52 TinyUSB).

Porting notes

nRF52 (RAK4631 etc.): same SX1262, different HAL; no light sleep needed (POWER.md). TinyUSB ECM instead of NCM.
Linux (lrcd): SX1262 HATs (Waveshare, Pi supHAT) via spidev + gpiod lane driver, or no radio at all (TCP-only backbone router). Multiple HATs = true parallel lanes (RADIO.md).
LR1121 / SX127x: lane preset table carries per-chip capability masks; P6/P7 (BW500) are masked off for SX127x. Don’t gate features on chip names in logic code — gate on capability bits from the variant.

RF capability descriptor

Every node reports in HELLO caps: frequency window it may legally/physically emit in (band-pass filter limits for filtered routers), max preset, PA ceiling dBm. This feeds lane planning and DCC burst-lane intersection (RADIO.md) — hardware limits are protocol data, not folklore.