@general-galactic/capacitor-esp-idf-provisioning

A capacitor plugin that wraps the Espressif IDF Provisioning libraries for iOS and Android.

• IDF Provisioning Overview
• IDF Provisioning Library for iOS
• IDF Provisioning Library for Android

Using this library will allow you to use an Ionic app to provision Espressif devices running the WiFi provisioning stack.

NOTE:

I've regained access to our npm organization so this package is now published on npm instead of github packages. To consume future versions you should remove the github packages config for this repo.

Android Support

This project will only work in Android apps using SDK Level 25 or higher. Android SDK Distribution Stats

Install

npm install @general-galactic/capacitor-esp-idf-provisioning
npx cap sync

Initial Integration into an Android App

Apps will need to add the maven repo to their build.gradle file so that the ESPProvision library from Espressif can be included:

allprojects {
    repositories {
        google()
        jcenter()
        maven { url 'https://jitpack.io' } // <-- Add This line
    }
}

Troubleshooting

Android build won't run after adding the npm dependency You need to add the https://jitpack.io repository to your build.gradle. See 'Initial Integration into an Android App' above.

ESPProvisioning is not implemented on [iOS|Android] You need to run npx cap sync

API

• checkPermissions()
• requestPermissions()
• checkStatus()
• searchESPDevices(...)
• connect(...)
• scanWifiList(...)
• provision(...)
• sendCustomDataString(...)
• disconnect(...)
• openLocationSettings()
• openBluetoothSettings()
• openAppSettings()
• enableLogging()
• disableLogging()
• Interfaces
• Type Aliases
• Enums

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the status of system permissions:

• ble - Bluetooth access
• location - Location access, android only

Returns: Promise<PermissionStatus>

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Have the system prompt the user for access to the proper permissions - Android only.

Returns: Promise<PermissionStatus>

checkStatus()

checkStatus() => Promise<EspProvisioningStatus>

See if the bluetooth adapter is up and running

Returns: Promise<EspProvisioningStatus>

searchESPDevices(...)

searchESPDevices(options: { devicePrefix: string; transport: ESPTransport; security: ESPSecurity; }) => Promise<{ devices?: ESPDevice[]; }>

Perform a BLE scan to find devices that are connection with the given devicePrefix. The transport and security parameters map directly to ESPProvision's own values.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | options | { devicePrefix: string; transport: ESPTransport; security: ESPSecurity; } |

Returns: Promise<{ devices?: ESPDevice[]; }>

connect(...)

connect(options: { deviceName: string; proofOfPossession: string; }) => Promise<{ connected: boolean; }>

Connect to the device with the given name using the given proofOfPossession.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | { deviceName: string; proofOfPossession: string; } |

Returns: Promise<{ connected: boolean; }>

scanWifiList(...)

scanWifiList(options: { deviceName: string; }) => Promise<{ networks?: ESPNetwork[]; }>

Request a list of available WiFi networks from the device with the given name.

| Param | Type | | ------------- | ------------------------------------ | | options | { deviceName: string; } |

Returns: Promise<{ networks?: ESPNetwork[]; }>

provision(...)

provision(options: { deviceName: string; ssid: string; passPhrase?: string; }) => Promise<{ success: boolean; }>

Provision the device onto WiFi using the given ssid and passPhrase.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | { deviceName: string; ssid: string; passPhrase?: string; } |

Returns: Promise<{ success: boolean; }>

sendCustomDataString(...)

sendCustomDataString(options: { deviceName: string; path: string; dataString: string; }) => Promise<{ success: boolean; returnString?: string; }>

Send a custom string to the device with the given name. This is usefull if you need to share other data with your device during provisioning. NOTE: Android will truncate returned strings to around 512 bytes. If you need to send more than 512 bytes back on a read you'll need to implement a mechanism to do so.

| Param | Type | | ------------- | ---------------------------------------------------------------------- | | options | { deviceName: string; path: string; dataString: string; } |

Returns: Promise<{ success: boolean; returnString?: string; }>

disconnect(...)

disconnect(options: { deviceName: string; }) => Promise<void>

Disconnect from the device.

| Param | Type | | ------------- | ------------------------------------ | | options | { deviceName: string; } |

openLocationSettings()

openLocationSettings() => Promise<{ value: boolean; }>

Open the user's location settings for your app. iOS only.

Returns: Promise<{ value: boolean; }>

openBluetoothSettings()

openBluetoothSettings() => Promise<{ value: boolean; }>

Open the user's bluetooth settings for your app. iOS only.

Returns: Promise<{ value: boolean; }>

openAppSettings()

openAppSettings() => Promise<{ value: boolean; }>

Open the OS settings for your app.

Returns: Promise<{ value: boolean; }>

enableLogging()

enableLogging() => Promise<void>

Enable extra logging - useful for troubleshooting. Best on iOS because the iOS ESPProvision library offers much more verbose logging when enabled.

disableLogging()

disableLogging() => Promise<void>

Disable detailed logging.

Interfaces

PermissionStatus

| Prop | Type | | -------------- | ----------------------------------------------------------- | | ble | PermissionState | | location | PermissionState |

EspProvisioningStatus

| Prop | Type | | -------------- | -------------------------------------------------------------------------- | | ble | { supported: boolean; allowed: boolean; poweredOn: boolean; } | | location | { allowed: boolean; } |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

ESPDevice

{ name: string // Your devices must have a unique name advertisementData?: ESPDeviceAdvertisingData }

ESPDeviceAdvertisingData

{ localName?: string isConnectable?: number manufacturerData?: any serviceUUIDs?: string[] }

ESPNetwork

{ ssid: string rssi: number auth: 'open' | 'wep' | 'wpapsk' | 'wpawpa2psk' | 'wpa2enterprise' | 'unknown' }

Enums

ESPTransport

| Members | Value | | ------------ | --------------------- | | ble | 'ble' | | softap | 'softap' |

ESPSecurity

| Members | Value | | -------------- | ----------------------- | | unsecure | 'unsecure' | | secure | 'secure' |