Report the installed firmware version, list the available firmware and get its download link.
| Topic | Direction |
|---|---|
things5-production/v1/devices/{device_id}/event/firmware_version_req | Device → Things5 |
things5-production/v1/devices/{device_id}/event/firmware_version_res | Things5 → device |
things5-production/v1/devices/{device_id}/req/firmwares_list_req | Device → Things5 |
things5-production/v1/devices/{device_id}/req/firmwares_list_res | Things5 → device |
things5-production/v1/devices/{device_id}/req/firmware_details_req | Device → Things5 |
things5-production/v1/devices/{device_id}/req/firmware_details_res | Things5 → device |
Device → Things5: event/firmware_version_req
event/firmware_version_reqUse this topic to let thing5 know which version is installed on the device. It's advised to use it every time the device is turned on.
things5-production/v1/devices/<device-id>/event/firmware_version_req
Payload
{
"request_id": "UUID",
"original_name": "XYZ_firmware-1-0-2-4",
"version": "1.0.0-foobar"
}
| name | description |
|---|---|
| request_id | UUID |
| original_name | Firmware original name. Can be any string manufacturer wants. |
| version | Firmware version, must be compatible with semver |
Things5 → device: event/firmware_version_res
event/firmware_version_resNotifies the device that things5 has received the firmware version sent in firmware version request
things5-production/v1/devices/<device-id>/event/firmware_version_res
Payload
{
"request_id": "UUID sent in the request",
"errors": [
"error description"
]
}
| name | description |
|---|---|
| request_id | UUID sent by the device in the request |
| errors | A list of strings with the errors |
On success errors is null. Possible errors: invalid input json, invalid semver version.
Device → Things5: req/firmwares_list_req
req/firmwares_list_reqRequest to things5 device available firmwares
Response will be published firmware list response
This resource can be used to list all available firmwares
things5-production/v1/devices/<device-id>/req/firmwares_list_req
Payload
{
"request_id": "UUID"
}
Things5 → device: req/firmwares_list_res
req/firmwares_list_resPublish all available firmwares for the device
things5-production/v1/devices/<device-id>/req/firmwares_list_res
Payload
{
"request_id": "UUID sent in the request",
"firmwares": [{
"id": "a1d4a886-0ad8-46fd-a042-abbc0493cca4",
"version": "1.0.3-beta2",
"main": true
}, {
"id": "45dd3c71-5a4c-4899-8cc6-9a26f26d9e20",
"version": "1.0.2",
"main": false
}]
}
| name | description |
|---|---|
| request_id | UUID sent in the request topic |
| device_id | |
| firmwares | List of firmwares with id and version in SEMVER format (https://semver.org/) |
Device → Things5: req/firmware_details_req
req/firmware_details_reqRequest to things5 device available firmwares
Response will be published firmware details response
things5-production/v1/devices/<device-id>/req/firmware_details_req
Payload
{
"request_id": "UUID",
"firmware_id": "UUID"
}
Things5 → device: req/firmware_details_res
req/firmware_details_resRequest to things5 device available firmwares
Response will be published in
things5-production/v1/devices/<device-id>/req/firmware_details_res
Payload
{
"request_id": "UUID",
"errors": ["error in the request"]
"firmware": {
"id": "UUID",
"url": "https://assets.things5.digital/firmwares/64ca02a3-6fd1-47c2-9a9d-8645552bdbee/0231_Informativa_IT.DOCX?Expires=1625652705&Signature=Te73tEN1N5KLaAncvHEeWl6hvxSkoSkFaVGIpYSDeg2HeiHAI1t7brNL~~b9OJe5qJlVRJgC4JR~bL-99NazmYy0wxViDNRLdqYvHxvEfTvo~hQimJXSXGI7eGpmXxJTZq-1Ut1ly9cC~Ubri20C5lmNJL78yqQCXPwGieYGU8Gp8iH-KTLMh4vlCR6Q1-PcLna5B1cjzIJ0L8ySWX6ziR3DW6N8if2ShstjnVhYSxAxy0TL624Z9KXELf1DjHt53TieJ7Sc5XEJW2GWz3BPqK7AcP90o4VV42Uf3sgBsJlBn3rq~yfCsSiCs3EcL84b5BsZFtj7t7jgX8SgVEqo9g__&Key-Pair-Id=KITSOBDSIRWBO",
"insecure_url": "http://assets.things5.digital/firmwares/64ca02a3-6fd1-47c2-9a9d-8645552bdbee/0231_Informativa_IT.DOCX?Expires=1625652705&Signature=Te73tEN1N5KLaAncvHEeWl6hvxSkoSkFaVGIpYSDeg2HeiHAI1t7brNL~~b9OJe5qJlVRJgC4JR~bL-99NazmYy0wxViDNRLdqYvHxvEfTvo~hQimJXSXGI7eGpmXxJTZq-1Ut1ly9cC~Ubri20C5lmNJL78yqQCXPwGieYGU8Gp8iH-KTLMh4vlCR6Q1-PcLna5B1cjzIJ0L8ySWX6ziR3DW6N8if2ShstjnVhYSxAxy0TL624Z9KXELf1DjHt53TieJ7Sc5XEJW2GWz3BPqK7AcP90o4VV42Uf3sgBsJlBn3rq~yfCsSiCs3EcL84b5BsZFtj7t7jgX8SgVEqo9g__&Key-Pair-Id=KITSOBDSIRWBO",
"md5": "88801fe439d38846eeb74efeaf865657",
"version": "0.1.0",
"size": 8445952
}
}
| name | type | description |
|---|---|---|
| size | integer | file size in bytes |
| md5 | string | result of md5 algorithm applied to file. Can be used to check file integrity |
| url | string | download url. Valid for 1 hour |
| insecure_url | string | same as firmware_url but using http instead of https |
| version | string | uses SEMVER https://semver.org/ |
Notes
- The firmware list contains the non-draft firmware of the device model; add
"include_archived": trueto the request to include archived ones. - List and details answers can be up to one minute old.