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.

Import devices interface
  1. Import Devices:

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

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

  2. 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.

Import device failures
  1. 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.

Import devices success

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

deviceId

Your unique device id, you should choose this to ensure you can identify your device

Required

deviceDescription

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

Starting OctaiPipe Edge Client#

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.

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.

NOTE: As of OctaiPipe version 2.3, running OctaiPipe thourhg WSL on a Windows machine does not support running octaipipe user images. Only root images can be run.

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

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}
  1. Run docker compose up for each of your devices on the same machine

docker-compose -f {compose_file_name} up -d
  1. Running docker ps -a should now show multiple edge clients running on the same machine

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