IoT Platform

Architecture

Every device is a "stem cell": the same firmware and platform code on every board, with only app.py differing per app type. The app type is read from the board's EEPROM at boot (the server can override it), and the server delivers the matching code. boot.py is only a small loader; all boot logic lives in platform_boot.py, which arrives by OTA like the rest of the platform. USB is needed only to set up a brand-new board — see First-time setup for exactly which files.

Core rules

• Offline-first. Every device works without WiFi. If WiFi, the API or an OTA fails and an app is installed, the app starts anyway; the platform keeps trying to connect in the background.
• Code arrives only at boot. The heartbeat never delivers files. To push an update, the server asks the board to restart (directly, or via the next heartbeat reply) and platform_boot installs it.
• The server is the single source of truth for device identity, name, app type, WiFi networks, boot policy and time. The device database is keyed by MAC.
• All times are UTC — on the device RTC, in the logs, and in the database.
• Every deliberate restart leaves a reason. On the Pico, machine.reset() reports as WDT, the same as a hang; the reason file tells them apart. Nothing calls machine.reset() without it.
• Server-side compilation. For boards that support it, the server compiles platform and library modules to .mpy; main.py, boot.py and app.py stay as .py. Nobody runs mpy-cross by hand.

Execution order

# every power-on or reset
boot.py  (loader)
  → run the first working slot: platform_boot → platform_boot_prev
                                → platform_boot_last_working

platform_boot
  → rotate logs, log the reset cause (+ requested reason, if any)
  → policy says skip network and an app exists → done, main.py runs
  → connect WiFi  (strongest known network; AP mode if none configured)
  → read app_type from EEPROM
  → POST /iot/boot  (MAC, hardware, app type, MD5 of code files, reset cause)
  → store name, time, boot policy, WiFi networks
  → if update: download + verify all files, then install → restart
  → any failure with an app installed → main.py runs offline

main.py
  → asyncio.gather(
      platform.start(app),   # web server, WiFi, heartbeat, watchdog
      app.run()              # device sensor / actuator loop
    )

platform
  → first heartbeat as soon as WiFi is up (firmware + META + vitals)
  → then every 5 min while online: vitals + telemetry; reply sets the clock,
    may carry "app" (→ app.on_server) or "restart": true

Telemetry flow

The app pushes key/value pairs through platform.report(). They appear at the top level of GET /status on the device, and every heartbeat carries them as telemetry. An app that wants a change shown at once calls await platform.heartbeat_now().

# app.py (sensor loop)
platform.report(
    distance_mm   = dist,
    sensor_status = "ok",
)
# → merged into GET /status
# → sent with the next heartbeat as "telemetry"

First-time Setup — What Goes on via USB

A brand-new board needs a few files over USB before OTA can take over. The reason is that boot.py is only a loader: it has no WiFi and no OTA code. A board with boot.py alone finds no boot slot, logs no working boot slot, and never contacts the server. At least one boot slot must therefore be on the board from the start.

Loaded via USB — once per new board

Not needed via USB — arrives by OTA at the first boot

• main.py, platform.py, web_server.py, iot_registry.py
• app.py and any app drivers (e.g. vl53l0x.py), from boot/<app_type>/
• platform_boot_prev and platform_boot_last_working
• A compiled platform_boot.mpy, which replaces the USB-loaded platform_boot.py (the .py is removed when the .mpy is installed)

App type

The app type is not a file. Either write it to the board's AT24C16 EEPROM, or leave the EEPROM empty or absent and assign the type from the console (PUT /iot/devices/<id>/app-type, as override or fallback) after the board's first check-in. Without either, the board comes up as undefined-xxxx with no app.

Copy order

boot.py goes last, so it cannot start running while the session is still copying:

mpremote cp microdot.py       :microdot.py      + \
         cp wifi.json         :wifi.json        + \
         cp platform_boot.py  :platform_boot.py + \
         cp boot.py           :boot.py          + \
         reset

What happens at the first power-on

Checking that the board is up

GET /iot/devices/by-mac/<mac> answers for this specific board, with no database credentials. heartbeat_after_boot tells you the platform is running, not just that the board checked in.

Boot — Loader, platform_boot & OTA

Two files run before main.py. boot.py is a permanent loader with no platform logic. platform_boot.py does the work: WiFi, boot policy, app type, check-in, OTA sync, name and clock. One set serves both Pico W (rp2) and ESP32 (esp32); the board is detected via sys.platform.

The loader (boot.py)

Tries three slots in order. A slot that raises goes to the next at once. A slot that hangs or resets the board 3 boots in a row (counted in /boot_try.txt) is skipped the next time. When every slot has failed repeatedly, only main.py runs. Problems are written to /loader_log.txt.

platform_boot sequence

Boot policy

