120 lines
5.5 KiB
Markdown
120 lines
5.5 KiB
Markdown
# Moonshine NRF52
|
|
|
|
DIY Meshtastic node variant based on the RF-BM-ND05 nRF52840 module.
|
|
|
|
## Hardware
|
|
|
|
- **MCU module**: RF-BM-ND05 (nRF52840, 512 KB flash / 128 KB RAM)
|
|
- **LF clock**: internal RC (`USE_LFRC`) - RF-BM-ND05 has no 32.768 kHz crystal; using
|
|
`USE_LFXO` without a crystal makes SoftDevice hang in `RTC1_IRQHandler` waiting
|
|
for LFCLK, causing LED-stuck-on and silent BLE failure.
|
|
- **LoRa**: E22-400M33S (SX1268 + 33dBm PA, 2W, 433MHz) - `SX126X_MAX_POWER=2`,
|
|
`TX_GAIN_LORA=25`, `SX126X_PA_RAMP_US=0x07` (3400us ramp). PA has no enable pin
|
|
and draws high transient current on TX; default 22dBm/200us-ramp causes BOD reset.
|
|
POFCON disabled in `variant_nrf52LoopHook()` to prevent POFWARN -> lfs_assert
|
|
-> reboot chain.
|
|
- **GPS**: u-blox (no EN pin)
|
|
- **Battery ADC**: 0.5 voltage divider (equal resistors)
|
|
|
|
## Pin map
|
|
|
|
| Function | Pin | Notes |
|
|
| ------------- | ----- | -------------------------------------- |
|
|
| LED | P0.30 | Active high (`LED_STATE_ON = 1`) |
|
|
| CHARGE_DET | P0.16 | Active high (charging) |
|
|
| BUTTON | P0.27 | User button |
|
|
| BUZZER | P0.26 | PWM buzzer |
|
|
| BATTERY_ADC | P0.05 | 0.5 divider |
|
|
| IIC_SDA | P0.09 | |
|
|
| IIC_SCL | P0.10 | |
|
|
| SPI_MISO | P0.24 | |
|
|
| SPI_MOSI | P0.25 | |
|
|
| SPI_SCK | P0.28 | |
|
|
| LORA_CS | P0.29 | |
|
|
| LORA_DIO1 | P0.21 | IRQ |
|
|
| LORA_BUSY | P0.22 | |
|
|
| LORA_RESET | P0.23 | |
|
|
| LORA_RXEN | P0.11 | TXEN tied to DIO2 internally |
|
|
| GPS_RX (MCU) | P0.07 | Data from GNSS to MCU |
|
|
| GPS_TX (MCU) | P0.08 | Data from MCU to GNSS |
|
|
| UART_TX | P0.14 | Serial2 |
|
|
| UART_RX | P0.15 | Serial2 |
|
|
| UART_RTS | P0.12 | Serial2 flow control (see note) |
|
|
| UART_CTS | P0.13 | Serial2 flow control (see note) |
|
|
|
|
Silkscreen GPS_TX/GPS_RX labels are from the GPS module perspective; Meshtastic
|
|
macros (`GPS_TX_PIN` / `GPS_RX_PIN`) are from the MCU perspective, so they are
|
|
swapped relative to the silkscreen.
|
|
|
|
Note: P0.12/P0.13 are physically wired as RTS/CTS, but the Adafruit nRF52 core's
|
|
`Serial2` singleton uses the 4-argument constructor (`uc_hwFlow = 0`), so
|
|
hardware flow control is not enabled by firmware. These pins are unused unless
|
|
the core is patched.
|
|
|
|
## Build & Flash
|
|
|
|
### Build
|
|
|
|
```sh
|
|
pio run -e moonshine_NRF52_node
|
|
```
|
|
|
|
Uses `PRIVATE_HW` (HardwareModel 255) - no protobuf or `architecture.h` changes
|
|
required.
|
|
|
|
The build links against `nrf52840_s140_v7.ld`, so the application is linked to
|
|
start at `0x27000` and requires the S140 SoftDevice v7.x to be present on the
|
|
chip at `0x0`-`0x26FFF`. The build output (`firmware-*.hex` / `.uf2`) contains
|
|
**only the application**, not the SoftDevice.
|
|
|
|
### Flash (first time on a bare RF-BM-ND05)
|
|
|
|
A factory-fresh RF-BM-ND05 module has **no SoftDevice and no bootloader**. The
|
|
SoftDevice must be flashed once via SWD before the application; otherwise
|
|
`Bluefruit.begin()` fails, `sd_flash_*` calls (LittleFS, NodeDB, config
|
|
persistence) return errors, and the node appears dead.
|
|
|
|
The S140 v7.3.0 SoftDevice hex is shipped in this repo at
|
|
`bin/s140_nrf52_7.3.0_softdevice.hex`. Flash via SWD with OpenOCD (CMSIS-DAP /
|
|
J-Link / ST-Link). The `nrf52_recover` command does a chip-wide ERASEALL through
|
|
the nRF52 CTRL-AP and clears APPROTECT, so it is the recommended first step on a
|
|
fresh module (ebyte/Raytac modules ship with APPROTECT engaged).
|
|
|
|
```sh
|
|
# Full flow: recover (erase all + unlock) -> SoftDevice -> app -> reset
|
|
C:/openocd/bin/openocd.exe -s C:/openocd/share/openocd/scripts \
|
|
-f interface/cmsis-dap.cfg -f target/nrf52.cfg \
|
|
-c "init; nrf52_recover; \
|
|
program bin/s140_nrf52_7.3.0_softdevice.hex verify; \
|
|
program .pio/build/moonshine_NRF52_node/firmware-moonshine_NRF52_node-*.hex verify; \
|
|
reset run; exit"
|
|
```
|
|
|
|
### Flash (app only, SoftDevice already present)
|
|
|
|
When the SoftDevice is already on the chip and only the application changed
|
|
(e.g. after editing the variant and rebuilding), skip `nrf52_recover` and the
|
|
SoftDevice line:
|
|
|
|
```sh
|
|
C:/openocd/bin/openocd.exe -s C:/openocd/share/openocd/scripts \
|
|
-f interface/cmsis-dap.cfg -f target/nrf52.cfg \
|
|
-c "init; \
|
|
program .pio/build/moonshine_NRF52_node/firmware-moonshine_NRF52_node-*.hex verify; \
|
|
reset run; exit"
|
|
```
|
|
|
|
### Notes
|
|
|
|
- The firmware hex filename contains a commit hash (e.g. `2.8.0.421838f`); use
|
|
the actual file produced by `pio run` or a shell glob.
|
|
- The SoftDevice hex occupies `0x0`-`0x26498` (~156 KB) and does **not** write
|
|
UICR, so `nrf52_recover` is safe (UICR resets to defaults).
|
|
- Swap `interface/cmsis-dap.cfg` for `interface/jlink.cfg` or
|
|
`interface/stlink.cfg` if using a different SWD probe.
|
|
- No UF2 bootloader is installed in this flow, so subsequent updates must go
|
|
through BLE DFU (secure DFU service) or SWD again. To enable UF2 drag-and-drop
|
|
updates, flash an Adafruit nRF52 UF2 bootloader
|
|
(https://github.com/adafruit/Adafruit_nRF52_Bootloader) at `0x0` in place of
|
|
the bare SoftDevice - the bootloader bundles its own SoftDevice.
|