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_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.
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 Adafruit nRF52 Bootloader
Section titled “Flashing with Adafruit nRF52 Bootloader”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_itsybitsy_nrf52840Flashing 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.
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.
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.
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_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_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)
-
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.