imp.setenroltokens(planID, token)

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/v5/enroll

The request must include the headers:

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

and the body:

{ "type" : "production_token" }

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 included in the HTTPS POST request’s body under the key plan_id. 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 token_id. The first of these is a production plan ID — pass this into imp.setenroltokens()’s first parameter. The token_id field yields the enrollment token, to be passed as imp.setenroltokens()’s second argument. 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");