Managed Campaigns

Managed campaigns upgrade many devices over time based on a few settings. A managed campaign runs on a single gateway for multiple days, weeks, or months. It listens for devices heard by the specified gateway, checks their firmware versions, and when it hears from devices matching the version pattern it is looking for, it schedules a campaign to upgrade those devices at a preferred time.

Before You Begin

You need:

• A firmware image uploaded to the FUOTA server. See Quick Start Guide.
• The NodeID of the gateway the managed campaign will observe. See Gateway Selection.
• Multicast keys uploaded for any non-MachineQ devices. See Multicast Key Management.
• $MQ_TOKEN exported from the authentication step. See Quick Start Guide.

Campaign vs. Managed Campaign

How to Run a Managed Campaign

Create the managed campaign with the create managed campaign API. The response contains a managed_campaign_id, which you use later to get the status of the managed campaign.

curl -sS -X POST "https://fuota.machineq.net/api/v3.2/managed_campaigns" \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Managed Campaign Demo: 0.123.x.x and 0.122.99.x to 0.123.4.56",
    "image_name": "firmware_v0.123.4.56",
    "gateways": ["1122334455667788"],
    "include_versions": ["....7B00........", "..637A00........"],
    "expected_version": "38047B00........",
    "preferred_start_time_utc": "11:00",
    "run_until": "2025-01-01T12:00:00.000000Z"
  }' | jq

Required Parameters

Note: Currently, only one gateway is supported in a managed campaign. Support for more than one gateway is planned.

Optional Parameters

The following payload upgrades every device except those matching 0.1.2.3:

{
  "name": "Managed Campaign Demo: Everything except 0.1.2.3 to 0.123.4.56",
  "image_name": "firmware_v0.123.4.56",
  "gateways": ["1122334455667788"],
  "include_versions": ["................"],
  "exclude_versions": ["03020100........"],
  "expected_version": "38047B00........"
}

Uploading Keys

The FUOTA server must know the multicast keys in advance to run the managed campaign. The managed campaign cannot include any devices for which it does not know or cannot generate keys.

Any DevEUI starting with 2CC407 can have its multicast key auto-generated and does not need a key uploaded. For all other devices, upload keys using the Multicast Key Management API before including them.

{
  "0011223344556677": "aabbccddeeffaabbccddeeffaabbccdd",
  "0102030405060708": "01020304050607080102030405060708"
}

Each DevEUI is an 8-byte hex string, and each key is a 16-byte hex string.

Managed Campaign Behavior

The managed campaign scans for devices for the first 24 hours after creation. Any device that matches an include_versions filter and does not match any exclude_versions filter is scheduled for the next campaign.

Once at least one device is scheduled, the server creates the first campaign at the preferred start time. While that campaign runs, the managed campaign continues to listen for new devices and includes them in the next campaign, which runs at the preferred start time 24 hours later.

As the managed campaign approaches its run_until time, it stops creating new campaigns. After passing run_until, it stops and transitions into a "Finished" state.

State

A call to the get managed campaign API returns the creation parameters plus:

The stage_str field can be:

• GATHERING_DEVICES — The main phase, where the server listens to devices and creates campaigns when new devices match the version filter.
• RUNNING_LAST_CAMPAIGN — A campaign is running, and no more campaigns will be created after it.
• FINISHED — The managed campaign is done.
• CLEANED — The managed campaign is done and its campaign history has been removed.

curl -sS "https://fuota.machineq.net/api/v3.2/managed_campaigns/<managed_campaign_id>" \
  -H "Authorization: Bearer $MQ_TOKEN" | jq

{
  "expected_version": "04030200........",
  "gateways": ["1122334455667788"],
  "image_name": "fuota_v2.3.4.bin",
  "include_versions": ["03020100........"],
  "managed_campaign_id": "mWa77N",
  "name": "Some managed campaign",
  "next_update_session_time": "2024-08-01T11:12:13.141516Z",
  "preferred_start_time_utc": "11:00",
  "run_until": "2025-01-01T12:00:00.000000Z",
  "scheduled_devices": {
    "1111222233334444": {
      "reported_at": "2024-07-01T01:01:01.010101Z",
      "version_hex": "03020100abcdef00"
    }
  },
  "stage": 1,
  "stage_str": "GATHERING_DEVICES",
  "started_at": "2024-06-06T06:06:06.654321Z",
  "stop_when_no_match": true,
  "updated_devices": {
    "1212232334344545": {
      "reported_at": "2024-06-20T00:00:00.000000Z",
      "version_hex": "04030200abcdef00"
    }
  },
  "whole_subscriber": false
}

State Transition Diagram

Problematic Devices

The managed campaign tracks devices that were included in campaigns but failed for any reason. Any device that fails in more than two campaigns is treated as a "problematic device" and is not included in future campaigns.

Use the get problematic devices API to list these devices, the campaigns they failed in, and why they failed.

[
  {
    "deveui": "0102030405060700",
    "failed_campaigns": [
      ["mQKuKK", "Some failure reason"],
      ["Zne1Vm", "Some other failure reason"]
    ]
  }
]

You can clear the problematic devices list with the delete problematic devices API, which allows the managed campaign to try including those devices again.

Deleting a Managed Campaign

You can delete a finished managed campaign with the delete managed campaign API. If a managed campaign is still running, you must halt it before deleting it.

Halting a Managed Campaign

To cancel a running managed campaign and put it into a finished state where it can be deleted, use the halt managed campaign API. It can return different status codes:

• 202 — The managed campaign is in the process of being halted.
• 204 — The managed campaign has been successfully halted.

Note: The managed campaigns feature does not support upgrade delegation yet.

What's Next?

• Firmware Version Parsing: Build the hexadecimal patterns used by include_versions and expected_version.
• Multicast Key Management: Upload keys for non-MachineQ devices before running a managed campaign.
• Troubleshooting: Understand why devices become problematic.