Artifacts

A firmware artifact is the binary payload that a device downloads and applies during an OTA update. OTA-Pulse stores artifacts server-side and serves them to devices on demand. Before you can create a deployment, the firmware record must have an artifact attached.

Format

OTA-Pulse accepts only OTA-Pulse artifacts — files with the .otapulse extension. An OTA-Pulse artifact is a tar-based container that includes the raw firmware payload, metadata headers (artifact name, compatible device types), and optional state-script hooks. The server rejects uploads with any other extension.

The artifact container is derived from an open-source artifact format, version 3. It is not a new container format. Its internal version member carries a format identifier. Artifacts written by otapulse-artifact 3.11.2-op2 and later report {"format":"otapulse","version":3}. Artifacts written by earlier tool builds report an older identifier, and OTA-Pulse accepts both. See Open-source attributions for the identifiers and the licensing details.

If you have a raw firmware image (.img, .ext4, .bin) you need to wrap it first using the otapulse-artifact CLI tool:

otapulse-artifact write rootfs-image \
    -t <your-device-type> \
    -n release-v1.2.0 \
    -f firmware.ext4 \
    -o firmware-v1.2.0.otapulse

The server can also wrap a previously uploaded raw image for you via POST /firmware/{id}/create-artifact if the otapulse-artifact tool is installed on the server. Call GET /firmware/artifact-tool/status to check availability.

What happens on upload

When you call an upload endpoint:

1. The file streams to disk at /var/lib/soc-monitoring/storage/firmware/{org_id}/{version}.otapulse.
2. A SHA-256 checksum is computed while writing and stored on the firmware record.
3. If otapulse-artifact is available, the server extracts artifact_name and device_types from the artifact headers and updates the record.
4. Signature status is evaluated and stored as signed, unsigned, or invalid.

To inspect metadata without saving, use POST /firmware/preview-artifact.

Signing

Signing is required by default (ARTIFACT_SIGNATURE_REQUIRED=true). An unsigned or invalid signature status causes the upload to be rejected with 422. Operators can opt out with ARTIFACT_SIGNATURE_REQUIRED=false for development only.

Supported public key types (imported as an SPKI BEGIN PUBLIC KEY PEM):

Algorithm	Details
RSA	2048, 3072 or 4096-bit
ECDSA-P256	NIST P-256 curve

ECDSA P-384, Ed25519, PKCS#1 keys and private keys are rejected on import, and the console can no longer generate P-384 keys: the signing tool and the device agent cannot use them. Legacy P-384 keys already registered are shown as not artifact-compatible and are ignored during verification.

Sign the .otapulse file with otapulse-artifact write ... --key <private-key> so the signature is embedded in the artifact. On upload, the server checks that embedded signature against the public keys it trusts: a match yields signed, a signature that matches none yields invalid, and no signature yields unsigned. The keys checked are your organization’s active signing keys plus any deployment-wide ARTIFACT_VERIFY_KEY_PATHS.

Register your key in the console: Signing Keys -> Import Public Key (organization owner; API: POST /signing-keys/import). Replace and Revoke on the same page (and POST /signing-keys/{id}/replace, DELETE /signing-keys/{id}) require typing delete to confirm. Revoked keys reject new uploads, and an organization can hold up to 10 active keys. Generate Key (RSA-4096 or ECDSA-P256) creates a pair server-side and shows the private key once, never stored.

The server cannot push keys to devices. Registering a key only changes what the server accepts at upload; the same public key must be baked into the device image. See the End-to-end quickstart.

On the device, place the public keys in /etc/soc-monitoring/signing-keys/active/ and list them under ArtifactVerifyKeys in the agent config.

Delta updates

Delta updates are not currently supported. Every device receives the complete artifact regardless of its current firmware version. The min_version field on a firmware record can be used to skip devices running firmware that is too old, but no binary diff is computed.

Storage

Artifacts are stored at /var/lib/soc-monitoring/storage/firmware/{organization_id}/ on the server filesystem. There is no API-layer size limit; available disk is the ceiling.

Devices download artifacts from /api/devices/v1/deployments/{id}/download. That URL is issued by the server in the check-for-update response, and it is the same on the native and legacy device APIs. See the Device API.

The SHA-256 checksum is returned in the X-Checksum response header when the agent downloads an artifact, enabling end-to-end integrity verification independent of TLS.