NRF52 Platform
This component contains platform-specific options for the NRF52 platform.
NOTE
Support for all aspects of ESPHome on the NRF52 is still in development.
# Example configuration entrynrf52: board: adafruit_feather_nrf52840Configuration variables
Section titled “Configuration variables”- board (Required, string): The board type. Valid options are
adafruit_feather_nrf52840,adafruit_feather_nrf52832,adafruit_itsybitsy,xiao_ble,nrf52840dongle,nrf54lm20dk(experimental),nrf54l15dk(experimental),xiao_nrf54lm20a(experimental). Other boards should work with those configuration as well.adafruit_itsybitsywas calledadafruit_itsybitsy_nrf52840before sdk-nrf 2.7 (Zephyr 3.7); both names are accepted, and older versions, including thetoolchain: platformiodefault, need the old one. ESPHome takes the chip (nRF52840, nRF52832, nRF54LM20 or nRF54L15) from the board name; the chip decides which pins are valid.nrf54lm20dkandnrf54l15dkare short names for the Zephyr boardsnrf54lm20dk/nrf54lm20a/cpuappandnrf54l15dk/nrf54l15/cpuapp; both forms are accepted.xiao_nrf54lm20abuilds on the nRF54LM20 DK’s Zephyr board with the XIAO’s pins.adafruit_feather_nrf52832is built on the Zephyr boardnrf52dk/nrf52832, see Adafruit Feather nRF52832. - bootloader (Optional, string): Bootloader type. Valid options are
mcuboot,adafruit,adafruit_nrf52_sd132,adafruit_nrf52_sd132_v6,adafruit_nrf52_sd132_v2,adafruit_nrf52_sd140_v6,adafruit_nrf52_sd140_v7,nrf. Default value depends on board type.adafruit_nrf52_sd132uses the nRF52840 flash layout; for the Adafruit Feather nRF52832 useadafruit_nrf52_sd132_v6oradafruit_nrf52_sd132_v2, see Bootloader. - dcdc (Optional, boolean): Enable DC/DC converter for REG1 stage. Defaults follow board settings from
Zephyr, except on
adafruit_feather_nrf52832, where it defaults tofalse. External LC filters must be connected to the DC/DC regulator pins if it is being used. The advantage of using a DC/DC regulator is that the overall power consumption is normally reduced as the efficiency of such a regulator is higher than that of a LDO. ⚠️ Warning: Enabling DC/DC may cause the board to fail to boot if external LC filter is misconfigured or is poor quality. - dfu (Optional): Enter DFU mode automatically when flashing; see DFU.
- reg0 (Optional): Configure the REGOUT0 output voltage; see REGOUT0.
Getting Started
Section titled “Getting Started”The nRF52840 requires a bootloader, with three supported options: MCUboot, Adafruit nRF52 Bootloader, and the Nordic Open DFU Bootloader (factory-flashed on the nRF52840 Dongle). It is recommended to use MCUboot as it supports OTA (Over-The-Air) updates with rollback. Boards with the Adafruit nRF52 Bootloader can be updated over BLE with Adafruit BLE OTA. Your board most likely comes with a manufacturer-provided bootloader. ESPHome determines the bootloader type based on the board name.
Examples of low power nRF52840 boards.
Flashing with MCUboot
Section titled “Flashing with MCUboot”Flashing with MCUboot requires an SWD connection, for which a programmer is necessary. A cheap ST-Link V2 can be utilized.
- Connect the board to the PC via SWD.
- Run
esphome upload yourfile.yaml --device PYOCD.
# Example configuration entrynrf52: board: adafruit_feather_nrf52840Flashing with a SEGGER J-Link
Section titled “Flashing with a SEGGER J-Link”Boards with a SEGGER J-Link probe, such as the debugger built into Nordic development kits, can be flashed over SWD
with the J-Link tools. This needs the sdk-nrf toolchain (the default); it does not work with
toolchain: platformio.
-
Install the J-Link Software and Documentation Pack from SEGGER. On macOS it can also be installed with Homebrew:
brew install --cask segger-jlink. ESPHome uses the first J-Link it finds that has its library next to it, in this order:- Linux and macOS:
JLinkExeon thePATH, then the default install folder (/opt/SEGGERor/Applications/SEGGER): its unversionedJLinkfolder, then the newestJLink_V*folder. - Windows: the install path from the registry, then
C:\Program Files\SEGGERandC:\Program Files (x86)\SEGGERin the same folder order. ThePATHis not searched, since the Javajlink.exehas the same name.
So a J-Link on the
PATHor in the registry is used even when a newer one is installed in the default folder. - Linux and macOS:
-
Connect the board to the PC through its debugger USB port.
-
Run
esphome upload yourfile.yaml --device JLINK.
ESPHome resets the chip after flashing, so the new firmware starts straight away.
When bootloader is mcuboot (the default on the nRF54 boards), you can also choose the J-Link’s serial port
instead of JLINK; ESPHome then flashes through the J-Link that port belongs to.
If the J-Link output says that the chip is protected, the chip must be erased (recovered) once, for example with
Nordic’s nRF Connect for Desktop
Programmer or nrfutil device recover. Then flash again.
Flashing with a CMSIS-DAP Probe
Section titled “Flashing with a CMSIS-DAP Probe”Boards with a built-in CMSIS-DAP debugger, such as the Seeed XIAO nRF54LM20A, are flashed through it when you
run esphome upload yourfile.yaml and choose the board’s serial port. This needs bootloader
to be mcuboot, the default on the nRF54 boards.
If flashing fails because the chip is locked, the upload error prints a pyocd erase ... --mass command that
uses ESPHome’s own pyOCD and the selected probe. Run it once, then upload again.
Flashing with Adafruit nRF52 Bootloader
Section titled “Flashing with Adafruit nRF52 Bootloader”These steps do not apply to the Adafruit Feather nRF52832, which has no native USB; see Adafruit Feather nRF52832.
For flashing via a flash drive.
- Connect the board to the PC via USB.
- Quickly short the reset pin to ground twice.
- Copy the UF2 package to the flash drive.
This bootloader supports updates over USB CDC.
- Connect the board to the PC via USB.
- Quickly short the reset pin to ground twice.
- Run
esphome upload yourfile.yaml.
# Example configuration entrynrf52: board: adafruit_itsybitsyFlashing the Nordic nRF52840 Dongle (PCA10059)
Section titled “Flashing the Nordic nRF52840 Dongle (PCA10059)”The dongle ships with Nordic’s Open DFU Bootloader factory-flashed at the top of
flash (0xE0000–0x100000). ESPHome reserves that region and boots your
application directly after the MBR page — no custom bootloader is built.
The bootloader speaks Nordic’s Secure DFU protocol, so ESPHome packages and
uploads the firmware with Nordic’s nrfutil. The first build downloads it from
Nordic, together with its nrf5sdk-tools command, into ESPHome’s tools cache;
nothing has to be installed by hand.
First flash and recovery
Section titled “First flash and recovery”- Connect the dongle to the PC and press the RESET button (the small button on the side of the PCB, next to the USB connector). The red LED fades in and out while the bootloader is running.
- Run
esphome run yourfile.yaml. ESPHome builds the firmware and sends the DFU package to the dongle over USB CDC.
The same procedure recovers a device whose application won’t boot; the factory bootloader is never erased by application uploads.
Updating a running device
Section titled “Updating a running device”With dfu: true in the nrf52 configuration, esphome upload reboots the running application
into the bootloader itself and flashes it: the dongle has a GPIO wired to its RESET pin (P0.19),
which the dfu component uses as its reset_pin on this board
without being told, and the factory bootloader stays in DFU mode after a pin reset. The bootloader
shows up as its own USB device, so the upload looks for it rather than for the port you named.
Without dfu:, press RESET while the application runs to drop back into the bootloader, then
upload again.
OTA updates
Section titled “OTA updates”The Open DFU Bootloader has no secondary slot to stage a download into, so
over-the-air updates are not supported with this bootloader. Choose mcuboot
(with an SWD connection) on boards where wireless updates are required.
On-board LEDs
Section titled “On-board LEDs”All four on-board LEDs are active-low, so set inverted: true on their pins so
that on lights the LED. LD1 is a dedicated green LED on P0.6; LD2 is an RGB LED
with red on P0.8, green on P1.9 and blue on P0.12, and turning on more than one
channel at a time blends the colors.
Adafruit Feather nRF52832
Section titled “Adafruit Feather nRF52832”The Adafruit Feather nRF52832 is supported with board: adafruit_feather_nrf52832.
nrf52: board: adafruit_feather_nrf52832 # bootloader: adafruit_nrf52_sd132_v2 # for boards with the original 0.5.0 bootloaderZephyr has no board definition for this Feather, so ESPHome builds it on the Zephyr board nrf52dk/nrf52832,
which has its console UART on the same pins.
- The nRF52832 needs sdk-nrf 2.9.2 or newer, the default. An older version is rejected, and so is
toolchain: platformio. - The nRF52832 has no USB. Logs go to UART0 (TX
P0.06, RXP0.08) at 115200 baud, which reaches the PC through the board’s USB serial chip;USB_CDCis rejected. - dfu is not supported, because it needs USB.
dcdcdefaults tofalse: the Feather’s bootloader and the Arduino core leave the regulator in LDO mode, while the nRF52 DK the build is based on turns DC/DC on.
Bootloader
Section titled “Bootloader”The Feather comes with one of two Adafruit bootloaders, which expect different SoftDevices and flash layouts:
bootloader | Bootloader | SoftDevice |
|---|---|---|
adafruit_nrf52_sd132_v6 (default) | The current Adafruit nRF52 Bootloader | S132 6.1.1 |
adafruit_nrf52_sd132_v2 | The original 0.5.0 bootloader of early boards | S132 2.0.1 |
To find out which one a board has, check the boot log: when the bootloader is older than 0.11.0, the logger
prints a warning with its version, and the original bootloader shows up as version 0.5.0. If the wrong value is
set, the bootloader refuses the firmware package and the upload fails with an error from adafruit-nrfutil;
set the other value and run esphome run yourfile.yaml again, which builds a new package for it.
Flashing
Section titled “Flashing”- Connect the board to the PC via USB.
- Run
esphome run yourfile.yamland pick the board’s serial port. ESPHome builds the firmware and then uploads it.
ESPHome uploads over serial DFU through the board’s USB serial chip. adafruit-nrfutil resets the board into the
bootloader through the chip’s DTR line, so no button press and no 1200 baud touch is needed. No UF2 file is
made for this board; the build gives a hex file and the DFU zip package.
Nordic nRF54LM20 DK
Section titled “Nordic nRF54LM20 DK”WARNING
Support for the nRF54LM20 is experimental.
The nRF54LM20 DK (PCA10184) is supported with board: nrf54lm20dk.
nrf52: board: nrf54lm20dk- The nRF54LM20 needs sdk-nrf 3.4.1 or newer. When
framework: version:is not set, ESPHome uses 3.4.1 for this board; an older version is rejected. - Only the
sdk-nrftoolchain (the default) can build for the nRF54LM20;toolchain: platformiois rejected. - Flash the board through the on-board J-Link debugger: connect the IMCU USB port and follow Flashing with a SEGGER J-Link.
- Logs go to UART0 by default, which is the J-Link virtual COM port on the IMCU USB port.
- The hardware watchdog is turned on automatically.
- I²C uses the TWIM21 peripheral, which can only use pins in its own power domain, all on one
port: put
sdaandsclboth on port 1 or both on port 3. ESPHome rejects other pins.
The buttons on the DK pull their pin to ground when pressed, so set inverted: true and turn on the pull-up.
The LEDs light up when their pin is high. For example:
binary_sensor: - platform: gpio name: "Button 0" pin: number: P1.26 inverted: true mode: input: true pullup: true
output: - platform: gpio pin: P1.22 id: led0Seeed XIAO nRF54LM20A
Section titled “Seeed XIAO nRF54LM20A”WARNING
Support for the nRF54LM20A is experimental.
The Seeed XIAO nRF54LM20A is supported with board: xiao_nrf54lm20a.
nrf52: board: xiao_nrf54lm20aIMPORTANT
The board has no built-in antenna. Connect an external 2.4 GHz antenna, or Bluetooth, Thread and Zigbee will not work.
- As on the DK, it needs sdk-nrf 3.4.1 or newer and the
sdk-nrftoolchain;toolchain: platformiois rejected. - Logs go to UART0 by default, which is the board’s USB serial port.
- Flash it over USB, see Flashing with a CMSIS-DAP Probe.
- I²C uses the TWIM21 peripheral, as on the DK. Put
sdaandsclboth on port 1 or both on port 3.
Nordic nRF54L15 DK
Section titled “Nordic nRF54L15 DK”WARNING
Support for the nRF54L15 is experimental.
The nRF54L15 DK (PCA10156) is supported with board: nrf54l15dk.
nrf52: board: nrf54l15dk- The nRF54L15 has no USB device. Logs go to UART0, which is the J-Link virtual COM port;
USB_CDCis rejected. - The nRF54L15 builds with the default sdk-nrf version. Flashing through the J-Link needs the
sdk-nrftoolchain (the default). - Flash the board through the on-board J-Link debugger, see Flashing with a SEGGER J-Link.
- The hardware watchdog is turned on automatically.
- I²C uses the TWIM21 peripheral, which can only use pins in its own power domain: put
sdaandsclon port 1. ESPHome rejects pins on other ports.
GPIO Pin Numbering
Section titled “GPIO Pin Numbering”There are two ways to reference GPIO pins:
- By pin name, e.g.,
P0.15orP1.11. - By pin number, e.g.,
15or43.
The pin number is the port number times 32 plus the pin on that port, so P1.11 is 43.
Which pins exist depends on the chip:
| Chip | Valid pins |
|---|---|
| nRF52840 | P0.00–P0.31, P1.00–P1.15 |
| nRF52832 | P0.00–P0.31 |
| nRF54LM20 | P0.00–P0.09, P1.00–P1.31, P2.00–P2.10, P3.00–P3.12 |
| nRF54L15 | P0.00–P0.06, P1.00–P1.16, P2.00–P2.10 |
DFU (Device Firmware Update)
Section titled “DFU (Device Firmware Update)”The dfu component enables automatic entry into DFU (Device Firmware Update) mode by monitoring
the USB CDC serial connection. When a host opens the port at 1200 baud, the component triggers
a reset to put the device into DFU mode. It needs a chip with USB, so it is not supported on the nRF52832 or
nRF54L15.
Opening the port at 2001 baud instead reboots the device straight back into its application,
without entering DFU mode, regardless of whether reset_pin is set. The USB CDC has no reset line,
so host tools such as the Device Builder use this for the Reset device action in the logs view.
ESPHome uses this component internally when uploading firmware via:
esphome upload d.yamlExample Configuration
Section titled “Example Configuration”Without a reset pin (uses software reset):
nrf52: dfu: trueNOTE
The pinless path issues a software reset and triggers the bootloader via the
retained GPREGRET register. It is less reliable than the dedicated reset
pin and the upload may need to be retried.
With a dedicated reset pin:
nrf52: dfu: reset_pin: number: 14 inverted: trueConfiguration variables
Section titled “Configuration variables”- reset_pin (Optional, Pin): The pin to use to trigger a hardware reset.
This pin should be connected to the MCU’s reset line or to a circuit that causes the bootloader to enter DFU mode after reset.
Defaults to
P0.19onnrf52840dongle, which is wired to the dongle’s RESET pin; on other boards a software reset is used when omitted.
REG0 Output Voltage (REGOUT0)
Section titled “REG0 Output Voltage (REGOUT0)”Output voltage from the REG0 regulator stage, which powers the GPIO pins when the board operates in high-voltage mode.
This setting can only be changed a limited number of times, unless uicr_erase is set to true.
Requires mcuboot or adafruit bootloader version 0.9.3 or higher.
Example Configuration
Section titled “Example Configuration”nrf52: reg0: voltage: 3.3V uicr_erase: trueConfiguration variables
Section titled “Configuration variables”- voltage (Required, voltage): The desired output voltage - must be one of 1.8V, 2.1V, 2.4V, 2.7V, 3.0V, 3.3V.
- uicr_erase (Optional, bool): If set to true, the User Information Configuration Registers (UICR) will be erased before writing the new voltage setting. ⚠️ Warning: Enabling this may cause the board to fail to boot if misconfigured. Default is false.
Powering a GPIO-Gated Peripheral Rail
Section titled “Powering a GPIO-Gated Peripheral Rail”Some nRF52 boards — mostly cheap hobby clones such as the “SuperMini nRF52840” (nRFMicro-style boards) — have no pull-up resistor on the GPIO pin that gates their external peripheral header. Without one, that pin floats at an indeterminate voltage instead of the rail reliably being on, so anything wired to that header (sensors, displays, etc.) may not receive stable power.
To check whether your board needs this before flashing, power the board on (without power_supply configured
yet) and measure the candidate pin against ground with a multimeter: a genuine pull-up holds it close to the
board’s GPIO supply voltage (typically 3.3V) on its own, while a floating pin settles at an indeterminate voltage
instead (around 1.9V was observed on a “SuperMini nRF52840” clone).
The Power Supply component already covers this case: with enable_on_boot: true on
an internal pin, it sets up before any bus, so the rail is confirmed on before
I²C or SPI try to use it.
power_supply: - id: ext_vcc pin: P0.13 enable_on_boot: true enable_time: 500msP0.13 is the external-VCC gate on nice!nano and SuperMini-nRF52840-style boards — check your own board’s
schematic for the equivalent pin. enable_time is the delay other components wait for after the rail turns on,
to let its voltage settle before anything uses it; 500ms was enough on a “SuperMini nRF52840” clone, but measure
your own board’s actual settle time rather than copying this value. See the Power Supply
page for the full set of configuration variables.
Troubleshooting
Section titled “Troubleshooting”Flashing is unstable
Section titled “Flashing is unstable”If you are using the Adafruit bootloader, upgrade to the latest version: Adafruit nRF52 Bootloader Releases
How to start
Section titled “How to start”Try minimum LED blinking config for the board:
nrf52: board: adafruit_itsybitsy
esphome: name: supermini-nrf52840
logger: level: DEBUG
output: - platform: gpio pin: P0.15 id: red_led
interval: - interval: 1s then: - output.turn_on: red_led - delay: 0.5s - output.turn_off: red_lednrf52: board: xiao_ble
esphome: name: xiao-nrf52840
logger: level: DEBUG
output: - platform: gpio pin: P0.26 id: red_led
interval: - interval: 1s then: - output.turn_on: red_led - delay: 0.5s - output.turn_off: red_lednrf52: board: nrf52840dongle
esphome: name: nrf52840-dongle
logger: level: DEBUG
output: - platform: gpio pin: number: P0.6 inverted: true id: green_led
interval: - interval: 1s then: - output.turn_on: green_led - delay: 0.5s - output.turn_off: green_ledBoard does not boot
Section titled “Board does not boot”Disable DC/DC:
nrf52: dcdc: falseFramework
Section titled “Framework”# Example configuration entrynrf52: framework: version: 2.9.2Configuration variables
Section titled “Configuration variables”-
version (Optional, string): The nrf-sdk version. One of:
2.6.1: Legacy2.9.2: Stable (default)3.2.0: Experimental (no Zigbee support)3.4.1: Required for the nRF54LM20 and its default there
-
libc_nano (Optional, boolean): Use the newlib-nano C library variant, newlib-nano produces a smaller binary but does not support all printf format specifiers. Notably, the
%zuspecifier is not handled correctly, which can cause incorrect log output when the logger component is used. Set tofalseto use the full newlib, which supports all standard printf format specifiers including%zuand 64-bit integers at the cost of a larger binary. Defaults tofalsewhenloggercomponent is present, otherwisetrue. -
advanced (Optional, mapping): See Advanced Configuration below.
Advanced Configuration
Section titled “Advanced Configuration”- enable_ota_rollback (Optional, boolean): Enable OTA rollback support. When enabled, the bootloader will
automatically roll back to the previous firmware if the device crashes or resets before the boot is marked as
successful. This works in conjunction with the safe_mode component - after the
boot_is_good_aftertime (default 60s), the firmware is marked as valid. Since ESPHome 2026.8.0, an orderly shutdown — entering deep sleep, a restart or a shutdown — also counts as a successful boot and marks the firmware as valid. If the device crashes before the firmware is marked as valid, it will roll back to the previous working firmware. Rollback needs MCUboot, either as the bootloader or as the second stage used by zephyr_mcumgr. Defaults totruewhen MCUboot is present and tofalseotherwise; setting it totruewithout MCUboot is ignored with a warning.