-
Notifications
You must be signed in to change notification settings - Fork 132
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'feature/prov-lib-integration' into 'master'
Version/2.0 See merge request idf/esp-idf-provisioning-android!33
- Loading branch information
Showing
134 changed files
with
5,999 additions
and
2,365 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,32 +1,147 @@ | ||
| # ESP-IDF Provisioning - Android | ||
|
|
||
| ESP-IDF consists of a provisioning mechanism, which is used to provide network credentials and/or custom data to an ESP32 device. | ||
| # Provisioning Library | ||
|
|
||
| Provisioning library provides mechanism to send network credentials and/or custom data to an ESP32 or ESP32-S2 devices. | ||
| This repository contains the source code for the companion Android app for this provisioning mechanism. | ||
|
|
||
| - [Features](#features) | ||
| - [Requirements](#requirements) | ||
| - [How to include](#how-to-include) | ||
| - [Usage](#using-ESPProvision) | ||
| - [****Introduction****](#introduction) | ||
| - [****Getting ESPDevice****](#getting-ESPDevice) | ||
| - [****Provisioning****](#provisioning) | ||
| - [License](#license) | ||
|
|
||
| ## Features | ||
|
|
||
| - [x] Search for available BLE devices. | ||
| - [x] Scan device QR code to provide reference to ESP device. | ||
| - [x] Create reference of ESPDevice manually. | ||
| - [x] Data Encryption | ||
| - [x] Data transmission through BLE and SoftAP. | ||
| - [x] Scan for available Wi-Fi networks. | ||
| - [x] Provision device. | ||
| - [x] Scan for available Wi-Fi networks. | ||
| - [x] Support for exchanging custom data. | ||
|
|
||
| ## Requirements | ||
|
|
||
| - Supports Android 7.0 (API level 24) and above. | ||
|
|
||
| This is licensed under Apache 2.0. The complete license for the same can be found in the LICENSE file. | ||
| ## How to include | ||
|
|
||
| Add it in your root build.gradle at the end of repositories: | ||
|
|
||
|
|
||
| ## Configuring Build | ||
| allprojects { | ||
| repositories { | ||
| ... | ||
| maven { url 'https://jitpack.io' } | ||
| } | ||
| } | ||
|
|
||
| There are multiple build options. It is a combination of 3 options - transport, security and release type. | ||
| And add a dependency code to your app module's `build.gradle` file. | ||
|
|
||
| - Transports | ||
| - WiFi | ||
| - BLE | ||
| - Security | ||
| - 0 (no security) | ||
| - 1 (security as per IDF docs for provisioning) | ||
| - Release type | ||
| - Debug | ||
| - Release | ||
| implementation 'com.github.espressif:esp-idf-provisioning-android:lib-2.0' | ||
|
|
||
| ## Using Provisioning Library | ||
|
|
||
| ## Introduction | ||
|
|
||
| Provisioning library provides a simpler mechanism to communicate with an ESP-32 and ESP32-S2 devices. It gives an efficient search and scan model to listen and return devices which are in provisioning mode. It embeds security protocol and allow for safe transmission of data by doing end to end encryption. It supports BLE and SoftAP as mode of transmission which are configurable at runtime. Its primarily use is to provide home network credentials to a device and ensure device connectivity status is returned to the application. | ||
|
|
||
|
|
||
| ## Getting ESPDevice | ||
|
|
||
| `ESPDevice` object is virtual representation of ESP-32/ESP32-S2 devices. It provides interface to interact with devices directly in a simpler manner. `ESPProvisionManager` is a singleton class that encompasses APIs for searching ESP devices using BLE or SoftAP transport. | ||
| `ESPDevice` instances can be obtained from two ways as described following : | ||
|
|
||
| So you can pick a build type as `bleSec1Debug`. Note that except for Release type, if you change any of the above options, you will have to change the corresponding firmware on ESP32. | ||
| ### Scan | ||
|
|
||
| Device information can be extracted from scanning valid QR code. User of this API decides the camera preview layer frame by providing `SurfaceView` as parameter. It return single `ESPDevice` instance on success. Supports both SoftAP and BLE. | ||
|
|
||
| ```java | ||
|
|
||
| ESPProvisionManager.getInstance(context).scanQRCode(Activity activityContext, SurfaceView surfaceView, QRCodeScanListener qrCodeScanListener) | ||
|
|
||
| ``` | ||
| ### Create | ||
|
|
||
| `ESPDevice` can be also created by passing necessary parameters as argument of below function. | ||
|
|
||
| ```java | ||
|
|
||
| ESPProvisionManager.getInstance(context).createESPDevice(TransportType transportType, SecurityType securityType); | ||
|
|
||
| ``` | ||
|
|
||
| > This will return ESPDevice with given transport and security type. | ||
| # Resources | ||
| 1. For BLE Transport | ||
| > For BLE transport type, library will need BluetoothDevice to connect with actual device. To get BluetoothDevice app can call search API or also app can use own BLE scanning. Library supports searching of BLE devices which are currently in provisioning mode. It returns list of devices that are discoverable and matches the parameter criteria. This API will return BluetoothDevice objects for the devices found in BLE scan with given prefix. | ||
| > After user select BLE device, app can call connect API. | ||
| ```java | ||
|
|
||
| ESPProvisionManager.getInstance(context).searchBleEspDevices(String prefix, BleScanListener bleScannerListener) | ||
|
|
||
| ``` | ||
|
|
||
| > After user select BLE device, app can call connect API. | ||
| * Documentation for the latest version of IDF: https://docs.espressif.com/projects/esp-idf/. | ||
| ```java | ||
|
|
||
| espDevice.connectBLEDevice(BluetoothDevice bluetoothDevice, String primaryServiceUuid) | ||
|
|
||
| ``` | ||
|
|
||
| * The [esp32.com forum](https://esp32.com/) is a place to ask questions and find community resources. | ||
|
|
||
| 2. For SoftAP Transport | ||
|
|
||
| * [Check the Issues section on github](https://github.com/espressif/esp-idf-provisioning-android/issues) if you find a bug or have a feature request. Please check existing Issues before opening a new one. | ||
| > For SoftAP transport type, app can call connect API to connect with the device. | ||
| * If you're interested in contributing to ESP-IDF, please check the [Contributions Guide](https://docs.espressif.com/projects/esp-idf/en/latest/contribute/index.html). | ||
| ```java | ||
|
|
||
| espDevice.connectWiFiDevice() | ||
|
|
||
| ``` | ||
|
|
||
| > For both transport app can listen device connected / disconnected events by resigtering for events. | ||
| ## Provisioning | ||
|
|
||
| The main feature of Provisioning library is to provision ESP devices. Once we get instance of `ESPDevice` from above APIs we need to establish session with the device before we can transmit/receive data from it. After receiving device connected event, app can get device capabilities and also set Proof of possesion if device has pop capability. | ||
|
|
||
| After that application can proceed to scan list of available networks visible to device. This list can be used to give option to the user to choose network of their own choice. | ||
|
|
||
| ```java | ||
|
|
||
| espDevice.scanNetworks(final WiFiScanListener wifiScanListener); | ||
|
|
||
| ``` | ||
|
|
||
| User can choose to apply Wi-Fi settings from the above list or choose other Wi-Fi network to provision the device. | ||
|
|
||
| ```java | ||
|
|
||
| espDevice.provision(final String ssid, final String passphrase, final ProvisionListener provisionListener); | ||
|
|
||
| ``` | ||
|
|
||
| ## License | ||
|
|
||
|
|
||
| Copyright 2020 Espressif Systems (Shanghai) PTE LTD | ||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| See the License for the specific language governing permissions and | ||
| limitations under the License. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,90 +1,57 @@ | ||
| apply plugin: 'com.android.application' | ||
| apply plugin: 'com.google.protobuf' | ||
|
|
||
| android { | ||
|
|
||
| compileSdkVersion 28 | ||
|
|
||
| defaultConfig { | ||
| minSdkVersion 21 | ||
| applicationId "com.espressif.wifi_provisioning" | ||
| minSdkVersion 24 | ||
| targetSdkVersion 28 | ||
| versionCode 5 | ||
| versionName "1.2" | ||
| versionCode 6 | ||
| versionName "2.0" | ||
| testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" | ||
| } | ||
|
|
||
| flavorDimensions "transport", "security" | ||
|
|
||
| productFlavors { | ||
|
|
||
| wifi { | ||
| dimension "transport" | ||
| applicationId "com.espressif.provsoftap" | ||
| } | ||
| ble { | ||
| dimension "transport" | ||
| applicationId "com.espressif.provble" | ||
| } | ||
| sec0 { | ||
| dimension "security" | ||
| } | ||
| sec1 { | ||
| dimension "security" | ||
| } | ||
| } | ||
|
|
||
| buildTypes { | ||
| release { | ||
| minifyEnabled false | ||
| debuggable false | ||
| proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro' | ||
| resValue "string", "proof_of_possesion", "abcd1234" | ||
| resValue "string", "wifi_base_url", "192.168.4.1:80" | ||
| resValue "string", "wifi_network_name_prefix", "PROV_" | ||
| resValue "string", "wifi_device_name_prefix", "PROV_" | ||
| resValue "string", "ble_device_name_prefix", "PROV_" | ||
| buildConfigField "boolean", "IS_QR_CODE_SUPPORTED", "true" | ||
| buildConfigField "boolean", "IS_ALLOWED_FILTERING_BY_PREFIX", "true" | ||
| } | ||
|
|
||
| debug { | ||
| debuggable true | ||
| resValue "string", "proof_of_possesion", "abcd1234" | ||
| resValue "string", "wifi_base_url", "192.168.4.1:80" | ||
| resValue "string", "wifi_network_name_prefix", "PROV_" | ||
| resValue "string", "wifi_device_name_prefix", "PROV_" | ||
| resValue "string", "ble_device_name_prefix", "PROV_" | ||
| buildConfigField "boolean", "IS_QR_CODE_SUPPORTED", "true" | ||
| buildConfigField "boolean", "IS_ALLOWED_FILTERING_BY_PREFIX", "true" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| protobuf { | ||
| protoc { | ||
| artifact = 'com.google.protobuf:protoc:3.5.1' | ||
| } | ||
| plugins { | ||
| javalite { | ||
| artifact = 'com.google.protobuf:protoc-gen-javalite:3.0.0' | ||
| } | ||
| } | ||
| generateProtoTasks { | ||
| all().each { task -> | ||
| task.builtins { | ||
| remove java | ||
| } | ||
| task.plugins { | ||
| javalite {} | ||
| } | ||
| } | ||
| } | ||
| } | ||
|
|
||
| dependencies { | ||
| implementation fileTree(include: ['*.jar'], dir: 'libs') | ||
| implementation 'com.android.support:appcompat-v7:28.0.0' | ||
| implementation 'com.android.support.constraint:constraint-layout:1.1.0' | ||
| implementation 'com.android.support:design:28.0.0' | ||
| testImplementation 'junit:junit:4.12' | ||
| androidTestImplementation 'com.android.support.test:runner:1.0.2' | ||
| androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2' | ||
| implementation 'androidx.appcompat:appcompat:1.1.0' | ||
| implementation 'androidx.constraintlayout:constraintlayout:1.1.3' | ||
| implementation 'com.google.android.material:material:1.0.0' | ||
| implementation 'com.wang.avi:library:2.1.3' | ||
| implementation 'org.greenrobot:eventbus:3.1.1' | ||
| implementation 'androidx.preference:preference:1.1.1' | ||
|
|
||
| implementation 'com.google.protobuf:protobuf-lite:3.0.1' | ||
| implementation 'com.google.crypto.tink:tink-android:1.1.0' | ||
| implementation project(path: ':provisioning') | ||
|
|
||
| testImplementation 'junit:junit:4.12' | ||
| androidTestImplementation 'androidx.test.ext:junit:1.1.1' | ||
| androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0' | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.