esp-idf-provisioning-web 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# ESP-IDF Provisioning Web SDK
+
+A TypeScript SDK for provisioning ESP32 devices from web browsers using the ESP-IDF provisioning protocol. Supports both BLE (Web Bluetooth) and SoftAP (HTTP) transport modes.
+
+## Features
+
+- [ ] **Multiple Security Modes**
+  - [ ] Security1 (not implemented)
+  - [ ] Security2 (not implemented)
+- [x] **BLE Transport**: Uses Web Bluetooth API for wireless provisioning
+- [x] **SoftAP Transport**: HTTP-based provisioning for devices in AP mode
+- [x] **Provisioning Protocol**: Supports ESP-IDF provisioning protocol for WiFi credentials
+  - [x] Scan APs
+  - [x] Provision device status monitoring
+  - [ ] Reset and re-provisioning
+  - [ ] Custom endpoints
+
+## Browser Compatibility
+
+- **BLE Mode**: Requires browsers with Web Bluetooth API support (Chrome, Edge, Opera)
+- **SoftAP Mode**: Works in all modern browsers (user must manually connect to WiFi)
+
+## Installation
+
+```bash
+npm install esp-idf-provisioning-web
+```
+
+## Usage
+
+### BLE Provisioning
+
+```typescript
+import { ESPProvisionManager } from 'esp-idf-provisioning-web';
+
+// Search for devices with BLE
+const device = await ESPProvisionManager.searchBLEDevice();
+
+// Connect with proof of possession
+await device.connect();
+
+// Scan for WiFi networks
+const wifiList = await device.scanWifiList();
+
+// Provision the device
+await device.provision('MyWiFiSSID', 'MyWiFiPassword');
+
+// Wait for STA connected
+let result;
+do {
+  result = await device.fetchWifiStatus();
+  await new Promise((resolve) => setTimeout(resolve, 2000));
+} while (result.staState !== ESPWifiStaState.connecting);
+
+if (result.staState === ESPWifiStaState.connected) {
+  console.log('Provisioning successful!');
+} else {
+  console.log('Provisioning failed:', result);
+}
+
+// Disconnect
+device.disconnect();
+```
+
+### SoftAP Provisioning
+
+**Important**: The browser cannot automatically connect to WiFi networks. Users must manually connect to the ESP device's access point before running this code.
+
+```typescript
+import { ESPProvisionManager } from 'esp-idf-provisioning-web';
+
+// Create device instance for SoftAP
+// User should already be connected to the device's WiFi network
+const device = ESPProvisionManager.createSoftAPDevice(new URL('http://192.168.4.1'));
+
+// Connect and provision
+await device.connect();
+await device.provision('MyWiFiSSID', 'MyWiFiPassword');
+```
+
+### Check Bluetooth Support
+
+```typescript
+// Check if Web Bluetooth is available
+if (ESPProvisionManager.isBluetoothSupported()) {
+  const isAvailable = await ESPProvisionManager.getBluetoothAvailability();
+  console.log('Bluetooth available:', isAvailable);
+}
+```
+
+## Browser Limitations
+
+### BLE Mode
+- Requires user interaction (button click) to initiate device scanning
+- User must manually select device from browser's device picker
+- HTTPS or localhost required for Web Bluetooth API
+- Service UUID must be filled in optionalServiceUUIDs for some browsers
+
+### SoftAP Mode
+- Browser cannot connect to WiFi networks programmatically
+- User must manually connect to ESP device's access point
+- CORS may need to be configured on the ESP device
+- May not work on all networks due to browser security restrictions
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+## License
+
+MIT
+
+## References
+
+- [ESP-IDF Provisioning Protocol](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/provisioning/provisioning.html)
+- [Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API)
+- [React Native ESP-IDF Provisioning](https://github.com/orbital-systems/react-native-esp-idf-provisioning)

package/dist/ESPDevice.d.ts

@@ -0,0 +1,66 @@
+import { ESPDeviceInterface, ESPWifiAp, ESPWifiStatus, ESPSecurityConfig } from './types';
+/**
+ * ESP Device class for provisioning operations
+ */
+export declare class ESPDevice implements ESPDeviceInterface {
+    private device;
+    private transportImpl?;
+    private securityImpl?;
+    /**
+     * Create a new ESPDevice instance
+     * @param device - BluetoothDevice for BLE or URL for SoftAP
+     */
+    constructor(device: BluetoothDevice | URL);
+    /**
+     * Connect to the device
+     * @param proofOfPossession - Proof of possession for secure modes
+     * @param softAPPassword - Password for SoftAP mode (not used in browser)
+     * @param username - Username for authentication
+     */
+    connect(security?: ESPSecurityConfig): Promise<void>;
+    /**
+     * Scan for available WiFi networks
+     * @returns List of WiFi networks
+     */
+    scanWifiList(): Promise<ESPWifiAp[]>;
+    /**
+     * Provision device with WiFi credentials
+     * @note Call fetchWifiStatus() after provisioning to check provisioning status
+     * @param ssid - WiFi network SSID
+     * @param passphrase - WiFi network password
+     */
+    provision(ssid: string, passphrase: string): Promise<void>;
+    /**
+     * Fetch WiFi status from device
+     * @returns WiFi status
+     */
+    fetchWifiStatus(): Promise<ESPWifiStatus>;
+    /**
+     * Disconnect from device
+     */
+    disconnect(): void;
+    /**
+     * Get device
+     */
+    getDevice(): BluetoothDevice | URL;
+    /**
+     * Initialize security layer based on security type
+     */
+    private initializeSecurity;
+    /**
+     * Establish secure session with device
+     */
+    private establishSession;
+    /**
+     * Initialize transport layer based on transport type
+     */
+    private initializeTransport;
+    /**
+     * Send custom data to device
+     * @param path - Data endpoint path
+     * @param data - Data to send
+     * @returns Response data from device
+     */
+    private sendData;
+}
+//# sourceMappingURL=ESPDevice.d.ts.map

package/dist/ESPDevice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ESPDevice.d.ts","sourceRoot":"","sources":["../src/ESPDevice.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAwBjB;;GAEG;AACH,qBAAa,SAAU,YAAW,kBAAkB;IAClD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,aAAa,CAAC,CAAY;IAClC,OAAO,CAAC,YAAY,CAAC,CAAW;IAEhC;;;OAGG;gBACS,MAAM,EAAE,eAAe,GAAG,GAAG;IAIzC;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1D;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAiC1C;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,aAAa,CAAC;IAc/C;;OAEG;IACH,UAAU,IAAI,IAAI;IAQlB;;OAEG;IACH,SAAS,IAAI,eAAe,GAAG,GAAG;IAIlC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;YACW,gBAAgB;IAkB9B;;OAEG;YACW,mBAAmB;IAajC;;;;;OAKG;YACW,QAAQ;CAevB"}

package/dist/ESPProvisionManager.d.ts

@@ -0,0 +1,34 @@
+import { ESPDevice } from './ESPDevice';
+/**
+ * ESP Provision Manager for device discovery
+ */
+export declare class ESPProvisionManager {
+    /**
+     * Search for ESP devices using BLE
+     * @param devicePrefix - Prefix to filter device names
+     * @param transport - Transport type (only BLE supported for search)
+     * @param security - Security type to use
+     * @returns Promise resolving to array of discovered devices
+     */
+    static searchBLEDevice(bleDeviceOptions?: RequestDeviceOptions): Promise<ESPDevice | null>;
+    /**
+     * Create an ESPDevice instance for SoftAP mode
+     * Note: Browser cannot automatically connect to WiFi.
+     * User must manually connect to the device's access point before using this.
+     *
+     * @param baseURL - Base URL for the SoftAP
+     * @returns ESPDevice instance configured for SoftAP
+     */
+    static createSoftAPDevice(baseURL: URL): ESPDevice;
+    /**
+     * Check if Web Bluetooth is supported
+     * @returns true if Web Bluetooth is available
+     */
+    static isBluetoothSupported(): boolean;
+    /**
+     * Get Bluetooth availability status
+     * @returns Promise resolving to availability status
+     */
+    static getBluetoothAvailability(): Promise<boolean>;
+}
+//# sourceMappingURL=ESPProvisionManager.d.ts.map

package/dist/ESPProvisionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ESPProvisionManager.d.ts","sourceRoot":"","sources":["../src/ESPProvisionManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC;;GAEG;AACH,qBAAa,mBAAmB;IAC9B;;;;;;OAMG;WACU,eAAe,CAC1B,gBAAgB,GAAE,oBAAiD,GAClE,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAyB5B;;;;;;;OAOG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,GAAG,GAAG,SAAS;IAIlD;;;OAGG;IACH,MAAM,CAAC,oBAAoB,IAAI,OAAO;IAItC;;;OAGG;WACU,wBAAwB,IAAI,OAAO,CAAC,OAAO,CAAC;CAY1D"}

package/dist/constants.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Constants for ESP provisioning protocol
+ */
+export declare const PROTO_ENDPOINTS: {
+    PROV_SESSION: string;
+    PROV_SCAN: string;
+    PROV_CTRL: string;
+    PROV_CONFIG: string;
+    PROTO_VER: string;
+};
+export declare const DEFAULT_DEVICE_PREFIX = "PROV_";
+export declare const FALLBACK_SERVICE_UUID = "1775244d-6b43-439b-877c-060f2d9bed07";
+export declare const FALLBACK_NU_LOOKUP: {
+    'prov-session': string;
+    'prov-config': string;
+    'proto-ver': string;
+};
+export declare const DEFAULT_BLE_DEVICE_OPTIONS: RequestDeviceOptions;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,eAAO,MAAM,eAAe;;;;;;CAM3B,CAAC;AAGF,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAG7C,eAAO,MAAM,qBAAqB,yCAAyC,CAAC;AAE5E,eAAO,MAAM,kBAAkB;;;;CAI9B,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,oBAGxC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ESP-IDF Provisioning Web SDK
+ *
+ * A TypeScript library for provisioning ESP32 devices via Web Bluetooth API and HTTP.
+ * Supports both BLE and SoftAP transport modes with Security0, Security1, and Security2.
+ *
+ * Note: Browser limitations apply:
+ * - BLE requires user interaction to select devices
+ * - SoftAP requires manual WiFi connection by the user
+ * - Some security features may require additional crypto libraries for production use
+ */
+export { ESPDevice } from './ESPDevice';
+export { ESPProvisionManager } from './ESPProvisionManager';
+export { ESPWifiAuthMode, ESPWifiStaState, type ESPDeviceInterface, type ESPSecurity1Config, type ESPSecurity2Config, type ESPWifiAp, type ESPScanStatusResponse as ESPStatusResponse, type ESPConnectFailReason, type ESPWifiStatus, } from './types';
+export { FALLBACK_SERVICE_UUID, DEFAULT_DEVICE_PREFIX, } from './constants';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,qBAAqB,IAAI,iBAAiB,EAC/C,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}