Skip to content
Get started

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 entry
nrf52:
board: adafruit_feather_nrf52840
  • 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_itsybitsy was called adafruit_itsybitsy_nrf52840 before sdk-nrf 2.7 (Zephyr 3.7); both names are accepted, and older versions, including the toolchain: platformio default, need the old one. ESPHome takes the chip (nRF52840, nRF52832, nRF54LM20 or nRF54L15) from the board name; the chip decides which pins are valid. nrf54lm20dk and nrf54l15dk are short names for the Zephyr boards nrf54lm20dk/nrf54lm20a/cpuapp and nrf54l15dk/nrf54l15/cpuapp; both forms are accepted. xiao_nrf54lm20a builds on the nRF54LM20 DK’s Zephyr board with the XIAO’s pins. adafruit_feather_nrf52832 is built on the Zephyr board nrf52dk/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_sd132 uses the nRF52840 flash layout; for the Adafruit Feather nRF52832 use adafruit_nrf52_sd132_v6 or adafruit_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 to false. 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.

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 requires an SWD connection, for which a programmer is necessary. A cheap ST-Link V2 can be utilized.

  1. Connect the board to the PC via SWD.
  2. Run esphome upload yourfile.yaml --device PYOCD.
# Example configuration entry
nrf52:
board: adafruit_feather_nrf52840

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.

  1. 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: JLinkExe on the PATH, then the default install folder (/opt/SEGGER or /Applications/SEGGER): its unversioned JLink folder, then the newest JLink_V* folder.
    • Windows: the install path from the registry, then C:\Program Files\SEGGER and C:\Program Files (x86)\SEGGER in the same folder order. The PATH is not searched, since the Java jlink.exe has the same name.

    So a J-Link on the PATH or in the registry is used even when a newer one is installed in the default folder.

  2. Connect the board to the PC through its debugger USB port.

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

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.

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.

  1. Connect the board to the PC via USB.
  2. Quickly short the reset pin to ground twice.
  3. Copy the UF2 package to the flash drive.

This bootloader supports updates over USB CDC.

  1. Connect the board to the PC via USB.
  2. Quickly short the reset pin to ground twice.
  3. Run esphome upload yourfile.yaml.
# Example configuration entry
nrf52:
board: adafruit_itsybitsy

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

  1. 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.
  2. 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.

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.

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.

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.

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 bootloader

Zephyr 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, RX P0.08) at 115200 baud, which reaches the PC through the board’s USB serial chip; USB_CDC is rejected.
  • dfu is not supported, because it needs USB.
  • dcdc defaults to false: 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.

The Feather comes with one of two Adafruit bootloaders, which expect different SoftDevices and flash layouts:

bootloaderBootloaderSoftDevice
adafruit_nrf52_sd132_v6 (default)The current Adafruit nRF52 BootloaderS132 6.1.1
adafruit_nrf52_sd132_v2The original 0.5.0 bootloader of early boardsS132 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.

  1. Connect the board to the PC via USB.
  2. Run esphome run yourfile.yaml and 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.

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-nrf toolchain (the default) can build for the nRF54LM20; toolchain: platformio is 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 sda and scl both 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: led0

WARNING

Support for the nRF54LM20A is experimental.

The Seeed XIAO nRF54LM20A is supported with board: xiao_nrf54lm20a.

nrf52:
board: xiao_nrf54lm20a

IMPORTANT

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-nrf toolchain; toolchain: platformio is 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 sda and scl both on port 1 or both on port 3.

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_CDC is rejected.
  • The nRF54L15 builds with the default sdk-nrf version. Flashing through the J-Link needs the sdk-nrf toolchain (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 sda and scl on port 1. ESPHome rejects pins on other ports.

There are two ways to reference GPIO pins:

  1. By pin name, e.g., P0.15 or P1.11.
  2. By pin number, e.g., 15 or 43.

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:

ChipValid pins
nRF52840P0.00–P0.31, P1.00–P1.15
nRF52832P0.00–P0.31
nRF54LM20P0.00–P0.09, P1.00–P1.31, P2.00–P2.10, P3.00–P3.12
nRF54L15P0.00–P0.06, P1.00–P1.16, P2.00–P2.10

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:

Terminal window
esphome upload d.yaml

Without a reset pin (uses software reset):

nrf52:
dfu: true

NOTE

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: true
  • 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.19 on nrf52840dongle, which is wired to the dongle’s RESET pin; on other boards a software reset is used when omitted.

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.

nrf52:
reg0:
voltage: 3.3V
uicr_erase: true
  • 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.

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: 500ms

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

If you are using the Adafruit bootloader, upgrade to the latest version: Adafruit nRF52 Bootloader Releases

Try minimum LED blinking config for the board:

supermini-nrf52840

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_led

xiao-nrf52840

nrf52:
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_led

nrf52840-dongle

nrf52:
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_led

Disable DC/DC:

nrf52:
dcdc: false
# Example configuration entry
nrf52:
framework:
version: 2.9.2
  • version (Optional, string): The nrf-sdk version. One of:

    • 2.6.1 : Legacy
    • 2.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 %zu specifier is not handled correctly, which can cause incorrect log output when the logger component is used. Set to false to use the full newlib, which supports all standard printf format specifiers including %zu and 64-bit integers at the cost of a larger binary. Defaults to false when logger component is present, otherwise true.

  • advanced (Optional, mapping): See Advanced Configuration below.

  • 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_after time (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 to true when MCUboot is present and to false otherwise; setting it to true without MCUboot is ignored with a warning.