Device Scripting

Overview

remote.it wants to make your life easier as a product creator and one of the tools we've developed to do that is called "Device Scripting".

In essence, Device Scripting allows you to run a script (written in any language you have installed on your Operating System) on any number of devices and then sit back and watch it run.

This is a quite powerful feature and takes away a lot of the drudgery involved in managing thousands of devices in the field.

Q: When should you use a script?

A: When you have a repetitive action that you would like to perform on one or more devices.

In this article, we will be going over:

  1. Creating Scripts
  2. Use cases
  3. Uploading a Device Script to your account
  4. Executing a Script on your Devices
  5. Job Status
  6. Cancelling a Job
  7. Detailed Scripting example
  8. Tips and Tricks
  9. Show Device status
  10. Send a file to your Device
  11. Upload the Script to your account
  12. Editing Script files in Windows
  13. Reboot your Device

 

1. Creating Scripts

remote.it allows you to write Device Scripts in any language your host operating system supports because the script is run just like any other executable script on your machine. This means you can write in bash, Python, Ruby, Node, etc., assuming you have these installed globally on your system.

Watch the video below to see how Device Scripting works:

Here's a webinar that provides an introduction to scripts in remote.it:

 

2. Use cases

Below are just some of the possible use cases for Device Scripting

  • Trigger an update of all your devices or a subset of them
  • Turn off a device, perhaps using PoE (Power over Ethernet) or some other method
  • Trigger your device to reboot or shutdown

As the product creator, the possibilities are endless with Device Scripting.

If you've come up with an interesting use case for running Device Scripts, we'd love to hear about it!

 

3. Uploading a Device Script to your account

You upload and manage Device Scripts in your account for use at any time.

Start by using the sample script in the first example, which you can find using the link below.

show-device-info.sh

Select "Scripting" from the menu:

wp_21.png

Next, click on "Upload".

wp_22.png

In the "Storage Upload" dialog, use "Choose File" to locate the script file you've downloaded or written.

Make sure that "Executable script or program" is selected, then click on "Upload".

wp_23.png

When the upload completes, you'll see this notification:

wp_24.png

Note:

Existing scripts will be overwritten without any warning.

The "Storage Upload" dialog will stay open until you click on "Cancel" to make it easier to upload multiple scripts.

 

4. Executing a Script on your Devices

On the "Devices" page, select the group of Devices that you wish to run a script on.

wp_25.png

In the "Actions" menu, choose "Execute Script".

wp_26.png

The "Bulk Execution" dialog lets you selected the desired script.

wp_27.png

After selecting the script you want to run, click on "Next".

If you have selected fewer than 10 Devices, you will now see a dialog that lets you choose to update the status columns during job execution.

wp_28.png
  • If you do select this option, the Status Columns will update as messages arrive from your script, however you will not be able to select any other devices until this process has completed.
  • If you don't select this option, status updates may be delayed slightly.

If your script uses commands to update the status columns, make sure that "Show Advanced Columns" is selected:

wp_29.png

As the script is executed on your group of Devices, it will fill in the Status cells as it proceeds.

wp_30.png

 

5. Job Status

The Scripting page shows you the execution status of Device Scripts.

wp_31.png

In the Job Status table you will see:

  • The Script name
  • Its overall status - one of new, running, done, or failed
  • Report status
  • Date and time the Script was started
  • Date and time the most recent update was received from any Device
  • Actions - a trash can so you can delete a completed Job, or a square that lets you cancel a Job which is still running
  • The number of Devices in the Job
  • The number of "Failure" messages received
 
wp_32.png

It is important to understand that on the average it takes 3 minutes for Job Status to update. So your script may actually complete and update the Status cells before the Job Status catches up. It should respond and update within 3 to 4 minutes.

 

6. Cancelling a Job

The most common reason for cancelling a job is that one of the tasks within the job has failed to complete, which will keep this job from being reported as "done" in the table on the "Scripting" page.

If your Job stays in the "running" state longer than you expect, you can check on the status of individual devices by clicking on the highlighted "running" link:

wp_33.png

Now you will see a dialog showing the detailed status of the script on each Device.

wp_34.png

The Status is "done" on all Devices in this example except for the "Liverock-Bulk-03" Device. In this example demonstrating a script failure, the "Liverock-Bulk-03" Device uses a different OS than all the others and it is missing a utility that the script depends on.

To cancel this Job, close the "Job Details" dialog, then click on the red circled "x" under "Actions".

wp_35.png
wp_36.png

Confirm that you wish to cancel, then click on "Submit".

The status will initially show as "Cancelling" and finally "Failed".

 

7. Detailed Scripting example

A simple example showing strategies for developing your own scripts
 

Most users of remote.it start by installing a remote.it Service for SSH. With an SSH connection you can really do "anything" possible on your device as long as you have the login password (and in some cases, a separate root password).

Let's suppose that you tend to run the following commands at the console to check various aspects of your device's operation.

  • df - report free disk space
  • uname - report information about the OS
  • ps ax - show all running processes
  • uptime - shows the amount of time since the device rebooted
  • dpkg - show the version of an installed Debian package

In each case, I use the following expression format to assign the output of a command to a shell variable:

diskfree="$(df)"

Then, I send the value of the variable to a log file on the device, so if needed, I have some traces of what the script actually did.

echo "$diskfree" >> $0.log

Finally, I report this value to the "Status A" cell.

Status a "$diskfree"

Notice that "Status" is actually a function declared earlier in this script. You should include this (and the other declared variables) in each of your scripts to make readability better.

