API for firmware rollout configuration

One of the most important features in managing fleets of devices is managing the software lifecycle. Various different lifecycle policies are available.

The basic functionality is that a specific version target selector is set for a device and the rollout service will automatically upgrade from whatever version is running to the specified target version. This is also the correct way to downgrade versions or switch to different testing versions for acceptance and compliance testing.

The current policies for version target selectors include:

null: follow the default for a given device type
- This is the Unwired default for newly created devices and will always use the latest stable version available for that specific device type.
- See null target selector (default, following the device type) for details.
version: set a specific version
- For fully externally controlled version selections
- See version target selector (specific version) for details.
disabled: disable any rollouts
- This is useful to ensure a device stays on whatever version it started up with
- See disabled target selector for details.

Hint

In general, the null (device type default) target selector provides the biggest automation, whereas custom policies or workflows can be implemented by setting the version target selector.

Unwired Edge Cloud OS Updates

Unwired Edge Cloud OS Updates are published regularly to include security updates as well as various new features and improvements.

Important

Unwired Networks operates a service that schedules Edge Cloud OS and container updates to devices.

Hint

See Firmware Updates for details.

Available target selectors

`null` target selector (default, following the device type)

This rollout mode selects the latest and best stable firmware. All these releases have gone through thorough QA and have been reviewed to modern software development standards.

With this mode you will get the latest firmware available for the respective device type including all new features and bug and stability fixes.

API call to set the null target selector (default, follow the device type):

# device level configuration
mutation set_specific_version {
  DM_update_node_rollout_config(
    macs: ["4A000102030405"]
    version_target_selector: { value: null }
  )
}

`version` target selector (specific version)

This is the preferred mode for deployments that seeks to control all device versions. A specific version can be selected for each device and this version will be maintained all time until changed.

All kinds of 3rd party workflows and processes for version updates and lifecycle management can be implemented on top of this feature.

API call to set the version target selector (specific version):

# device level configuration
mutation set_specific_version {
  DM_update_node_rollout_config(
    macs: ["4A000102030405"]
    version_target_selector: {value: "version:19.07-471"}
  )
}

Caution

Please note that the respective version can be derived from Unwired Edge Cloud OS release notes that are published to the respective release channels. The available firmware versions depend on the device type.

`disabled` target selector

This will ensure that the rollout service is disabled. The device version will not be touched and will stay on whatever version it started up with.

API call to set the disabled target selector (disable rollouts):

# device level configuration
mutation set_specific_version {
  DM_update_node_rollout_config(
    macs: ["4A000102030405"]
    version_target_selector: {value: "disabled"}
  )
}

Set daily update windows

Updates are typically done in a rolling manner whenever a device has a different target than the running version. You can control when those updates happen by setting a time window on a

device level
group level (see Group based update configuration more details)

This time window is in UTC and applies to all days.

# device level configuration
mutation set_update_window_device {
  DM_update_node_rollout_config(
    macs: ["4A000102030405"]
    time_span: {value: {start: "22:30:00", end: "23:59:59"}}
  )
}

# group level configuration
mutation set_update_window_group {
  DM_update_node_rollout_config(
    group_ids: ["12345"]
    time_span: {value: {start: "22:30:00", end: "23:59:59"}}
  )
}

Set scheduled rollout windows (maintenance windows)

Scheduled rollout windows let you define exact date/time ranges when rollouts are allowed. Use these windows to keep updates aligned with planned maintenance periods.

Key rules:

Windows are explicit date/time ranges in UTC (RFC3339).
Use scheduled windows for one-time ranges; use the classic daily window for recurring schedules.
Provide both from and to for each window; zero-duration windows (from equals to) are rejected.
Leave a gap between windows so each range is distinct; see examples here.
Apply scheduled windows at the device level (MACs or node IDs).
Choose either scheduled windows or the classic daily window (time_span).

mutation set_rollout_windows_device {
  DM_update_node_rollout_config(
    macs: ["4A000102030405"]
    rollout_windows: {
      value: [
        { from: "2025-12-20T20:00:00Z", to: "2025-12-20T23:00:00Z" },
        { from: "2025-12-24T18:00:00Z", to: "2025-12-25T06:00:00Z" }
      ]
    }
  )
}

