Knowledgebase

The BlinkUp API key you use to make calls to the BlinkUp SDK’s methods must be the one associated with your account. If this is not the case — for example, it is used with devices blessed to application firmware that is associated with a different account than yours — then your end-users will not be able to perform BlinkUp with your app successfully and they will find their devices are unresponsive.

Almost all of the text in the BlinkUp process can be customized for your application. The Android BlinkUp SDK allows you to set these programmatically; the iOS BlinkUp SDK includes a file of strings which can be edited. Both SDKs also include default BlinkUp strings.

Standard BlinkUp presents a user interface generated by the BlinkUp SDK. It allows the user to select which network they wish to connect to, and then perform a BlinkUp. You and your app developer can customize much of the text presented throughout the process.

If you feel you want more control over the look and feel of the BlinkUp process, you can do a custom BlinkUp. This integrates BlinkUp into your own network-selection UI. More information on this process can be found in the documentation accompanying the BlinkUp SDK.

This is not recommended and should be avoided. Each user has their own plan ID to ensure proper security. Please spend some time architecting your use and management of agent URLs in your app and on your server. Develop a proper plan for the agent URL before launch.

The agent URL is derived from both the device ID and the plan ID. If either of these tokens change, a new URL will be generated and the previous agent URL associated with the device ID will be invalidated.

The device ID never changes. The plan ID can be changed — by requesting a new one from the Electric Imp impCloud™ — but this should be avoided in order to prevent the loss of a user’s agent and device settings. Using a new plan ID, even for the same device, will always generate a new agent.

A pre-existing plan ID must be passed to a BlinkUpController object before the BlinkUp process is initiated, otherwise a new plan ID will be requested by the BlinkUp SDK automatically. If the same device is set up with the same plan ID, the agent URL returned will be the same as before.

The plan ID should be unique per user. If you have a single user — ‘George’, for example — you can use the plan ID generated for George each time he uses BlinkUp on a device. It is your job to keep track of the association between plan ID and users. If you need to keep track of unique devices, the device ID should be used.

If an issue occurs during the BlinkUp process, the agent URL may never be returned. In this case, a delegate method (iOS) or callback method (Android) will be called with an error after one minute. The BlinkUp may fail for a number of reasons, such as incorrect WiFi settings, obstructions between the phone’s screen and the device’s photosensor, and the device’s on-board imp being unable to connect to the Electric Imp impCloud™. It is possible to change the default timeout.

The agent URL is the Internet address of the unique agent assigned to the device being configured by BlinkUp. When the BlinkUp process completes successfully, the agent URL is returned to the app performing the operation. It should be recorded: the app will need to use it to interact with the agent in future, for instance to issue commands to the device or to request information from the device.

The device ID — previously termed the impee ID and still referred to by the SDK as such — is an imp’s authentication ID. It is used to identify which devices are tied to your developer account and which production devices should get the application firmware they were assigned. You can view a developer device’s ID in the IDE, at the top of the device code pane. A device’s ID never changes.

The plan ID is a token that is used to identify a device’s user. New users should be given a new plan ID, which your app should store and use in future BlinkUp operations by setting the planID property of the BlinkUpController object instanced in your app code. A user’s plan ID should be retained and used this way to allow them to re-configure the device’s network access without the loss of agent and device settings. Using a new plan ID, even for the same device, will always generate a new agent.

The logical steps to BlinkUp that your app should perform are as follows:

1. If this is the first time a user has configured a device, connect to the Electric Imp impCloud™ to obtain a plan ID. If this is a subsequent BlinkUp, an existing plan ID may be used to ensure an identical agent URL is generated (for the same device).
2. Connect to the impCloud to obtain an enrollment token. This token is temporary and is not accessible via the BlinkUp SDK.
3. Perform a BlinkUp to combine the new or pre-existing plan ID, enrollment token and WiFi network settings (standard SSID and password combination, or WPS code) and send it to the device.
4. The device’s on-board imp attempts to connect to the wireless network and then to the impCloud.
5. The imp sends the enrollment token to the impCloud.
6. The app uses the BlinkUp SDK to request a notification from the impCloud when the device has connected and been authorized for impCloud access.
7. The app receives this notification, which includes the URL at which the device’s unique agent can be contacted.