merge: add in-app robot hotspot connection
This commit is contained in:
@@ -14,10 +14,12 @@ Implementation status: implemented and enabled by default. Exact environment val
|
||||
|
||||
- For V1 delivery only, this decision supersedes the proposed Security 2 / automatic-claim onboarding path in task `20260816-device-provisioning-flow-a4d91c`.
|
||||
- Authenticated BLE provisioning and automatic claim remain a deferred production-security direction, not a current implementation contract.
|
||||
- ADR-003 supersedes only this decision's manual operating-system hotspot-selection step; all other firmware, Portal, credential, Binding, rollback, and readiness boundaries remain active.
|
||||
|
||||
## Related
|
||||
|
||||
- Source proposal commit `14afe4a`: `.project-docs/10-decisions/proposals/20260816-minimal-firmware-onboarding-c3e8b7__guided-hotspot-binding-v1.md`
|
||||
- Cross-platform page-owned hotspot connection: ADR-003, `adr-003-robot-in-app-hotspot-connection.md`
|
||||
- Current Robot binding implementation: `src/pages/AiHardware/index.tsx`, `src/lib/ai-hardware.ts`, `electron/api/routes/ai-hardware.ts`
|
||||
- Firmware audit target: `D:\Datas\HardwareProjects\xiaozhi-esp32-firmware` at audited commit `0449e51`
|
||||
|
||||
@@ -33,7 +35,7 @@ V1 is a Renderer-guided, Main-gated workflow:
|
||||
|
||||
`choose_path -> prepare_robot -> connect_device_ap -> configure_wifi -> reconnect_internet -> enter_activation_code -> binding -> bound`
|
||||
|
||||
- Makelore explains how to place the Robot in provisioning mode and connect the computer to the Robot's existing Wi-Fi hotspot through the operating system.
|
||||
- Makelore explains how to place the Robot in provisioning mode, scans eligible open `Xiaozhi-*` hotspots through the Main-owned ADR-003 Module, and connects only the candidate the user explicitly selects. System Wi-Fi remains the recovery fallback.
|
||||
- Electron Main alone may open the fixed system-browser portal `http://192.168.4.1/`; Renderer never supplies or receives an arbitrary portal URL.
|
||||
- After Wi-Fi provisioning, Makelore instructs the user to reconnect the computer to the internet and obtain the freshly issued six-digit activation code from the Robot.
|
||||
- Binding continues to use the existing `bindAiHardwareDevice(activationCode, agentId, { operationId })` cloud contract.
|
||||
@@ -63,12 +65,12 @@ The user explicitly chose default-on on 2026-08-16 while retaining the current f
|
||||
|
||||
1. The exact shipped Robot component/image uses the audited Hotspot portal flow and fixed portal address.
|
||||
2. The deployed activation issuer emits exactly six ASCII digits accepted by the existing Works Binding validator, with documented freshness and consumption behavior.
|
||||
3. Electron E2E through the real Host API/native-opener seam and a physical-device smoke pass; focused Renderer/Main route tests already cover default-on, exact `0` rollback, fixed portal ownership, local-before-cloud behavior, and error redaction.
|
||||
3. Electron E2E through the real Host API/native opener and native hotspot seams plus Windows/macOS physical-device smoke pass; focused Renderer/Main/native tests already cover default-on, exact `0` rollback, fixed portal ownership, candidate constraints, local-before-cloud behavior, cancellation, and error redaction.
|
||||
4. Release/support instructions retain the exact `=0` rollback and do not describe V1 as authenticated discovery, automatic Wi-Fi delivery, automatic claim, or proof of online readiness.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The first implementation is desktop-only and requires no firmware, BLE, manufacturing, or cloud-contract change.
|
||||
- V1 cannot truthfully advertise automatic nearby-device discovery or automatic device claim.
|
||||
- The UI becomes a single coherent onboarding journey while system Wi-Fi selection and firmware portal entry remain explicit user actions.
|
||||
- V1 may advertise nearby provisioning-hotspot discovery and explicit user-selected connection as an unauthenticated convenience, but not trusted device discovery or automatic device claim.
|
||||
- The UI becomes a single coherent onboarding journey while system Wi-Fi remains a recovery path and firmware Portal entry remains an explicit user action.
|
||||
- A later authenticated BLE/automatic-claim design requires a new accepted ADR and must not silently widen this V1 interface.
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# ADR-003: Robot 配网页内连接 Windows 与 macOS 热点
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
Implementation status: implemented and enabled with Guided Hotspot Binding. Exact environment value `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0` disables the complete guided path and preserves direct six-digit Binding.
|
||||
|
||||
## Date
|
||||
|
||||
2026-08-16
|
||||
|
||||
## Supersedes
|
||||
|
||||
- Supersedes only ADR-002's requirement that the user leave Makelore and select the Robot hotspot in the operating-system Wi-Fi panel.
|
||||
- Preserves ADR-002's firmware-zero-change, fixed Portal, Wi-Fi credential isolation, Activation, six-digit Binding, `bound` semantics, and exact `=0` rollback.
|
||||
|
||||
## Context
|
||||
|
||||
ADR-002 delivered a coherent firmware-zero-change journey, but its `connect_device_ap` step remained manual. The user explicitly requested that Makelore show connectable Robot hotspots and connect the selected hotspot inside the binding dialog on both Windows and macOS.
|
||||
|
||||
The current firmware exposes an open `Xiaozhi-*` provisioning hotspot. Its SSID prefix is only a convenience filter: it does not authenticate Robot identity, ownership, account Binding, or online readiness. Exact shipped-image and physical-device behavior remain release evidence rather than assumptions.
|
||||
|
||||
## Decision
|
||||
|
||||
Electron Main owns a Robot Hotspot Module with platform Adapters:
|
||||
|
||||
- Windows uses the native WLAN API for open-network scanning, temporary discovery connection, and exact current-SSID verification. It does not parse `netsh` output or persist a Wi-Fi profile.
|
||||
- macOS uses CoreWLAN for scanning, association, and exact current-SSID verification. Main owns CoreLocation authorization; CoreWLAN work runs in an abortable worker that owns its Objective-C objects.
|
||||
- Unsupported platforms fail safely to the existing system-Wi-Fi/manual fallback.
|
||||
|
||||
Renderer accesses only two typed Host operations:
|
||||
|
||||
- `POST /api/works/ai-hardware/provisioning-hotspots/scan` accepts exact body `{}` and returns bounded `{ candidate_id, ssid, signal_percent, connected }` projections.
|
||||
- `POST /api/works/ai-hardware/provisioning-hotspots/connect` accepts exact body `{ candidate_id }` and succeeds only after the current SSID exactly matches the selected candidate.
|
||||
|
||||
Both routes authenticate through the normal loopback Host boundary, check the Main-owned capability, and finish locally before Works credentials or upstream access. Native diagnostics, BSSID, interface names, profiles, and location data never cross into Renderer.
|
||||
|
||||
Entering `connect_device_ap` starts a scan. Makelore displays nearby eligible hotspots and requires the user to choose one explicitly; it never auto-connects the strongest candidate. A verified connection advances to the existing fixed-Portal step. Permission denial, no candidates, timeout, unsupported platform, or connection failure retains a safe retry and manual system-Wi-Fi path.
|
||||
|
||||
## Candidate And Operation Rules
|
||||
|
||||
- Only explicitly open, connectable, printable `Xiaozhi-*` SSIDs no longer than 32 UTF-8 bytes are eligible.
|
||||
- Duplicate SSIDs collapse to the strongest candidate. BSSID never leaves Main.
|
||||
- Candidate IDs are unpredictable and valid only for the latest bounded Main snapshot; rescan, clear, process restart, or the 60-second TTL invalidates them.
|
||||
- Scan and connect are mutually exclusive and bounded. Abort or dialog-session replacement prevents stale permission, worker, or UI continuation.
|
||||
- Discovery and association are unauthenticated convenience signals. They must not be presented as trusted physical identity, automatic claim, or protocol-online proof.
|
||||
|
||||
## Security And Privacy
|
||||
|
||||
- Main is the only native-network owner. Renderer cannot submit an arbitrary SSID, BSSID, interface, profile, command, or URL.
|
||||
- Makelore handles no Robot-hotspot password and no home-network credential. Home Wi-Fi SSID/password remain inside the firmware Portal.
|
||||
- Logs and safe errors exclude BSSID, interface/profile details, native diagnostics, Wi-Fi credentials, and location data.
|
||||
- The current open SoftAP/plain-HTTP risk and public-environment warning remain. Default-on does not make the channel authenticated.
|
||||
|
||||
## Verification And Release Gates
|
||||
|
||||
The implementation passed focused Renderer/Main/native tests, the full unit suite, typecheck, lint, production build, Windows Electron/Koffi/WLAN definition loading, a Windows permission-denied native probe, and independent Standards/Spec review.
|
||||
|
||||
Before claiming complete two-platform hardware acceptance, release evidence must still include:
|
||||
|
||||
1. A Windows physical Robot scan, selection, connection, exact-SSID verification, Portal, and Binding smoke with location/Wi-Fi access enabled.
|
||||
2. Signed packaged macOS x64 and arm64 permission, scan, association, worker/ASAR/Koffi loading, current-SSID, Portal, and Binding smoke.
|
||||
3. Electron E2E through the real Host API and native platform seam for success and recovery outcomes.
|
||||
4. Exact shipped-firmware hotspot naming/open-network behavior, fixed Portal, and six-digit issuer/validator compatibility.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Users can select and connect a Robot provisioning hotspot without first leaving Makelore, while the manual system path remains available.
|
||||
- The firmware, fixed Portal, cloud Binding contract, and credential boundary remain unchanged.
|
||||
- Packaging now includes a native Koffi dependency and macOS location usage descriptions, expanding signing and platform acceptance work.
|
||||
- Trusted discovery, automatic claim, or new firmware provisioning still requires a separate authenticated protocol and accepted ADR.
|
||||
@@ -6,6 +6,7 @@
|
||||
|---|---|---|---|---|---|
|
||||
| ADR-001 | AI 绘画采用 Workspace / Conversation / Task 分层状态与服务端持久 Conversation Session | Accepted | 2026-08-11 | AI 绘画客户端、Main 适配器、Works Square API | `adr-001-ai-design-conversation-ownership.md` |
|
||||
| ADR-002 | Robot V1 采用 Main 门控的引导式热点配网并衔接现有六位 Binding | Accepted / implemented, default on | 2026-08-16 | Robot Renderer、Host API、Electron Main、现有固件热点入口 | `adr-002-robot-guided-hotspot-binding-v1.md` |
|
||||
| ADR-003 | Robot 配网页内扫描并连接 Windows/macOS 热点 | Accepted / implemented with physical release gates pending | 2026-08-16 | Robot Renderer、Host API、Electron Main、Windows WLAN、macOS CoreWLAN/CoreLocation | `adr-003-robot-in-app-hotspot-connection.md` |
|
||||
|
||||
## Superseded Decisions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user