Skip to main content

How To Activate Production Devices In The Connected Factory

Enroll Blessed Units Before They Ship To Your Customers

Many Electric Imp customers choose to implement the standard Production Device enrollment flow: new devices are initially enrolled into their target impCloud™ — a process called activation — by using a BlinkUp™ SDK-enabled mobile app operated by an end-user or field engineer. However, some customers may instead prefer to bypass this process in order to ship pre-enrolled production devices. This requires activation to take place within the Connected Factory under the control of your factory firmware.

This guide shows how customers can implement factory activation.

What Happens During Standard Activation

During the standard BlinkUp process, the BlinkUp SDK acquires two items from the impCloud: a plan ID and an enrollment token. These are combined with WiFi network credentials, if required, and transmitted to the imp-enabled Production Device optically or by an out-of-band method such as Bluetooth LE.

The Production Device uses the WiFi credentials to connect to the local network and gain Internet access. Alternatively, depending upon the type of imp it contains, the device may connect via Ethernet or cellular network. However it connects, it now sends the enrollment token to the server in order to authenticate itself for access to the impCloud.

Factory Activation

Because factory activation does not make use of BlinkUp, the credentials that are used in the standard BlinkUp process must instead be retrieved by your factory firmware’s agent and manually applied to the Device Under Test (DUT) on which the factory firmware is running. This takes place after blessing and before the device restarts. As soon as the device restarts, it will attempt to connect to the impCloud in order to undergo activation.

Pre-requirements

Enrollment tokens are intentionally short-lived, so activation must take place immediately after the token has been acquired. It is not possible to cache tokens for later use, eg. at the time that the device is installed in the end-user’s premises.

In order to connect for activation, the device must be able to reach a wireless network with the same credentials (SSID, password) that have been programmed into the device. These may be different from the factory’s own network; in this case you will need to equip your factory with an Internet-connected access point or router set to the pre-programmed credentials. This may not be necessary if the product is intended to connect by Ethernet or cellular.

To ensure that your application firmware is not imposed upon the device immediately after blessing, you must set your application firmware to be loaded after BlinkUp. Please note that this is not the default setting. To change this, navigate to your Product’s list of Production Device Groups and click Settings under MANAGE for group to which your DUTs will be auto-assigned after BlinkUp:


Make sure your Production Device Group is set correctly for factory activation:
devices should download application code after BlinkUp

Acquiring A Token And A Plan ID

Enrollment tokens are acquired from the AWS-hosted Public impCloud by making an HTTP POST request to https://api.electricimp.com/v1/setup_tokens. If your accounts is on the Azure-hosted Public impCloud, the URL is https://api-az.electricimp.io/v1/setup_tokens. Private impClouds will have different API domains — please contact Electric Imp Support for more information.

The request made by the agent must include the headers:

{ "Content-Type": "application/json",
  "Authorization": "Basic <YOUR_BASE64_ENCODED_BLINKUP_API_KEY_PLUS_COLON>" }

Simply set an empty string ("") as the request body.

A successful response will include the HTTP status code 201 (‘resource created’). The endpoint will return JSON data containing both a new plan ID and a new enrollment token with the keys plan_id and id, respectively. The values will be hexadecimal strings ready for use.

Applying The Token And Plan ID

The token and plan ID can now be relayed to the DUT using device.send(); the factory firmware’s DUT code flow should include an agent.on() call which registers a function that will make use of the received data. You should follow this registration call with the agent.send() call that signals the agent that the DUT is ready to receive the token. This is demonstrated in the sample code at the end of this guide.

The DUT calls imp.setenroltokens() to store the received plan ID and enrollment token ready for reconnection and activation. It then calls imp.setwificonfiguration() to apply the WiFi credentials that will be used at the next connection attempt (this is not necessary if the Production Device will connect via Ethernet or cellular. If the WiFi SSID and password are not device-specific, they can be hardcoded into your factory firmware, or you may choose to retrieve them from your own server by making a suitable HTTP request via the agent and then relaying the data to the DUT.

When To Apply The Token And Plan ID

Because of the short-lived nature of the enrollment token, it is best to acquire this immediately before the device is blessed, with blessing progressing once the token and plan ID have been received by the DUT. In the blessing callback, if blessing was successful, call imp.setenroltokens() and imp.setwificonfiguration() with the data you have just retrieved.

Finally, call imp.reset() (impOS™ 38 and up) to cause the Production Device (the DUT becomes a Production Device upon blessing) to reboot, connect using the set WiFi credentials and to request activation with the set token and plan ID. If you are working with an earlier version of impOS, you will need to manually power-cycle the Production Device to trigger activation.

Notification Of Successful Activation

There are a number of alternative methods by which you can indicate that a Production Device has been activated successfully. The BlinkUp webhook, for example, will fire upon activation, so your server can be informed that this has taken place (and receive useful device information).

The sample code below shows another option: the factory agent sends the retrieved token data on to the agent of the fixture which configured the DUT. The fixture’s agent then polls the impCloud for a token ‘claim’ — this is the indicator that the DUT has been enrolled and includes in its response the device ID and agent URL of the activated device. This polling process follows the procedure that the BlinkUp SDK implements after configuring a device.

Sample Code

The following code demonstrates the process described above. The device code has been written with the use of an Electric Imp impFactory™ fixture in mind, but can be readily adapted for other fixtures. The crucial parts of the device code for factory activation are to be found in the function blessDeviceUnderTest().

Agent Code

Device Code