Industries

Platform

Upswift©2020

Company

imgFlasher

Let's Talk.

  • Upswift Twitter
  • Facebook

Developer

UPSWIFT Documentation

Getting started

Getting Started

 

Requirements

Edge device

​This specification defines the minimum hardware and software requirements necessary to install UpSwift service on a new edge device.
 

Software

  • UpSwift service works on Linux based operating systems. Therefore, your edge-device must run Linux based OS (Yocto based, Debian, Ubuntu, etc..)

  • apt Package manager and Systemd / SysV (init.d) service manager must be installed.

* if you are using SysV, make sure systemd directory path '/etc/systemd/system' doesn't exist.

Hardware

  • UpSwift service works on a list of common processors architecture: x64, x86, armv6, armv7 and armv8.

 

Registering new devices by duplicating image

Install UPSWIFT

  • Register Upswift account

  • Copy and Run the command from the Register Device Section:
    su -c 'wget -O - "https://dashboard.upswift.io/install_upswift" | bash -s <user-token> <project-name>'

  • Optionally, it is possible to add additional device details at registration:

    • su ... | bash -s <user-token> <project-name> -n=<device-name> -g=<device-group> -s=<software-version>'

  • Note - if you set the device group, that group must exist.

  • You should see your new device registered under "Devices" category in the dashboard.

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.

If you need help with this topic, please contact our support team to assist you.

Installation process

 

In case of a problem:

  • Make sure "systemd" or "SysV" is installed.

  • If you are using SysV, make sure the systemd directory doesn't exist: '/etc/systemd/system'.

  • Run the installation command as a root user.

  • Make sure the user-token/project name is correct.

Deploying Micro-update

Working Convention

  • 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 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 "Devices Applied To" in order to deploy the same Micro-update on the "Production" group. 

Using "Rollback" in case of 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.

Running command Before & After

  • You can choose to run a Bash command before and/or after the Micro-update is deployed on the edge-device.

  • Any Bash command will work.

    • For example:

      • mkdir /home/my_new_dir​

      • touch /home/my_new_file

  • In most cases, the best way to use the command function is to stop and start an app service before and after deploying the Micro-update.​

    • For example:

      • Fill in the "Before command" input: systemctl stop my_app

      • Fill in the "After command" input: systemctl restart my_app

Troubleshooting

  • Make sure openssh-server is installed, or install it by running 'apt-get -y install openssh-server'

  • Make sure network port 80 is OPEN in the device firewall or on the Router (OUTPUT table) when opening a remote control session.

  • Make sure DNS nameserver 8.8.8.8 exists or Add it using the command: echo "nameserver 8.8.8.8" >> /etc/resolv.conf

  • In case the device firewall on DROP mode, please run the next commands to allow Upswift agent using iptables:

iptables -I INPUT 1 -i lo -j ACCEPT

iptables -A INPUT -s 127.0.0.1 -p tcp --sport 442 -j ACCEPT
iptables -A INPUT -s 127.0.0.1 -p tcp --dport 442 -j ACCEPT
iptables -A OUTPUT -s 127.0.0.1 -p tcp --sport 442 -j ACCEPT
iptables -A OUTPUT -s 127.0.0.1 -p tcp --dport 442 -j ACCEPT
iptables -A OUTPUT -p tcp -d api.upswift.io --dport 80 -j ACCEPT
iptables -A OUTPUT -p tcp -d api.upswift.io --dport 443 -j ACCEPT
iptables -A OUTPUT -p tcp -d remote.upswift.io --dport 80 -j ACCEPT
iptables -A OUTPUT -p tcp -d remote.upswift.io --dport 443 -j ACCEPT
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

Installing Upswift agent returns "http/1.1 400 bad request"

  • Upswift installation requires an updated "wget" or "Busybox" (from 2015 and above).

    • To upgrade "Busybox", please ​download the binary and replace with the old binary or contact us at contact@upswift.io for technical installation support.

    • To upgrade "wget", please run the command below: ​

      • apt-get -y update​

      • apt-get -y wget

Remote control tool doesn’t work

 
  • Add '--no-check-certificate' after 'wget' inside the installation command:
    "wget --no-check-certificate -O - "https://dashboard.upswift.io/install_upswift"....

Installing Upswift agent - cannot verify dashboard.upswift.io's certificate

Installing Upswift agent on CentOS/Red Hat - SELinux permission issue

  • Upswift agent can’t work properly with SElinux enabled, to fix the issue, please create a rule to allow systemd upswift_manager service, or disable SELinux using the next commands:

    • ​vim /etc/selinux/config (edit SELinux config file)

    • ​Edit and save -  'SELINUX' parameter from 'enforcing' to 'disabled' (disable SELinux system)

    • reboot (reboot the device)

