Update Moddable Four Firmware with BLE

BLE update illustration

We've recently added the ability to use BLE to update the firmware of Moddable Four and other nRF52 devices with a mobile app. This capability is essential for products in the real-world to allow customers to easily install updates that deliver new features and security fixes. Updating the nRF52 in the field is particularly challenging because of its relatively small flash memory size. Having an off-the-shelf solution available makes a big difference.

How it Works

The bootloader is the software on the nRF52 that receives the update over BLE and installs it. The Moddable SDK for nRF52 uses a derivative of Adafruit's nRF52 bootloader. Unfortunately, that bootloader's support for BLE hasn't been reliable for some time. Moddable investigated the failure and eventually tracked down the problem to a queue overflow. More on how we found that below.

To install the firmware with BLE, you need a mobile app. We install updates using Nordic's nRF Connect for Mobile app for iOS and Android. This is possible because the bootloader implements Nordic's Device Firmware Update Over-the-Air (DFU OTA) protocol over BLE. If your product has its own mobile app, you can integrate DFU OTA support into it to deliver an all-in-one mobile solution to your customers.

Installing firmware with BLE is not typically used during development because Moddable Four is usually connected by a USB interface to a host computer. USB is used to program the Moddable Four and to connect to the xsbug debugger. For nRF52 devices without a USB connection, we can also configure and build for a device that uses a serial interface.

Try it Out

Installing a firmware update with BLE is easy using the nRF Connect mobile app. Before you doing that, you'll need to make sure that your Moddable Four (or other nRF52 board) has the latest bootloader and you'll need to package your firmware update for using with the DFU OTA protocol. The following sections outline the process and link to documents with additional details.

Update your Bootloader

To update the bootloader on Moddable Four, connect it to your computer with a USB cable and double-tap the reset button to put the device into programming mode. A "disk" appears on your desktop named MODDABLE4. Copy the Moddable Four bootloader (v8.1 or later) onto the disk.

For other nRF52 devices, you have to build the bootloader for your device. Then, in a similar way, you'll copy the bootloader to your device.

Moddable uses a modified version of the Adafruit Bootloader. Support of DFU OTA requires v8 or later.

Package Firmware for DFU OTA

When building your application, use the -t ble-package target with mcconfig to package the firmware for DFU OTA. You should create a release build, which is done by omitting both -d and -i options (for debugging and instrumented, respectively) on the command line for mcconfig.

mcconfig -m -p nrf52/moddable_four -t ble-package

The firmware is automatically packaged into a file named ble-package.zip. The output of the mcconfig command includes the path to the firmware image. Transfer that ble-package.zip file to your phone's file system.

Install the Update

Install nRF Connect for Mobile to install the firmware contained in the ble-package.zip file to your nRF52 device.

The nRF52 device must be put into DFU OTA mode to be recognized by nRF Connect for Mobile. This can be done programmatically or with a GPIO. When the device is in DFU OTA mode, the LED double-blinks regularly to indicate advertises that it is ready to receive an update. Follow the steps to connect and transfer your firmware image.

If Something Goes Wrong

When installing new firmware, the previous firmware image is erased and overwritten. There isn't enough flash space in many nRF52 devices to have two copies of the firmware simultaneously. Consequently, if the DFU OTA update fails, the original firmware is already gone. To allow the user to recover, the bootloader automatically enters DFU OTA mode after resetting so the user can try installing again.

Debugging the Bootloader

As mentioned earlier, the Adafruit bootloader that Moddable uses as a starting point for our own bootloader is unreliable for DFU OTA. In our experience, the transfer would fail almost immediately after starting. Judging from reports on the web, this problem that has prevented many developers from using the feature. We decided to try to fix it and eventually succeeded.

Finding the problem was difficult because debugging the bootloader is difficult. We found that the most practical approach was simply to add logging with printf to watch the flow of execution. Even that was difficult because the space allocated to the bootloader is limited, and we needed to add support for the RTT PRINTF facility, which allows the log to be viewed using the J-Link RTT Viewer tool.

With patience, we were able to discover that deep within the BLE callbacks a queue in the bootloader was overflowing, which caused the transfer to fail. Simply increasing the queue size allows it to work reliably.


Moddable has done important work to enable firmware updates on nRF52 products built using Embedded JavaScript, including Moddable Four. This allows developers to support this fundamental capability with very little effort. This is great news for users of their products, because they can easily keep their devices up to date with the latest features and fixes.