Connecting devices at scale

How to register devices at scale

Upswift agent automatically recognizes new hardware based on the MAC addresses of the device. The next 2 methods can help you install Upswift on a fleet of devices easily without the need to register each device separately.

Option A Register devices by duplicating an existing OS image that has the Upswift Agent installed inside it.

  1. Install Upswift agent on a single device and make sure the device has been registered at Upswift dashboard.

  2. Disconnect the device from the internet, and follow the next steps on the device terminal:

    1. Open and edit the file '/etc/upswift/service/settings.json'.

    2. Remove the value of the parameter 'device_token'.

    3. Save the file.

    4. Don't connect the device to the internet until duplicating the image.

  3. Duplicate this device image, and burn it on other SD cards or eMMC flashes.

  4. Boot a new device with the duplicated image, Upswift agent will automatically recognize that it is running on new hardware and will register that device as a new device.

Option B Register devices by copying Upswift agent to the build of your custom OS (mainly for Yocto, Buildroot, Debian based images).

  1. Copy the Installation command and run it on one of your device's terminal.

  2. After the installation complete successfully, make sure the device exists in Upswift platform dashboard.

  3. From the registered device, copy the next files and directories to OS build file-system:

    1. /etc/upswift

    2. Depends if you have Systemd or SysV For Systemd:

      • /etc/systemd/system/upswift.service

      For SysV:

      • /etc/init.d/upswift

      • /etc/crontab

  4. Open and edit the copied file - /etc/upswift/service/settings.json

    1. Remove the value of the parameter 'device_token'.

    2. Save the file.

  5. Paste those files at the same paths on the build of the OS file-system. *In case of using Systemd, please also paste upswift.service in:

    • /etc/systemd/system/multi-user.target.wants/

  6. Build the OS image and burn it on your device's flash.

Set custom device name and group automatically at scale

Option A The device name ad group can be changed using Upswift REST API - change devices details.

By using Upswift REST API, the device can run a script to change the name and group after device registration.

Option B After adding Upswift agent to the file-system image, we might want to add 'Device name' and 'Group' to each of the devices that are registering along the way.

To set a custom name and group for each deployed device, will be needed to run a script on the device boot that pulls device name based on your requirement - MAC, serial id, anything else, and pushing it to Upswift agent settings JSON file -/etc/upswift/service/settings.json to the value of the parameter "device_name" and the same method to set "device_group". By default, if no device name or group have been defined, Upswift will register the device with a generic name - "New device" to group "Production".

Explanation of Upswift device registration identification algorithm

By default, Upswift is capable of registering new devices by duplicating an image that has Upswift agent installed inside it. Upswift device registration algorithm depends on the MAC addresses of the devices.

There are devices that have several MAC addresses, but at least 1 of them is unique and persistent across reboots. Using this method, Upswift will automatically recognize new devices that registered using a copied image.