impCloud Plan IDs And Device Activation

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.

What Is A Plan 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.

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 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.

impCloud Production Plan ID Usage

Each of your end-users will gain their own plan ID (Plan ID_1..n) which, when combined with
each production device’s ID (Dev. ID_1..n), will generate a unique per-user, per-device agent URL.

How Are Plan IDs Generated?

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 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, as requested by your BlinkUp SDK-based app.
  • All blessed devices take a production plan ID — only blessed devices should be distributed to end-users.
    • Do not pass a developer plan ID to a blessed device: its enrollment will fail.

• If the device is to be operated by you, or on your behalf by a developer:

  • If it is a prototype or other development device, always use a developer plan ID.
    • Do not pass a production plan ID to an unblessed device.
  • If the device is a BlinkUp fixture, always use a developer plan ID. This device must not be blessed.

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

impCloud Developer Plan ID Usage

Each impCloud customer account has its own plan ID: account A has Plan ID_A, account B has Plan ID_B, etc.
Combined with each development device’s ID, these per-account developer plan IDs generate unique agent URLs for each development device

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: 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.

Testing BlinkUp SDK-based Apps

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.

Summary

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

Common Scenarios and Issues

Your app reports the agent URL is ‘Unknown’ or ‘Undefined’

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.

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 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.

Troubleshooting

• Are you selecting the correct type of BlinkUp?
  • For all Development Devices and BlinkUp Fixtures:
    • Use the Electric Imp app.
  • For all end-user (blessed)devices:
    • Use your BlinkUp SDK-based app, which should be coded to request a new production plan ID.
• Are you requesting a new plan ID?
  • For all Development Devices and BlinkUp Fixtures:
    • The Electric Imp app does this for you (it always uses your developer plan ID).
  • For all end-user devices:
    • Code your BlinkUp SDK-based app to request a new plan ID via the SDK. This will always be a production plan ID.
• Are you using an existing plan ID?
  • For all Development Devices and BlinkUp Fixtures:
    • Do not provide a plan ID. The Electric Imp app does this for you (it always uses your developer plan ID).
  • For all end-user devices:
    • Code your BlinkUp SDK-based app to re-use a plan ID previously obtained via the SDK. This will always be a production plan ID.
    • Never include or use your developer plan ID for testing or any other purpose.