Skip to content

Commit 403c787

Browse files
shahpiyushvshahpiyushv
committed
Merge branch 'feature/prov-lib-integration' into 'master'
Version/2.0 See merge request idf/esp-idf-provisioning-android!33
2 parents b6775b7 + b1d2cd0 commit 403c787

File tree

134 files changed

+5999
-2365
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

134 files changed

+5999
-2365
lines changed

‎README.md

+135-20
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,147 @@
1-
# ESP-IDF Provisioning - Android
21

3-
ESP-IDF consists of a provisioning mechanism, which is used to provide network credentials and/or custom data to an ESP32 device.
2+
# Provisioning Library
3+
4+
Provisioning library provides mechanism to send network credentials and/or custom data to an ESP32 or ESP32-S2 devices.
45
This repository contains the source code for the companion Android app for this provisioning mechanism.
6+
7+
- [Features](#features)
8+
- [Requirements](#requirements)
9+
- [How to include](#how-to-include)
10+
- [Usage](#using-ESPProvision)
11+
- [****Introduction****](#introduction)
12+
- [****Getting ESPDevice****](#getting-ESPDevice)
13+
- [****Provisioning****](#provisioning)
14+
- [License](#license)
15+
16+
## Features
17+
18+
- [x] Search for available BLE devices.
19+
- [x] Scan device QR code to provide reference to ESP device.
20+
- [x] Create reference of ESPDevice manually.
21+
- [x] Data Encryption
22+
- [x] Data transmission through BLE and SoftAP.
23+
- [x] Scan for available Wi-Fi networks.
24+
- [x] Provision device.
25+
- [x] Scan for available Wi-Fi networks.
26+
- [x] Support for exchanging custom data.
27+
28+
## Requirements
29+
30+
- Supports Android 7.0 (API level 24) and above.
531

6-
This is licensed under Apache 2.0. The complete license for the same can be found in the LICENSE file.
32+
## How to include
33+
34+
Add it in your root build.gradle at the end of repositories:
35+
736

8-
## Configuring Build
37+
allprojects {
38+
repositories {
39+
...
40+
maven { url 'https://jitpack.io' }
41+
}
42+
}
943

10-
There are multiple build options. It is a combination of 3 options - transport, security and release type.
44+
And add a dependency code to your app module's `build.gradle` file.
1145

12-
- Transports
13-
- WiFi
14-
- BLE
15-
- Security
16-
- 0 (no security)
17-
- 1 (security as per IDF docs for provisioning)
18-
- Release type
19-
- Debug
20-
- Release
46+
implementation 'com.github.espressif:esp-idf-provisioning-android:lib-2.0'
47+
48+
## Using Provisioning Library
49+
50+
## Introduction
51+
52+
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.
53+
54+
55+
## Getting ESPDevice
56+
57+
`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.
58+
`ESPDevice` instances can be obtained from two ways as described following :
2159

22-
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.
60+
### Scan
61+
62+
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.
63+
64+
```java
65+
66+
ESPProvisionManager.getInstance(context).scanQRCode(Activity activityContext, SurfaceView surfaceView, QRCodeScanListener qrCodeScanListener)
67+
68+
```
69+
### Create
70+
71+
`ESPDevice` can be also created by passing necessary parameters as argument of below function.
72+
73+
```java
74+
75+
ESPProvisionManager.getInstance(context).createESPDevice(TransportType transportType, SecurityType securityType);
76+
77+
```
78+
79+
> This will return ESPDevice with given transport and security type.
2380
24-
# Resources
81+
1. For BLE Transport
82+
> 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.
83+
> After user select BLE device, app can call connect API.
84+
85+
```java
86+
87+
ESPProvisionManager.getInstance(context).searchBleEspDevices(String prefix, BleScanListener bleScannerListener)
88+
89+
```
90+
91+
> After user select BLE device, app can call connect API.
2592
26-
* Documentation for the latest version of IDF: https://docs.espressif.com/projects/esp-idf/.
93+
```java
94+
95+
espDevice.connectBLEDevice(BluetoothDevice bluetoothDevice, String primaryServiceUuid)
96+
97+
```
2798

28-
* The [esp32.com forum](https://esp32.com/) is a place to ask questions and find community resources.
99+
100+
2. For SoftAP Transport
29101

30-
* [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.
102+
> For SoftAP transport type, app can call connect API to connect with the device.
31103
32-
* 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).
104+
```java
105+
106+
espDevice.connectWiFiDevice()
107+
108+
```
109+
110+
> For both transport app can listen device connected / disconnected events by resigtering for events.
111+
112+
## Provisioning
113+
114+
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.
115+
116+
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.
117+
118+
```java
119+
120+
espDevice.scanNetworks(final WiFiScanListener wifiScanListener);
121+
122+
```
123+
124+
User can choose to apply Wi-Fi settings from the above list or choose other Wi-Fi network to provision the device.
125+
126+
```java
127+
128+
espDevice.provision(final String ssid, final String passphrase, final ProvisionListener provisionListener);
129+
130+
```
131+
132+
## License
133+
134+
135+
Copyright 2020 Espressif Systems (Shanghai) PTE LTD
136+
137+
Licensed under the Apache License, Version 2.0 (the "License");
138+
you may not use this file except in compliance with the License.
139+
You may obtain a copy of the License at
140+
141+
http://www.apache.org/licenses/LICENSE-2.0
142+
143+
Unless required by applicable law or agreed to in writing, software
144+
distributed under the License is distributed on an "AS IS" BASIS,
145+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
146+
See the License for the specific language governing permissions and
147+
limitations under the License.

‎app/build.gradle

+20-53
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,57 @@
11
apply plugin: 'com.android.application'
2-
apply plugin: 'com.google.protobuf'
32

43
android {
54

65
compileSdkVersion 28
76

87
defaultConfig {
9-
minSdkVersion 21
8+
applicationId "com.espressif.wifi_provisioning"
9+
minSdkVersion 24
1010
targetSdkVersion 28
11-
versionCode 5
12-
versionName "1.2"
11+
versionCode 6
12+
versionName "2.0"
1313
testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
1414
}
1515

16-
flavorDimensions "transport", "security"
17-
18-
productFlavors {
19-
20-
wifi {
21-
dimension "transport"
22-
applicationId "com.espressif.provsoftap"
23-
}
24-
ble {
25-
dimension "transport"
26-
applicationId "com.espressif.provble"
27-
}
28-
sec0 {
29-
dimension "security"
30-
}
31-
sec1 {
32-
dimension "security"
33-
}
34-
}
35-
3616
buildTypes {
3717
release {
3818
minifyEnabled false
3919
debuggable false
4020
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
4121
resValue "string", "proof_of_possesion", "abcd1234"
4222
resValue "string", "wifi_base_url", "192.168.4.1:80"
43-
resValue "string", "wifi_network_name_prefix", "PROV_"
23+
resValue "string", "wifi_device_name_prefix", "PROV_"
4424
resValue "string", "ble_device_name_prefix", "PROV_"
25+
buildConfigField "boolean", "IS_QR_CODE_SUPPORTED", "true"
4526
buildConfigField "boolean", "IS_ALLOWED_FILTERING_BY_PREFIX", "true"
4627
}
4728

4829
debug {
4930
debuggable true
5031
resValue "string", "proof_of_possesion", "abcd1234"
5132
resValue "string", "wifi_base_url", "192.168.4.1:80"
52-
resValue "string", "wifi_network_name_prefix", "PROV_"
33+
resValue "string", "wifi_device_name_prefix", "PROV_"
5334
resValue "string", "ble_device_name_prefix", "PROV_"
35+
buildConfigField "boolean", "IS_QR_CODE_SUPPORTED", "true"
5436
buildConfigField "boolean", "IS_ALLOWED_FILTERING_BY_PREFIX", "true"
5537
}
5638
}
5739
}
5840

59-
protobuf {
60-
protoc {
61-
artifact = 'com.google.protobuf:protoc:3.5.1'
62-
}
63-
plugins {
64-
javalite {
65-
artifact = 'com.google.protobuf:protoc-gen-javalite:3.0.0'
66-
}
67-
}
68-
generateProtoTasks {
69-
all().each { task ->
70-
task.builtins {
71-
remove java
72-
}
73-
task.plugins {
74-
javalite {}
75-
}
76-
}
77-
}
78-
}
79-
8041
dependencies {
8142
implementation fileTree(include: ['*.jar'], dir: 'libs')
82-
implementation 'com.android.support:appcompat-v7:28.0.0'
83-
implementation 'com.android.support.constraint:constraint-layout:1.1.0'
84-
implementation 'com.android.support:design:28.0.0'
85-
testImplementation 'junit:junit:4.12'
86-
androidTestImplementation 'com.android.support.test:runner:1.0.2'
87-
androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
43+
implementation 'androidx.appcompat:appcompat:1.1.0'
44+
implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
45+
implementation 'com.google.android.material:material:1.0.0'
46+
implementation 'com.wang.avi:library:2.1.3'
47+
implementation 'org.greenrobot:eventbus:3.1.1'
48+
implementation 'androidx.preference:preference:1.1.1'
49+
8850
implementation 'com.google.protobuf:protobuf-lite:3.0.1'
8951
implementation 'com.google.crypto.tink:tink-android:1.1.0'
52+
implementation project(path: ':provisioning')
53+
54+
testImplementation 'junit:junit:4.12'
55+
androidTestImplementation 'androidx.test.ext:junit:1.1.1'
56+
androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'
9057
}

‎app/src/main/AndroidManifest.xml

+21-11
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,26 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
3-
package="com.espressif.provision">
3+
package="com.espressif.wifi_provisioning">
44

5+
<uses-permission android:name="android.permission.CAMERA" />
56
<uses-permission android:name="android.permission.INTERNET" />
67
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
78
<uses-permission android:name="android.permission.BLUETOOTH" />
89
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
910
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
1011
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
12+
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
1113
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
1214
<uses-permission android:name="android.permission.VIBRATE" />
1315

1416
<application
15-
android:name="com.espressif.EspApplication"
1617
android:allowBackup="true"
1718
android:icon="@mipmap/ic_launcher"
1819
android:label="@string/app_name"
1920
android:roundIcon="@mipmap/ic_launcher_round"
2021
android:supportsRtl="true"
21-
android:usesCleartextTraffic="true"
22-
android:theme="@style/AppTheme">
22+
android:theme="@style/AppTheme"
23+
android:usesCleartextTraffic="true">
2324
<activity
2425
android:name="com.espressif.ui.activities.EspMainActivity"
2526
android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
@@ -33,25 +34,34 @@
3334
</intent-filter>
3435
</activity>
3536
<activity
36-
android:name="com.espressif.ui.activities.ProvisionLanding"
37+
android:name="com.espressif.ui.activities.AddDeviceActivity"
3738
android:label="@string/title_activity_provision_landing"
3839
android:screenOrientation="portrait"
3940
android:theme="@style/AppTheme.NoActionBar" />
4041
<activity
41-
android:name="com.espressif.ui.activities.ProvisionActivity"
42-
android:label="@string/title_activity_provision"
42+
android:name="com.espressif.ui.activities.BLEProvisionLanding"
43+
android:label="@string/title_activity_connect_device"
4344
android:screenOrientation="portrait"
4445
android:theme="@style/AppTheme.NoActionBar" />
4546
<activity
46-
android:name="com.espressif.ui.activities.ProvisionSuccessActivity"
47-
android:label="@string/title_activity_provision_success"
47+
android:name="com.espressif.ui.activities.WiFiProvisionLanding"
48+
android:label="@string/title_activity_provision_landing"
4849
android:screenOrientation="portrait"
4950
android:theme="@style/AppTheme.NoActionBar" />
5051
<activity
51-
android:name="com.espressif.ui.activities.BLEProvisionLanding"
52-
android:label="@string/title_activity_connect_device"
52+
android:name="com.espressif.ui.activities.ProvisionLanding"
53+
android:label="@string/title_activity_provision_landing"
5354
android:screenOrientation="portrait"
5455
android:theme="@style/AppTheme.NoActionBar" />
56+
<activity
57+
android:name="com.espressif.ui.activities.ProvisionActivity"
58+
android:label="@string/title_activity_provisioning"
59+
android:screenOrientation="portrait"
60+
android:theme="@style/AppTheme.NoActionBar" />
61+
<activity
62+
android:name="com.espressif.ui.activities.SettingsActivity"
63+
android:label="@string/title_activity_settings"
64+
android:screenOrientation="portrait" />
5565
<activity
5666
android:name="com.espressif.ui.activities.WiFiScanActivity"
5767
android:label="@string/title_activity_wifi_scan_list"

0 commit comments

Comments
 (0)