Skip to content

Campaigns

Overview

Campaigns are used to update the configuration of multiple devices at the same time. Once a campaign is launched, it can also be used to monitor the devices to check if they have the requested configurations and state. Campaigns can also be split into batches to spread the update over time and not update everything at once. They can be created from the built-in front-end or through the API.

Creating a campaign requires providing the following information:

  • A name to identify the campaign.
  • A selection of devices that are part of the campaign.
  • Configurations that must be applied to all devices.
  • Configurations that must be removed from all devices.
  • State values that the devices are expected to take once the campaign is complete.
  • The configurations of the batches.

Once created, the campaign can be updated until it is launched. After that, only its name and its description can still be changed; the device selection, the configurations and the batches are frozen.

A campaign is backed by a supervision, created together with the campaign and used to monitor the targeted devices. Launching the campaign starts the background job which handles the configuration updates for each batch.

There are two ways of launching a campaign:

  • By calling the "launch" route of the campaign controller.
  • By setting a start date for the campaign, it will be launched automatically when the date is reached.

The background job will start a dedicated sub-job for each batch. Each batch will then update the requested configurations in the database for all its devices, and will then proceed with synchronizing those configurations on the interface on which the devices are provisioned. This means that you do not have to take device connectivity into account when starting a campaign.

Info

Since the configurations are written in the database before being synchronized to the different interfaces, it is possible that during a short amount of time after starting the campaign, devices are shown to have taken the expected configuration without having really been notified.

For more details on the technical aspects of the background tasks used by the campaigns, see jobs.

Selecting the devices

The devices of a campaign are selected through any combination of the following criteria:

  • Folders
  • Device tags
  • Device types
  • Explicit device IDs

The resulting device set is the union of the devices matching the filters and the devices listed explicitly. At least one criterion must be provided, and the selection must match at least one device for the campaign to be launched.

Configurations

Applying values

A campaign targets configuration keys of two types:

  • Desired configurations are the values the campaign writes to the devices.
  • State (reported) values are what the campaign expects the devices to report back. They are only monitored, never written — the devices themselves report their state.

The association of a key and a type is unique within a campaign.

Removing configurations

A campaign can also remove desired configurations instead of giving them a value, by listing the keys to remove in configurationsToDelete. This is the way to retire a configuration key from a fleet — for example rolling back a feature flag — with the same batching, scheduling and monitoring as a regular campaign.

The rules are the following:

  • Only desired configurations can be removed. A reported state is written by the device, so a campaign never removes one.
  • A key cannot be both given a value and removed. Providing a key in configurationsToDelete and in configurations with the desired type is refused.
  • Supervising the state of a key whose desired value is removed is allowed, and is the way to confirm that the removal reached the device.
  • A campaign may consist of removals only. In that case configurations is left empty.
  • At least one configuration to set or to remove must be provided.

A device counts as valid for a removed key once it holds no desired value for that key at all — the opposite of the verdict for a key the campaign assigns a value to. A device that still holds the key is reported as invalid, so a removal that has not reached a device is visible in the campaign result like any other failure.

Info

Removing a desired configuration removes it from Kamea and from the device: the key is taken out of the device's twin on the interface it is provisioned on. It does not delete the value the device reports for that key.

Batches

Details

Batches are a core feature of Kamea that enables controlled, sequential execution of device operations across large fleets of IoT devices. This mechanism ensures that device updates and firmware deployments are executed in manageable groups rather than simultaneously across all devices, providing better control, monitoring, and error handling.

Configuration

When a campaign is created or updated, the system will generate batches based on the configuration provided.

For each batch, the configurations are the following:

  • Number of devices in the batch
  • The execution order of the batch
  • The type of execution (automatic or manual)

When creating a campaign, it is possible to provide these configurations for each batch or to let the system generate all the batches based on a common configuration. The common configuration will include a number of devices per batch and a type of execution. All the batches created this way will have the same configuration.

A batch cannot hold more than 250 devices. If no batch configuration is provided, a single batch containing every selected device is created.

Execution

During the execution of the campaign, the batches will be executed following two strategies: automatic or manual.

Batches programmed to be executed automatically will be executed when the previous batch is over. Whereas batches programmed to be executed manually will wait for a user action before starting. Starting the next waiting batch is done through the "startNextBatch" route; only batches in the waiting state are started, batches already executed or in progress are left untouched.

For automatic batches, a "delay between batches" that allows waiting before automatically executing the next batch can also be set.

Info

