Firmware Update

Matěj Sychra edited this page Aug 1, 2017 · 1 revision

Firmware Update Methods

THiNX Firmware update can be currently initiated only using HTTP/S transport on device checkin. However there is a feature in progress, that would allow providing new firmware update immediately using MQTTT transport.

OTT request cannot be initiated using MQTT, however may be initiated from the device-library-side, when MQTT reports new firmware version availability. The device can then initiate OTT request and will retrieve a token using HTTP/S transport.

API endpoint for accessing the firmware update is /device/firmware but the FIRMWARE_UPDATE message will be send as a response instead of OK on device-checkin in cases, where the device has new firmware available on the server-side.

Firmware update will be commenced immediately only, if the THINX_AUTO_UPDATE environment variable in the device firmware is changed from default value false to true.

In case the auto-update is disabled by default, device owner will receive retained MQTT message forwarded through websocket upon his login to the administration UI (RTM).

For development and service purposes, there's also a Forced Update available. It will be commenced in case the request body contains a "forced":"true" key-value.

Different methods for performing the firmware update are available:

Simple

Device must send HTTPS POST request to the API endpoint (/device/firmware) in order to download the firmware binary immediately.

This method may deprecate in favour of optinally multi-file uploads using OTT (because OTT can store all incoming request params, AND single-file/simple-download can be initiated using a http body key).

OTT

Device sends HTTP(S) POST request to the API endpoint (/device/) while having "use":"ott" as a part of the request. The request is authenticated by API Key only and will support plain HTTP transfers in the future, in order to support legacy low-performance devices without TLS and/or security gateway.

Higher level of security (TLS) can be enforced by starting THiNX-Connect on your local network. THiNX-Connect is a HTTP-to-HTTPS gateway that serves as a secure tunnel between your HTTP-only devices and the THiNX cloud.

If the use attribute is not set, Simple transfer will be falled back to.

Device will retrieve only the OTT (one-time-token) and can asynchronously use it to retrieve data using simple HTTPS GET (request is not authenticated) anytime in next 24 hours or in 1 hour from first attempt to use the token.

OTT request is currently supported only by single-file/whole-firmware updates (Arduino, Platformio).

On the API side, while request is stored to Redis saved as "ott:" to the Redis store.

Request is the retrieved using the OTT value when the /device/firmware API is called using HTTP GET method instead of POST.

Multi-file

Device sends HTTPS POST request to the API endpoint (/device/firmware) and will retrieve JSON object with multiple files immediately.

Implementation

All the update requests should end-up in device/updateFromPath method, that requires two parameters:

  • FILE (or basename) that will be uploaded to device after validation (file must be at least readable)

  • OTT, optionally – identifier of the OTT token that will to be invalidated on successful upload

The OTT request may be validated.

Abbreviations

RTM – Remote Things Management; administrative UI part of the THiNX platform

OTT – One-Time-Token; part of or whole URL that can be used only once to fetch firmware update for given device.

TLS - Transport Layer Security. Standard set of features that prevents attacker to inspect or modify network traffic (e.g. steal your password from pre-build firmware on update).

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.