# 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 [](version-target-selector-null) for details.
- ```version```: set a specific version
  - For fully externally controlled version selections
  - See [](version-target-selector-version) for details.
- ```disabled```: disable any rollouts
  - This is useful to ensure a device stays
    on whatever version it started up with
  - See [](version-target-selector-disabled) 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.
```

(version-target-selector)=
## Available target selectors

(version-target-selector-null)=
### ```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):

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

(version-target-selector-version)=
### ```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):

```graphql
# 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.
```

(version-target-selector-disabled)=
### ```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):

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

(setting-daily-update-windows)=
## 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-rollout-configuration) more details)

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

```graphql
# 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"}}
  )
}
```

(scheduled-rollout-windows)=
## 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](#allowed-vs-rejected-windows).
- Apply scheduled windows at the device level (MACs or node IDs).
- Choose either scheduled windows or the classic daily window (`time_span`).

```graphql
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.
```

(allowed-vs-rejected-windows)=
### Window examples

```{mermaid}
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

```

```{mermaid}
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-rollout-configuration)=
## 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.

(rollout-monitoring-metrics-api)=
## 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](api_metrics.md).

```{caution}
1. The metric shows the status from the Unwired Edge Cloud's perspective
1. The value of the metrics is always `1`
1. The actual status is in the labels, e.g. ```rollout_state```
1. 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 [](version-target-selector)
- ```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