Rate this page Â
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
An increasing number of MCUs produced in the last decade are shipped with their
primary bootloaders in ROM, unmodifiable by any user operation. On these
devices, including all modern ST Microelectronics and Espressif
microcontrollers, when a RESET
pin is asserted, the device enters this ROM
bootloader. The bootloader can load and execute code from a variety of sources
including Flash, RAM, UART, USB, I2C, or SPI. This ROM bootloader's behavior is
controlled by actively probing those I/O ports and by sampling the state of
"strapping pins" or specially locked "boot option bytes" in flash.
These manufacturer-provided ROM bootloaders present new alternatives for hardware designers - specifically, to perform firmware updates in a manner that is far more flexible in terms of language and RTOS, and far less vulnerable to inadvertent programming bugs.
Beginning with firmware version 3.5.1, the Blues Wireless Notecard is now capable of utilizing these capabilities of modern MCUs, performing firmware updates "from the outside", and not involving the firmware running on the MCU, whatsoever. It can update firmware regardless of RTOS or language, and can be used to switch between them, even modifying flash memory layout and partitioning any time after-the-fact, at the developer's discretion.
By using the Notecard in conjunction with a modern MCU with a ROM bootloader, you can achieve a far more robust form of firmware update that we call Notecard Outboard Firmware Update.
At a high level the process works as follows:
Notecard Outboard Firmware Update is only compatible with the following card.aux modes:
off
dfu
neo-monitor
To take advantage of Notecard Outboard Firmware Update you must lay out several connections between the Notecard's AUX pins and your own host MCU's RESET, BOOT, and UART pins.
The following carriers have the required wiring available out of the box, and are ready-made for using Notecard Outboard Firmware Update:
If you're not using a ready-made carrier, you can still utilize Outboard Firmware Update on most modern STM32 and ESP32 hosts by connecting the following pins.
Pin Mapping Table:
Notecard | MCU |
---|---|
AUX1* | -- |
AUX3 | B0 |
AUX4 | RST |
AUXRX | TX |
AUXTX | RX |
AUX1
- Not DFU in progress (NDFU).
AUX1
has no corresponding pin on the Host MCU; instead, it is used to drive
an external multiplexor (or mux). AUX1
is active LOW
when a DFU is in
progress, otherwise it remains HIGH
.
AUX1
is not enabled by default. It must be explicitly enabled by issuing a
card.aux
request and
specifying "mode":"dfu"
.
Several examples of using Outboard Firmware Update on a variety of different hosts are available in our Notecard Outboard Firmware Update Examples GitHub repository.
In order to use Notecard Outboard Firmware Update you must first configure your
Notecard to receive firmware updates. To do so, you can run the Notecard's
card.dfu
request, setting
"name"
to the architecture of the host (e.g. stm32
, esp32
) and "on"
to
true
.
{"req":"card.dfu","name":"<host_mcu>","on":true}
Now that you've enabled Notecard Outboard Firmware Update, you next need to prepare your firmware image file.
In this section you'll learn how to build a firmware image file for use with Notecard Outboard Firmware Update.
Building your firmware binary itself is not unique to Notecard Outboard Firmware
Update. This is the standard creation of a firmware binary that will be deployed
to a target device. The only thing new is we will be operating on this
binary (.bin
) file instead of immediately installing it on the target device.
When using the Arduino IDE, you can find the location of the binary in the final logs of the compilation step, as illustrated below.
Looking in the folder specified, we will find the .bin
file alongside the
.elf
file mentioned in the build output.
The binpack
utility is provided through the
Notecard CLI. Binpack is used to create a thin
wrapper around your binary, which both offers protection and enables
optimization of binary installation.
The syntax of the binpack
utility is as follows:
notecard -binpack <host_arch> <memory_addr>:<binary.bin> [<memory_addr>:<binary.bin> ...]
<host_arch>
- Replace with the architecture of your host MCU. (See the
card.dfu
request's name
argument
for a list of possible values.)<memory_addr>
- The address* where the binary should be installed.<binary.bin>
- The binary file to package.* Minimally, the page of memory associated with the address provided will be completely erased and rewritten.
Targeting an STM32 device and performing binpack
on the Arduino example
provided above would result in the following syntax:
notecard -binpack stm32 0x8000000:Example1_NotecardBasics.ino.bin
After the command executes, you will see output similar to the following:
2022-10-20-205150.binpack now incorporates 1 files and is 28999 bytes: HOST: stm32 LOAD: Example1_NotecardBasics.ino.bin,0x08000000,0x70a8,0x70a8
Alternatively, targeting an ESP32 device and performing binpack
on the
Arduino example provided above would result in the following syntax:
notecard -binpack esp32 0x10000:Example1_NotecardBasics.ino.bin
The two changes worth noting, are...
<host_arch>
parameter changed from stm32
to esp32
<memory_addr>
parameter changed from 0x8000000
to 0x10000
A simple binary (.bin
) might be stored at 0x08000000
on an STM32,
or at 0x10000
on an ESP32. However, let's focus on something slightly more
complex, like CircuitPython. CircuitPython is typically configured as a 3-part
image containing a UF2 secondary bootloader, a CircuitPython interpreter, and
the CircuitPython scripts.
In order for a CircuitPython script to become a candidate for Binpack, it will first need to be translated from a text file into a binary compatible with the CircuitPython interpreter. To this end, Blues has published a utility, the CircuitPython Filesystem Builder, in order to transform scripts into binaries ready for the interpreter.
Once you have installed the tool following the steps in the README file, you can invoke the tool with the following syntax:
python3 main.py <directory> <output_filename>.cpy
<directory>
- The directory containing the files to store in the filesystem<output_file>
- The file that will ultimately be packaged within the
.binpack
fileExample:
python3 main.py my_cp_app/ scripts.cpy
The .cpy
extension is REQUIRED to facilitate the .binpack
utility.
notecard -binpack stm32 0x8000000:tinyuf2-swan_r5-0.10.1.bin 0x8010000:circuitpython-swan_r5.bin 0x8100000:scripts.cpy
You can see from the call to the binpack
utility, the UF2 bootloader will
be loaded at 0x08000000
, the CircuitPython interpreter will be loaded at
0x08010000
, and the Python script will be loaded at 0x08100000
.
Alternatively, CircuitPython can be flashed as a 2-part Image. This can be useful once you have stopped iterating on your firmware, and no longer plan to flash new firmware from a USB connected laptop. The syntax to perform this operation is shown below:
notecard -binpack stm32 0x8000000:circuitpython-swan_r5-nobootloader.bin 0x8100000:scripts.cpy
As you can see, the UF2 bootloader has been elided, and instead the
CircuitPython interpreter will be loaded directly at 0x08000000
and the
Python script will be loaded at 0x08100000
.
Now that you've built your firmware image file and your Notecard is ready to receive it, your last step is to upload your firmware to Notehub and send it to your devices.
To do so, see our guide on managing host firmware, which shows you how to upload a binary to Notehub, and deploy that binary to individual devices or fleets of devices.
Once you've queued up a firmware update in Notehub, the Notecard detect a new host binary is available on its next sync and download the firmware (up to 1.5MB) into its own flash storage.
The Notecard will then perform a RESET
on the host microcontroller, which
places it into its ROM bootloader. Then, using a microcontroller-specific
communications protocol, the Notecard reprograms the various areas in flash as
directed by instructions within the firmware image file, verifies them via MD5
hashes, and restarts the MCU.