mobile-app: commission an ESP32 over its setup Wi-Fi (SoftAP)

Aperta
  • Qualcosa non va?
#341 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@issdn ci sta già lavorando.

Dal 28/10/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

iot client mobile-app

Sub-issue of #57 (SoftAP half). Builds on #331 (feat/softap-provisioning, ADR-0074).

Context

ADR-0074 decision 11 has installers commission an ESP32 over its setup network with locker-firmware/scripts/commission.py --softap on a laptop. It leaves the mobile app as "a later issue", and the plan comment on #57 calls it "a later decision". This issue is that decision. No other issue covers it.

The goal is to commission a unit from mobile-app/ with nothing but a phone: join the unit's setup Wi-Fi, prove the setup password (Security 2), send ol-config (broker, bootstrap login, token), then the Wi-Fi settings. The unit's device side does not change.

Research result: feasible on both platforms, not yet tried on a device

Verified by reading the library sources, not by running anything.

Need iOS: ESPProvision (Swift, iOS 13+) Android: esp-idf-provisioning-android (API 26+)
Join the unit's WPA2 setup AP with the label passphrase Yes. ESPDevice(... softAPPassword:) and connect() use NEHotspotConfiguration Yes. connectWiFiDevice(ssid, password) uses WifiNetworkSpecifier on Android 10+
Security 2 with a username Yes. username: and proofOfPossession: (the SRP password) Yes. setUserName(), setProofOfPossession()
Send bytes to a custom endpoint (ol-config) Yes. sendData(path:data:completionHandler:) Yes. sendDataToCustomEndPoint(path, byte[], ResponseListener)
Provision Wi-Fi (prov-config) Yes. provision(ssid:passPhrase:) Yes. provision(ssid, passphrase, listener)

Neither README documents the custom-data call; the signatures are from ESPDevice.swift and ESPDevice.java on the default branches.

Fit with the firmware (components/lc_softap_espidf/softap.c): the unit's SRP username is the standard wifiprov, and the endpoints are proto-ver, prov-config and ol-config. The ol-config v1 payload is a version byte plus tag-length-value items (commission.py: ol_config_payload), which is trivial to build in TypeScript.

The React Native layer is the work

There is no Espressif React Native library. Candidates found:

  • react-native-esp-prov-toolkit: MIT, iOS and Android, SoftAP and BLE, Security 0/1/2 with username and softAPPassword. Needs RN 0.78+ and react-native-nitro-modules. Its README does not mention a custom-endpoint send, so it would need a fork or an addition. Its README also lists known BLE hang issues (not relevant to SoftAP).
  • futuristiclabs/react-native-esp32-idf-provisioning: lists custom data, but it is unpublished and proprietary. Not usable.
  • react-native-esp32-provisioning (Android wrapper only), @kafudev/react-native-esp-idf (about 20 downloads a week), esp-idf-ble-provisioning-rn (Android, BLE focused). Not suitable.
  • A local Expo module (Swift and Kotlin) wrapping the four calls above is the fallback and is small.
Expo and project fit
  • mobile-app already runs as a dev build (expo start --dev-client), so native code is possible. Expo Go will not work for this screen.
  • Needs an Expo config plugin for: iOS "Hotspot Configuration" and "Access WiFi Information" capabilities, NSLocationWhenInUseUsageDescription, NSLocalNetworkUsageDescription (per the iOS README); Android permissions and the JitPack repository.
  • iOS Hotspot Configuration works on a physical device only and needs a signed build, so it depends on #242.
  • On iOS, SoftAP device search is not supported by the library; the app must already know the unit's SSID. The label would need to carry it, for example as a QR code. Decision needed on the label format.

Scope

  • Spike on a physical iPhone and Android phone: join the AP, Security 2 session, ol-config, provision, unit enrolls. Prove or kill the points under "Risks" first.
  • Choose the wrapper: fork of react-native-esp-prov-toolkit or an own Expo module.
  • Config plugin for entitlements, Info.plist keys, Android permissions and repositories.
  • Commissioning flow in mobile-app/: scan the label, join, send, show "saved", then read the result from the bank's status in the app, as ADR-0074 decision 8 requires (the unit reports only "saved").
  • Get the one-time token and the bootstrap login to the phone (see below).
  • ADR for the flow and any new API (see CLAUDE.md: API contract and cross-component changes need an ADR).
  • Docs: update the install guide for ESP32 with the phone path.

Open questions and risks

  1. Where do the token and bootstrap login come from? A token is issued today only in the admin panel (LockerBankResource, "Issue provisioning token"; I found no provisioning route in routes/). The bootstrap login is the backend's MQTT_PROVISIONING_USERNAME and MQTT_PROVISIONING_PASSWORD. A phone flow needs an authenticated API for an administrator to issue a token and receive the bootstrap login, without shipping the login in the app. This changes the API contract, so it needs an ADR.
  2. Security 2 patch level. commission.py reads the patch level from the unit's proto-ver reply (ESP-IDF 6.1, network_provisioning 3.0.0). The spike must show the native libraries negotiate it correctly.
  3. Label format. SSID, AP passphrase and setup password are on the label today. For the phone, decide on a QR payload.
  4. Release blocker unchanged: flash and NVS encryption (ADR-0074 decision 18). The phone flow does not change the exposure of the setup secrets stored on the unit.
  5. Is a phone flow worth it? The benefit over USB or a laptop is phone-only commissioning by non-technical installers. If installers have laptops, commission.py --softap already works.

Not in scope

  • BLE provisioning (rejected for the pilot in ADR-0074).
  • Changes to the firmware portal.
  • A browser-based flasher.
Lingua principale
PHP
Stelle
26
Fork
2
Merge medio
2g 19h
PR unite (30g)
10

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

  • Nessun Dockerfile né file Docker Compose
  • Nessun modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Open-Locker/Open-Locker

Tutte le issue di Open-Locker/Open-Locker

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.