Let's Talk.

  • Upswift Twitter
  • Facebook

Upswift©2019

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.

 

In case of a problem:

Install UpSwift

  • Register

  • 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>'

  • You should see your new device registered under "devices" page in the dashboard.

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

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

  • Make sure you are running the command as a root user.

  • Make sure the user-token is correct.

Installation process

 

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

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