Skip to main content

Public impCloud Plan IDs And Device Activation

A Guide For Electric Imp Public 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 with Public impCloud-hosted accounts. If you are an Electric Imp Private impCloud customer, please consult this document instead.

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 Customers (ie. developers and manufacturers) and their 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.

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

impCloud Production Plan ID Usage


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.

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 Public Cloud 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 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 Android and/or iOS BlinkUp SDK for 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 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 users — the enrollment will fail.

Do not use a hardcoded developer plan ID for single or multiple 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 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 BlinkUp SDK. This approach to testing 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 Public impCloud and the wider Internet until they are enrolled with a valid production plan ID.

Working with Test Blessed 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 supported device, BlinkUp tool and plan ID combinations. 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 Blessed 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

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) log to the Public impCloud. Those logs can be viewed in impCentral or 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 (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 Factory 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 Factory Device Groups can be viewed by selecting the 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 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.