Upswift REST API - Triggering Updates

This guide explains how to control the update trigger from the device to stop or start deployments of updates using Upswift REST API, Including ready-to-use Python scripts.

Time to read:

3

minutes

Upswift device management platform can be used to deploy OTA updates on your Linux edge devices. However, executing an update routine on an edge device must need to be carried out cautiously to minimize the disturbance and downtime that can be caused by the update process. This can be done by 2 methods:

  • Manually - Update edge devices when they are idling
  • Automatically - Use the edge device to request for updates from the platform when it’s idling

Typically, since there can be many devices performing different tasks, it can be challenging to monitor the device’s usage just to push an update. Therefore, it’d be an elegant solution to add a small REST API call within the program that runs on a Linux device that can inform the dashboard of its availability to receive an update.

Upswift’s update trigger API call allows you to take the advantage of such a mechanism, which you may use to simply inform the dashboard whether it’s ready to receive an update or not. This API call is an HTTP POST request, of which the payload should be of JSON format.

For simplicity, the script is written in Python and the prerequisite modules are json and requests. These are by default installed with every Python installation, and the scripts are cross-platform compatible.

Step 1 - Python script template for changing the update trigger

The Device Token is unique per device and each device receives one upon first enrollment/registration, and can be found at /etc/upswift/service/settings.json file on each device. The next python script includes an automatic function to pull the Device Token and the User Token that will be used to change the update trigger using an API call.


Create a new file using nano <filename>.py and type in the script, and update the details accordingly. Then, press Ctrl+O and press Enter to confirm save.

import json
import requests

UPSWIFT_SETTINGS_FILE = '/etc/upswift/service/settings.json'

#Pull Upswift tokens
with open(UPSWIFT_SETTINGS_FILE) as json_file:
   data = json.load(json_file)

#Upswift tokens
user_token = data['user_token']
device_token = data['device_token']

json_content = {'user_token': user_token,
            	'device_token': device_token,
            	'trigger_set': True}

call_request = requests.post("https://api.upswift.io/v1/set_update_trigger", json=json_content)
call_response = json.loads(call_request.text)

if call_request.status_code != 200:
	if call_request.status_code == 429:
    	error = "API limit reached"
	else:
    	error = call_response["error_message"]
	print(error)
else:
	print("Update trigger status successfully updated.")

Step 2 - Execute the script and verify the functionality


Type in the command python <filename>.py, and press Enter. (in the following example, the file has been saved as upswift_device_update_trigger.py)

Step 3 - Changing the update trigger availability

By changing the trigger_set JSON key’s value to True/False in the script in Step 2 and re-running the script, the device’s availability to receive updates can easily be changed on the dashboard. If the trigger_set has been set to True and the script is executed, Upswift will defer any future updates until the trigger_set flag has been set to False by a future execution of the script.


Although this example has been written in Python for clarity, basically any programming language that supports HTTP POST requests should be able to call these APIs with the required JSON format payload and perform the same task.


For more information on the Upswift Change Device Details API, please feel free to refer to the official documentation.