Firmware Management API — Fleet Update Rollouts

View firmware versions across your fleet and manage rollouts using canary, rolling, or all-at-once strategies with pause and stage-execution controls.

The firmware management API lets you inspect what firmware version is running on every charger in your fleet and orchestrate updates safely using staged rollout strategies. You can deploy to a small canary group first, roll out incrementally, or push to all chargers simultaneously.

List firmware versions across fleet

GET /api/v1/cpo/fleet/firmware

Returns a list of all distinct firmware versions currently running in your fleet along with the chargers on each version.

site_id · string

Filter results to chargers at a specific site.

vendor · string

Filter by charger vendor/manufacturer.

curl "https://api.dynamo-csms.com/api/v1/cpo/fleet/firmware" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "versions": [
    {
      "firmware_version": "3.5.0",
      "charger_count": 98,
      "vendor": "ABB",
      "model": "Terra AC",
      "release_date": "2024-04-01"
    },
    {
      "firmware_version": "3.4.1",
      "charger_count": 26,
      "vendor": "ABB",
      "model": "Terra AC",
      "release_date": "2023-11-15"
    }
  ],
  "total_chargers": 124
}

versions · object[]

Show properties

firmware_version · string

Version string.

charger_count · number

Number of chargers running this version.

vendor · string

Charger manufacturer.

model · string

Charger model.

release_date · string

Date this firmware was released.

---

Create a firmware rollout

POST /api/v1/cpo/firmware/rollout

Defines and schedules a new firmware update rollout. The rollout does not begin automatically — call the execute stage endpoint to start it.

Three rollout strategies are available:

• canary — deploys to a small initial subset, then waits for manual promotion before continuing to the rest
• rolling — deploys to chargers in sequential batches of a configurable size
• all_at_once — deploys to all specified chargers simultaneously

charger_ids · string[] · required

List of charge_point_id values to include in the rollout.

firmware_url · string · required

HTTPS URL where chargers can download the firmware file. Must be publicly reachable by chargers.

strategy · string · required

Rollout strategy. Accepted values: canary, rolling, all_at_once.

batch_size · number

Number of chargers per batch. Used by the rolling strategy. Defaults to 10% of total chargers.

canary_count · number · default: "1"

Number of chargers in the initial canary stage. Used by the canary strategy.

retrieve_date · string

ISO 8601 date/time chargers should start downloading the firmware. Defaults to immediately on execution.

curl -X POST "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "charger_ids": ["CP-001", "CP-002", "CP-003", "CP-004", "CP-005"],
    "firmware_url": "https://updates.example.com/firmware/terra-ac-3.5.1.bin",
    "strategy": "canary",
    "canary_count": 1
  }'

{
  "rollout_id": "rollout_4XNQP8",
  "strategy": "canary",
  "firmware_url": "https://updates.example.com/firmware/terra-ac-3.5.1.bin",
  "total_chargers": 5,
  "status": "pending",
  "stages": [
    {
      "stage": 1,
      "label": "Canary",
      "charger_ids": ["CP-001"],
      "status": "pending"
    },
    {
      "stage": 2,
      "label": "Rollout",
      "charger_ids": ["CP-002", "CP-003", "CP-004", "CP-005"],
      "status": "pending"
    }
  ],
  "created_at": "2024-06-15T09:00:00Z"
}

rollout_id · string

Unique identifier for the rollout.

status · string

Overall rollout status. One of: pending, in_progress, paused, completed, failed.

stages · object[]

Show properties

stage · number

Stage number.

label · string

Human-readable stage label.

charger_ids · string[]

Chargers included in this stage.

status · string

Stage status: pending, in_progress, completed, failed.

---

Get rollout status

GET /api/v1/cpo/firmware/rollout/{rollout_id}

Returns the current status of a rollout and per-charger progress.

rollout_id · string · required

The unique identifier of the rollout.

curl "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout/rollout_4XNQP8" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "rollout_id": "rollout_4XNQP8",
  "strategy": "canary",
  "firmware_url": "https://updates.example.com/firmware/terra-ac-3.5.1.bin",
  "status": "in_progress",
  "current_stage": 1,
  "stages": [
    {
      "stage": 1,
      "label": "Canary",
      "status": "in_progress",
      "chargers": [
        {
          "charge_point_id": "CP-001",
          "status": "downloading",
          "progress_percent": 62,
          "started_at": "2024-06-15T09:05:00Z",
          "completed_at": null
        }
      ]
    },
    {
      "stage": 2,
      "label": "Rollout",
      "status": "pending",
      "chargers": [
        { "charge_point_id": "CP-002", "status": "pending" },
        { "charge_point_id": "CP-003", "status": "pending" },
        { "charge_point_id": "CP-004", "status": "pending" },
        { "charge_point_id": "CP-005", "status": "pending" }
      ]
    }
  ],
  "created_at": "2024-06-15T09:00:00Z",
  "updated_at": "2024-06-15T09:05:30Z"
}

---

Execute rollout stage

POST /api/v1/cpo/firmware/rollout/{rollout_id}/execute-stage

Advances the rollout to the next pending stage. For a canary rollout, call this once to deploy to the canary group, verify results, then call it again to release to the remaining chargers. For a rolling rollout, each call releases the next batch.

rollout_id · string · required

The unique identifier of the rollout.

curl -X POST "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout/rollout_4XNQP8/execute-stage" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "rollout_id": "rollout_4XNQP8",
  "executed_stage": 2,
  "status": "in_progress",
  "chargers_triggered": ["CP-002", "CP-003", "CP-004", "CP-005"],
  "triggered_at": "2024-06-15T10:30:00Z"
}

executed_stage · number

The stage number that was just triggered.

chargers_triggered · string[]

Chargers in the stage that have been sent the update command.

---

Pause a rollout

POST /api/v1/cpo/firmware/rollout/{rollout_id}/pause

Pauses an in-progress rollout. Chargers that are already downloading or installing will complete their current operation, but no new chargers will be triggered. Call execute stage to resume.

rollout_id · string · required

The unique identifier of the rollout.

reason · string

Optional explanation for why the rollout was paused. Stored for audit purposes.

curl -X POST "https://api.dynamo-csms.com/api/v1/cpo/firmware/rollout/rollout_4XNQP8/pause" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Elevated error rate detected on canary charger CP-001"}'

{
  "rollout_id": "rollout_4XNQP8",
  "status": "paused",
  "paused_at": "2024-06-15T10:45:00Z",
  "reason": "Elevated error rate detected on canary charger CP-001"
}