TOOL_DIR="/usr/bin"
NOTIFIER="connectd_task_notify"
JobId="$1"
API="$2"

Status()
{
ret=$(${TOOL_DIR}/$NOTIFIER "$1" "$JobId" "$API" "$2")
}

The following script performs those functions and reports the results back to the 5 Status Columns in the "View Devices" mode.

Get-Pi-Status-basic.sh

You will notice that when you upload and run this script, some of the status columns get quite filled with data, not all of which may be interesting. This may be OK for one or a small number of devices, but it can become unmanageable with a large number of devices.

The following script introduces additional shell commands to filter the results down to a manageable state.

Get-Pi-Status-filtered.sh

This article does not seek to teach you how to write these expressions using shell language. You should understand that while you can return multi-line status responses, it may be helpful to filter some of the command output to make the results more readable and meaningful.

 

8. Tips and Tricks for developing scripts

General

  • Only the “Bulk Service” is required to run scripts.
  • Scripts may operate differently on different versions of the operating system or different devices
  • Scripts are only supported currently on Linux devices
  • Scripts execute as root user – so “sudo” is not needed and you can mess things up if you are not careful!

Writing scripts

  • Start with the supplied examples
  • Scripts MUST end with either “Status 1 OK” (success) or “Status 2 Failed” (failure) commands. Without one of these, tasks and jobs will never get to the "completed" state.
  • You can clear a status cell in your scripts by executing, e.g. “Status a '' “ (that is two single quotes without anything in between following the letter "a").
  • Learn how to use Linux utilities like “grep”, “awk” and “sed” to trim the information you want to display
  • Test script fragments at the console first

Debugging scripts

  • Scripts download to and execute from the /tmp folder.
  • Install and connect to a remote.it SSH service
  • Write frequently to a log file which you can review at the console
  • Send intermediate results to a status cell

Job Status

  • One task (a script running on a device) which does not complete keeps the Job in the “Running” state.
  • Cancel Jobs which you suspect have not completed, then debug.
  • Canceling a Job does not “undo” the action of the script.
  • Job status can take several minutes to update, so be patient

 

9. Show Device status

Easily display the results of up to 5 console commands.

This script returns the following info into status columns A through E:

  • Operating System name
  • Linux Version (uname -a command)
  • Uptime (time since last reboot)
  • Number of installed remote.it Services
  • Version of of the installed connectd or remoteit package
wp_37.png

Download the attached file to your PC, then upload it to remote.it:

Script returns status from any Linux based device

If you are on Windows, editing this file in Notepad will cause issues because the line feeds are not compatible with your Pi's Linux OS. We suggest you use a Linux compatible text editor for Windows such as Notepad++.

In the script, the /usr/bin/connectd_task_notify script is used to report various interesting bits of info about your systems. /usr/bin/connectd_task_notify is installed when you install the remoteit or connectd packages. The variables TOOL_DIR and NOTIFIER are used for this purpose.

TOOL_DIR="/usr/bin" 
NOTIFIER="connectd_task_notify"

For example, the OS Name is reported in Status column A.

# Update status column A (StatusA) in remote.it portal
#-------------------------------------------------
# retrieve the os ID as reported by the command “cat /etc/os-release”
os=$(cat /etc/os-release | grep -w ID | awk -F "=" '{print $2 }')
# send to status column a in remot3.it portal
ret=$(${TOOL_DIR}/$NOTIFIER a $1 $2 $os)
#------------------------------------------------- You MUST use the final line:
ret=$(${TOOL_DIR}/$NOTIFIER 1 $1 $2 "Job complete")

This tells the Job Server that your script has completed its task. It may take several minutes for the Job Status to fully update and clear, even after running a script which by itself completes rapidly.

 

10. Send a file to your device

Select a file which you have uploaded to storage to send to one or more devices.

Here is a script which lets you pick a file from your storage area, which is then downloaded by your device. After that, it reports the file size and MD5 checksum in the status columns. This is a trivial example and we expect that you will add your own actions to perform upon the file if needed.

 

11. Upload the script to your account

Download the attached file to your system, then upload it to remote.it:

Send-File-Sample.sh

Upload the file you wish to send to your device as you uploaded the script, but selecting "General Purpose Content" in the dialog.

Run the script and select the file you wish to transfer, then click on "Finish".

wp_38.png

Once the process completes, you will see the file name, size, and MD5 checksum as reported from the target Device(s):

wp_39.png

 

12. Editing Script files in Windows

If you are on Windows, editing scripts in Notepad will cause issues because the line feeds are not compatible with your Device's Linux OS. We suggest you use a Linux compatible text editor for Windows such as Notepad++.

In Notepad++, make sure EOL encoding is set to UNIX (LF):

wp_40.png

 

13. Reboot your Device

This scripts demonstrates passing information through a reboot.

It's simple enough to write a script that just reboots your device. It's a little more work to make sure that the status confirms the reboot when it is done. The attached script demonstrates writing some information about the bulk job prior to rebooting.

Device-reboot.sh

This script uses "cron" to run the second half of the script after rebooting, so you'll need to have the cron utility installed.

This script adds a line to your crontab to execute the part of the script that reports that the script completed. The script that runs after rebooting also removes the crontab reference so that it runs only once.

When the rebooting process starts, you should see:

wp_41.png

When it has completed, you should see:

wp_42.png

This can take several minutes to complete.

Was this article helpful?
0 out of 0 found this helpful