Quick Start

Last updated: February 9th, 2020

Requirements

Hardware

Upswift service works on the next processors architectures: x64, x86, armv6, armv7 and armv8.

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.

Register device

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.

Installation command example

su -c 'wget -O - "https://dashboard.upswift.io/install_upswift" | bash -s <ACCOUNT_TOKEN> <PROJECT_NAME>'

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.

If you don't see your device:
  1. Check your internet connection.
  2. Make sure "systemd" or "SysV" is installed.
  3. If you are using SysV, make sure the systemd directory doesn't exist: /etc/systemd/system.
  4. Make sure the user_token and the project_name are correct.
  5. You run the installation command as a root user.
  6. Check the Troubleshooting section for common issues and fixes.
How to register a device in 60 seconds

Register devices in scale

Registering new devices by duplicating image

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.

Working Convention

Deploying Micro-update

  • 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 "Micro-Updates" page, to the recent Micro-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 Control Center 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.