By Marcus Linderoth, Thingsquare VP of EngineeringWhen updating the software of already deployed devices, we use wireless Over-The-Air (OTA) updates. But there is a time before deployment, when the hardware is blank, and you need to program the first firmware image onto your devices.
Today we look at how to use the thsq-device-flasher tool to burn individual firmware images onto a large number (10-1000) of devices. This saves considerable time during development, testing, proof-of-concept deployments, as well as during factory manufacturing of a fleet of devices.
Throughout this article, we use the LPSTK hardware platform from Texas Instruments, and its CC1352r1 microprocessor.
There is a time before deployment, when the hardware is blank, and you need to program the first firmware image onto your devices.
What is a Firmware Image?
A firmware image is a dump of the entire memory of the microprocessor of your hardware device. The firmware image contains the program, operating system, communication stack, device drivers, and other software that your device needs. Without this, the microprocessor cannot function.
When you receive a microprocessor from the microprocessor manufacturer, it is completely blank. To make it do something useful, you must burn your own firmware image into it’s flash memory. This is called programming the device.
Programming a device is usually done with a special piece of hardware, called a programmer. The programmer is connected to your target hardware with a special cable called a JTAG cable. Through the JTAG cable, the programmer can erase and write new data to the device’s internal flash memory. To use the programmer, you typically need a piece of software from the hardware manufacturer.
Creating Unique Firmware Images
By default, when you compile a firmware image, that firmware image contains no identifying information about the device. It is a blank device.
When a blank device boots up for the first time, it will need to be invited to a network, through which it can connect to its backend server and obtain its unique identity, security credentials, and other information. This process takes about 30 seconds for each device. When programming many devices, this process can therefore take a substantial amount of time.
Enter the thsq-device-flasher tool.
The thsq-device-flasher takes a blank firmware image, populates it with a unique identity for a device, including the necessary security keys, and optionally binds the device to a given network, then burns this firmware image into the flash memory of the device.
The tool reads out the MAC address from the device hardware before flashing the firmware image into its memory, so that it can recreate the same identity for a device, in case the device should need to be physically reprogrammed.
With thsq-device-flasher, it is easy to manually program large numbers of devices.
Let’s look at how it is done.
How to Program Devices with thsq-device-flasher
The thsq-device-flasher tool needs NodeJS and the TI Uniflasher software to be installed.
Install the Software
Step 1 is to install the software:
- Install UNIFLASH from Texas Instruments: http://www.ti.com/tool/UNIFLASH
- Install NodeJS version 12 (LTS): https://nodejs.org/en/
- Open the command prompt and install the thsq-device-flasher npm module:
npm install -g thsq-device-flasher
Build the Firmware Binary
Step 2 is to build your firmware binary. (Talk to your Thingsquare customer contact in case you need help with this, as the build procedure may be different between different customer projects.)
We assume that the firmware binary is called code.bin.
Get a Frontend ID and User API Token
To be able to assign the device to a specific product and user account, the thsq-device-flasher needs the frontend ID and user API token for the user to which the new devices should be assigned.
The frontend ID is the first string of numbers and letters in the frontend URL for one of your product’s frontends.
For example, the default Thingsquare product as the URL https://b72af87d-42d7-4f09-bf8c-b9f721a3e6ef.developer.thingsquare.com/. The frontend ID is then b72af87d-42d7-4f09-bf8c-b9f721a3e6ef.
The user API token is obtained from the User tab in the default Thingsquare frontend. It consists of a string of hexadecimal numbers, such as 423f4c2c9fd351f65359dd831833493f.
The frontend ID and user API token are used to construct the command line. This this case, the command line would be:
thsq-device-flasher -f b72af87d-42d7-4f09-bf8c-b9f721a3e6ef \
-u 423f4c2c9fd351f65359dd831833493f -n device -e code.binThe -n device flag will give each device a name starting with the word device and the -e flag will make the name to have the device’s EUI as its suffix.
Program the Devices
Open the command prompt in the directory with code.bin
- Run the
thsq-device-flashercommand line from above - When the program has started, it will show a list of available networks that the device can be associated with. Enter the corresponding number on the keyboard, and the Return key
- The flasher should now program the device
- The new device should now show up in the user account for the user
- After successfully flashing the device, the program will output something like
Device name of new device: device-02124b001797ecab Device EUI: 02124b001797ecab - If you are putting a sticker with the EUI on the devices, the EUI in the output above should be printed on that sticker
- Repeat the process for each device
Reprogramming Devices in the Field
Once the devices are deployed, it is much quicker to use Over-The-Air (OTA) updates to reprogram them. But the method described in this article is useful as the first step before the first deployment.
