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:

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.

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

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.

  • 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.