SWAP firmware loader
- Introduction
- Installation
- Building compatible images from Arduino
- Usage
- Flash architecture
- How it works
- Potential problems
- Firmware server
SWAP firmware loader (or RF loader as named in the source files) is a wireless bootloader developed to download code from a central server in the SWAP network. This wireless bootloader is only compatible with panStamp NRG. Adding support on the AVR modules for this bootloader is still pending. Thus, all the chapters below make reference to the NRG platform.
This process has to be done out of the Arduino IDE, from a system terminal or console
- Plug your panStamp onto a panStick and connect it to a USB port
- Enter arduino/hardware/panstamp/msp430/bootloaders/rf and open Makefile
- In Makefile edit "SERPORT" and "TOOLCHAIN" according to the serial port where your panStamp is connected
- From the system terminal, run "make" for compiling
- Run "make bsl-flash" to install the bootloader into your panStamp NRG 2/1.1 or "make gdb-flash" for panStamp NRG 1.0
In order to build HEX files compatible with the wireless bootloader we need to go back to the Arduino IDE. Turn on the "Wireless bootloader" option from "Tools->Wireless bootloader" and then compile from "Sketch->Verify/Compile" or with Ctrl+R. Arduino will store the hex file in a temporary directory. Enable compilation verbose from "File->Preferences" before compiling to show the location of the binary files in your computer. This HEX file is prepared to work with the wireless uploader that you flashed into your module in the installation step.
Run SWAPdmt-cmd
python swapdmt.py
After starting the SWAPdmt session enter the path to the firmware image (HEX file)
>> hexfile path_to/myhexfile.hex
Now put the panStamp in programming mode. For a node with address 0x12 we would run the following command from SWAPdmt:
>> node 0x12 program
In case your device is sleeping you will have to restart it right after running the above command. After this, the panStamp will enter in upgrade mode and will start downloading the binary information from SWAPdmt.
This bootloader sits on top of user flash and takes only 3.2 KB. I can co-exist with other serial bootloaders as GDB or Texas Instrument's BSL.
The serial bootloader always brings the stack pointer to address 0x8000. In case the wireless loader is not installed then the user application will be automatically called. Otherwise, the wireless bootloader starts and goes to UPGRADE mode when 1) no user application is flashed or 2) a specific memory location in RAM (0x2BFF) is zero. As you may guess, this memory location is controlled by the user application so when it wants to start a wireless upgrade, it sets the memory at that location to zero and jumps to the SWAP loader. All this is already handled by the SWAP stack, so when we want to do a wireless upgrade of any NRG node, we have only to send a command to the device (switch SWAP state to UPGRADE mode (5)).
Once in wireless upgrade mode (SWAP firmware loader running) the transfer mechanism works more or less like a FTP download; the device sequentially queries the server for a specific line from the HEX file until the end of the file is reached. This method has the advantage of giving the device full control over the transfer process so that, for example, when a line is not correctly received the device can ask the server again. Another particularity is that the device receives the HEX file almost in raw format so it can check the CRC field from every line (HEX line CRC, not to confuse with wireless packet CRC) for possible errors.
The MCU has no place in flash or RAM to buffer the whole firmware image before flashing the user space. As result, the application is flashed "line by line" along the transfer process. This means that a power outage on either the device or the firmware server might abort the firmware upgrade before its completion. In this case, the device would stay in wireless upgrade so that the process could be later restarted as far as the device remains powered.
Wireless upgrade is not a low-power mode so, mainly for battery-powered nodes, you should pay attention to the correct completion of the wireless firmware upgrade. Otherwise the node might remain in upgrade mode forever, until the battery runs out.
The firmware server is a key part in the wireless upgrade process. It stores the new firmware image and splits it into lines, each of them is then passed to the device by means of a SWAP status packet (register ID 0x0B). In order to simplify the boot code in the wireless node, firmware servers must be configured with address 0x01. At the moment of writing this documentation only SWAPdmt (command-line version) implements this feature.