Skip to content

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.