Hardware

Upswift service works on the next processors architectures: x86_64, armv6, armv7 and armv8.
* No support for x86 32bit (contact us for more details).

Software

1. Upswift service works on Linux based operating systems. Therefore, your edge-device must run Linux-based OS (Yocto based, Debian, Ubuntu, etc..)
2. Systemd/SysV (init.d) service manager must be installed.
3. To connect devices running other Operating Systems such as RTOS, Windows CE, Android, please refer to our Agent API

After creating Upswift.io account, Login to the platform. Choose the free Prototyping plan and create a project.
Once you have created your first project, click on the Register Device button at the top of the dashboard page. Copy the Installation command and run it at your device's terminal.

Optional Parameters

1. Device Name - to enter a device name at registration, add the flag '-n=<DEVICE_NAME>' at the end of the registration command.
2. Device Group - to make the device register to a specific group, add the flag '-g=<GROUP_NAME>' at the end of the registration command (the group must exist).
3. Device Software version - to set the device software version at registration, add the flag '-s=<SOFTWARE_VERSION>' at the end of the registration command.

For Example
su -c 'wget -O - "https://dashboard.upswift.io/install_upswift" | bash -s <ACCOUNT_TOKEN> <PROJECT_NAME> -n=<DEVICE_NAME> -g=<GROUP_NAME> -s=<SOFTWARE_VERSION>'

After a few seconds, your device should appear at the Devices category.

How-to register devices in scale

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

1. Register devices by duplicating an existing OS image that has the Upswift Agent installed inside it.
   • Install Upswift agent on 1 device and make sure the device has been registered at Upswift dashboard.
   • Duplicate this device image, and burn it on other SD cards or emmc flashes.
   • Boot a new device with the duplicated image, Upswift agent will automatically recognize that it is running on a new hardware and will register that device as a new device.
2. Register devices by coping Upswift agent to the build of your custom OS (mainly for Yocto, Buildroot, Debian based images).
   1. Copy the Installation command and run it at one of your device's terminal.
   2. Copy the next files/directories to the offline device 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
   3. 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/
   4. Boot a new device

Explanation of the Identification Algorithm

Upswift is capable of registering new devices by duplicating an image which has Upswift agent installed inside it. Upswift device registration algorithm depends on the MAC addresses of the devices. Every device has at least 1 MAC address. There are devices that have several MAC addresses, but at least 1 of them is unique and persistent across reboots. There might be situations when some of the MAC addresses are changing after a reboot. You can find out if this is the situation with your devices by checking your MAC addresses, reboot the device, and check them again.

If you are going to register new devices by duplicating an image, you have to check the checkbox that you are using this method and enter the number of the persistent MAC addresses your devices have at the Account Settings. This will adapt the new devices registration algorithm for your account to work with the type of your devices.

Examples

1. You have 5 devices, all of them have 1 MAC address each. In that case, you will enter the number 1 at the persistent MAC addresses input.
2. You have 5 devices, all of them have 3 MAC addresses each. If so, you have to check how many of those MAC addresses are persistent across reboots. Let's say, 2 of them are persistent (meaning they are not changing when you reboot the device) and 1 of them changes every reboot. In that case, you will enter the number 2 at the persistent MAC addresses input.
3. You have 5 devices, some of them have 3 MAC addresses and others have 2 MAC addresses. In that case, you have to check how many of those MAC addresses are persistent across reboots for both types of devices. Let's say that 1 MAC address is persistent on the devices that have 2 MAC addresses in total, and 2 MAC addresses are persistent on the devices that have 3 MAC addresses in total, then you will enter the lower number of them at the persistent MAC addresses input, which is 1 in this case.

Micro-updates

Micro-updates are application updates. You can update your application's code, install new packages and run bash commands before/after the update is deployed. Usually you would use a Micro-update to deploy a new release of your application or patch a bug on your entire fleet of devices.

• Before deploying a new Micro-update on the Production group, it is recommended to deploy the Micro-update on the Test group first and make sure that everything works as planned.
• When the update's status turns to Success, go back to the "Updates" category, to the recent updates table, find the relevant Micro-update row and click on Deploy to others in order to deploy the same Micro-update on the Production group.

Running commands Before and After

You can choose to run a Bash command or a Bash script before and/or after the Micro-update is deployed on the edge-device. Most bash commands will work, please note the exceptions below.

1. Any command that is requiring user input. If such command is ran, the update will stuck. The solution for that can be to run the next command before your command: DEBIAN_FRONTEND=noninteractive. In any case, it is recommended to check that this solution works with your devices.
2. apt upgrade - Upgrading your device kernel and core packages may result in a bricked device. We strongly not recommend running that command at all.
   In case you decide to run that command, you must run it from the Remote Command using a command. The full command must be: DEBIAN_FRONTEND=noninteractive apt -y update; DEBIAN_FRONTEND=noninteractive apt -y upgrade; reboot

Using Rollback in case of a failure

When creating a new Micro-update, make sure to fill out the "Micro Update Rollback" section as desired. Those settings will be executed when a Micro-update fails for any reason.

Container Updates

Container updates are updates for containers. You can deploy a new release of your container on your entire fleet of devices. Currently, container updates are available only for Docker containers.

Requirements

1. Private or Public repository at https://hub.docker.com/
2. Docker engine must be installed on the Linux device.

Install docker

Upswift container update tool uses the Docker engine as the basis for the container update. Before using Upswift container update, please make sure that the docker engine is installed on the device. To install docker on any type of device architecture run the next command:
curl -fsSL https://get.docker.com | sh

Container update flow

After creating a container update, the following steps will be executed on the edge devices:

1. If private repository, login to Dockerhub using your access token.
2. Pull the container image.
3. Stop any containers that are running using the same repository name.
4. Run a container using the new pulled image.
5. If succeeded running the new container, removing the old container. If an error occurred, re-running the old container(s).
6. If specified, removing the image of the old container(s).

Docker Hub access token

Upswift container update tool uses the Docker Hub access token to pull images from your private repository in order to deploy the container update on your devices. Make sure to create an access token and to provide it when creating the container update at Upswift dashboard.

Follow the next steps to create an access token at the Docker Hub dashboard:

1. Login to your account at https://hub.docker.com/
2. Click on your username at the top right corner.
3. Click on ‘Account Settings’, and move to the ‘Security’ section.
4. Under the ‘Access Tokens’, click on the ‘New Access Token’ button.
5. Enter the description for your access token (for example: ‘Upswift’) and click on the ‘Create’ button.
6. Copy the access token (example of similar token: a0b35e8e-8ebb-49d0-8297-4fa407887e22).
7. Paste the token in the relevant place when creating container update in Upswift dashboard.

Container RollBack

Upswift Agent detects errors while deploying container updates. If an error is detected during the deployment process, it will automatically bring up and re-run the previous container that was running with the same image name.

For example: Before the deployment, a container of the image: test with the tag: v1 was running. We deploy a new release of the same image test, but with a new tag: v2. If during the deployment process an error occurred, Upswift agent will re-run the container with the tag: v1. You will receive a message with the error explained.