JavaScript BlinkUp Librarybeta 0.3.2
Electric Imp’s BlinkUp™ technology provides a means to securely configure an imp-enabled device for local network access and authorize its access to an Electric Imp impCloud™. Connectivity may be wireless or wired, depending on the type of imp integrated into the device. The network access credentials are transmitted to the device optically using the display of a mobile phone or tablet: they are encoded as screen flashes of various intensities.
BlinkUp can be supported in iOS- and Android-based mobile apps using native SDKs which Electric Imp makes freely available to its commercial partners. This is the recommended means of incorporating BlinkUp into customers’ mobile apps.
Electric Imp also provides a third BlinkUp implementation which uses JavaScript to deliver the process through a mobile web browser. Our intention is to make this available to customers to allow them to target mobile platforms which are not supported by Electric Imp through native SDKs. It also allows them to develop apps for enterprise end-users who restrict access to mobile OS app stores for security or other reasons.
This document describes how the Electric Imp JavaScript BlinkUp library might be used to deliver BlinkUp through a mobile browser. The term ‘mobile browser’ includes not only web browsers on mobile devices but also web browser functionality integrated into native mobile apps. Web browser apps will require the JavaScript and entry point HTML to be stored on a remote server as part of a web app. The use of a web browser view within a native app allows the code to be stored locally, inside the app itself.
Important This software is being provided in a pre-release beta form solely for customer evaluation and testing.
Limitations of JavaScript BlinkUp
Where possible, we recommend customers make use of the two native BlinkUp SDKs. These provide much greater control over the BlinkUp process than is possible through the web browser views which are used to deliver JavaScript BlinkUp. The JavaScript BlinkUp Librarybeta has a number of other important limitation of which potential users need to be aware:
JavaScript BlinkUp may not be compatible with all mobile browsers. At this time, mobile Safari (WebKit) and Android Browser are compatible. Chrome on Android is not fully compatible (results vary with device). Windows 10 (mobile) is not supported, but Internet Explorer on earlier versions of Windows Phone has limited support.
Web apps can generally not control the mobile device’s screen brightness. As such, the end-user should be prompted by your web app’s UI to increase the brightness of their device’s display to prevent failed BlinkUps.
Power-saving features made available by mobile operating system and device providers may affect JavaScript BlinkUp performance, typically by auto-dimming the screen. Again, the end-user should be prompted to disable these features to prevent failed BlinkUps.
The code is intended for use with mobile devices but may also operate within a desktop browser. This usage mode is not recommended: configuring a connected product by holding it up to a desktop monitor is not ideal (or comfortable for the user). The JavaScript BlinkUp librarybeta’s
BU
object now contains a property, preventFastFlashing which can be set to force a lower speed, desktop-oriented mode. In the example code provided with the JavaScript BlinkUp librarybeta, this mode is automatically selected if the user runs the sample web app on a non-mobile browser. Note this mode requires the target device to be running impOS 34 or above.
Using the JavaScript BlinkUp librarybeta
The code provided with this Read Me forms a complete working example of JavaScript BlinkUp. It is aimed at commercial customers who are preparing JavaScript BlinkUp-based web app(s) for the imp-enabled connected products. Customers will require an API key (see below).
To produce a commercial web app, it is necessary to create a UI which prompts the user for the required network configuration information and, once the BlinkUp process has been initiated by the user, assists the user through the BlinkUp process. The app should also guide the end-user through preparing their device fro BlinkUp: for example, instructing them to put their device’s display on a high brightness setting (see ‘Limitations’, above). An end-user facing web app would not require the user to enter an API key — this should retrieved at runtime from the customer’s server in a secure manner. Depending on the nature of the connected product, not all of the configuration options presented by this example may be needed in the web app.
Important Customers should remember that, under the terms of their agreement with Electric Imp, they must include the text “BlinkUp™ powered by Electric Imp” prominently in any UI that incorporates BlinkUp. The image is typically included in the pre-flash countdown screen, as demonstrated by the Electric Imp mobile app. A white and black version of the image can be found at the path example/images/countdownTextBlack.svg
and example/images/countdownTextWhite.svg
.
Please see our current Terms of Service and our Branding Usage Guidelines for more information and guidance on the commercial usage of Electric Imp trademarks and imagery.
The JavaScript BlinkUp librarybeta makes use of third-party software which must be appropriately acknowledged in any web app. See ‘License’, below, for more information on the JavaScript BlinkUp librarybeta license and those of its third-party software components.
How to include the JavaScript BlinkUp librarybeta in Your Web App
The JavaScript BlinkUp librarybeta can be included as a module using require. This can be especially useful if a build system is used.
var blinkup = require('blinkup/blinkupSDK');
If modules are not used in the project, the global variable BU can be used in place of the require if the blinkupSDK.min.js
file has been loaded.
// In the HTML file
<script src="blinkupSDK.min.js" type="text/javascript"></script>
// In the JS file or script portion of the HTML
var blinkup = BU;
Prerequisites
JavaScript BlinkUp is supported by the jQuery, jQuery mobile, jQueryUI and AnimationFrame libraries. In order to use the JavaScript BlinkUp, the required libraries must be loaded in the correct order. What follows is an example to go in the <head>
section of the web page presenting the device configuration UI:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
<link rel="stylesheet" href="https://ajax.googleapis.com/ajax/libs/jquerymobile/1.4.5/jquery.mobile.min.css">
<script src="https://ajax.googleapis.com/ajax/libs/jquerymobile/1.4.5/jquery.mobile.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
<script src="AnimationFrame.min.js" type="text/javascript"></script>
<script src="blinkupSDK.min.js" type="text/javascript"></script>
Note This example imports blinkupSDK.min.js
which is the minified version of blinkupSDK.js
. It is recommended that you always use the minified version as it is compressed for faster load times. The JavaScript BlinkUp librarybeta is always loaded synchronously.
JavaScript BlinkUp assumes that some elements exist in the web page’s DOM and uses these elements to present the BlinkUp and associated information. The page structure is as follows:
BU-root
BU-progress
BU-canvas
The BU-root
element specifies the root element under which other BlinkUp UI elements can be found. It is a recommended (but not required) convention.
BU-progress
is an element (typically a div
element) which functions as the progress visual for when the BlinkUp is in progress. By default the item is scaled horizontally. The default behavior can be changed by setting the BU.progressCallback(progress) function.
BU-canvas
is the canvas element which will become the target for the BlinkUp flasher. The canvas must be placed in a parent that has a white background color.
Authentication and API Keys
To perform BlinkUp you will need an API key. For production BlinkUp, ie. for a web app which an end-user will run to configure a production device in the field, you need to pass in your BlinkUp API key, just as you do for apps based on the native iOS and Android BlinkUp SDKs. Customers can obtain BlinkUp API Keys from Electric Imp. Note BlinkUp API keys are only made available to Electric Imp Customers, not to holders of free Electric Imp accounts.
Basic JavaScript BlinkUp librarybeta Usage
A basic JavaScript BlinkUp consists of three calls to the JavaScript BlinkUp librarybeta. Here is a simplified example:
var blinkup = require('blinkup/blinkupSDK'); // or blinkup = BU; if not using modules
blinkup.getConfigId("myElectricImpAPIKey", null, "production", function(err, configId){
if (err){
// Handle error
} else {
var networkConfig = new blinkup.NetworkConfig({
ssid: "someSSID",
password: "somePassword"
});
blinkup.startNetworkFlash(configId, networkConfig,
function(){
blinkup.pollForDeviceInfo(configId, function(err, data){
if (err){
// Handle error
// (device rejected or server connection timed out)
}
else if (data){
// Do something with data
}
});
}
);
}
});
Web App UI Recommendations
GPU Rasterization
In order to enable GPU improvements on Chrome, please add the following meta viewport tags to your HTML header. user-scalable=no
is optional, but recommended:
<meta name="viewport" content="width=device-width, minimum-scale=1.0, user-scalable=no">
Mobile Scrolling
When a hardware device is placed on the mobile screen, it may cause the screen to scroll due to interference. It is recommended that you capture touchmove
events on the body during the countdown / flashing stage. If you are using the provided ui.js
example, this will already be performed.
License
The Electric Imp JavaScript BlinkUp librarybeta contains software copyright © 2015-16, Electric Imp, Inc.
The animation code contained in the file AnimationFrame.min.js
is copyright © Oleg Slobodskoi, 2015 and issued under terms of the the MIT License. The source code can be found at https://github.com/kof/animationFrame.
Lightbox code contained in the file featherlight.min.js
is copyright © Noël Raoul Bossart, 2013 and issued under the terms of the the MIT License. The source code can be found at http://noelboss.github.io/featherlight/.