101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
|
# 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:
|
||
|
|
|
||
|
|
```text
|
||
|
|
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.
|