Skip to content
Get started

nRF52 Firmware Updates

The nRF52 platform supports firmware updates over the air (OTA). This page covers updates with MCUboot; boards with the Adafruit nRF52 Bootloader can be updated over BLE with Adafruit BLE OTA instead. MCUboot can be used as a second-stage bootloader, enabling OTA updates even when the board was originally shipped with a different bootloader.

To flash firmware onto the device, you can use any of the tools or libraries listed in the Zephyr MCUmgr documentation. Firmware updates are also available via the ESPHome command-line interface. For flashing over BLE, the MCUmgr Web Tool provides a convenient browser-based interface.

In addition to OTA updates, ESPHome also supports a “safe mode” to help with recovery if/when updates don’t work as expected. This is automatically enabled by this component, but it may be disabled if desired. See Safe Mode for details.

# Example configuration entry
ota:
  - platform: zephyr_mcumgr

Configuration variables

Section titled “Configuration variables”
  • status (Optional, mapping): Configure a GPIO pin that MCUboot will use as an indication LED during OTA updates.
  • transport (Optional, mapping): Specifies the transport method used by Zephyr MCUmgr for OTA updates. By default, Bluetooth Low Energy (ble: true) is enabled.

status

Section titled “status”

An optional LED that MCUboot controls during firmware updates to show progress.

# Example configuration entry
ota:
  - platform: zephyr_mcumgr
    status:
      pin: P0.13

Configuration variables

Section titled “Configuration variables”
  • pin (Required, Pin Schema): The GPIO pin connected to the LED. The pin can be configured as active-low or active-high using the inverted option.

transport

Section titled “transport”

Zephyr MCUmgr can operate over multiple transport protocols, which are selected via configuration options.

# Example configuration entry
ota:
  - platform: zephyr_mcumgr
    transport:
      ble: true
      hardware_uart: CDC

Configuration variables

Section titled “Configuration variables”
  • ble (Optional, boolean): Enable Bluetooth Low Energy transport for MCUmgr OTA. Default false once transport is set; leaving out transport enables BLE.
  • udp (Optional, boolean): Enable the SMP over UDP transport, so the device can be updated over an IPv6 network such as Thread. It also listens on IPv4 when the network component enables IPv4. Default false.
  • hardware_uart (Optional, enum): Select a hardware UART interface to use for MCUmgr OTA communication. This is used when updating devices over a serial interface rather than BLE. Options: CDC, CDC1, UART0, UART1.

Updating Over the Network

Section titled “Updating Over the Network”

With udp: true the device runs the MCUmgr server on UDP port 1337 and can be updated by IP address, hostname or mDNS (.local) name:

# Example configuration entry
ota:
  - platform: zephyr_mcumgr
    transport:
      udp: true

The UDP transport adds about 5 KB of RAM: a listener thread with its receive buffer, two packet buffers, and the Zephyr connection manager thread it needs.

WARNING

The UDP endpoint has no authentication or encryption. Any host that can reach the device, including hosts on your LAN behind a Thread border router, can upload firmware to it or reset it without knowing the Thread network key. Enable udp only on networks where every host is trusted, or block UDP port 1337 to the device on the border router or firewall.

Usage

Section titled “Usage”

To connect and update the device over BLE:

Terminal window
esphome upload nrf52_device.yaml --device BLE

Or connect to a specific BLE address:

Terminal window
esphome upload nrf52_device.yaml --device 00:11:22:33:44:55

To connect and update the device over serial:

Terminal window
esphome upload nrf52_device.yaml

Or connect to a specific serial:

Terminal window
esphome upload nrf52_device.yaml --device /dev/ttyACM0

To update over the network when udp is enabled, pass the device’s hostname, mDNS name or IP address:

Terminal window
esphome upload nrf52_device.yaml --device my-device.local

WARNING

The image slots end below the partition of the Zephyr Coredump component, so enabling or disabling that component moves them. Flash the device over USB once after such a change. An OTA update alone leaves the installed MCUboot with the old slot layout, and later OTA updates would silently fail.

Troubleshooting

Section titled “Troubleshooting”
  • The build fails because the image is too large for MCUboot: MCUboot keeps part of each image slot for its own bookkeeping, so the largest image it can swap in is a little smaller than the slot. The build checks the image against that limit and says how many bytes to remove, for example by leaving out components or lowering the logger level.
  • An upload is refused because an earlier update is still pending: the device holds an update it has not applied yet, for example because it was never restarted. Restart the device to apply it. If it then still runs the old firmware, the pending image could not be swapped in, and the device must be flashed once over USB.
  • Over the network, the upload reports that the device did not answer after the reset: swapping the image and rejoining the network can take a minute or more. Check that the device runs the new firmware once it is back.

See Also

Section titled “See Also”