From 8eb048d6817748164d8d81b4a98d4b6e0f447a63 Mon Sep 17 00:00:00 2001 From: Asklv Date: Sun, 8 Mar 2026 23:12:55 +0800 Subject: [PATCH 1/3] feat: add onboarding ap guide --- docs/WIFI_ONBOARDING_AP.md | 100 +++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/WIFI_ONBOARDING_AP.md diff --git a/docs/WIFI_ONBOARDING_AP.md b/docs/WIFI_ONBOARDING_AP.md new file mode 100644 index 0000000..bb06868 --- /dev/null +++ b/docs/WIFI_ONBOARDING_AP.md @@ -0,0 +1,100 @@ +# 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. From 4d5d2e1e5a93e833470e3517bf68af210cfc223b Mon Sep 17 00:00:00 2001 From: Asklv Date: Sun, 8 Mar 2026 23:13:01 +0800 Subject: [PATCH 2/3] feat: link onboarding guide in docs --- README.md | 1 + docs/tool-setup/README.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/README.md b/README.md index b733fbf..86dac08 100644 --- a/README.md +++ b/README.md @@ -291,6 +291,7 @@ Technical details live in the `docs/` folder: - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — system design, module map, task layout, memory budget, protocols, flash partitions - **[docs/TODO.md](docs/TODO.md)** — feature gap tracker and roadmap +- **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — how the local `MimiClaw-XXXX` onboarding/admin AP flow works - **[docs/tool-setup/](docs/tool-setup/README.md)** — configuration guides for external service integrations (Tavily, etc.) ## Contributing diff --git a/docs/tool-setup/README.md b/docs/tool-setup/README.md index 9eaaee5..4abdbea 100644 --- a/docs/tool-setup/README.md +++ b/docs/tool-setup/README.md @@ -2,6 +2,10 @@ Configuration guides for MimiClaw's external service integrations. +Related local setup guide: + +- [Wi-Fi AP Onboarding Guide](../WIFI_ONBOARDING_AP.md) — configure firmware builds that expose the local `MimiClaw-XXXX` onboarding/admin access point + ## Guides | Guide | Service | Description | From 05c23b2f65a0841b76c6487abad063cb025dda1e Mon Sep 17 00:00:00 2001 From: Asklv Date: Sun, 8 Mar 2026 23:13:04 +0800 Subject: [PATCH 3/3] feat: add onboarding guide links --- README_CN.md | 1 + README_JA.md | 1 + 2 files changed, 2 insertions(+) diff --git a/README_CN.md b/README_CN.md index f1cefa5..36e8e6e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -306,6 +306,7 @@ MimiClaw 内置 cron 调度器，让 AI 可以自主安排任务。LLM 可以通 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 系统设计、模块划分、任务布局、内存分配、协议、Flash 分区 - **[docs/TODO.md](docs/TODO.md)** — 功能差距和路线图 +- **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — 说明本地 `MimiClaw-XXXX` onboarding / 管理热点的使用方式 - **[docs/im-integration/](docs/im-integration/README.md)** — IM 通道集成指南（飞书等） ## 贡献 diff --git a/README_JA.md b/README_JA.md index fe91a8a..c134391 100644 --- a/README_JA.md +++ b/README_JA.md @@ -291,6 +291,7 @@ MimiClawにはcronスケジューラが内蔵されており、AIが自律的に - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — システム設計、モジュール構成、タスクレイアウト、メモリバジェット、プロトコル、Flashパーティション - **[docs/TODO.md](docs/TODO.md)** — 機能ギャップとロードマップ +- **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — ローカル `MimiClaw-XXXX` onboarding / 管理アクセスポイントの使い方 - **[docs/im-integration/](docs/im-integration/README.md)** — IMチャネル統合ガイド（Feishuなど） ## 貢献