Over-the-Air (OTA) Updates
Why can't I go directly to the latest version?
OTA update will always go to the next firmware release, not the latest. This may be necessary to perform changes to the underlying file structures, introduced only in certain versions. For example, if you are running version 1, and the latest release is version 4, you must update to version 2, then version 3, and finally version 4. You cannot directly upgrade from version 1 to version 4.
FireFly Controller supports OTA updates for both the firmware and SPIFFS (www
partition). Data stored on the config
partition is never updatable over OTA.
While the device is performing any type of OTA update, the OLED display will indicate the percentage complete. Additionally, events will be written to the Event Log.
OTA Update Service
The OTA Update Service allows you to configure a webserver that will provide OTA updates to the device. By default, the controller will check for OTA updates once per day and 30 seconds after a reboot. Both http and https protocols are supported, provided a certificate for the website has been uploaded to the certificates storage.
The OTA Update Service configuration is stored in the config
partition as a simple JSON file. It can be saved and deleted, but not updated.
When the web server payload specifies both an application and SPIFFS update, the SPIFFS are updated first, then the application. The web server should respond to the GET request with a formatted payload as an array (see examples below). Optionally, the list of software versions can be curated based on the hardware product ID and/or device UUID. The controller will send custom headers to identify the device in the GET request to the web server:
Header Name | Example Value | Description |
---|---|---|
product_id | FFC0806-2305 | Hardware Product ID |
uuid | 7a060b6b-dc2f-4d10-ba9e-6109f788cd95 | Device UUID |
Response Payloads
The fields included in the response are:
Field | Usage | Recommended Maximum Length |
---|---|---|
type | Matches the APPLICATION_NAME definition at compile time, typically FireFly Controller | 20 |
version | The version number of the file being described in the url or spiffs binary | 10 |
url | URL of the application binary | 60 |
spiffs | URL of the SPIFFS binary | 60 |
title | Optional, a short title for the new release version, used by Home Assistant | 30 |
release_summary | Optional, URL for release notes, used by Home Assistant | 75 |
Recommended maximum lengths
The recommended maximum lengths reflect the total maximum size of the object that has been tested. Shortening some fields can allow for others to be slightly longer. For example, if your URL is only 20 characters in length, you could add 40 characters to your release summary.
Example Web Server Response Payloads
Application-only update
[
{
"type": "FireFly Controller",
"version": "2024.5.2",
"url": "https://server.myhost.com/hwreg/app_2024.5.2.bin",
"title": "App release 2024.5.2",
"release_summary": "We added awesome new features!",
"release_url": "https://github.com/BrentIO/FireFly-Controller/releases/tag/2024.5.2"
}
]
SPIFFS-only update
[
{
"type": "FireFly Controller",
"version": "2024.3.21",
"spiffs": "https://server.myhost.com/controller/spiffs_2024.3.21.bin",
"title": "App release 2024.3.21",
"release_summary": "We added awesome new features!",
"release_url": "https://github.com/BrentIO/FireFly-Controller/releases/tag/2024.3.21"
}
]
Combined Application and SPIFFS update
[
{
"type": "FireFly Controller",
"version": "2024.5.2",
"url": "https://server.myhost.com/hwreg/app_2024.5.2.bin",
"spiffs": "https://server.myhost.com/hwreg/spiffs_2024.5.2.bin",
"title": "App release 2024.5.2",
"release_summary": "We added awesome new features!",
"release_url": "https://github.com/BrentIO/FireFly-Controller/releases/tag/2024.5.2"
},
{
"type": "FireFly Controller",
"version": "2024.3.21",
"url": "https://server.myhost.com/controller/app_2024.3.21.bin",
"spiffs": "https://server.myhost.com/controller/spiffs_2024.3.21.bin",
"title": "App release 2024.3.21",
"release_summary": "We added awesome new features!",
"release_url": "https://github.com/BrentIO/FireFly-Controller/releases/tag/2024.3.21"
}
]
Forced OTA Updates
OTA updates can also be forced, which is helpful for ensuring a specific version of the firmware or SPIFFS are downloaded.
A different certificate can be uploaded and configured for forced OTA updates than for the OTA Update Service, if required.