Firmware Management

Over-the-air firmware updates for provider clients.

Beacon Tower's firmware management system enables you to upload firmware packages, create versioned releases, define deployment templates, and orchestrate phased rollouts to IoT devices. Updates target provider clients (e.g., Azure IoT Hub devices) within your Assets.

Overview

The firmware update lifecycle consists of four stages:

Upload — Upload a firmware binary to Beacon Tower storage
Release — Create a release record with metadata, compatible models, and configuration
Deploy — Create a deployment that targets specific devices using a template
Monitor — Track deployment progress, handle failures, and manage device-level operations

Privilege Required: All firmware upload and deployment operations require the firmware_management privilege.

Uploading Firmware

Firmware files are uploaded as Resources using a multipart form data request.

curl -X POST https://api.beacontower.ai/releases/upload \
  -H "X-API-Key: your_api_key" \
  -F "file=@firmware-v2.1.0.bin"

Response:

{
  "fileResourceId": "res_abc123",
  "filename": "firmware-v2.1.0.bin",
  "size": 524288,
  "contentType": "application/octet-stream"
}

Save the fileResourceId — you'll use it when creating the release.

Firmware Releases

A release is a firmware package with metadata that defines:

Display name and description for human-readable identification
Firmware file (via fileResourceId)
Starting models — Asset models compatible with this firmware
Property values — Key-value pairs for configuration (e.g., {"version": "2.1.0", "checksum": "sha256:..."})

Releases are created once and can be used in multiple deployments.

Creating a Release

curl -X POST https://api.beacontower.ai/releases \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Firmware v2.1.0",
    "description": "Security patches and performance improvements",
    "fileResourceId": "res_abc123",
    "startingModels": ["model_temp_sensor_v1", "model_temp_sensor_v2"],
    "propertyValues": {
      "version": "2.1.0",
      "checksum": "sha256:a3f5b8c...",
      "minBatteryLevel": "20"
    }
  }'

Response:

{
  "releaseId": "rel_xyz789",
  "displayName": "Firmware v2.1.0",
  "description": "Security patches and performance improvements",
  "fileResourceId": "res_abc123",
  "startingModels": ["model_temp_sensor_v1", "model_temp_sensor_v2"],
  "propertyValues": {
    "version": "2.1.0",
    "checksum": "sha256:a3f5b8c...",
    "minBatteryLevel": "20"
  },
  "createdAt": "2026-02-08T14:30:00Z"
}

Managing Releases

Operation	Endpoint	Description
Get release	`GET /releases/{releaseId}`	Retrieve release details
Update release	`PUT /releases/{releaseId}`	Modify display name, description, or properties
Delete release	`DELETE /releases/{releaseId}`	Remove release (fails if used in active deployments)
List releases	`GET /releases`	Query all releases with optional filters

Deployment Templates

Deployment templates define the sequence of steps devices follow during a firmware update. Each step specifies:

Type — The operation to perform (e.g., download, apply, reboot)
Name — Human-readable step identifier
Value — Configuration or command for the step
Status mappings — How device status values map to deployment states

Templates provide a reusable blueprint for consistent rollout behavior across deployments.

Creating a Template

curl -X POST https://api.beacontower.ai/deployments/templates \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Firmware Update",
    "steps": [
      {
        "type": "download",
        "name": "Download Firmware",
        "value": "https://storage.beacontower.ai/releases/{releaseId}",
        "statusMappings": {
          "downloading": "running",
          "downloaded": "succeeded"
        }
      },
      {
        "type": "apply",
        "name": "Apply Update",
        "value": "install",
        "statusMappings": {
          "installing": "running",
          "installed": "succeeded"
        }
      },
      {
        "type": "reboot",
        "name": "Reboot Device",
        "value": "restart",
        "statusMappings": {
          "rebooting": "running",
          "online": "succeeded"
        }
      }
    ]
  }'

Managing Templates

Operation	Endpoint	Description
Get template	`GET /deployments/templates/{deploymentTemplateId}`	Retrieve template configuration
Update template	`PUT /deployments/templates/{deploymentTemplateId}`	Modify steps or mappings
Delete template	`DELETE /deployments/templates/{deploymentTemplateId}`	Remove template
List templates	`GET /deployments/templates`	Query all templates

Deploying Updates

A deployment applies a release to a set of target devices using a deployment template.

Creating a Deployment

curl -X POST https://api.beacontower.ai/deployments \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentTemplateId": "tmpl_def456",
    "releaseId": "rel_xyz789",
    "targetDeviceIds": [
      "device_12345",
      "device_67890",
      "device_abcde"
    ],
    "name": "Phase 1 Rollout - Building A",
    "description": "Initial rollout to temperature sensors in Building A"
  }'

Response:

{
  "deploymentId": "dep_qrs321",
  "name": "Phase 1 Rollout - Building A",
  "status": "Not Started",
  "releaseId": "rel_xyz789",
  "deploymentTemplateId": "tmpl_def456",
  "targetDeviceIds": ["device_12345", "device_67890", "device_abcde"],
  "createdAt": "2026-02-08T15:00:00Z"
}

Starting a Deployment

