Skip to main content

Private impCloud Plan IDs And Device Activation

A Guide For Electric Imp Private impCloud™ Customers

When you start to write your connected product’s BlinkUp™ app, you will encounter the term plan ID. This name refers to a property that Electric Imp’s impCloud™ uses to distinguish one user from another during BlinkUp. Whenever a device first connects to the impCloud, it goes through a process called enrollment. If the enrollment fails, the device will not be permitted to access the impCloud. Devices which fail to enroll may try to do so again. Devices which successfully enroll may later re-enroll. Whenever the enrollment is successful, an agent is instantiated for the device and made available at a unique URL. This URL is determined by the plan ID of the user who performed the BlinkUp, and of the hardware’s own unique device ID.

The FAQs that follow are for Electric Imp customers using Private impClouds. If you are an Electric Imp Public impCloud customer, please consult this document instead.

What Is A Plan ID?

A plan ID is a unique code that identifies a single Private impCloud user during BlinkUp. There are two types of user:

  • Private impCloud owners and their partners (ie. entities with accounts in the Private impCloud).
  • End-users.

Consequently, there are two types of plan ID:

  • Developer Plan ID Identifies a single Private ImpCloud account holder. There are as many developer plan IDs as there are Private impCloud account holders.

  • Production Plan ID Identifies a single end-user of a Private impCloud-connected product. There are as many production plan IDs as there are end-users.

How Are Plan IDs Used?

Every imp-enabled device has a unique ID. During the BlinkUp process, this device ID and the user’s plan ID are combined to generate the unique URL at which the device’s agent can be accessed.

Using two identifiers (device ID and plan ID) ensures that if either of these identifiers ever changes, a subsequent re-enrollment will result in an entirely new agent at a new agent URL being created.

This guarantees that if a device changes ownership (same device ID but a different plan ID), the device gets a new agent. This prevents the new user from accessing any data that was held by the previous agent. If a user adopts a second device (same plan ID but a different device ID), then even though the two devices share a common user, they will each have entirely separate agents.

If the user simply reconfigures the device (same plan ID and device ID) then the device re-enrolls but it continues to use the same agent instance as before.

Private impCloud Production Plan ID Usage


Each of your end-users will gain their own plan ID (Plan ID1..n) which, when combined with each device’s ID (Dev, ID1..n), will generate a unique per-user, per-device agent URL. End-user 1 has two devices: two device IDs
(Dev. ID1 and Dev. ID2) combined with the user’s single plan ID generate two unique agent URLs, one per device

How Are Plan IDs Generated?

Plan IDs are generated by the Private impCloud.

  • Developer plan IDs are generated when a developer account is created or the account holder subsequently changes their password.
  • Production plan IDs are created when an end-user configures a Production Device using BlinkUp.

Which Plan ID Do I Use?

Which type of plan ID is used in a given BlinkUp operation depends solely on the device’s intended user:

  • If the device is to be operated by an end-user, always use a production plan ID. Note Only blessed devices should be provided to end-users — only blessed devices take a production plan ID.

  • If the device is to be operated by you, or on your behalf, ie. it is a prototype or other development device, always use a development plan ID. Do not pass a development plan ID to a blessed device.

  • If the device is a BlinkUp Fixture, always use a development plan ID. Again, this device must not be blessed.

If you’d like to know more about blessing, please see ‘What Is A Connected Factory?’.

How Do I Ensure I Use The Right Type Of Plan ID?

The easiest way to do this is to leave the decision to your BlinkUp tools. All Private impCloud BlinkUp operations are mediated by the Electric Imp JavaScript BlinkUp library, which forms the basis for the web apps you will create to configure production, development and factory devices.

You may choose to develop two web apps: one for development and factory devices, the other for end-user devices. Or you may produce a single web app and allow the user to select the type of BlinkUp manually, typically by pressing one button or another. We recommend the former, which can make use of the same codebase for the two apps and minimizes the opportunity for user error (eg. end-users performing development BlinkUps) that will prevent devices from being successfully enrolled.

Plan IDs are only required during the BlinkUp process and only need be explicitly set or requested if your web app is performing a production BlinkUp, ie. a blessed device is being configured by an end-user. The library supports the selection of either either a production or development BlinkUp at the start of a BlinkUp operation. The configuration of BlinkUp Fixtures, which are used to configure Devices Under Test (DUTs) prior to blessing, is performed using development BlinkUp.

Private impCloud Development Plan ID Usage


Each Private impCloud product account has its own plan ID: account A has Plan IDA, account B has Plan IDB, etc. Combined with each development device’s ID, these per-account plan IDs generate unique agent URLs
for each development device

Testing BlinkUp SDK-based Apps

The recommended approach to app testing is to work with Test Blessed Devices or Production Devices, ie. DUTs that have undergone factory enrollment either with development factory firmware deployed to a Test Factory Device Group or production factory firmware deployed to a Factory Device Group.

For the purposes of testing, Test Blessed Devices and Production Devices are the same. Both are enrolled using a production plan ID delivered by the JavaScript BlinkUp library.

Working with Test Blessed Devices has the advantage that their logs are accessible via impCentral™, giving you scope for extra feedback during testing.

Common Scenarios

Below are listed a number of common scenarios that may be encountered by Private impCloud customers as they work with plan IDs. The recommended (supported) operating procedure is provided for each scenario.

