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: Project → Artifacts → Upload. You'll need:
firmware.bin: the binary itself.- A manifest sidecar (required for Arduino, optional for ESP-IDF). The manifest declares compatibility (chip, board, partition, NVS schema) because the binary itself is unreliable for self-description on Arduino. 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¶
Project → Deployments → 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.
5is 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 now active. The next time targeted devices poll, eligible cohorts will receive the offer.
3. Watch progress¶
Open the deployment detail page. The counters live-update:
- Eligible: devices in the audience whose hardware matches.
- Offered: devices that fell inside the cohort cutoff.
- Succeeded / Failed: outcomes reported via
/api/v1/ota/status/.
When you're confident, ramp up: edit the deployment, raise the percentage
to 25, then 50, then 100. Same seed → existing cohort decisions
stick; only new buckets cross the threshold.