Firmware updates over the air
This document details how to perform a firmware update over the air of your devices.
To build a binary suitable for an over-the-air update you will need the following:
- The Thingsquare firmware SDK
- Your own Thingsquare server stack (although you can do the same procedure using the public development/demo stack)
- A working installation of the
git
versioning tool, and a bit of experience with it - At least one instance of a wireless mesh installation to be used for testing your new binaries
- One or more hardware platforms running the Thingsquare system
- A test setup where you can verify the operation of your binaries before making them available to your users
What Needs to be Done
In the Thingsquare system, firmware versions are kept as a set of files on the server stack. Each configured product has its own set of files. We will build one such firmware file and upload it to the server stack.
Once a firmware file is made available via the server stack, that file can be sent to devices via the API or through a frontend app. Only the files that are stored in the product's directory can be sent to a device. This means that it is not possible to send any random file to a device, only the files that have been configured to be accessible may be sent to the device. This is a security measure to ensure that only verified firmware updates will be sent out.
Each firmware image file also has a corresponding description file that describes the firmware version. For example, it may contain information about what hardware platforms it can run on. This information is available in the frontend app and may be shown to a user.
Step 1: Clone Your Product git Repository
Each Thingsquare product has its own git
repository. This repository stores all files pertaining to a product, such as any frontend HTML5 files and assets as well as all firmware versions that are available via the API.
To clone your product's git
repository, go to the product administration console and tap the Product Configuration
icon.
Tap the `Product Configuration` icon.
Inside the product configuration, enable Git access:
Tap the `git access` button to enable `git` access and to get a `git` URL.
When git
access is enabled, a git
URL appears. This will begin with git clone
and a git
URL.
Copy the git clone
command line into a terminal window and execute the command. This will create a local copy of your product's repository. This will be called something like 36e19185-a237-4f12-8e97-8bd235e5d6b6/
(a version 4 uuid) and contains all your frontend files as well as any firmware versions.
Frontend files are in the frontend/
subdirectory and firmware files (if any) are in the firmware/
directory. If the firmware/
directory does not exist, we will create it below.
Step 2: Compile a Signed Binary
Now we turn to actually generating the firmware binary. This is done from within the Thingsquare firmware SDK and you will need to have all the SDK compilers and tools installed. To generate a signed binary, you will need to have openssl installed.
To compile a signed firmware binary, go to your application directory in the Thingsquare firmware SDK tree and use make
to build the binary:
cd customer/project
make TARGET=customer-platform project-name.sotabin
This will generate a binary called project-name.sotabin
that contains the new firmware version in a format that is suitable to load over-the-air to a connected device. Note that it may take a while to build the binary as it will contain the entire operating system along with the application files.
We next copy the generated binary to the git
repository and make it available to the server stack.
Step 3: Make the Binary Available
To make the binary available to the server stack, we need to copy the generated binary to the git
repository and push it to the server.
First, we should make sure we have a firmware/
subdirectory in our git
repository, alongside our frontends/
directory. If we do not have such a directory, we create it:
mkdir firmware/
The firmware/
directory may contain any structure that we wish it to contain. We suggest using subdirectories that are named either after the date at which the firmware binary was generated, or version numbers.
Suppose we use subdirectories with dates, we create one with today's date:
cd firmware/
mkdir 20180628
This directory should contain any firmware images we generate on this day and their description files.
We copy the firmware file we generated in step 2 above from the Thingsquare firmware SDK location into this directory.
cp ../../path/to/firmware/sdk/customer/project/project-name.sotabin 20180628/
Next we create a description file for this firmware version. The description is in JSON format and describes what platforms this firmware image can be loaded onto as well as what platform it provides. For example, here is a description file for firmware file for the CC1310 Launchpad board:
{
"platforms": {
"from": [
"cc1310",
],
"to": {
"platform": "cc1310",
"name": "CC1310 Launchpad"
}
}
}
The description file is named as the firmware file, but with an added .json
at the end. In our case, that would be project-name.sotabin.json
.
Once the firmware file and the description file are inside the git
repository, we must make it available to the server. We do this by adding the files to the git
repository and push it to the server:
cd 20180628
git add project-name.sotabin
git add project-name.sotabin.json
git commit -m "Added an example firmware update"
git push
Conclusions
Building and updating the firmware of a device is a fairly complicated procedure. The Thingsquare platform makes it as easy as it can be, allowing the developers to have control of what files are made available and the user to control when and how to update their devices.