Magnifica_S-Pro/docs/SETUP.md

Setup

1. Flash MicroPython

Use a current ESP32-C3 MicroPython build.

2. Initial device files

Copy:

firmware/boot.py       -> /boot.py
firmware/launcher.py   -> /launcher.py
firmware/app/          -> /app/
.env.example           -> /.env

Edit /.env on the ESP32 with real Wi-Fi/repository credentials.

3. Build the manifest before pushing a release

On your development machine:

python tools/build_manifest.py 1.0.0

Commit/push the resulting firmware/manifest.json together with the code.

The ESP32 compares SHA-256 hashes. A changed hash, not just the release label, determines whether a file updates.

4. Application interface

Recommended application shape:

async def setup(ctx):
    # initialize GPIOs and internal state
    ctx["system"].ready()

async def main(ctx):
    ...

ready() is significant after OTA: it says the new launcher/app got through setup successfully, so rollback backups may be deleted.

Context entries

• ctx["env"] — parsed local .env
• ctx["wifi"] — WiFiManager
• ctx["ble"] — BLE object or None
• ctx["uart"] — UART object or None
• ctx["activity"] — idle/busy tracker
• ctx["updater"] — UpdateManager
• ctx["system"] — ready/reboot helpers

5. Activity tracking

On user/device activity:

ctx["activity"].touch()

For a protected operation:

ctx["activity"].begin()
try:
    await operation()
finally:
    ctx["activity"].end()

A due update is postponed while the machine is active.

6. Energy-conscious configurations

OTA-only Wi-Fi:

WIFI_ENABLED=true
WIFI_KEEP_CONNECTED=false
BLUETOOTH_ENABLED=false
UPDATE_CHECK_INTERVAL_HOURS=24

Always-online remote-control Wi-Fi:

WIFI_ENABLED=true
WIFI_KEEP_CONNECTED=true
WIFI_POWER_SAVE=true

The ESP32-C3 supports BLE, not Bluetooth Classic.