Skip to content

Your first deployment

A deployment is the answer to "who, of what, at what percentage?". It binds a firmware artifact to one or more device groups and/or release channels, with a percentage rollout.

1. Upload a firmware artifact

From the dashboard, in Advanced mode: the Firmware artifacts card on the project page, then Upload. You'll need:

  • firmware.bin: the application binary.
  • The manifest, which declares compatibility (chip, board, partition, NVS schema). It is required for every upload, on both frameworks. In the dashboard you fill it in as ordinary form fields; over the API it is a JSON form field. See Manifest schema.

Or via the API:

MANIFEST_JSON=$(jq -c . manifest.json)

curl -X POST https://simpleota.com/api/v1/projects/${PROJECT_ID}/artifacts/ \
  -H "Authorization: Bearer ${PROJECT_TOKEN}" \
  -F "manifest=${MANIFEST_JSON}" \
  -F "[email protected]"

The response includes the build number SimpleOTA allocated. Build numbers are project-scoped, monotonic, and never reused.

2. Create a deployment

On the project page, the Deployments card, then New deployment. Pick:

  • Artifact: the build you just uploaded.
  • Audience: one or more device groups and/or channels (the default channel is stable).
  • Percentage: start small. 5 is a sensible canary.
  • Rollout seed: auto-generated. Used for cohort math; same seed always produces the same exposure ordering. Don't change it during a rollout.

Save. The deployment is created in the draft state, which means it is not offering anything yet.

Saving does not start it

Open the deployment and click Start. Until you do, no device is offered the build, however long you wait. Over the API this is POST .../transition/ with {"action": "start"}.

Once started, the next time targeted devices poll, eligible cohorts receive the offer.

3. Watch progress

Open the deployment detail page. The counters refresh on their own:

  • Offered: devices that fell inside the cohort cutoff.
  • Downloaded, Confirmed, Failed, Rolled back: outcomes reported via /api/v1/ota/status/.
  • Pending: offered, with no terminal status yet.

When you're confident, ramp up using the deployment's rollout control: 25, then 50, then 100. The audience and artifact are immutable, so this is the only thing you can change after creation. Same seed means existing cohort decisions stick; only new buckets cross the threshold, and ramping is refused if it would lower the percentage.

4. If something goes wrong

Pause deployments →