Skip to main content

imp.setenroltokens(planID, token)

Stores Electric Imp impCloud™ enrollment tokens on the imp

Availability

Device (from impOS™ 30)

Parameters

Name Type Description
planID String The plan ID for the enrollment
token String The enrollment token itself

Returns

Nothing

Description

A device’s enrollment token and plan ID are usually transmitted to the device during the BlinkUp™ process. However, this method, together with imp.setwificonfiguration(), allows the device to be configured with WiFi network and Electric Imp impCloud access credentials without having to use BlinkUp. The supplied credentials will be used for all subsequent connections, including those initiated after a cold boot. However, the credentials can be overwritten by a subsequent BlinkUp operation.

During BlinkUp, the enrollment token and plan ID are obtained through the methods provided by the BlinkUp SDK. For imp.setenroltokens(), they must be obtained by making an HTTPS POST request to the Electric Imp impCloud’s REST API:

https://api.electricimp.com/v1/setup_tokens

The request must include the headers:

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

Your BlinkUp API key should be appended with a colon before it is base64 encoded. See the first example below for a typical request construction.

Production devices being configured for a new end-user should not provide a plan ID — a new one will automatically be generated and returned along with the requested enrollment token (see below). However, if the device is being re-configured for the same end-user, you may pass a previously retrieved plan ID when you request a token. The existing plan ID is passed in the HTTPS POST request’s body as a string in JSON encoded form. This will ensure the device is paired with its existing agent, which will be accessed via the same agent URL as before. Implicitly requesting a new plan ID (by not passing one in the token request, ie. by sending an empty body) will cause a new agent with a different agent URL to be created for the device.

If the request passes authentication, the JSON-encoded body of the HTTP response will include the fields plan_id and id. The first of these is a production plan ID — pass this into imp.setenroltokens()’s first parameter. The id field yields the enrolment token, to be passed as imp.setenroltokens()’s second parameter. A successful response will include the HTTP status code 201 (‘resource created’). This is also the status code if you pass in a plan ID (ie. do not create one).

The tokens themselves are 64-bit numbers. Squirrel doesn’t directly support integers of this size, so the tokens should be passed to the method as strings, in hexadecimal form. For example:

imp.setenroltokens("0x1a2b3c4d5e6f7a8b", "0x1a2b3c4d5e6f7a8b");

Because the REST API issues production plan IDs and enrollment tokens, this approach should not be used to configure development devices.

Example Code

The first two examples below show the agent-side construction of typical token requests and their issue to the API. The first block shows how you might make a request that requires a new production plan ID. The second shows how you might make use of an existing, persisted plan ID. The third code block provides device-side processing of the information retrieved by either of the first two blocks.