App Design Considerations

Application design

Before you start designing the ZipKey onboarding experience in your mobile app, you will need to answer a few questions:

Will your app always bind the device to a particular user account? Some products are always associated with a user account whereas other products may work just fine without being associated with a particular account.

Will you require the user to confirm that the right device is being onboarded? In some cases manufacturers want a confirmation by having the user take some action on the device, such as pressing a button. This adds an extra step to the onboarding process, but can eliminate some low likelihood corner case issues where the wrong device was selected, and can provide an additional layer of security.

Will you want to identify the device to the user? If a user is likely to onboard multiple devices at once, you can identify the device (e.g. by flashing a light or playing a sound on the device) to help the user identify which is which. This can be helpful if the user needs to name individual devices.

Once the device has been onboarded to a private Wi-Fi network, does the user have to take some action to set it back into onboarding mode (e.g. press a switch on the device) if they want to provision a different network or does it happen automatically on reboot?

If the device did not join a ZipKey network, do you want to use Cirrent's implementation of SoftAP or BLE to push private network credentials to the device, or do you have an alternative local onboarding process?

Cirrent provides an SDK for iOS and Android that supports all of these use cases easing the development effort to deliver a mobile app with the seamless onboarding experience for ZipKey-enabled devices, whether they are in range or out of range of ZipKey networks.

Example Application Flow

The high level flow is as follows -

The user is prompted to login. The user needs to log into your cloud, so that your cloud knows who the user is, and can track who is the owner of the ZipKey-enabled device. Cirrent does not need to know who the owner is - this login is managed entirely by your cloud.

The user selects an option to add a nearby device. The app calls your cloud to get a token authorizing the app to search for nearby ZipKey-enabled devices.

The app gathers its environment (lat/long if available, wi-fi scans, and a traceroute to confirm which network the app is on)

The app uploads its environment to the Cirrent cloud. This enables the Cirrent cloud to identify nearby devices that have not yet been bound (based on matching up the BSSIDs that the app and device can see, and also using GPS coordinates if available). It also enables the Cirrent cloud to confirm whether the user's broadband provider has credentials for the network the phone is on.

The app calls the Cirrent Cloud looking for any unbound devices that are of this product type, and have been powered on recently (typically in the last 15 minutes). Cirrent will return a list of nearby devices. If there are no devices found, the app should go into the SoftAP or alternative onboarding process.

The user selects the device they wish to onboard. See “What happens if more than one device is found?” below for more detail.

The app gets a new token from your cloud, authorizing it to bind and manage this device. If you want to bind the device to the user, the app can do that now. Also see “User binding” section below.

The app calls the Cirrent cloud to get the status for the selected device. This includes the Wi-Fi networks the device can see, and whether the broadband provider can auto-provision the network (saving the user from having to enter their private network credentials manually).

If the broadband provider can auto-provision the network, you should give the user this option as it is the most reliable and easiest for the user - no chance of entering the wrong credentials.

Otherwise, the user is shown a drop-down list of networks the device can see. The user selects one and enters the pre-shared-key for this network. Then the app sends the credentials to the Cirrent cloud.

The app polls the Cirrent cloud for status updates, waiting to see if the device has successfully joined the private network.

When the app sees a status that the device has joined the private network, the app confirms to the user that the onboarding is complete. The device is now on the user's private network and ready for use.

Local Onboarding

There are two situations where the app may not find any nearby devices in the Cirrent cloud: 1) the device was unable to join a ZipKey network, or 2) the Cirrent cloud could not determine the location of the mobile app. In either case, the app should use SoftAP or some other local onboarding mechanism to provision the device onto the private network. If using softAP, the flow is as follows:

On Android, the app moves the phone over to the SoftAP network being broadcast by the device. On iOS the app instructs the user on how to move the phone over to the SoftAP network (via the Apple settings screen) and waits for the phone to confirm it is on the SoftAP network.

The app gets device information from the device, including the list of networks that the device can see, and the device's public key.

The app prompts the user to select their private network, and enter the pre-shared key.

The app encrypts the pre-shared key with the device's public key.

The app sends the private network credentials to the device, over the SoftAP network.

The app starts polling the device for status updates, waiting to see if the device has successfully joined the private network.

When the device has joined the private network, the device will bring down the softAP network, so the app will drop off the softAP network, and rejoin the network that it was on.

BLE works in a very similar fashion.

The app connects the phone to the BLE network being broadcast by the device.

The app gets device information from the device, including the list of networks that the device can see, and the device's public key.

The app prompts the user to select their private network, and enter the pre-shared key.

The app encrypts the pre-shared key with the device's public key.

The app sends the private network credentials to the device, over the BLE network.

The app starts polling the device for status updates, waiting to see if the device has successfully joined the private network.

When the device has joined the private network, the app disconnects from the BLE network.

If your device doesn't support SoftAP or BLE and you have an alternative local onboarding mechanism, that's fine too. Any mechanism that delivers private network credentials to the device is sufficient to support this case.

What happens if more than one nearby device is found?

In some cases there may be more than one device found. For some products that may be expected (a set of wireless speakers, for example), whereas for others it might be unusual. You can figure out how you want to handle this. If the user wants to onboard multiple devices at the same time, one approach is to have the user onboard one device onto their private network, and then when that is successful (and you know you have valid private network credentials) give the user an option to onboard all the other devices onto the same network using the same credentials. This enables the user to just enter credentials once, and makes the error handling simpler.

If you want to ensure that the user is onboarding the right device, there are a number of techniques you can use to identify the specific devices the user is looking for.

Have the user turn on/off the device. Once the user turns off the device and turns it back on again, the app can call the product cloud looking for devices that came on very recently, so only the expected device will be found.

Have the user take an action on the device. The user can be instructed to take some action on the device (e.g. press a button or turn a knob), and the device will report an updated status to the Cirrent cloud indicating that a user-action was taken. The app can query the Cirrent cloud for the status of each device from the original list and then select the device on which a user action was taken. This can be useful for both identifying specific devices for a user (“press Volume Up on the left speaker”) and for verifying that a user has physical access to the device for security reasons (“press the button on your camera to verify that it is your camera”).

Have the device identify itself. Send an instruction to the Cirrent cloud to have the device flash a light or play a sound, so that the user can confirm that the right device was found.

Binding a device

Some products need to be associated with a user account for normal operation (e.g. a home security camera that uploads videos to a user’s cloud account). Other products may not necessarily be associated with a user account (e.g. a music speaker that can be used by any user on the local network). In either case, the Cirrent cloud needs to know whether a device has already been bound, and should no longer show up in the list of nearby discoverable devices.

Devices are discoverable in the Cirrent cloud whenever SoftAP is running, and vice versa. Devices are discoverable when they are first powered up. A device is never discoverable when it is on a user’s private Wi-Fi network. If a device had previously been on a user’s private network, but can no longer join that network, it is up to you to decide whether it should become discoverable again on reboot, or if the user needs to take some action to put it back in onboarding mode (e.g. pressing a SoftAP button on the device). If the device has been bound to a user’s account, it is never discoverable unless the user takes some explicit action (in the app or on the device) to reset the device into onboarding mode.

The concept of discoverability and user binding is an important one to get right. See here for a more detailed discussion of this topic. If you are unsure as to how to set these parameters for your app and device, just contact us.