Note

If a device already has a classic daily window (time_span) set, clear it before setting scheduled windows. Set a single window type per request.

Window examples

        gantt
  title Windows with a gap (recommended)
  dateFormat HH:mm:ss
  axisFormat %H:%M:%S
  section Windows
  Window A        :a1, 12:00:00, 12:59:00
  Small Gap (between windows):g2, 12:59:00, 1m
  Window B        :a2, 13:00:00, 14:15:00

        gantt
  title Overlap example (add a gap)
  dateFormat HH:mm:ss
  axisFormat %H:%M:%S
  section Windows
  Window A :a1, 12:00:00, 13:00:00
  Window B :a2, 12:30:00, 13:30:00

Clearing or pausing scheduled windows

Clear all scheduled windows: rollout_windows: { value: null } (rollouts follow the classic daily window if set; otherwise they can happen anytime).
Pause rollouts until a window is set: rollout_windows: { value: [] }.

Group based update configuration

Update time windows can also be set on group level. This might be useful if groups of devices need to be updated at the same time or need similar update windows. One caveat is that you cannot set a firmware version target selector on group level, as devices in the group might need different version branches. Scheduled rollout windows are supported at the device level.

When using DM_update_node_rollout_config with a group, you are not allowed to set a version target selector.

Also, you can only set a time window for a group that has its own configuration, meaning it is not inheriting from a parent group. Please see details in the GraphQL API documentation.

Monitoring through Metrics API

In addition to querying the API for rollout state, you can also monitor rollouts in your own monitoring system. These metrics can be collected by Prometheus and similar tools.

For details on the available endpoints and queries, see Metrics API.

Caution

The metric shows the status from the Unwired Edge Cloud’s perspective
The value of the metrics is always 1
The actual status is in the labels, e.g. rollout_state
The metrics can still appear even if a device is offline

`dm_firmware_rollout_status`

dm_firmware_rollout_status exposes the current firmware rollout status with the following important labels.

Example

dm_firmware_rollout_status{firmware_version="24.10-154", firmware_version_last_good="24.10-154", firmware_version_target_selector="version:24.10-154", mac="AAAABBBBCCCC", rollout_state="ok"}

Labels

mac - device MAC, main identifier for monitoring and alerting purposes
firmware_version - current or last recorded active firmware version
firmware_version_last_good - last known good firmware version
- If a rollout is successful, it is set to the same value as the current version
- This label is best effort. It may be missing or not fully accurate after manual changes or rollbacks
firmware_version_target_selector - firmware target version, see Available target selectors
rollout_state - current firmware rollout status
- Can be ok, in_progress, ``failed’

`dm_container_rollout_status`

dm_container_rollout_status exposes the current container rollout status with the following important labels:

Example

dm_container_rollout_status{container_image="main", container_name="Unwired On-board WiFi Portal", container_version="227", container_version_last_good="227", mac="AAAABBBBCCCC", node_service_id="d6uhwuby6oab", node_service_id_last_good="d6uhwuby6oab", node_service_instance_id="mq73kmk41256", rollout_state="ok"}

Labels

mac - device MAC address, main identifier for monitoring and alerting purposes
node_service_id - ID of the current or last recorded active container image version
- Changes when a new version is rolled out
- For checks that are easier to read over time, you can use container_image and container_version instead of node_service_id
node_service_id_last_good - ID of the last known good container image version
- If a rollout is successful, it is set to the same value as the current version
- It may differ after manual changes or rollbacks
node_service_instance_id - unique ID of the running container on the device
- It only changes if the instance is recreated in the Unwired Edge Cloud Console

API for firmware rollout configuration

Unwired Edge Cloud OS Updates

Available target selectors

null target selector (default, following the device type)

version target selector (specific version)

disabled target selector

Set daily update windows

Set scheduled rollout windows (maintenance windows)

Window examples

Clearing or pausing scheduled windows

Group based update configuration

Monitoring through Metrics API

dm_firmware_rollout_status

Example

Labels

dm_container_rollout_status

Example

Labels

`null` target selector (default, following the device type)

`version` target selector (specific version)

`disabled` target selector

`dm_firmware_rollout_status`

`dm_container_rollout_status`