Web App For End-user Device BlinkUp

The JavaScript BlinkUp library should be used to perform a production BlinkUp by calling BU.getConfigId(apiKey, existingPlanId, environment, callback) with the environment parameter set to the string "production". Initially, a new end-user will have no plan ID so you should pass null into the existingPlanId parameter. The end-user’s plan ID will be returned within the deviceInfo structure passed into the callback function registered with BU.pollForDeviceInfo(configId, callback), a function called to poll the Private impCloud to discover whether the device was successfully enrolled or rejected. The plan ID is placed in the deviceInfo.planID property.

If you wish end-users who re-configure their devices to retain the same agent URL as before (and thus the same agent instance, which is essential if you wish to make use of persisted data), you should retain their plan ID and pass it back into existingPlanId at the start of any subsequent BlinkUp. However, this is optional. If no plan ID is passed in, a new one will always be generated and returned.

Web App For Development Device BlinkUp

The JavaScript BlinkUp library should be used to perform a development BlinkUp by calling BU.getConfigId(apiKey, existingPlanId, environment, callback) with the environment parameter set to the string "development". Always pass null into the existingPlanId parameter.

Testing End-user Oriented Web Apps

Follow the same procedure outlined in Web App For End-user Device BlinkUp, above.

Web App For BlinkUp Fixtures

The JavaScript BlinkUp library should be used to perform a development BlinkUp by calling BU.getConfigId(apiKey, existingPlanId, environment, callback) with the environment parameter set to the string "development". Always pass null into the existingPlanId parameter.

Once the fixture has been added to a Private impCloud account, it can be assigned to a Factory Device Group or Test Factory Test Device Group as required.

Agent URL Is Reported As ‘Unknown’ Or ‘Undefined’

You have used a development plan ID to configure a Production Device (a blessed device). If this has been done in order to enable development logging while the device operates in an end-use context, you should instead configure the device with a production plan ID, obtain the device’s ID through the Blessing or BlinkUp webhook, and use Electric Imp impCentral or the impCentral API to monitor the device’s operation. You can now run BlinkUp again to re-enroll the device if you wish to observe this behavior.

Device Logging

Plan IDs do not affect device logging directly — the level of device logging is determined by whether the device is blessed or not.

Development Devices (ie. those which have not been blessed and have been configured with an account’s development plan ID) log to the Private impCloud. Those logs can be viewed via impCentral in a given Development Device Group’s code editor, or the impCentral API.

Production Devices (ie. those which have been blessed for end-use and subsequently configured by an end-user with a production plan ID) do not log unless explicitly set to do so. Logs for production devices can be viewed by entering the target’s device ID into the Device Lookup panel in the devices menu (Devices Menu). This will call up a page of detailed device information; select the LOGS tab to activate logging for that device and to view the subsequent log output.

Do not use a developer plan ID during the BlinkUp of a blessed device in order to view the device’s logs in impCentral. This will not work and will prevent the device from accessing the Private impCloud. To log information from a Production Device, use the procedure described above.

Logs for your BlinkUp Fixtures (ie. those devices which have been configured with a developer plan ID and assigned to a Factory Device Group or Test Factory Device group in impCentral) can be viewed by selecting the relevant Device Group in impCentral. For Factory Device Groups, click Fixtures under the MANAGE column. Locate the fixture in the list and click Details under MANAGE and then click on the LOGS tab in the device details view. Fixtures assigned to Test Factory Device Groups can be viewed by selecting the code editor and viewing the log pane.

Using Incorrect Plan IDs

Using the wrong type of plan ID can result in the device being prevented from accessing your Private impCloud. This is typically seen when an end-user device, ie. a Production Device, fails to connect to your Private impCloud when it is first configured or the app is provided with an undefined agent URL (see above). This will typically result from passing an incorrect plan ID (such as a Private impCloud account’s development plan ID) or an invalid plan ID (the app is attempting to pass a self-generated plan ID or some other customer-created ID in place of a production plan ID).

The JavaScript BlinkUp library does not send a passed plan ID (via the existingPlanId parameter of BU.getConfigId()) to the Private impCloud when it is performing a development BlinkUp, only when it is performing a production (end-user) BlinkUp. If you pass an incorrect or invalid plan ID into a development BlinkUp, it will be ignored and the Private impCloud account’s development plan ID used automatically.

Troubleshooting

  • Are you selecting the correct type of BlinkUp? Check you have passed the correct BlinkUp type string:
    • For all Development Devices and BlinkUp Fixtures:
      • Pass the string "development" into BU.getConfigId()’s environment parameter.
    • For all end-user devices:
      • Pass the string "production" into BU.getConfigId()’s environment parameter.
  • Are you requesting a new plan ID?
    • For all Development Devices and BlinkUp Fixtures:
      • You do not to request a plan ID. Pass null into BU.getConfigId()’s existingPlanID parameter.
    • For all end-user devices:
      • Pass null into BU.getConfigId()’s existingPlanID parameter. The returned configID’s planId key will yield the new production plan ID.
  • Are you using an existing plan ID?
    • For all Development Devices and BlinkUp Fixtures:
      • You do not provide a plan ID. Pass null into BU.getConfigId()’s existingPlanID parameter.
    • For all end-user devices:
      • Only pass the plan ID received after the same end-user’s previous BlinkUp operation.