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_itsybitsy_nrf52840, xiao_ble, nrf52840dongle. Other boards should work with those configuration as well.
  • bootloader (Optional, string): Bootloader type. Valid options are mcuboot, adafruit, adafruit_nrf52_sd132, adafruit_nrf52_sd140_v6, adafruit_nrf52_sd140_v7, nrf. Default value depends on board type.
  • dcdc (Optional, boolean): Enable DC/DC converter for REG1 stage. Defaults follow board settings from Zephyr. 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

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_nrf52840

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.

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

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