Updates

Description

The updates module handles displaying of update status and triggering updates via the API. It also enables other features such as auto updating or checking updates based on a cron-like scheduler expression. The image below shows a more in depth explanation of when updates are triggered and actually applied.

Inherit to the device is the option to not allow automatic updates at all. This has to be communicated by the device. Should the device not allow an auto update, the only way to update the device is by calling the appropriate API endpoint. With the config option disableConnectUpdate it is possible to not run an update once the device connects. This can be used to enforce certain update times, e.g. at midnight, for all devices.

WARNING

Disabling the connect update should only be done while also using the autoUpdate configuration parameter. Otherwise, devices might never be updated, in case they do not reconnect and are not updated by hand.

In case you do want to use a CRON-based way of updating (autoUpdate config parameter), you might want to change the WebHook to only run updates for pins (see config parameter).

Events

Following events are transmitted via the websocket.

DEVICE_DISCOVERY

UPDATE_AVAILABLE

UPDATE_STARTED

UPDATE_NOT_AVAILABLE

The device discovery event is triggered when a device is connecting to the backend and the device meta information such as identifier and firmware is required. This event requires read access to the resource updates.

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$
flakeAddress integer	The flake address for the given action. This value is the address the device is available at internally. The value might be removed from the event since it offers no real value for developers.
timestamp integer	The timestamp of event.
type stringconstant	Constant value: DEVICE_DISCOVERY
updates array	A list of property updates gathered within the device discovery process.

API

Endpoints

GET

List Updates

GET

Get Device Firmware Information

POST

Trigger Firmware Update

POST

Webhook

List Updates

Returns a list of devices that have known firmware information. Adding the depth query parameter will return more information in a single request.

GET

/api/v1/updates

Access

This endpoint requires read permission for the resource updates.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$
project stringoptional	The project the device belongs to, returned when the depth greater than zero is set.
firmwares arrayoptional	When using depth greater than zero the firmware information is returned if available.
firmwares.[ ].firmware string	The firmware identifier in semantic versioning format.
firmwares.[ ].hardware stringoptional	The hardware identifier used to differentiate between different hardware.
firmwares.[ ].index number	Value to differentiate between multiple firmwares for a single device.
firmwares.[ ].updateAvailable boolean	Whenever an update is available.

Get Device Firmware Information

Returns the firmware information for a single device if found.

GET

/api/v1/updates/:deviceIdentifier

Access

This endpoint requires read permission for the resource updates.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$

Response

Name	Description
project string	The identifier of the project on the update server side.
firmwares array	When using depth greater than zero the firmware information is returned if available.
firmwares.[ ].firmware string	The firmware identifier in semantic versioning format.
firmwares.[ ].hardware stringoptional	The hardware identifier used to differentiate between different hardware.
firmwares.[ ].index number	Value to differentiate between multiple firmwares for a single device.
firmwares.[ ].updateAvailable boolean	Whenever an update is available.

Trigger Firmware Update

In order to trigger a firmware update for a single device, use this endpoint.

POST

/api/v1/updates/:deviceIdentifier

Access

This endpoint requires update permission for the resource updates.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API. Pattern: ^(\S.)?(\\*|[a-zA-Z0-9=-]+)$

Response

Name	Description
status stringenum	The status of the update. The `STARTED` status is returned when the device handled the update message as expected and is not starting to update. `OFFLINE` is returned if the device can currently not be reached. Possible values: UPDATE_SERVER_OUT_OF_RESOURCES, STARTED, DEVICE_OFFLINE, SERVER_ERROR, UPDATE_SERVER_ERROR, DEVICE_NOT_OK, NO_UPDATE
message string	An optional message containing more information

Webhook

WARNING

This endpoint is used internally for the communication between the update server and the coldwave backend environment. It is used to send events such as a new rollout to the coldwave backend in order to not rely on polling.

POST

/api/v1/updates/hook/:projectIdentifier

URL Parameter

Name	Description
projectIdentifier string	The identifier of the project on the update server side.

Request Body

Name	Description

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.