Sent by the server in the /iot/boot answer and cached in /boot_policy.json, so it also applies to boots that skip the network.

POST /iot/boot — request

POST /iot/boot — response

platform.py — Runtime Contract

The public API that app.py is written against. Identical across all devices — never edited per device.

What the platform gives app.py

What app.py exports

DEVICE_TYPE is no longer used — platform_boot reports the hardware.

Minimal app.py skeleton

# app.py — skeleton for a new app type
import asyncio
import platform

FIRMWARE = "1.0.0"
META     = {"capabilities": ["sensor"], "sensor": "my_sensor"}

platform.register_pins({"i2c_sda": 4, "i2c_scl": 5})

_last = {"value": None}

async def get_reading(request):
    return _last

platform.register_routes([
    ("GET", "/reading", get_reading),
])

async def run():
    while True:
        _last["value"] = read_sensor()
        platform.report(value=_last["value"], status="ok")
        await asyncio.sleep_ms(100)

Identify

POST /identify blinks every indicator in groups of three fast blinks for ?seconds=N (default 10). Indicators are the onboard LED and an external status LED for boards inside an enclosure:

Override with "onboard_led" and "status_led_pin" in /config.json (null disables). Both pins are reserved automatically. If the app defines identify(), it runs as well. Apps that only report np_pin/num_leds get the old blue strip blink as a legacy fallback.

Platform tasks

platform.start(app) runs these concurrently; the app's run() is gathered alongside by main.py.

Restart reasons

On the Pico, machine.reset() reports as reset cause WDT — exactly like a hang. So every deliberate restart first writes /restart_reason.txt: UTC time, source and reason, e.g. 2026-10-25 11:39:23Z boot: OTA installed version a98f7213509a.

At the next boot, platform_boot logs one of:

[boot] reset cause: WDT (requested: 2026-10-25 11:39:23Z boot: OTA installed version a98f7213509a)
[boot] reset cause: WDT — no restart was requested: the watchdog fired (something blocked or hung), or machine.reset() from a REPL

It then moves the file to /last_restart.txt, so an old reason can never explain a later hang, and sends it as restart_reason. The platform logs it once in platform_log.txt as previous restart: …, or previous reset: WATCHDOG … when none was requested.

Memory safety net

An HTTPS heartbeat needs a large contiguous block of RAM for the TLS handshake. Two measures keep it working on small boards:

• TLS reserve. At import, before the app fragments the heap, platform.py takes a block (default 40 KB, "tls_reserve_kb", 0 = off) and releases it for the first heartbeat after boot. It is not taken back afterwards.
• Self-restart. A heartbeat that fails for lack of memory (MemoryError / ENOMEM) is retried once after gc.collect(). After 3 such failures in a row the board restarts with that reason. A loop guard in /restart_count.txt allows at most 2 such restarts without a successful heartbeat; after that the board keeps running and retrying. Network and server errors never cause a restart, and a server-requested restart does not count.

Configuration keys used by the platform

Read at start-up — changes take effect after a restart. Boot settings live in the boot policy, set by the server.

web_server.py — HTTP Layer

Microdot server on port 80. Owns the platform endpoints below, present on every device, and exposes the Microdot app so platform.register_routes() can attach app routes. Every request (except /logs/api) is logged to a 10-entry ring buffer in /api_log.json. microdot.py itself is loaded via USB on a new board (see First-time setup).

iot_registry.py — Heartbeat Client

Talks to the IoT API on behalf of the platform. Registration and heartbeat OTA are gone: platform_boot reports what the board is, the first heartbeat reports what the app says, and code only ever arrives at boot.

The heartbeat uses asyncio streams with TLS, so the web server, app and watchdog keep running during it. If this MicroPython build lacks async TLS, it falls back to blocking urequests. Timeout 15 s; replies are capped at 8 KB.

Functions

Heartbeat payload

Heartbeat reply

Server Side

api/iot/devices.py serves OTA files from iot-device-code/boot/: base/ for the platform (including boot.py and platform_boot.py), overlaid by <app_type>/. An app-type folder must exist for a type to be valid.

Naming and identity

• The MAC is the identity. The name is always derived: <app_type>-<last 4 MAC hex>, widened to 6 hex digits on a clash.
• When the effective app type changes, the device is renamed (a rename event); heartbeats under the old name still reach it.
• App type resolution: server override → EEPROM → server fallback → undefined. Assignments take effect at the next boot. Proto 2 boards can't follow a server-chosen type; they need proto 3.
• Deleting a device archives it: the row and events are kept, the MAC moves to old_mac, the name becomes <name>~<registered_at>. If the board shows up again it is a new device, linked to its previous incarnation. ?purge=true removes a row for good.

Status (computed, never stored)

Endpoints

/iot/register no longer exists.

Files on the device

Changes