Register a Device

Device registration is performed via OctaiPipe’s online interface:

Steps

1. Login: Access the online portal using your credentials.

2. Navigate to Device Management:

   • Select “Device Management” from the main menu.

   • Choose “Devices”.

   • Click on the “Import Devices” button in the top-right corner.

3. Import Devices:

   • Drag your devices CSV file into the designated upload area.

   • Click on the “Import” button to start the registration process.

4. Device validation:

   • If any devices failed to register, an error message will be displayed.

   • To view errors per device, click on export to download a CSV with detailed info.

5. Download docker compose files:

   • Successful device registration will generate docker compose files which provide the configuration to pull and spin up OctaiPipe Edge Client containers on your devices.

   • If all devices can be successfully registered, you will be provided with a zip file containing the docker compose files.

   • Click on the download docker compose files device initialization button.

Device registration CSV format

The device registration CSV must be formatted as follows, note that these are in camel case and case sensitive:

Field	Description	Notes
id	Your unique device id, you should choose this to ensure you can identify your device	Required
description	Further description here can be added here. We recommend being as descriptive as possible.	Optional
os	Operating System of the edge device.	Optional
architecture	Hardware architecture such as AMD or ARM on this edge device.	Optional
influxUrl	If using InfluxDB, provide your InfluxDB URL. If one InfluxDB field is provided then all InfluxDB fields must be provided	Optional
influxToken	Your InfluxDB token	Optional
influxOrg	Your InfluxDB org name	Optional
influxOrgId	Your Influx org id	Optional
grafanaUrl	If usingGrafana deployed by Octaipipe, provide your URL	Optional
timeToOfflineSeconds	The total number of seconds from the devices last update until it’s status is deemed to be offline	Optional

Starting OctaiPipe Edge Client

NOTE: If you are running OctaiPipe in WSL2 on a Windows machine, please see the Windows Configuration section below.

Once you have downloaded the zip file with docker compose files, transfer the docker compose file to the matching device, e.g. the file “device-1-octaipipe.yml” to device-1

You will need to set up an octaipipe user and assign it to the docker group, with correct group ID (1080). This is to limit access by the client to the filesystem of the device in order to enhance security. The following lines of code create the docker group with ID 1080, adds an octaipipe user with user ID 1080 and adds it to the docker group. newgrp docker then implements the changes and the final line gives the docker group ownership of the docker socket, enabling OctaiPipe and other docker users to use the host’s docker engine.

sudo groupadd -o --gid 1080 docker
sudo adduser --disabled-password --uid 1080 --gid 1080 octaipipe
sudo usermod -aG docker octaipipe
newgrp docker
sudo chown -R root:1080 /var/run/docker.sock

If the docker group already exists, you can change the group id with sudo groupmod --gid 1080 docker.

If you face issues running newgrp docker, you can also close and reopen your shell. This line is not necessary to run successfully, but makes sure you get the group changes without having to close and reopen the shell.

To ensure smooth communication between all OctaiPipe services, please create a docker network on each of your devices as well as a docker volume. The docker volume will be named octaipipe_{your_device_id}. When running the code below, replace {your_device_id} with the ID of each device.

sudo docker network create octaipipe
sudo docker volume create octaipipe_{your_device_id}
sudo chown -R 1080:1080 /var/lib/docker/volumes/octaipipe_{your_device_id}

If you are not able to change or set up users or change permissions on your device, you can use our root images, see OctaiPipe Images. This generally not recommended as it gives wider permissions than necessary to the OctaiPipe containers and lowers overall security. If you use root images, you will need to change the mounted volume in the docker compose file from octaipipe:/home/octaipipe/.octaipipe to octaipipe:/root/.octaipipe.

After creating the network and setting up the user, you are ready to start the OctaiPipe Edge Client. Run the following from the same directory containing the docker compose file:

docker compose -f {compose_file_name} up -d

In case you need to see Edge Client logs, run the following:

docker compose logs -f

Finally to stop the OctaiPipe Edge Client, run:

docker-compose -f {compose_file_name} down

Device Groups

Device groups can be used to organize your devices. Device groups can be created and managed in the Portal or via the Python Interface. A device group can contain multiple devices and a device can belong to multiple groups. Deleting a device group does not delete the devices within it.

To create a device group using the Portal, follow these steps:

1. Create a Device Group:

   • Navigate to the “Device management > Devices” page.

   • Select the desired device(s) to add to the group.

   • Click on the “Add to Group” button.

   • Click on the “Create New Group” button.

   • Enter a group name and optional description.

   • Click on the “Create” button.

   • Select the new group from the select list.

   • Click on the “Add” button.

