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 list of devices that are part of the campaign.
- Configurations that must be applied to 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, it cannot be edited anymore. Launching a campaign has two effects:
- It starts a background job which will handle the configuration updates for each batch.
- It creates a supervision used to monitor the devices.
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.
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.
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.
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
Once a batch is started (i.e., IN_PROGRESS status), it cannot be paused anymore. But pausing the campaign will pause the following batches.
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.
Lifecycle
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.