feat: Add NiceRF LoRa2021 (LR2021 Gen 4) variant support by c03rad0r · Pull Request #2739 · meshcore-dev/MeshCore

c03rad0r · 2026-06-10T00:00:16Z

Summary

Adds MeshCore support for the NiceRF LoRa2021 module (Semtech LR2021 Gen 4) on ESP32-C3_Mini_V1 development board.

Hardware

Component	Details
MCU	ESP32-C3_Mini_V1 (Maker go, 22.52x18mm, USB-C, 4MB flash)
Radio	NiceRF LoRa2021 (Semtech LR2021 Gen 4, 19.72x15mm, 18-pin)
Antenna	Wire dipole (~8.2cm for 868 MHz Sub-GHz)
Cost	~$8 total (MCU + radio module)
Frequency	Sub-GHz: 150-960 MHz + 2.4 GHz (dual-band)

RadioLib Class

Uses the LR2021 class (extends LRxxxx → PhysicalLayer). This is a separate RadioLib class from LR1121 (which extends LR11x0). RadioLib v7.6.0 (already in MeshCore deps) includes LR2021 support.

Key differences from SX1262:

IRQ on DIO9 (not DIO1) — set via irqDioNum = 9 + setDioFunction(9)
setRxBoostedGainMode(uint8_t level) takes 0-7, not bool
No DIO2-as-RF-switch (NiceRF handles internally)
Crystal oscillator (XTAL), not TCXO — tcxoVoltage = 0
getPacketLength() override handles header errors (same as LR1110 pattern)

Known Issue: Arduino SPI

The Arduino SPIClass on ESP32-C3_Mini_V1 returns all-zero SPI responses, causing RADIOLIB_ERR_SPI_CMD_FAILED (-707). The same hardware works with ESP-IDF's spi_bus_initialize().

This variant includes EspIdfHal.h — a custom RadioLib HAL that bypasses Arduino SPIClass and uses ESP-IDF's spi_bus_initialize() / spi_device_polling_transmit() directly. This is the same approach used in our ESP-IDF tracker firmware.

Root cause hypothesis: The ESP32-C3 has one SPI peripheral (FSPI/SPI2_HOST). The Arduino SPIClass may not properly reconfigure FSPI when the SPI pins differ from the default boot-time configuration (our board uses GPIO2/6/7 instead of default SPI pins).

If anyone has insight into why Arduino SPI fails on this board, I would love to fix this properly and remove the custom HAL.

Build Targets

All verified building against dev branch:

Target	Flash	RAM	Status
`LR2021_companion_radio_usb`	542 KB (41%)	140 KB (43%)	✅
`LR2021_repeater`	—	—	✅
`LR2021_room_server`	—	—	✅
`LR2021_secure_chat`	—	—	✅
`LR2021_kiss_modem`	—	—	✅

All fit within ESP32-C3 4MB flash. Reference build (Heltec_v3_companion_radio_ble) passes — no regressions.

Files Added

Radio Helpers (in `src/helpers/radiolib/`)

CustomLR2021.h — Extends LR2021, adds std_init(), isReceiving(), getPacketLength() override
CustomLR2021Wrapper.h — Extends RadioLibWrapper, implements setParams(), doResetAGC(), getSpreadingFactor()

Board Variant (in `variants/nicerf_lr2021/`)

platformio.ini — 5 build environments with LR2021 pin mapping
target.h / target.cpp — Radio init via EspIdfHal
NiceRFLR2021Board.h — Board class (deep sleep, battery ADC)
EspIdfHal.h — ESP-IDF SPI HAL (documented workaround)

Board Definition (shared)

boards/esp32c3_supermini.json — ESP32-C3 SuperMini V1 board definition
variants/esp32c3_supermini/pins_arduino.h — Pin mapping (D0-D10 = GPIO0-GPIO10)

Testing

All build targets compile on dev branch
No regressions on reference builds
Flash to ESP32-C3_Mini_V1 + NiceRF LoRa2021 hardware
Radio init succeeds
Noise floor calibration: -102 dBm stable
Companion connects via meshcore-cli v1.5.7
Advert TX verified
Two-device encrypted chat (second board in progress)
Community node reception test (Berlin, no nearby nodes found indoors)