2. Add a device to an existing group:

   • Navigate to the “Device management > Devices” page.

   • Select the desired device(s) to add to the group.

   • Click on the “Add to Group” button.

   • Select the desired group from the select list.

   • Click on the “Add” button.

3. Delete a Device Group:

   • Navigate to the “Device management > Groups” page.

   • Select the desired group.

   • Click on the “Delete” button.

4. Remove a Device from a Device Group:

   • Navigate to the “Device management > Groups” page.

   • Select the desired group.

   • Select the desired device(s) to remove from the group.

   • Click on the “Remove from Group” button.

To create a device group using the Python Interface, follow these steps:

1. Create a Device Group:

   Use the new_group function to create a new device group.

   from devices import new_group
   
   group = {
       "groupName": "example_group",
       "groupDescription": "This is an example group"
   }
   
   new_group(group)
   

2. Add a Device to a Device Group:

   Use the add_device_to_group function to add a device to a group.

   from devices import add_device_to_group
   
   device_id = "device_123"
   group_name = "example_group"
   
   add_device_to_group(device_id, group_name)
   

3. Remove a Device from a Device Group:

   Use the remove_device_from_group function to remove a device from a group.

   from devices import remove_device_from_group
   
   device_id = "device_123"
   group_name = "example_group"
   
   remove_device_from_group(device_id, group_name)
   

4. Delete a Device Group:

   Use the delete_group function to delete a device group.

   from devices import delete_group
   
   group_name = "example_group"
   
   delete_group(group_name)
   

Multiple OctaiPipe devices on one machine

During the experimentation stage, it can sometimes be useful to try out OctaiPipe code and configs without running it on production hardware. When a limited number of devices are available outside of production, it might be useful to simulate multiple devices on a single physical device or Virtual Machine.

From OctaiPipe version 2.3 and forward, it is possible to run multiple OctaiPipe devices on a single machine. This means a single machine will run multiple OctaiPipe edge clients, each showing up as a separate device in the OctaiPipe front end. In this way, a user could for example simulate running Federated Learning on 4-5 devices, while only having access to a single physical device or VM. Note that the number of OctaiPipe devices that can be run on a single machine depends on the resources available on that machine.

To set up multiple devices on a single machine, do the following:

1. Register multiple devices the same way you would if they were on separate machines, following the guide above.

2. You will get a zip folder with multiple docker compose files.

3. Run the docker and device set-up for each OctaiPipe device, i.e. run the following for each OctaiPipe device

sudo docker network create octaipipe
sudo docker volume create octaipipe_{your_device_id}
sudo chown -R 1080:1080 /var/lib/docker/volumes/octaipipe_{your_device_id}

4. Run docker compose up for each of your devices on the same machine

docker-compose -f {compose_file_name} up -d

5. Running docker ps -a should now show multiple edge clients running on the same machine

6. When running OctaiPipe code, such as an FL experiment, each device can now be specified as a separate device in the YAML config

Windows Configuration:

If you are running OctaiPipe on a Windows machine, you will need to use WSL2. WSL2 is a Windows Subsystem for Linux that allows you to run a Linux kernel on Windows. You can follow the guide here to set up WSL2: https://docs.microsoft.com/en-us/windows/wsl/install.

1. Allow editing of the WSL configuration file by running the following command in the WSL terminal:

sudo chmod 755 /etc/wsl.conf

2. Open the WSL configuration file in a text editor:

sudo nano /etc/wsl.conf

3. Add the following lines to the configuration file:

[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
mountFsTab = false

4. Save the file and exit the text editor.

5. Restart the WSL service by running the following command:

wsl --shutdown

6. Restart the WSL terminal.

7. In a windows terminal, run the following command to mount the docker data folder to a drive:

net use w: \\wsl$\docker-desktop-data

8. Mount the docker data folder to the WSL2 file system by running the following command in the WSL terminal:

sudo mkdir /mnt/w
sudo mount -t drvfs W: /mnt/w -o uid=1080,gid=1080,umask=22,fmask=11
sudo mkdir /w
sudo mount --bind /mnt/w /w

9. Update the fstab file to automount the drive by running the following command in the WSL terminal:

echo "W: /mnt/w drvfs rw,uid=1080,gid=1080,umask=22,fmask=11 0 0" | sudo tee -a /etc/fstab
echo "/mnt/w /w none bind" | sudo tee -a /etc/fstab

10. Register the devices as described above and then create the required volume for each device:

sudo docker network create octaipipe
sudo docker volume create octaipipe_{your_device_id}

4. Run docker compose up for each of your devices on the same machine

docker compose -f {compose_file_name} up -d

NOTE: If you are running the root image rather than the octaipipe user image, you will need to remove the change-vol-ownership service, the depends-on reference to it and the line specifying the user in the downloaded docker compose files.