The delay is calculated from the start of the previous batch and not its termination. So if there is a delay of 1 hour between each batch and the first batch takes more than 1 hour to finish, then the next batch will start before the previous one has ended. But due to the batches executing rather quickly this is very unlikely to happen.

Batch Lifecycle

Batches will go through different statuses along their lifecycle to help monitor the progress of the campaign.

The status lifecycle is the following:

WAITING → IN_PROGRESS → SUCCESS/FAILURE
    ↓
PAUSED

A batch waiting for a user action is created in the manual status instead of waiting. Cancelling a campaign moves the batches that have not run yet to cancelled.

Once a batch is started (i.e., IN_PROGRESS status), it cannot be paused anymore. But pausing the campaign will pause the following batches.

Retrying a failed batch

When a batch fails, the campaign moves to the failure status and the following batches do not start. The last failed batch can be retried through the "retry" route, which restarts the failed job for the devices of that batch. A retry requires the campaign to be launched and not paused, and to actually have a failed batch.

Locking configurations

A campaign can be created with the locksConfigurations option. While such a campaign is active, the desired configuration keys it targets cannot be modified outside of it — neither by a user editing a device, nor by another campaign targeting the same keys on the same devices. This avoids two campaigns fighting over the same key, and prevents a device from drifting away from the value the campaign is rolling out while it is still running.

The keys a campaign removes are locked exactly like the keys it assigns: a key a campaign has taken off its devices cannot be re-added while that campaign is active.

The lock applies as soon as the campaign is launched and is released when the campaign reaches a terminal status (terminated or cancelled). It is still held while the campaign is dispatched, because devices may still answer at that point.

Before creating or launching a campaign, the "lock-status" route can be used to know which keys are already locked, and by which campaign. It accepts both the keys to set and the keys to remove, and reports each locked key once. A campaign can exclude itself from the check by passing its own id.

Campaign lifecycle

Statuses

Status Meaning
launchable Created, not launched yet. Everything can still be edited.
launched Running: batches are being executed.
paused Manually paused. Batches that have not started yet are held.
dispatched Every configuration has been sent to every targeted device. It does not mean the devices have applied it.
terminated Manually declared over by a user. Terminal success state.
cancelled Manually stopped before dispatch finished — the rollout was abandoned. Terminal.
failure A batch failed. The campaign can be resumed by retrying the failed batch.

The available actions are:

  • Pause a launched campaign, then resume it. Batches already in progress finish; the following ones wait.
  • Cancel a launched campaign that has not finished dispatching. This abandons the rollout.
  • Terminate a dispatched campaign to declare it over.
  • Delete a campaign that has not been started, or one that has finished.

Info

dispatched and terminated are two different things. dispatched is reached automatically once the last batch has sent its configurations; the devices may not have applied them yet. terminated is only ever set by an explicit user action, and means the campaign is concluded.

Result of a terminated campaign

Terminating a campaign freezes a snapshot of its result: for each targeted device, the desired and reported values of the keys the campaign targeted, as they stood at that instant. From then on, the campaign's result is read from that snapshot instead of the live device configurations.

This keeps a closed campaign's result true indefinitely: a device answering late, a user editing a value, or a newer campaign overwriting the same keys can no longer change what the terminated campaign reports. A device that has since been deleted also stays in the result. The live state can still be requested explicitly with the source=live parameter.

For a removed key, an empty snapshot is the success case: the snapshot only holds the values a device actually had, so a device that no longer holds the key has nothing frozen for it and reads as valid.

One-off semantics

The jobs started by a campaign will run until completed and will not start again. A campaign is a one-off operation; it does not guarantee that the devices will keep the requested values forever. For example, if a device takes the configuration requested by the campaign and a user updates it afterwards, the campaign will not update it another time. The device will keep the value set by the user and will be displayed with an invalid state in the related supervision.

Locking the configurations of a campaign narrows this window, but only while the campaign is active.

OTA update

Campaigns work particularly well with the firmware feature. When combined, it is possible to trigger a mass update of a device fleet. There is no required formalism, but here is a suggestion of campaign configuration for an OTA update campaign:

Key State Configuration
firmware_version 1.1 1.1
firmware_url - https://your-asset-storage.com/fw/v1_1.bin
firmware_token some_secret_token_value
app_version 5.1.9_beta01 5.1.9_beta01
app_url - https://your-asset-storage.com/app/5.1.9_beta01.bin
app_token some_secret_token_value

When creating a campaign on the built-in front-end, an option is available to set those values based on the available firmware for the device type that matches the selected devices.