Skip to main content

Firmware OTA update

Overview​

This addon allows you to update Connhex Edge services by abstracting the low-level details of the Connhex Firmware OTA update process.

info

The details on how the firmware OTA update works in Connhex can be found here.

How it works​

With the Firmware OTA Update addon, the latest firmware release associated with the connectable's model will be automatically downloaded and installed according to the configuration settings.

info

More information about Connhex models and releases can be found here.

Addon configuration​

The addon can be configured through three main parameters available in the agent.toml file:

  • auto_download: Determines if the OTA service will automatically download updates. Default: false.
  • auto_install: Determines if the OTA service will automatically apply updates (implies auto_download). Default: false.
  • check_interval: How frequently the OTA service should check for updates. Default: 1h.
agent.toml
...

# OTA service configuration.
[ota]
auto_download = true
auto_install = true
check_interval = '24h0m0s'

Release file​

Each release file must be a valid .zip file containing an update.sh script that includes all the steps that will be performed during the update process: once downloaded and extracted, the script will be executed by the addon.

Example​

The following is a simple example of an update.sh script. When executed, it will copy a new service file to the filesystem.

In this case, the folder structure of the release file is the following:

fw-update-0.0.3.zip
.
├── update.sh
└── new_service.py
update.sh
#!/bin/sh

echo "----------------------------------"
echo "FW Update version 0.0.3"
echo "----------------------------------"

echo "copying new service file..."
cp ./new_service.py /opt/connhex/custom_services/

echo "update complete"

Update flow​

When started, the addon will periodically check for updates. The first check is performed right after startup, and then every check_interval.

In general, the update flow is the following:

  1. The addon will perform a HEAD HTTP request to check whether a new firmware is available and has to be downloaded. In particular, it checks if a release with a different version number is available.
  2. If a new release is available and if any of the auto_download or auto_install options are enabled, the addon will download the release file. The file will be downloaded in the .store/ota folder inside the main Connhex Edge installation directory.
    info

    Failed or partial downloads are automatically handled by the addon on the next check.

    danger

    The release file download is synchronous and blocking: If you plan to have a large release file, you should consider developing a dedicated custom service to handle the download. Typically, to handle large updates, we use the update.sh script in the release file to notify a custom service that a new firmware is available and provide some information and parameters about the update, and then the custom service will handle the actual download.

  3. If the auto_install option is enabled, the addon will unpack and install the release (i.e., run the update.sh script). The release file will be unpacked in the .store/ota/current folder inside the main Connhex Edge installation directory.

Update status messages​

During the whole update process and at periodic intervals, the addon will emit status messages that can be used by other services to track the progress of the update or to perform actions (sending messages to Connhex Cloud, etc.). The status messages are emitted to the NATS subject heartbeat.ota.service.

The payload of each message is the following:

{
  "current_version": "",
  "latest_version": "",
  "status": "checking" | "check_failed" | "downloading" | "download_failed" | "update_available" | "update_ready" | "updating" | "update_failed" | "updated",
  "error": "",
  "last_checked": ""
}