Related to [Feature request] LilyGo T-Watch S3 + T3S3 (LR1121 / SX1280) board support + a 2.4 GHz LoRa frequency plan #2678 — LR2021 also supports 2.4 GHz LoRa (future work)
Related to [Suggestion] [repater] Support multiple radios, to build backhauls or bridges. #2441 — LR2021 is dual-band (Sub-GHz + 2.4 GHz), relevant to multi-radio
Note: LR2021 is a different RadioLib class from LR1121 (PRs Lilygo T3S3 LR1121 Variant Support #2696, Add MuziWorks Base Duo board support (nRF52840 + LR1121) 🤖🤖 #2198) — not conflicting

Pin Mapping

ESP32-C3_Mini_V1  →  NiceRF LoRa2021
3V3               →  Pin 1 (VCC)
GND               →  Pin 2,8,11,12,18
D2 (GPIO2)        →  Pin 3 (MISO)
D7 (GPIO7)        →  Pin 4 (MOSI)
D6 (GPIO6)        →  Pin 5 (SCK)
D10 (GPIO10)      →  Pin 6 (NSS/CS)
D4 (GPIO4)        →  Pin 7 (BUSY)
D3 (GPIO3)        →  Pin 14 (RST)
D5 (GPIO5)        →  Pin 15 (DIO9/IRQ)

Adds MeshCore support for the NiceRF LoRa2021 module (Semtech LR2021 Gen 4) on ESP32-C3_Mini_V1 development board. RadioLib LR2021 class (extends LRxxxx -> PhysicalLayer). This is a separate class from LR1121 (extends LR11x0). Key differences from SX1262: - IRQ on DIO9 (not DIO1): irqDioNum=9 + setDioFunction(9) - setRxBoostedGainMode(uint8_t 0-7) vs bool - No DIO2-as-RF-switch (NiceRF handles internally) - Crystal oscillator (XTAL): tcxoVoltage=0 - getPacketLength() override handles header errors Uses ESP-IDF SPI HAL (EspIdfHal) because Arduino SPIClass returns all-zero responses on the ESP32-C3_Mini_V1 with non-default SPI pins. Direct spi_bus_initialize() works correctly. See EspIdfHal.h for details. Build targets: companion_usb/ble/wifi, repeater, room_server, secure_chat, kiss_modem. All verified building. Hardware tested: radio init OK, noise floor -102 dBm, companion connects via meshcore-cli v1.5.7, advert TX verified.

c03rad0r · 2026-06-10T06:11:48Z

Community mesh test (Berlin): Prior to opening this PR, I tested the LR2021 + ESP32-C3 against the live Berlin MeshCore community mesh:

Discovered community relays and contacts via the MeshCore Android companion app
Sent and received messages on the public group channel with users multiple hops away
Confirmed multi-hop flood routing works correctly through the LR2021
Validated interoperability with the standard EU MeshCore PHY (869.618 MHz, SF8, BW62.5, CR4/5)

ripplebiz · 2026-06-23T02:05:59Z

Looks good. Just a small suggestion: I'd probably move the IDF Hal to /src/helpers/radiolib, as it's related only to RadioLib and could potentially be re-used by other variants

c03rad0r · 2026-06-24T14:55:04Z

Thanks for the detailed review @oltaco! I'm working through all 4 items:

SPI: Investigating SPIClass(0) / FSPI approach — will update with results
getPacketLength override: Reviewing whether LR2021 actually needs it — will remove if not confirmed necessary
IRQ constants: Will switch to RADIOLIB_LR2021_IRQ_* chip-specific constants
irqDioNum: Will make configurable via -D LR2021_IRQ_DIO platformio build flag

Will push updates to this branch soon.

… constants (meshcore-dev#3), make irqDioNum configurable (meshcore-dev#4)

…, keep EspIdfHal as opt-in via USE_ESPIDF_HAL

…meshcore-dev#4)

@ripplebiz

…estion Move the ESP-IDF SPI HAL from the variant-specific directory to the shared helpers/radiolib/ directory, making it available for reuse by other ESP32 variants that may need the same SPI workaround. Addresses feedback from @ripplebiz: 'I'd probably move the IDF Hal to /src/helpers/radiolib, as it's related only to RadioLib and could potentially be re-used by other variants' Also update the include path in target.cpp to use the shared location.

c03rad0r · 2026-07-05T16:12:27Z

Thanks again @oltaco and @ripplebiz! All review items are now addressed and tested on real hardware. Latest commit: 05ad173.

Review items resolved:

SPI — SPIClass(0) (oltaco): Switched to static SPIClass spi(0) (FSPI) as default. EspIdfHal is now opt-in via -D USE_ESPIDF_HAL. (e5a0e5b)
getPacketLength override (oltaco): Removed entirely — not confirmed necessary on LR2021. (627909a)
LR2021 IRQ constants (oltaco): Now uses RADIOLIB_LR2021_IRQ_PREAMBLE_DETECTED / RADIOLIB_LR2021_IRQ_LORA_HEADER_VALID with #ifdef fallback to LR11X0_IRQ_*. (627909a)
Configurable IRQ DIO (oltaco): -D LR2021_IRQ_DIO=9 in platformio.ini, irqDioNum = LR2021_IRQ_DIO instead of hardcoded. (627909a, 684e9d9)
EspIdfHal location (ripplebiz): Moved to src/helpers/radiolib/EspIdfHal.h — reusable by other variants. (05ad173)

Build verification: All 7 LR2021 targets + 2 reference targets (Xiao_C3, Heltec_v3) compile clean. No regressions.

2-device hardware test: Two ESP32-C3 + LR2021 boards, ~10cm apart, EU MeshCore PHY (869.618 MHz, SF8, BW62.5):

Board Update README.md #2 (repeater): boots, generates Ed25519 identity (53A53B5D...), starts broadcasting adverts
Board General Feedback #1 (companion): boots, receives Board Update README.md #2's advert packet at 19s — cross-board flood routing confirmed
Previously validated against live Berlin community mesh (multi-hop, encrypted chat)

Ready for another pass when you have a moment.

c03rad0r · 2026-07-05T16:44:41Z

Full hardware test evidence (annotated serial logs, build matrix, wiring diagram, test timeline) published on Nostr:

https://npub1l06qpv6kr4l4sfjqm30jcd0jdtqlrel5nhhdtxfprjdu6dfyns0qnghahp.nsite.lol/

Includes 2-device cross-board flood routing confirmation, all 9 build targets, and the EspIdfHal explanation.

Enables USE_ESPIDF_HAL in platformio.ini to ensure reliable SPI communication on ESP32-C3 boards where SPIClass(0) may return zeros.

Your Name added 2 commits June 10, 2026 05:13

fix: adapt to upstream dev API changes (setParams, getSpreadingFactor)

0696114

oltaco requested changes Jun 23, 2026

View reviewed changes

Comment thread variants/nicerf_lr2021/target.cpp

Comment thread src/helpers/radiolib/CustomLR2021.h Outdated

Comment thread src/helpers/radiolib/CustomLR2021.h

oltaco requested changes Jun 23, 2026

View reviewed changes

Comment thread src/helpers/radiolib/CustomLR2021.h Outdated

c03rad0r added 3 commits June 24, 2026 22:04

fix: remove getPacketLength override (meshcore-dev#2), use LR2021 IRQ…

627909a

… constants (meshcore-dev#3), make irqDioNum configurable (meshcore-dev#4)

fix: try standard SPIClass(0) per reviewer suggestion (meshcore-dev#1)…

e5a0e5b

…, keep EspIdfHal as opt-in via USE_ESPIDF_HAL

fix: add configurable LR2021_IRQ_DIO=9 build flag per review feedback (…

684e9d9

…meshcore-dev#4)

c03rad0r mentioned this pull request Jun 25, 2026

Performance research: RadioLib per-packet overhead caps FLRC throughput at ~80 kbps on ESP32-C3 #2841

Closed

c03rad0r marked this pull request as ready for review July 5, 2026 17:30

c03rad0r requested a review from oltaco July 5, 2026 17:30

fix: enable ESP-IDF HAL by default for LR2021 variant

886b23d

Enables USE_ESPIDF_HAL in platformio.ini to ensure reliable SPI communication on ESP32-C3 boards where SPIClass(0) may return zeros.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: Add NiceRF LoRa2021 (LR2021 Gen 4) variant support#2739

feat: Add NiceRF LoRa2021 (LR2021 Gen 4) variant support#2739
c03rad0r wants to merge 7 commits into
meshcore-dev:devfrom
c03rad0r:feature/nicerf-lr2021-variant

c03rad0r commented Jun 10, 2026 •

edited

Loading

Uh oh!

c03rad0r commented Jun 10, 2026

Uh oh!

ripplebiz commented Jun 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

c03rad0r commented Jun 24, 2026

Uh oh!

c03rad0r commented Jul 5, 2026

Uh oh!

c03rad0r commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

c03rad0r commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Hardware

RadioLib Class

Known Issue: Arduino SPI

Build Targets

Files Added

Radio Helpers (in src/helpers/radiolib/)

Board Variant (in variants/nicerf_lr2021/)

Board Definition (shared)

Testing

Related

Pin Mapping

Uh oh!

c03rad0r commented Jun 10, 2026

Uh oh!

ripplebiz commented Jun 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

c03rad0r commented Jun 24, 2026

Uh oh!

c03rad0r commented Jul 5, 2026

Uh oh!

c03rad0r commented Jul 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

c03rad0r commented Jun 10, 2026 •

edited

Loading

Radio Helpers (in `src/helpers/radiolib/`)

Board Variant (in `variants/nicerf_lr2021/`)