Deployments are created in Not Started status. Initiate the rollout with:

curl -X POST https://api.beacontower.ai/deployments/dep_qrs321/start \
  -H "X-API-Key: your_api_key"

Response:

{
  "deploymentId": "dep_qrs321",
  "status": "Running",
  "startedAt": "2026-02-08T15:05:00Z"
}

Deployment Lifecycle

Status	Meaning
`Not Started`	Created but not yet initiated
`Running`	Actively updating devices
`Succeeded`	All devices successfully updated
`Failed`	One or more devices failed
`Cancelled`	Manually stopped

Monitoring Deployments

Track deployment progress at both the deployment and device levels.

Deployment-Level Status

curl -X GET https://api.beacontower.ai/deployments/dep_qrs321/status \
  -H "X-API-Key: your_api_key"

Response:

{
  "deploymentId": "dep_qrs321",
  "status": "Running",
  "totalDevices": 3,
  "succeededDevices": 2,
  "failedDevices": 0,
  "runningDevices": 1,
  "cancelledDevices": 0,
  "lastUpdated": "2026-02-08T15:20:00Z"
}

Device-Level Status

curl -X GET https://api.beacontower.ai/deployments/dep_qrs321/devices/device_12345/status \
  -H "X-API-Key: your_api_key"

Response:

{
  "deviceId": "device_12345",
  "deploymentId": "dep_qrs321",
  "status": "Running",
  "currentStep": "Apply Update",
  "stepStatus": "installing",
  "progress": 67,
  "lastUpdated": "2026-02-08T15:20:00Z"
}

Batch Status Queries

For deployments with many devices, query statuses in batches:

curl -X POST https://api.beacontower.ai/deployments/batch-statuses \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentIds": ["dep_qrs321", "dep_tuv654"]
  }'

Device-Level Control

Manage individual device update operations or entire deployments.

Cancel a Device

Stop the update process for a single device:

curl -X POST https://api.beacontower.ai/deployments/dep_qrs321/devices/device_12345/cancel \
  -H "X-API-Key: your_api_key"

Restart a Device

Retry the update process for a single device:

curl -X POST https://api.beacontower.ai/deployments/dep_qrs321/devices/device_12345/restart \
  -H "X-API-Key: your_api_key"

Cancel Entire Deployment

Stop all device updates in the deployment:

curl -X POST https://api.beacontower.ai/deployments/dep_qrs321/cancel \
  -H "X-API-Key: your_api_key"

Restart Entire Deployment

Retry all failed or cancelled devices:

curl -X POST https://api.beacontower.ai/deployments/dep_qrs321/restart \
  -H "X-API-Key: your_api_key"

Best Practices

Phased Rollouts

Deploy updates in stages to minimize risk:

Pilot — Target a small subset of devices (5-10%)
Validate — Monitor pilot devices for 24-48 hours
Expand — Gradually increase target set (25%, 50%, 100%)
Rollback — If failures occur, cancel deployment and investigate

Targeting Strategy

Use provider client IDs from asset bindings to target specific devices. Query assets and their bound clients before creating deployments:

curl -X GET https://api.beacontower.ai/assets/{assetId}/provider-clients \
  -H "X-API-Key: your_api_key"

Configuration Properties

Use propertyValues in releases to:

Version tracking — {"version": "2.1.0"}
Integrity checks — {"checksum": "sha256:..."}
Deployment conditions — {"minBatteryLevel": "20", "requiresWiFi": "true"}

Devices can read these properties from the deployment metadata to enforce preconditions before starting the update.

Error Handling

Monitor device-level status codes to diagnose failures:

Network errors — Check connectivity, retry with longer timeouts
Battery too low — Wait for charging or adjust minBatteryLevel
Incompatible firmware — Verify startingModels match device asset models
Checksum mismatch — Re-upload firmware or verify file integrity

Next Steps

Assets, Providers, and Bindings — Understand device targeting
Resources — Learn about file storage and resource management
API Reference — Full endpoint documentation for firmware operations

Overview​

Uploading Firmware​

Firmware Releases​

Creating a Release​

Managing Releases​

Deployment Templates​

Creating a Template​

Managing Templates​

Deploying Updates​

Creating a Deployment​

Starting a Deployment​

Deployment Lifecycle​

Monitoring Deployments​

Deployment-Level Status​

Device-Level Status​

Batch Status Queries​

Device-Level Control​

Cancel a Device​

Restart a Device​

Cancel Entire Deployment​

Restart Entire Deployment​

Best Practices​

Phased Rollouts​

Targeting Strategy​

Configuration Properties​

Error Handling​

Next Steps​

Overview

Uploading Firmware

Firmware Releases

Creating a Release

Managing Releases

Deployment Templates

Creating a Template

Managing Templates

Deploying Updates

Creating a Deployment

Starting a Deployment

Deployment Lifecycle

Monitoring Deployments

Deployment-Level Status

Device-Level Status

Batch Status Queries

Device-Level Control

Cancel a Device

Restart a Device

Cancel Entire Deployment

Restart Entire Deployment

Best Practices

Phased Rollouts

Targeting Strategy

Configuration Properties

Error Handling

Next Steps