Files
2026-09-01 14:53:23 +02:00

116 lines
4.7 KiB
Markdown

# Hardware
## Board
```
Board: Heltec WiFi LoRa 32 V4.3
Model: HTIT-WB32LAF
MCU: ESP32-S3 (16 MB flash, 2 MB PSRAM)
Radio: Semtech SX1262
FEM: KCT8103L (868-928 MHz high-power variant)
```
DUT USB identity (native ESP32-S3 USB):
- factory Arduino firmware enumerates as `usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__F85B1BA1F86C-if00`
- our ESP-IDF firmware / ROM bootloader enumerate as `usb-Espressif_USB_JTAG_serial_debug_unit_F8:5B:1B:A1:F8:6C-if00`
`tools/discover_devices.sh` handles both.
## SX1262 pin mapping — DOCUMENTED + EXPERIMENTALLY VERIFIED
```
SX1262:
NSS GPIO8
SCK GPIO9
MOSI GPIO10
MISO GPIO11
RESET GPIO12
BUSY GPIO13
DIO1 GPIO14
```
Verified: SPI register write/readback passes and GFSK RX runs
(`radio_init` diagnostic: `spi:true, reset:true, tcxo:true`, heartbeat
`chip_mode:5` = RX with plausible RSSI). See docs/FINDINGS.md.
Sources:
- Heltec product manual / wiki, "WiFi LoRa 32 V4":
https://wiki.heltec.org/docs/devices/open-source-hardware/esp32-series/lora-32/wifi-lora-32-v4/
- Heltec schematic: https://resource.heltec.cn/download/WiFi_LoRa_32_V4/Schematic/HTIT-WB32LAF_V4.3.pdf
- RNode_Firmware 1.86 board table via jrl290/RTNode-HeltecV4 `Boards.h`
(working firmware for this exact board):
https://github.com/jrl290/RTNode-HeltecV4
## Status LED — GPIO35 (white), EXPERIMENTALLY VERIFIED
Driven by firmware since the LED-heartbeat build:
solid = booting, 30 ms blip / 2 s = alive in RX, single blink = valid RX,
double blink = repeat transmitted, rapid flash = recovery engaged.
Note: the board has no hardware power LED; before this firmware a powered
board was visually indistinguishable from a dead one, which cost a full
afternoon of RF-only diagnosis (docs/RF_FRONTEND_TESTS.md, FUTURE_UI.md).
## KCT8103L FEM — DOCUMENTED + EXPERIMENTALLY VERIFIED
```
FEM:
POWER GPIO7 supply enable, drive HIGH
CSD GPIO2 chip enable, drive HIGH (internal pull-up on KCT8103L)
CTX GPIO5 path select: LOW = RX/LNA, HIGH = TX/PA
CPS -- wired to SX1262 DIO2 (enable DIO2-as-RF-switch)
```
Notes:
- V4.2 boards use a GC1109 FEM with different control (CSD + CPS, CTX on
DIO2). Do NOT copy V4.2 configuration.
- RNode 1.86 auto-detects the FEM by reading CSD as input after powering
the FEM: KCT8103L pulls HIGH, GC1109 pulls LOW.
- After TX, CTX must be driven LOW again or the FEM stays in TX-bypass and
RX is dead (documented failure mode in RTNode sx126x.cpp).
## TCXO — DOCUMENTED (RNode 1.86), verified working
- DIO3-controlled TCXO, 1.8 V (`SetDIO3AsTCXOCtrl` code 0x02), ~4 ms start.
- After enabling the TCXO, recalibrate all blocks or `XOSC_START_ERR`
persists in device errors.
- OCP register set to 0x28 (RNode 1.86 "OCP_TUNED" for the V4 PA chain).
## SDR
```
Nooelec NESDR SMArt v5
RTL2832U + R820T, USB ID 0bda:2838, serial 33999948
```
### Observer reliability (EXPERIMENTALLY VERIFIED)
This dongle is not a stable instrument and every measurement must record
its state. Three distinct failure modes were observed and characterised:
1. **Sensitivity drift.** Within minutes of continuous streaming the tuner
loses roughly 17 dB. Measured with `hil/sdr_health.py`: fresh after
replug ~ +22 dB mean power at 42.1 dB gain and ~51 dB spectrum span;
after a few minutes ~ +5 dB and ~19 dB span. Captures at "the same
gain" taken minutes apart are therefore NOT comparable.
2. **Tuner death mid-stream.** `r82xx_write: i2c wr failed` appears and the
receiver goes deaf, but `rtl_sdr` does NOT exit -- it keeps producing
nothing. A naive long capture silently returns "no traffic". Observed at
~192 s into a 1800 s capture. Mitigation: bounded capture segments with
`-n` plus `usbreset` between them (`hil/capture_both.sh`).
3. **Descriptor / enumeration faults.** The device can enumerate with empty
descriptor strings (`rtl_test` prints `0: , , SN: `) or disappear from
the bus entirely, in which case `usbreset` reports "No such device
found" and only a physical replug recovers it. Discovery therefore
identifies the dongle by USB VID:PID 0bda:2838, not descriptor text.
`usbreset 0bda:2838` recovers modes 1-3 as long as the device is still
enumerated. Kernel `over_current_count` stayed 0 throughout, so the port
never tripped protection; the dongle's own controller hangs.
Note: "[R82XX] PLL not locked!" printed while tuning is BENIGN -- it is
emitted while `rtl_sdr` probes and disables direct-sampling mode, and
appears on both rtl-sdr-blog and osmocom builds. An earlier revision of
this document blamed `rtl_test -t` for wedging the tuner; that was
DISPROVEN. The real symptom of a deaf receiver is railed, gain-independent
noise, which is what `hil/sdr_health.py` tests for.