Skip to main content

Over The Air (OTA) Updates

Over The Air (OTA) Updates Service definitions over CoAP.

How to use guides:

Interface

MethodDescriptionPath
GET/ObserveGet desired release version in Manifest Format/.u/desired
GET/ObserveGet desired release version in SUIT Manifest Format/.u/desired/suit
GETDownload binary of a given component and version/.u/c/{package}@{version}
POST/PUTReport firmware state for a given package/.u/c/{package}
note

The desired release version returned in the manifest will be the most recently created release that is enabled.

Release Manifest Format

Here is an example of a release manifest in JSON format:

{
"sequenceNumber":1631741642,
"hash":"25e73431ac4a1a09392d51c8af14b611defdd877e8021803af4414ad470ad6fb",
"components":[
{
"package":"main",
"version":"1.0.0",
"hash":"feb982c3fbec352441caddaa85bd5c69ef5feadb5dfc1f57171e88e070771241",
"size":538208,
"uri":"/.u/c/[email protected]",
"type": "mcuboot"
}
]
}

When data is CBOR encoded, the keys are sent as numbers to reduce the size of the message.

JSON KeyCBOR Number KeyDescription
sequenceNumber1Release Sequence Number
hash2Release SUIT Manifest SHA256 Hash
components3List of packages/components that are part of the release
components.$.package1Artifact Package name
components.$.version2Artifact Version
components.$.hash3SHA256 of Artifact Binary
components.$.size4Artifact Binary Size in Bytes
components.$.uri5Relative URI to download binary
components.$.type6Binary Detected Type - "mcuboot" or "default"

Firmware/Artifact State Reporting parameters and attributes

These are the query/body parameters that can be sent when reporting a given firmware/artifact state. When the device reports states for it's components, we will use these parameters to determine the current state of the device in regards to DFU and also save the historical information on our Device Logs feature, so you can query information for your fleet of device. Data is saved on the golioth_dfu module.

AttributeDescriptionDefault
state or sFirmware/Artifact State See Valid Firmware States0 - Idle
reason or rReason for Firmware/Artifact Report See Valid Reason0 - ready state
package or pkgFirmware/Artifact package namemain
version or vRunning firmware/artifact version
target or tTarget firmware/artifact version

Firmware States

CodeDescription
0Idle
1Downloading
2Downloaded
3Updated

Firmware Report Reason

CodeDescription
0ready state
1firmware updated successfully
2not enough flash memory for the new firmware package
3out of RAM during downloading process
4connection lost during downloading process
5integrity check failure for new downloaded package
6unsupported package type
7invalid URI
8firmware update failed
9unsupported protocol