Skip to main content

Over The Air (OTA) Updates

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

How to use guides:


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}

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:

"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

A number of parameters are available when the device reports its firmware state to the Golioth server. Here is an example payload that indicates the device is currently downloading an update of the main package; going from the current version to the target version:

"state": 3,
"reason": 0,
"package": "main",
"version": "1.2.3",
"target": "1.2.4"
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

  • The list of state codes, can be viewed in the golioth_ota_state enum on the Golioth Firmware SDK doxygen reference.

Firmware Report Reason

  • For a full list of reason codes, please see the golioth_ota_reason enum on the Golioth Firmware SDK doxygen reference.