@general-galactic/capacitor-esp-idf-provisioning
TypeScript icon, indicating that this package has built-in type declarations

0.0.97 • Public • Published

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

A capacitor plugin that wraps the Espressif IDF Provisioning libraries for iOS and 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()

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. Android only.

Returns: Promise<{ value: boolean; }>


openBluetoothSettings()

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

Open the user's bluetooth settings for your app. Android 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'

Readme

Keywords

Package Sidebar

Install

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

Weekly Downloads

104

Version

0.0.97

License

MIT

Unpacked Size

138 kB

Total Files

39

Last publish

Collaborators

  • deadmeta4