OTA Firmware Upgrade

FastBee devices support full OTA (Over-The-Air) firmware upgrades via local file upload and online URL upgrade in the Web UI.

Requirement

OTA requires an app1 (ota_1) partition. Devices on the 4MB single-app layout (e.g. esp32-F4R0) cannot OTA; the API returns 501. See Partition Layout Constraints.

1. Prerequisites

Condition	Detail
ota_1 partition present	8MB layout (3.5MB × 2 apps) or 16MB layout (4MB × 2); not possible on 4MB single-app
Free DRAM ≥ 20KB	Memory gate before begin (OTA_MIN_FREE_DRAM = 20480); otherwise 503 (retryable)
Firmware ≤ maxSketchSpace	Roughly the OTA partition size
Authenticated session	All /api/ota/* routes require the sessionId cookie

2. Upgrade Methods

1. Web local upload (recommended): System → OTA page → select .bin → upload. The device reboots automatically 3 seconds after the write completes.
2. Online URL upgrade: paste a firmware download URL; progress via /api/ota/status.
3. API: see API Reference - OTA.

3. Flow

Client                          Device
  │  POST /api/ota/begin          │
  ├──────────────────────────────►│ memory gate + ota_1 pre-check
  │  ◄────────────────────────────┤ ok: max_size; fail: 400/501/503
  │  POST /api/ota/upload         │
  ├──────────────────────────────►│ writeData into app1; endOTA on final chunk
  │  ◄────── completion ──────────┤ reboot scheduled in 3s (reason OTA_UPDATE)
  │        (3s later)             │ rst:0xc (SW_CPU), boots app1
  │  GET /api/health (poll)       │

Key design points:

• Response before reboot: the completion response is sent first; reboot happens 3s later so clients can read it.
• Restart diagnostics: /api/system/diag-bundle → restart.lastRestartReason records OTA update completed, usable as the success verdict.
• Cancellable: POST /api/ota/cancel aborts a stuck session.

4. Status Codes

Code	Meaning	Client Strategy
200	Success	Continue
400	Bad params / OTA session conflict / upload without begin	Do not retry
501	No OTA partition (permanent hardware limitation)	Never retry
503	Memory-pressure gate	Retry per Retry-After
500	Other internal error	Retry cautiously

5. Client-Side False Failures

After a successful write the device reboots and the HTTP connection drops. Clients like Node.js undici may throw fetch failed / connection reset — this does not mean the upgrade failed.

Reliable verdict chain:

1. On upload network error, don't fail immediately;
2. Poll /api/ota/status — a 401 means the device already rebooted (sessions are memory-only);
3. Poll /api/health (no auth) until the device is back;
4. Log in again and check diag-bundle.restart.lastRestartReason for an OTA match.

scripts/e2e-ota-test.js implements exactly this arbitration chain and can serve as a reference client.

6. Serial Verification

At 115200 baud you should see:

ota_start → write progress → ota_success
[RESTART] Reason: OTA update completed
rst:0xc (SW_CPU)
... normal boot, [BOOT] Platform ready!

Related

• Partition Layout Constraints
• API Reference
• Troubleshooting