meshtastic_firmware/variants/nrf52840/diy/moonshine_NRF52/readme.md

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: multi-module compatible (SX1262 / SX1268 / RF95 / LLCC68 / LR1121 / LR2021) with TCXO
• 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

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).

# 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:

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.