Ship your first update

Once a device is registered and online, you can push firmware to it in three steps: build an .otapulse artifact, upload it to the console, and create a deployment targeting your device. This page walks through each step.

What is a firmware artifact?

An .otapulse artifact is a signed package that contains a complete root filesystem image plus metadata (device type, artifact name, version). The OTA agent on the device reads the metadata to confirm the artifact is intended for its device type, then writes the filesystem to the inactive root partition.

You build artifacts with the otapulse-artifact CLI tool, which you can download from the OTA-Pulse releases page.

Steps

1. Build your firmware image

   Build a root filesystem image for your target. With Yocto:

   # In your Yocto build environment
   bitbake soc-monitoring-image

   This produces an .ext4 image, typically at:

   tmp/deploy/images/<machine>/soc-monitoring-image-<machine>.ext4

   For a quick test with a pre-existing image, any .ext4 filesystem image will work — the agent writes it block-by-block to the inactive partition.

2. Package the image as an OTA-Pulse artifact

   Use otapulse-artifact to wrap the image with the required metadata:

   otapulse-artifact write rootfs-image \
       --device-type radxa-cm5-io \
       --artifact-name release-v1.0.0 \
       --file soc-monitoring-image.ext4 \
       --output firmware-v1.0.0.otapulse

   Flags:

   Flag	Value
   --device-type	Must match the value in /etc/otapulse/device_type on the target device
   --artifact-name	A unique name for this release (recommend release-vX.Y.Z)
   --file	The .ext4 root filesystem image
   --output	Output filename (use the .otapulse extension)

   Tip

   You can check what device type the agent reports by running cat /etc/otapulse/device_type on the device over SSH. The --device-type flag here must match exactly.

3. Upload the artifact to OTA-Pulse

   In the console, navigate to Firmware and click Upload Firmware. Select the .otapulse file, enter the version string, and click Upload.

   Alternatively, upload via the API. Firmware creation and file upload are two separate calls, authenticated with the Bearer access token from /api/auth/login — the console/management API uses JWTs, not the X-API-Key device credential:

   # 1. Create the firmware record
   curl -X POST "http://localhost:8000/api/firmware?organization_id=<organization-id>" \
     -H "Authorization: Bearer <access-token>" \
     -H "Content-Type: application/json" \
     -d '{"version": "1.0.0", "name": "release-v1.0.0"}'
   # → { "id": "<firmware-id>", ... }
   
   # 2. Attach the artifact file
   curl -X POST "http://localhost:8000/api/firmware/<firmware-id>/upload?organization_id=<organization-id>" \
     -H "Authorization: Bearer <access-token>" \
     -F "file=@firmware-v1.0.0.otapulse"

   The upload call stores the artifact and makes it available for deployment.

4. Create a deployment

   In the console:

   1. Navigate to Deployments → New Deployment.
   2. Select your target device (or a device group).
   3. Select the artifact you just uploaded.
   4. Set the schedule to Now and click Deploy.

   Via the API — deployments are created against the firmware record itself, not a separate /deployments endpoint:

   curl -X POST "http://localhost:8000/api/firmware/<firmware-id>/deploy?organization_id=<organization-id>" \
     -H "Authorization: Bearer <access-token>" \
     -H "Content-Type: application/json" \
     -d '{"device_ids": ["your-device-uuid"]}'

5. Watch the update

   The agent polls for deployments every 30 minutes by default. To trigger an immediate check:

   ssh user@<device-ip> "sudo systemctl restart soc-ota-agent"

   In the console, the deployment status transitions through:

   queued → downloading → installing → rebooting → success

   You can also tail the agent log on the device:

   ssh user@<device-ip> "sudo journalctl -u soc-ota-agent -f"

   A successful update ends with:

   INFO: Committing update
   INFO: Update successfully installed

Tip

Automatic rollback: If the device reboots into the new image but fails a health check, the bootloader counts boot attempts. After three consecutive failures, it automatically boots back into the previous (known-good) partition. The console shows the deployment status as failed and the device reverts to the prior artifact version.

Where to go next

Concepts

Understand the device lifecycle, deployment model, and how artifacts and RBAC work.

Read the concepts →

Device Integration

Guides for integrating the OTA agent into Yocto-based Linux images and custom board configurations.

Device integration guides →