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 — with 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.
- If you are unfamiliar with the Electric Imp Connected Factory Process, please take a moment to read our brief overview, which includes a full glossary of the terminology you will encounter here.
What Happens During Standard Activation
During the standard activation process, the BlinkUp SDK acquires two items from the impCloud: a production plan ID and a production enrollment token. These are combined with WiFi network credentials, if required, and transmitted to the 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, or it may connect via Ethernet or cellular network, depending on your application. However the Production Device connects, it now sends the production enrollment token to Electric Imp in order to authenticate itself for access to the impCloud. Once access is granted, the device is said to have been activated.
- For more detailed information on plan IDs and enrollment tokens, please see Activating imp-Enabled Devices and Plan IDs and Successful Device Enrollment.
Factory Activation
Because factory activation does not make use of BlinkUp, the credentials that are used in the standard activation process must instead be retrieved by a Device Under Test’s agent and then sent to the DUT and manually applied. This takes place after blessing but before the device is cold-booted. Upon a power-cycle, the unit will attempt to connect to the impCloud in order to immediately undergo activation (rather than wait for BlinkUp).
Pre-requirements
Production 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 connect by Ethernet, by cellular, or reach a wireless network with the same credentials (SSID, password) that have been programmed into the device. In the case of WiFi, if the programmed credentials are different from the factory’s own network, you will need to equip your factory with an Internet-connected access point or router set to the pre-programmed credentials. This is not necessary if the product is intended only 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 setting, 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 blessing:
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
Production enrollment tokens are acquired from the impCloud by making an HTTP POST request to https://api.electricimp.com/v5/enroll.
The request made by the agent must include the headers:
{ "Content-Type": "application/json",
"Authorization": "Basic <YOUR_BASE64_ENCODED_BLINKUP_API_KEY>" }
Set the request body to the following JSON as a string:
{ "type": "production_token" }
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 production enrollment token with the keys plan_id and token_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 DUT firmware 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. The WiFi SSID and password can be hard-coded into your DUT 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
It is best to acquire the token and Plan ID 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. This is demonstrated in the sample code below.
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 DUT sends the retrieved token data back via its own agent to the agent of the BlinkUp 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().