Onboarding a Device

Onboarding a new devices involves configuring thin-edge.io to connect to a cloud for the first time. This generally involves the following steps:

1. Configure the cloud url to connect to
2. Generate the device certificate (if it does not already exist)
3. Upload the device certificate to the cloud
4. Connect the associated tedge-mapper

Onboarding a device to Cumulocity

The onboarding described in this section involved onboarding a device by executing remote commands on the device via SSH.

It is a two step process which is described as follows:

1. Detect the device (by using DNS Service Discovery)
2. Onboard it via ssh commands

Below shows a diagram of the intended setup to perform the onboarding, where both your computer and the device (to onboard) are in the same network, and you can ssh into the device.

Pre-requisites

On your machine (not the target device that will be on-boarded) you will need on of the following:

1. One of the following CLI tools to scan for devices

   • avahi-browse
   • dns-sd
   MacOS Users

   dns-sd is installed by default.

2. A valid ssh key which matches the authorized key loaded in the built image

   The ssh key on your local machine should be loaded. You can check if your key is loaded into the ssh-agent on your host by running:

   ssh-add -l
   Output

   2048 SHA256:abcdef/E1bA+DbVEsw3RoqKEMK9kU /home/powersuser/.ssh/id_rsa (RSA)
   info

   If you are using an image built using Rugpi, the authorized ssh key/s should have been included in the image. If you can't ssh into your device please review the build instructions again to make sure the correct ssh key/s was added during build time.

3. go-c8y-cli

4. go-c8y-cli extension c8y-tedge

Setting up go-c8y-cli

1. Install go-c8y-cli as per the instructions

2. Install the go-c8y-cli extension, c8y-tedge

   c8y extension install thin-edge/c8y-tedge
   tip

   If you have already installed the c8y-tedge go-c8y-cli extension, then make sure it is up-to-date using:

   c8y extension update tedge

3. Create a Cumulocity session file (if one does not already for the Cumulocity instance you wish to connect to)

   c8y sessions create

Procedure

1. Insert the SD Card and power on the device, making sure the ethernet cable is also connected

2. Activate your go-c8y-cli session where you would like to onboard your device to

   set-session

3. Scan for the device using DNS Service Discovery (DNS-SD)

   c8y tedge scan
   Output

   rpi1-b827eb21100e.local
   rpi2-b827ebed6e5a.local
   rpi3-b827ebe1f7d6.local
   rpi4-dcb630486720.local
   rpi5-d83add9a145a.local
   rpizero-b827ebdddb46.local
   rpizero2-d83add030bfd.local
   info

   The device may take a few minutes to start and run the initialization tasks, so be patient.

   If the device is still not connected after 10 minutes, then double check that the ethernet is connected correctly, and that you are in a network which assigns an automatic IP address via DHCP.

4. Bootstrap the image using the detected device in the previous scan

   c8y tedge bootstrap root@rpi5-d83add9a145a.local

5. If you have Wi-Fi on your device, then you can also connect to it so that you can remove the ethernet cable

   The ncmli command can be issued via ssh to configure and connect the device to a given Wi-Fi network:

   ssh root@mydevice.local nmcli device wifi connect "<AP name>" password "<password>"

   Where <AP name> is the Access Point Name (e.g. SSID) of the network, and the <password> is the password required to connect to the access point.