mimiclaw/docs/WIFI_ONBOARDING_AP.md

Wi-Fi AP Onboarding Guide

This guide documents the Wi-Fi onboarding flow for firmware builds that include the MimiClaw onboarding portal.

What It Does

When onboarding is enabled, MimiClaw can expose a local Wi-Fi access point such as MimiClaw-XXXX and serve a configuration page at http://192.168.4.1.

Typical uses:

• first-time Wi-Fi setup without editing firmware
• updating saved Wi-Fi, model, proxy, or bot credentials later
• recovering a device that can no longer join the previous router

Requirements

• a firmware build with the Wi-Fi onboarding portal enabled
• an ESP32-S3 board powered on and booted normally
• a phone or laptop that can join the temporary MimiClaw-XXXX network

First-Time Setup

1. Power on the device.
2. Wait for the onboarding hotspot MimiClaw-XXXX to appear.
3. Join that hotspot from your phone or laptop.
4. Open http://192.168.4.1 if the captive page does not open automatically.
5. Fill in at least:
   • SSID
   • Password
6. Add optional settings if needed:
   • API Key
   • Model
   • Provider
   • Telegram
   • Feishu
   • Proxy
   • Search
7. Click Save & Restart.
8. Wait for the device to reboot and join your normal Wi-Fi network.

Updating Settings Later

If the firmware keeps the admin AP online after normal Wi-Fi connection, you can reconnect to MimiClaw-XXXX later and open http://192.168.4.1 again.

The page should prefill the currently effective configuration so you can edit only the fields you want to change.

Config Priority

The onboarding page follows the same config priority as the firmware:

1. saved NVS values
2. build-time defaults from main/mimi_secrets.h

That means:

• if a field exists in NVS, it overrides the build-time default
• if you clear a saved field and reboot, the device falls back to main/mimi_secrets.h
• if both NVS and build-time values are empty, the field stays empty

Clearing Saved Values

On firmware versions that support clearing fields from the portal:

• leaving a field blank and saving removes the corresponding NVS key
• after reboot, the page shows the build-time fallback if one exists

If you need to wipe all saved runtime settings, use:

mimi> config_reset

Troubleshooting

No MimiClaw-XXXX hotspot appears

• verify that the running firmware actually includes the onboarding portal
• if the device already connects successfully and does not keep the admin AP online, clear Wi-Fi config and reboot
• confirm the board has finished booting before scanning for Wi-Fi

The page still shows old values

• refresh the page manually
• reconnect to the AP and open http://192.168.4.1 again
• if needed, restart the browser once to clear stale captive portal state

The build-time provider/model do not show up

If the device already has model or provider saved in NVS, the saved values win over main/mimi_secrets.h.

To return to build-time defaults:

• clear those fields in the portal and save, or
• run config_reset

Notes

• The onboarding AP is typically local-only and intended for nearby configuration.
• Current onboarding implementations may use an open AP for simplicity, so avoid leaving it exposed longer than necessary.
• If your deployment needs stronger local protection, add an AP password before using the flow in production.