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 beta 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 additionally need to have the Jacksum checksum utility 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.signed

This will generate a binary called project-name.signed 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 20160628

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.signed 20162628/

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 Weptech gateway:

{
  "platforms": {
    "from": [
      "weptech-24ghz",
      "weptech-subghz"
    ],
    "to": {
      "platform": "weptech-24ghz",
      "name": "Weptech 2.4 GHz Gateway"
    }
  },
  "warning": "Will upgrade the Weptech to use the 2.4 GHz radio."
}

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.signed.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 20160628
git add project-name.signed
git add project-name.signed.json
git commit -m "Added an example firmware update"
git push

Step 4: Run the Firmware Update on a Device

Once the firmware files have been pushed to the server, they are available to be pushed to connected devices. They may be accessed using your own app (in case you have a standalone app), the API, or via the Thingsquare device viewer app.

If you are using a version of the Thingsquare device viewer app on your stack, you can use it to download the new firmware onto a device.

Go to the Firmware tab and open it.

On the `Firmware` tab, the new firmware update should now be available

Tap one of the devices that needs to be updated. Then go to the Details tab. On the Details tab, scroll down to the Change Mode zone and tap the Connected button.

Tap the `Connected` button to ask the device to connect with the server stack to receive the new firmware update. Scroll down all the way to the end. When the device has connected, the firmware update buttons will be available. Tap the `Check for firmware updates` button to check if the device has connected.

After tapping the confirmation dialog for the firmware update, the firmware update should now be in progress. The progress can be seen both in the Firmware tab and in the device page.

Firmware update in progress.

The firmware update should take some 10-20 minutes to complete for a wireless device.

Once the update is complete, reboot the device with the Reboot button and restore the mode using the Change Mode buttons.

Once the update has succeeded (as indicated by the `fwstatus` variable being set to `succeeded`), reboot the device with the `Reboot` button and restore the mode.

Wait until the device has rebooted. The Firmware tab should now show the device as being updated.

Device is now up to date.

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.