Platform Components

Last updated: February 9th, 2020

Project Parameters

Each project has 2 important parameters that will determine when and how your edge devices 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

Device communication cycle is the interval time (seconds) which the edge devices are sending a "keepalive" signal to Upswift servers. Those keepalive packets are responsible for the next tools:

  1. Sending keep-alive status that will keep the device online at Upswift dashboard.
  2. Checking if a new Micro-update is pending.​
  3. Checking if a new Remote connection is pending.​
  4. Checking if a new Command is pending to be executed on the device.​
  5. Checking for changes of project parameters (if any of the communication cycle parameters have been changed).​

This parameter is set by default to 10 seconds. You can change it as needed, although we recommend to set it as low as possible.

  • Each communication cycle takes approximately 5KB of data.

Logs communication cycle

Logs communication cycle is the interval time between log files that are sent from the edge device to Upswift servers.

  • Refer to Application logs section below to understand how to send log files from your edge devices to Upswift servers.
  • Paying customers can set the Logs communication cycle timeout to as low as once per minute.

Application Logs

Upswift service let you send your application logs from your edge devices to the dashboard. When sending log files, they will appear at the Logs category under your devices. You can view the logs content at the dashboard or you can also download those files.

To send logs files, you have to move the relevant files to the specified directory: /lib/upswift/logs/.

  • Logs files should be only text files.
  • Keep in mind that those files will stay in the directory and won't be deleted by the Upswift service after each send.
  • After moving the relevant files to the logs directory, we recommend overwriting the existing files.
  • You can control the frequent interval between each send by changing the Logs communication cycle parameter under your project parameters

Diagnostics - Application alerts

Send Alert

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

If Send email on alert is set (you can find it under Diagnostics -> Application category), you will receive an email every time an alert is triggered.

To send an alert from your edge device, your application will need to send a POST request to our API servers.

URL: https://api.upswift.io/v1/send_app_alert

You must send a POST request with the following parameters:

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • application_alert_message - Required - String - This is the message you want to send.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
    • The value of the message parameter is a JSON with the key: application_alert_id. Save that ID, as when you would like to finish the alert from your application, you will have to send another POST request with that ID (see below).
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.


Finish Alert

To finish an Alert from within the application, you have to send a POST request to the following url:

URL: https://api.upswift.io/v1/finish_app_alert

You must send a POST request with the following parameters:
  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Required - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • application_alert_id - Required - Integer - This is the alert ID that you have received from the https://api.upswift.io/v1/send_app_alert call.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.

Application Monitor

Depending on your application, there may be situations when you would like to monitor and receive a real-time view of specific parameters from your edge device application (like data from sensors). The Application Monitor tool let you send metrics which you will be able to view under the Application Monitor category.

JSON file

To send application parameters from your edge device using a JSON file, your application will need to modify 1-5 parameters under Upswift's configuration JSON file. That configuration file is placed at the directory: /lib/upswift/ and its name is config.json.
Then you will have to set a Name for each of those parameter at the dashboard under the Application Monitor category.

  • To send a parameter value - change the string parameter app_X(1-5) value to text/number that you would like to receive at the dashboard. example: {"app_1": "17%"} - The device battery level.
  • It is possible to set up to 5 parameters values at the same time.
  • By default, the parameters app_1, app_2, app_3, app_4, app_5 value is empty.
  • The agent will send the values to Upswift servers every 30 seconds.

REST API

To send application parameters from your edge device using a REST API, your application will need to send appropriate POST requests to our API server.

URL: https://api.upswift.io/v1/change_app_parameter

You must send a POST request with the following parameters:

  • user_token - Required - String - This is your account token. You can find it under Account category at the dashboard.
  • device_token - Optional (if device_id is used) - String - This is your device token. You can find it on each device after the device has been successfully registered to the platform inside the file: /etc/upswift/service/settings.json.
  • device_id - Optional (if device_token is used) - Integer - This is your device ID. You can find it at the Devices category in the dashboard.
  • app_parameter_name - Required - String - The name of the application parameter. This parameter must exist at the App Monitor category in the dashboard.
  • app_parameter_value - Required - String - The value you want to send to the dashboard.

  • You can send the POST request up to 3 times per minute (once in every 20 seconds).
  • If you are duplicating an OS image and using that image to register a fleet of devices, please make sure to pull the device_token parameter from the JSON file only after your new device has been successfully registered to the platform.

Response

The response will include a JSON with the key message for success and error_message for any error.
  1. Success - status code is 200
  2. Error
    • status code 400 - Check the error_message key.
    • status code 429 - You have reached the limit of post requests per minute.