Adding a device is as easy as running a Docker container. The Docker container launched onto each device is an agent container that is used to talk back to Deviceplane. For each device that you want to add, a device registration token must be used as part of the Docker command. Click on the "Add Device" button to grab the Docker command to start adding devices. By default, the registration token displayed is the "default" registration token.
Registration tokens are used to authenticate the registration of devices and are required anytime you're trying to add a new device. By default every new project will get a "default" registration token. This is the token that is used when adding a device through the "Add Device" button on the "Devices" page.
A registration token can have a "maximum device registrations" set. This is an optional positive integer that represents the total number of times a registration token can be used. Registration with this token will no longer be possible once the maximum is reached. The "default" registration token does not have a maximum set which means it can be used an unlimited number of times. The maximum of a registration token can be updated anytime. More information on this feature and its security implications can be found in the "Security" section below.
For many basic use cases and security requirements using the default registration should be sufficient. There are two main use cases for creating and using registration tokens other than the default registration token.
These two use cases are documented more below.
To best explain how to use registration token labels, let's consider a user who has multiple "types" of devices in their project and applications that are set to run on only one type of device. Device labels and scheduling rules are used to accomplish this. Specifically suppose they have the following two devices and applications.
Device 1, with label
Device 2, with label
Application 1, with a schedule rule set to only run on devices with label
Application 2, with a schedule rule set to only run on devices with label
These are the results of this setup.
In most cases having to manually add labels to a device after it's registered is impractical. Instead you can create two registration tokens, one for registering devices of type 1 and one for registering devices of type 2. To do this add the label
type=type1 to the first registration token and label
type=type2 to the second registration token. Use the approriate registration token when registering a device of a certain type.
Registration tokens can be used to improve security in cases where devices are physically compromised by a bad actor. Imagine a scenario where you're using the default registration token and then a bad actor gets access to this token through a device. This bad actor will then be able to register any number of devices in your project.
There are two ways registration tokens could be used to address this threat.
Using a registration token with no limit on registrations is the most convenient option. Option (1) is slightly more inconvenient, and option (2) is the most inconvenient. Choose between these options depending on your specific security requirements. If you trust the people or organizations who have physical access to your devices then not setting limits on your registration tokens is likely safe. In cases where you aren't as trusting of the owners of your physical devices (perhaps a consumer product) then option (2) is a better choice.
Having a separate registration token per device has the added security benefit of making them revokable. If you use the same registration token for multiple of your devices (before registration occurs) then revoking this token will prevent registration of multiple devices and not just one.