Onboarding a new node or communicator securely adds the device to your private cluster, allowing it to communicate and share location with all other devices in your cluster. Only the root device is allowed to onboard new devices (this is a security feature).
Onboarding uses LoRa frequencies, just like all other ChatterBox communication. During onboarding, the first thing that happens is public keys are exchanged between the two devices. After that exchange, all other onboarding steps utilize asymmetric encryption and digital signatures. This is the only time your cluster’s private symmetric keys are shared with anything. Private keys are never shared.
Note: If you are onboarding many devices, such as building a cluster of 4+ devices, you will need to allow some time after onboarding for the devices to fully trust one another. If you’re building a large cluster, it is recommended to onboard each device one at a time, then leave them running in the same room/area for several hours or overnight, to ensure trust is fully established. This is a one-time process.
Onboarding a Communicator
Onboarding a Communicator| 1. | Ensure no other nearby devices are currently in Join Mode or Onboard Mode | Only one device can be onboarded at a time, or interference will happen. |
| 2. | Put your Root device in Onboard Mode | On the root device, choose Settings / Cluster / Onboard Device |
| 3. | Put the new/secondary communicator in Join Mode | On the new device, choose Settings / Cluster / Join Cluster |
| 4. | Wait a minute or two | Onboarding typically takes about a minute. If it seems frozen after several minutes, you can safely restart both devices and attempt to onboard again. |
| 5. | After onboard completes, other devices automatically discover this new device | Over the course of minutes (or hours) other nearby on-cluster devices will automatically discover this new device. All devices must exchange public keys with this new device, so it may take some time for your new device to be fully trusted by the cluster. Until the new device is fully trusted, its messages may be ignored by certain devices that haven’t yet exchanged public keys. To speed up this process, on your new device, you can go into settings and choose “Broadcast Identity” a few times. That broadcasts the new device’s public key, in many cases, removing the need for key exchanges. |
Onboarding a Node
| 1. | Ensure no other nearby devices are in Join Mode or Onboard Mode | Only one device can be onboarded at a time, or interference will happen. |
| 2. | Power on the new node | The new node should automatically be in Join Mode immediately. If it has a screen, the screen should show it waiting for a connection. If doesn’t have a screen, its indicator light should be purple. If the device is not in Join Mode (maybe it was previously used for another cluster), remove its SD card, delete the contents, put the SD card back in and restart. In the case of a SAMD node, hold the “boot” button for at least 10 seconds while restarting to clear its fram. |
| 3. | Put your Root device in Onboard Mode | On the root device, choose Settings / Cluster / Onboard Device |
| 4. | Wait a minute or two | Onboarding typically takes about a minute. If it seems frozen after several minutes, you can safely restart both devices and attempt to onboard again. |
| 5. | After onboard completes, other devices automatically discover this new device | Over the course of minutes (or hours) other nearby on-cluster devices will automatically discover this new device. All devices must exchange public keys with this new device, so it may take some time for your new device to be fully trusted by the cluster. Until the new device is fully trusted, its messages may be ignored by certain devices that haven’t yet exchanged public keys. To speed up this process, on your new device, you can go into settings and choose “Broadcast Identity” a few times. That broadcasts the new device’s public key, in many cases, removing the need for key exchang |