FAQ¶
General¶
Why ESP32 only?¶
Because that's what we use, and because constraining the scope keeps the compatibility model simple. The data model is generic enough that adding a new chip family is a field-and-filter change, not a redesign.
Is there a CLI?¶
Not yet, but for GitHub the SimpleOTA actions cover most of what a CLI would be used for: they sign, upload and deploy in a few lines. Elsewhere the dev API is stable and CI-friendly; see the GitLab CI guide for a ready-to-paste template.
Rollouts¶
How do I do a 100% rollout?¶
Set percentage = 100 on the deployment. Every device in the target
groups + channel that is compatible with the artifact will be offered
the update on its next poll.
How do I revert?¶
Create a new deployment that targets the previous artifact (lower build number). Devices polling will receive… nothing, because the decision engine compares strictly: a device on build 47 is not "updated" to build 42.
To roll back, you upload a new artifact whose contents are the old build, and which therefore gets a fresh, higher build number. See Pausing deployments for the long version.
Can I schedule a rollout to start at a specific time?¶
Active deployments take effect immediately. Pre-creating a deployment
in the paused state and flipping it to active at the desired time
is the supported workaround today.
Will my staging device always get the update before production?¶
Yes, if you put it in a staging device group and target your staging-only deployments at that group. The decision engine never crosses group boundaries.
Devices¶
What's a device UID?¶
Whatever stable identifier you supply when calling /api/v1/ota/check/.
The MAC address or chip ID work well. SimpleOTA does not generate one
for you; your firmware must pick one and stick with it.
A device polled twice and got two different cohorts. Bug?¶
No; the cohort is a function of (deployment.seed, device.id). If
you re-registered the device (different device_id ⇒ different UUID)
between polls, that's a new cohort. Otherwise check whether the
deployment's seed was edited.
What does active=False mean?¶
The device is recognized but excluded from updates. Common causes:
- Plan downgrade exceeded the device cap (plan enforcement).
- Operator manually deactivated it via the dashboard.
Billing¶
What happens at the end of a paid trial?¶
Stripe transitions the subscription to active (if the card succeeded)
or canceled (if it didn't). Your plan updates accordingly. If it
lands on canceled, oldest-active-wins runs.
My payment method failed and devices are over the cap. Will they break?¶
Devices over cap receive {"status": "over_limit"} with HTTP 200; no
retry storm, no broken hardware. As soon as the subscription is
restored, the cap re-expands and devices resume receiving updates.
Operations¶
How do I rotate a project token?¶
Issue a new token from the Project API tokens card, update your CI secret, then Revoke the old one. That order leaves no window where CI is without a working token. Both actions are audited.
Where are the build logs?¶
Wherever your CI puts them. SimpleOTA stores the firmware artifact, the manifest, and the audit trail of who uploaded it. Your CI run history is the source of truth for how the artifact was built.
Can I delete an artifact?¶
No. Once an artifact is ready it is permanent, in the dashboard and the
API alike. Deleting the project is what removes it.
To take a build out of circulation, archive it from the artifact's page. An archived build is never offered and cannot be picked for a new deployment, while the history of which devices ran it survives. Archiving is refused while a live deployment still references the build, so cancel or complete those first. Its build number stays spent either way, since devices may already have recorded it.