Installing package with 'apt-get' which requires interactive screen

  • Please install the specific package using bash command through "Execute before/after update", by running the next command:

    • ​DEBIAN_FRONTEND=noninteractive apt-get -y install <package name>

Developer

 

Update trigger

Depending on your application workflow, there may be situations where you would not like to deploy a Micro-update on your edge device. The "Update trigger" let you choose when to deploy a pending Micro-update and to check if an update is currently in progress. Monitor a JSON file to check whether a Micro-update is in progress and change the parameters to let the UpSwift service know when to deploy a pending Micro-update.

 

Using this method will help you keep a minimal downtime for your application without disturbing the main application flow.
 

Changing method:

  • Under the path "/lib/upswift/edit the file "config.json":

    • Stop getting updates - change the boolean parameter "ready_to_update" value to false .

    • Start getting updates - change the boolean parameter "ready_to_update" value to true .
       

  • The parameter "update_status" will change automatically when a Micro-update is in a process to one of the following values:

    • "error" - ​the Micro-update finished with a failed status.

    • "in_progress" - the Micro-update is in the middle of the deploying process. 

    • "done" - the update finished successfully. 
       

  • By default, the parameter "ready_to_update" value is set to true .

Examples:

  • Stop getting updates:
     

  • Start getting updates:

 

Device cycles

Each project includes 2 important parameters that will determine when and how the edge device will communicate with UpSwift servers. Those parameters should be set after considering the data network usage that is suitable for the current project.
 

Device communication cycle:

  • Sending keep-alive status that will keep the device online on UpSwift dashboard.

  • Checking for a new Micro-update.​

  • Checking for a new Remote connection.

  • Checking for changes on project parameters.


Log files cycle:

  • Time between log files that are sent from the edge device to the UpSwift servers.

 

Sending application logs

UpSwift service let you pull your application logs from the edge device to the "logs" category under devices.

Using this method will help you to continuously monitor your application status easily.
 

Adding method:

  • Under the path "/lib/upswift/logs/" on the edge device put any relevant text files you would like to pull.
    Keep in mind that those files will stay in the directory and won't be deleted by the UpSwift service after each pull.

  • After adding relevant files to the logs directory, we recommend overwriting the existing files.

  • Control logs cycle frequent by changing the "Logs cycle" parameter under "project parameters"
     

 

Diagnostics - Application alerts

Depending on your application error/alert handling, there may be situations where you would like to get notice if an error occurred in your application on the edge device. The "Application alert" tool let you set error alerts which you will be able to view under 'Diagnostics' category.

If 'Email alert notification' is set (you can find it under 'Account' category), you will receive an email every time an alert is triggered.
 

To send an alert from the edge-device, your application will need to modify 2 parameters under UpSwift's configuration JSON file.

 

Using this method, will help you find out when an error occurred in one of your edge devices instantly. 

Changing method:

  • Under the path "/lib/upswift/edit the file "config.json":

    • To ​send a new alert - change the boolean parameter "alert_detected" value to true.

    • To set an alert message - change the string parameter "alert_message" value to any text message that you would like to receive (example: "Bluetooth disconnected").

    • To finish the alert - change the boolean parameter "alert_detected" value to false.
       

  • By default, the parameter "alert_detected" value is set to false.

Examples:

Sending an alert:

Finish current alert:

Application Monitor

Depending on your application, there may be situations where you would like to monitor and get a real-time view of parameters from your edge device application. The "Application Monitor" tool let you set application parameters which you will be able to view under 'Application Monitor' category.

If 'Email alert notification' is set (you can find it under 'Account' category), you will receive an email every time an alert is triggered.
 

To send an application output parameters from the edge-device, your application will need to modify 1-5 parameters under UpSwift's configuration JSON file. Then you will have to set meaning for each parameter under the 'Application Monitor' category.

 

Using this method, will help you find out what is the current state of the device important outputs from sensors/application.

Changing method:

  • Under the path "/lib/upswift/edit the file "config.json":

    • To set an application output - change the string parameter "app_X" (1-5) value to any text/number message that you would like to receive. example: {"app_1": "17%"} - The device battery level.

    • It is possible to set, up to 5 application outputs at any given moment.
       

  • By default, the parameters "app_1", "app_2", "app_3", "app_4", "app_5"  value is empty.

Examples:

Sending an application outputs:

set application outputs meaning at the dashboard :

app_1 = battery level

app_2 = button state

app_3 = motor cycles

app_4 = mode

app_5 = green led