A Guide For Electric Imp 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.
A plan ID is a unique code that identifies a single impCloud user during BlinkUp. There are two types of user — Electric Imp account holders (ie. developer accounts and production-enabled enterprise ‘customer’ accounts) and customers’ end-users — so there are two types of plan ID:
Developer Plan ID Identifies a single Electric Imp account holder. There are as many developer plan IDs as there are account holders in a given impCloud.
Production Plan ID Identifies a single end-user of an impCloud-connected product. There are as many production plan IDs as there are end-users.
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 a unique ID for the device’s agent. This agent ID is used to form the 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 the creation of an entirely new agent at a new agent URL.
This guarantees that if a device changes ownership (same device ID but a different plan ID), the device gets a new agent. This in turn prevents the new user from having access to 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 changes the device’s network information (same plan ID and device ID) then the device re-enrolls but it continues to use the same agent instance as before.
Each of your end-users will gain their own plan ID (Plan ID1..n) which, when combined with
each production device’s ID (Dev. ID1..n), will generate a unique per-user, per-device agent URL.
Plan IDs are generated by the impCloud.
Developer plan IDs are generated when a customer creates an Electric Imp account or subsequently changes their account password.
Production plan IDs are created when an end-user configures a Production Device via an app incorporating the BlinkUp SDK.
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:
If the device is to be operated by you, or on your behalf by a developer:
If you’d like to know more about blessing, please see ‘What Is A Connected Factory?’.
Each impCloud customer 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 developer plan IDs generate unique agent URLs for each development device
The easiest way to do this is to leave the decision to your BlinkUp tools: the BlinkUp SDK within the app you will provide to your end-users, and the Electric Imp mobile app, which you will use for your development and factory hardware. The Electric Imp mobile app will always use the developer plan ID of the account used to sign in to the app.
When an end-user performs a BlinkUp, they will use your BlinkUp SDK-based app. The simplest approach you can take is to code your app to request a fresh plan ID at every BlinkUp. This will guarantee that a production plan ID is used.
If you choose to re-use an end-user’s existing plan ID whenever they reconfigure their device, provided that plan ID was originally sourced by the BlinkUp SDK (ie. not hardcoded) it will be a production plan ID.
Do not use a hardcoded production plan ID for multiple end-users — the enrollment will fail.
Do not use a hardcoded developer plan ID for single or multiple end-users — the enrollment will fail.
End-users should never use the Electric Imp mobile app to configure a production device — the enrollment will fail.
The recommended approach to app testing is to work with Test Production Devices, ie. devices that have either been blessed during factory firmware development and testing, or have been manually assigned to a Test Production Device Group using impCentral™ or the impCentral API.
For the purposes of testing, Test Production Devices and Production Devices are the same. Both are enrolled using a production plan ID delivered by the BlinkUp SDK. This has the advantage that no developer credentials, eg. your developer plan ID, need be included at any phase of the app’s development therefore eliminating the risk that these credentials may be exposed to unauthorized persons.
Never allow your BlinkUp SDK-based app to be released to the public with your developer plan ID set to be the plan ID used for end-user BlinkUp. This will prevent your end-users from successfully enrolling their devices. These devices will not be permitted to access the impCloud and the wider Internet until they are enrolled with a valid production plan ID.
Simply use your BlinkUp SDK-based app to activate one or more Test Production Devices. Working with Test Production Devices has the advantage that their logs are accessible via impCentral, giving you scope for extra feedback during testing.
The following table lists the device, BlinkUp tool and plan ID combinations that are supported by Electric Imp. Any combinations not listed here are not supported — Electric Imp does not guarantee their behavior and they should not be attempted.
|Blessed Devices||Unblessed Devices|
|Device Type||Production Device||Test Production Device||Development Device||BlinkUp Fixture|
|Intended User||Your end-users||Your app testers and/or your developers||Your assembly line staff|
|App to Use for BlinkUp||Your BlinkUp SDK-based app||The Electric Imp app|
|Plan ID Type Supplied||Production plan ID||Developer plan ID|
|Enrollment Token Type Supplied||Production||Development|
You have used a developer plan ID to configure a (blessed) Production Device. If this has been done in order to enable development logging while the device operates in an end-use context, you should instead obtain the device’s ID through the Blessing or BlinkUp webhook, and use 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.
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 developer plan ID) always log to the impCloud. Those logs can be viewed in impCentral by selecting Development Device Group to which the device has been assigned and viewing the code editor’s log pane. Logs can also be accessed via the impCentral API.
Production Devices (ie. those which have been blessed for end-use and are expected to be 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 (). 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 impCloud. To log information from a Production Device, use production logging as described above.
Logs for your BlinkUp Fixtures (ie. those devices which have been configured with a customer’s developer plan ID and assigned to a Fixture Device Group in impCentral) can be viewed by selecting the relevant Device Group in impCentral and clicking 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 Fixture Device Groups can be viewed by selecting the group’s code editor and viewing the log pane.