# Setup

## 1. Flash MicroPython

Use a current ESP32-C3 MicroPython build.

## 2. Initial device files

Copy:

```text
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:

```bash
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:

```python
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:

```python
ctx["activity"].touch()
```

For a protected operation:

```python
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:

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

Always-online remote-control Wi-Fi:

```env
WIFI_ENABLED=true
WIFI_KEEP_CONNECTED=true
WIFI_POWER_SAVE=true
```

The ESP32-C3 supports BLE, not Bluetooth Classic.