Skip to content

Commit f813e90

Browse files
smittytonesmittytone
committed
Initial upload
0 parents  commit f813e90

File tree

327 files changed

+9343
-0
lines changed

Some content is hidden

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

327 files changed

+9343
-0
lines changed

Diff for: ‎README.md

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# The Electric Imp BlinkUp SDK for Android #
2+
3+
This repo contains the Electric Imp BlinkUp™ SDK for Android that it is made available to Electric Imp customers. As such it mirrors the downloadable files hosted by the [Dev Center](https://developer.electricimp.com/manufacturing/sdkdocs), but in a form that allows customer developers to add the SDK to their app project repos as a sub-module. This will allow them to pull in SDK changes manually at build time, or automatically through their own build scripts.
4+
5+
## Sub-module Installation ##
6+
7+
To install the SDK as a sub-module, navigate to your project repo directory and then enter the following command:
8+
9+
```
10+
git submodule add https://github.com/electricimp/BlinkUpSDK-Android.git
11+
```
12+
13+
This will add the SDK repo as a sub-module referenced through the file `.gitmodules`, which will be added if it is not present. You can now push your local repo to its origin:
14+
15+
```
16+
git push origin <working_branch>
17+
```
18+
19+
To update the sub-module contents at any time, eg. in a build script, call:
20+
21+
```
22+
git submodule update --remote
23+
```
24+
25+
**Note** The BlinkUp SDK repo is considered solely for consumption by a customer’s project. We will not be accepting pull requests made to the BlinkUp SDK repo. If you have support or related questions concerning the SDK, please submit them through your customer account’s [Electric Imp Support access](https://support.electricimp.com/).
26+
27+
## BlinkUp SDK Installation ##
28+
29+
To understand how to add the BlinkUp SDK files to your app project, please see the relevant documentation included with each of the SDK:
30+
31+
- [Android SDK Installation](./android/README.md)
32+
33+
## Release Notes and Known Issues ##
34+
35+
Please see the [Dev Center SDK page](https://developer.electricimp.com/manufacturing/sdkdocs), or the SDK documentation in this repo.
36+
37+
---
38+
39+
The BlinkUp SDK is copyright &copy; 2020, Twilio, Inc.

Diff for: ‎sdk/README.md

+233
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Electric Imp Android BlinkUp SDK 6.4.3 #
2+
3+
- [Introduction](#introduction)
4+
- [Installation](#installation)
5+
- [SDK Usage](#sdk-usage)
6+
- [Customization](#customization)
7+
- [Sample Code](#sample-code)
8+
- [Out-of-Band Usage](#out-of-band-usage)
9+
- [Third-party Code](#third-party-code)
10+
- [Release Notes](#release-notes)
11+
12+
## Introduction ##
13+
14+
Electric Imp's BlinkUp™ technology is used to activate and configure devices based on the Electric Imp Platform. The BlinkUp SDK can be used by Electric Imp customers to incorporate BlinkUp into their Android apps. Usage requires a BlinkUp API key which is only made available to individuals and organizations who have entered into a commercial relationship with Electric Imp. For more information on becoming an Electric Imp customer, please [contact Electric Imp Sales](mailto:sales@electricimp.com).
15+
16+
#### Notice ####
17+
18+
The Electric Imp Android BlinkUp SDK is licensed solely for the provision of BlinkUp services within mobile apps developed by or on behalf of Electric Imp customers. All rights reserved. The Android BlinkUp SDK is copyright Twilio, Inc. 2020.
19+
20+
## Installation ##
21+
22+
1. Extract the zip file
23+
2. In Android Studio, choose **Import Project**. Go to the extracted zip directory and select the `build.gradle` file for the project you like to import, eg. `sample_theme`.
24+
3. Set the constant *API_KEY* to your customer BlinkUp API key in *MainActivity.java*.
25+
4. Build and run the sample.
26+
27+
After you have compiled a sample project successfully, you can integrate the BlinkUp SDK into your own app:
28+
29+
1. Open your project in Android Studio. Copy the directory `repo` into `app/repo` in the project list.
30+
2. Add the following code to `app/build.gradle`:
31+
```java
32+
repositories {
33+
maven {
34+
url "$projectDir/repo"
35+
}
36+
}
37+
```
38+
39+
3. Click **Sync Project with Gradle Files** in Android Studio.
40+
41+
## SDK Usage ##
42+
43+
1. In the code where you want to access BlinkUp, import the package by adding the following line to the top of your Java class:
44+
```java
45+
import com.electricimp.blinkup.BlinkupController;
46+
```
47+
2. Now add a instance variable to your Class and response code:
48+
```java
49+
private BlinkupController blinkup;
50+
```
51+
3. In your Activity *onCreate*, or wherever you plan to initiate BlinkUp, instantiate your BlinkupController object:
52+
```java
53+
blinkup = new BlinkupController();
54+
```
55+
4. Define an error handler for server errors:
56+
```java
57+
private ServerErrorHandler errorHandler = new ServerErrorHandler() {
58+
@Override
59+
public void onError(String errorMsg) {
60+
// Customize the error handling for your app
61+
Toast.makeText(MainActivity.this, errorMsg, Toast.LENGTH_SHORT).show();
62+
}
63+
};
64+
```
65+
5. Call BlinkUp:
66+
```java
67+
blinkup.selectWifiAndSetupDevice(this, API_KEY, errorHandler);
68+
```
69+
6. Fetch the agent URL to communicate with the imp by calling the *getTokenStatus()* function.
70+
71+
Please see the included `sample_agent` project for a complete example.
72+
73+
#### Terminology Note ####
74+
75+
The SDK makes reference to ‘setup tokens’, eg. in the BlinkupController function *acquireSetupToken()*. Modern Electric Imp documentation refers to ‘enrollment tokens’. Both types of token are identical.
76+
77+
## Customization ##
78+
79+
Customization involves performing the key BlinkUp processes manually rather than allowing the function *selectWifiAndSetupDevice()* *(see Step 6, above)* to present a WiFi-centric UI for you.
80+
81+
Automatic BlinkUp will get a new plan ID and a new enrollment token (aka a ‘setup token’) for you, but you may wish to re-use a previously acquired plan ID (this is recommended when an end-user is re-configuring a device they have already activated). To provide the SDK with an existing plan ID, you will first need to record it at the end of the BlinkUp process and persist it, either locally or remotely. When the end-user re-configures their device, retrieve the saved plan ID and pass it into the SDK using the function *setPlanID()*:
82+
83+
```java
84+
blinkup = new BlinkupController();
85+
blinkup.setPlanID(retrievedPlanID);
86+
```
87+
88+
You can now call one of the SDK's *setupDevice(...)* functions according to whether your imp-enabled device connects by Ethernet, cellular or WiFi. Whichever of these calls you use, the SDK will retrieve a new setup token, bundle it with the previously set plan ID and send them to the device using BlinkUp.
89+
90+
**Note** If you do not call *setPlanID()*, then the SDK will acquire a new plan ID for you.
91+
92+
### Sample Code ###
93+
94+
The following sample projects demonstrate the different ways you can customize the BlinkUp UI and process:
95+
96+
- `sample_countdown` &mdash; Change the pre-BlinkUp countdown.
97+
- `sample_strings` &mdash; Use your own strings at various parts of the UI.
98+
- `sample_theme` &mdash; Use your own Android theme.
99+
- `sample_interstitial` &mdash; Add an interstitial page before BlinkUp
100+
- `sample_direct` &mdash; Invoke BlinkUp directly without going through the WiFi network selection screen
101+
- `sample_agent` &mdash; Fetch the agent URL, device ID and device-authorization date after BlinkUp
102+
103+
Please see the file [`javadoc/BlinkupController.html`](javadoc/BlinkupController.html) in the SDK folder for the *javadoc* description of the SDK's functions.
104+
105+
## Out-of-Band Usage ##
106+
107+
The SDK supports out-of-band BlinkUp, ie. the acquisition of a setup token and, if required, a plan ID which the host app can then transmit to a device by some means other than BlinkUp.
108+
109+
For example, an app which uses Bluetooth LE to communicate with and activate a compatible imp, such as the imp004m, can use the function *acquireSetupToken()* to retrieve a setup token *and* a plan ID &mdash; these will be passed into the the function (type TokenAcquireCallback) that you pass into *acquireSetupToken()* as its *onSuccess* handler. If you are using *acquireSetupToken()*, you can still use *setPlanID()* to apply a retrieved plan ID.
110+
111+
**Note** It is not necessary to call this function if you are using BlinkUp &mdash; the call to *setupDevice(...)* will retrieve a new token for you.
112+
113+
## Third-party Code ##
114+
115+
The Android BlinkUp SDK contains the following third-party code:
116+
117+
- [OkHttp 3.10.0](http://square.github.io/okhttp/)
118+
- [Retrofit 2.4.0](http://square.github.io/retrofit/)
119+
- [Moshi](https://github.com/square/moshi)
120+
121+
For information on licensing, please see the file `licensing/README.md`.
122+
123+
## Release Notes ##
124+
125+
### 6.4.3 ###
126+
127+
- Documentation only update.
128+
129+
### 6.4.2 ###
130+
131+
- Auto-cancel BlinkUp when the user switches out of the host app to the home screen or another app.
132+
133+
### 6.4.1 ###
134+
135+
- Restore *device_id* key to post-BlinkUp polling JSON responses.
136+
137+
### 6.4.0 ###
138+
139+
- Support certificate pinning for custom URLs.
140+
- Update the SDK to support Electric Imp’s v5 enrollment API. This has no impact on SDK usage or functionality.
141+
142+
### 6.3.5 ###
143+
144+
- If during a device enrollment poll, the SDK times out while attempting to connect to the server, this is now treated as an error (ie. any registered *onError* handler will be called). If the SDK times out after contacting the server (ie. the target imp-enabled device did not come online and attempt to enroll, or the enroll was rejected by the server), that is treated as a timeout (ie. any registered *onTimeout* handler will be called).
145+
- Minor bug fix.
146+
147+
### 6.3.4 ###
148+
149+
- Add option to perform BlinkUp in a small window (for phones with LCDs adversely affected by flashing).
150+
- Fixed in an issue in which a plan ID was requested even when an existing one was passed in.
151+
152+
### 6.3.3 ###
153+
154+
- Networking update.
155+
156+
### 6.3.2 ###
157+
158+
- Fixed an issue in which an app-supplied plan ID was being ignored by the SDK.
159+
160+
### 6.3.1 ###
161+
162+
- Proguard rules are bundled with the SDK, so there is no need to modify your `proguard-rules.pro` file *(see 6.3.0, Proguard, below)*.
163+
164+
### 6.3.0 ###
165+
166+
#### Proguard ####
167+
168+
If you use [Proguard](https://www.guardsquare.com/en/proguard) and experience crashes (`"Fatal Exception: java.lang.NullPointerException: value == null"`) when you run an app updated to 6.3.0, you may need to a new Proguard configuration. Add the following code to your `proguard-rules.pro` file:
169+
170+
```
171+
##### OkHttp
172+
-dontwarn okhttp3.**
173+
-dontwarn okio.**
174+
-dontwarn javax.annotation.**
175+
-dontwarn org.conscrypt.**
176+
# A resource is loaded with a relative path so the package of this class must be preserved.
177+
-keepnames class okhttp3.internal.publicsuffix.PublicSuffixDatabase
178+
179+
##### Retrofit
180+
# Platform calls Class.forName on types which do not exist on Android to determine platform.
181+
-dontnote retrofit2.Platform
182+
# Platform used when running on Java 8 VMs. Will not be used at runtime.
183+
-dontwarn retrofit2.Platform$Java8
184+
# Retain generic type information for use by reflection by converters and adapters.
185+
-keepattributes Signature
186+
# Retain declared checked exceptions for use by a Proxy instance.
187+
-keepattributes Exceptions
188+
189+
##### BlinkUp
190+
-keep class com.electricimp.blinkup.retrofit.Token { *; }
191+
-keep class com.electricimp.blinkup.retrofit.TokenStatus { *; }
192+
```
193+
194+
This should allow subsequent builds to run correctly.
195+
196+
#### OkHttp ####
197+
198+
This release contains **OkHttp 3.10.0**. If you are also using OkHttp in your app, please update it to version 3.10.0 to avoid `java.lang.NoClassDefFoundError` and/or `java.lang.NoClassDefFoundError` issues.
199+
200+
#### Maven Repo ####
201+
202+
The SDK is packaged as a maven repo instead of just a .aar file. Please replace the `libs` directory with `repo`, and update `app/build.gradle` accordingly. Please see the instructions under [Installation](#installation), above, for more details.
203+
204+
### 6.2.0 ###
205+
206+
- Raised *minSdkVersion* to 19.
207+
- Moved BlinkUp activities declaration to the SDK itself. Please remove the following lines from your app manifest:
208+
209+
```java
210+
<activity android:name="com.electricimp.blinkup.WifiSelectActivity" />
211+
<activity android:name="com.electricimp.blinkup.BlinkupGLActivity"
212+
android:screenOrientation="nosensor" />
213+
<activity android:name="com.electricimp.blinkup.WifiActivity" />
214+
<activity android:name="com.electricimp.blinkup.WPSActivity" />
215+
<activity android:name="com.electricimp.blinkup.ClearWifiActivity" />
216+
<activity android:name="com.electricimp.blinkup.InterstitialActivity" />
217+
```
218+
219+
### 6.1.1 ###
220+
221+
- Minor code changes.
222+
223+
### 6.1.0 ###
224+
225+
- The BlinkupController class gains a new property, *setScreenBrightnessPercent*, which allows you to specify a screen's maximum brightness during BlinkUp rather than the default 100%. This will useful for manufacturers of devices with photosensors that have been set with too high a gain: the BlinkUp brightness can be reduced in the app.
226+
- The SDK can now report the version of BlinkUp its provides. Use the BlinkupController class’ new properties *BLINKUP_VERSION_NUMBER* and *BLINKUP_VERSION_STRING*.
227+
228+
### 6.0.0 ###
229+
230+
- **BREAKING CHANGE** BlinkupController interfaces has been moved:
231+
- BlinkupController.ServerErrorHandler -> ServerErrorHandler
232+
- BlinkupController.TokenAcquireCallback -> TokenAcquireCallback
233+
- BlinkupController.TokenStatusCallback -> TokenStatusCallback

0 commit comments

Comments
 (0)