When a device is powered on for the first time, it is deemed to be discoverable, in that it can be found by a user who is trying to set up the device. Once a device has been associated to a user's account (it is bound) or it is on a private network, it is no longer considered discoverable. When the device joins a ZipKey network, it will upload its location and Wi-Fi scan list to the Cirrent cloud. From that, the Cirrent cloud can determine the approximate location of the device. The device will also turn on its local onboarding network (SoftAP or BLE, depending on which is being used for local onboarding).
When the user starts the app and searches for a nearby device, the app will call the Cirrent cloud, passing the user's location. The Cirrent cloud will find any nearby discoverable devices of the right type (i.e. devices that are not yet bound to a user's account, are made by the correct manufacturer, and are nearby to the user). The user can then confirm that this is the device they want to provision, and it will be marked as bound, so that it is no longer discoverable by any other users. A nearby device that is not discoverable (because it is bound to a user's account, or on a private network) will not be returned in any searches for nearby devices.
This all makes sense for the first time flow with a brand-new device. There are a number of product decisions to be made about how the device, the app and the Cirrent cloud should behave later on in the product lifecycle. For example, if the device can no longer join a private network that was previously configured, should it turn on the local onboarding network (softAP or BLE) automatically, or should it wait for the user to press an onboarding button to bring the local onboarding network back up? What happens on a factory reset? What happens when the user deletes the device from their app? The table below summarizes the default behavior, but as part of your product design process you can certainly change these options to suit your product and the user experience you want to deliver.
Note: the local onboarding network in the chart below is the softAP network if using softAP, or the BLE network if using BLE.
|Nearby discoverable device is found||Binds to user account||Device is marked as bound, no longer discoverable|
|Device joins private network||Brings down local onboarding network||Binds to user account (if not already bound)||Device is marked as bound, no longer discoverable|
|Device can no longer join private network (either private network is not in range, or device has invalid credentials for the private network)||Rejoins ZipKey network, updates status.||Give user an option to 'add a network' either via Cirrent cloud or via local onboarding network||Device is not discoverable as it is still bound to user's account|
|User presses local onboarding button||If on private network, ignore. If on ZipKey or on no network, bring up local onboarding network||Give user an option to 'add a network' either via Cirrent cloud or via local onboarding network|
|Factory reset||Device tells cloud it has been reset, clears all private networks, deletes logs, rejoins ZipKey network and brings up local onboarding network.||Device is marked as unbound, and is once again discoverable|
|User deletes device from their account||When device gets the RESET, it clears all private networks, deletes logs, rejoins ZipKey network and brings up local onboarding network. (If the device had got new private credentials over the local onboarding network after the RESET was sent to the cloud, that private network is not deleted.)||App sends RESET to cloud||Device is marked as unbound, and is once again discoverable. RESET is sent to the device.|