Configuring Adapters

Overview

Once an adapter has been created in the ClearBlade Platform, shell commands or scripts need to be specified on the Config tab within adapter settings so that the adapter can be correctly administered. The currently supported commands are:

  • Deploy Command - A command or shell script that will be run after the files are installed on a ClearBlade Edge
  • Start-up Command - A command or shell script that will be executed to start the adapter on a ClearBlade Edge
  • Stop Command - A command or shell script that will be run to stop the adapter on a ClearBlade Edge
  • Status Command - A command or shell script that will be run to determine the status of the adapter on a specific ClearBlade Edge
  • Undeploy Command - A command or shell script that will be run to uninstall the adapter from a ClearBlade Edge
  • Logs Command - A command or shell script that will be used to retrieve any logs printed out by the adapter while it is

Note

Commands specified in the Config tab of the adapter settings dialog are executed from the directory where the Edge was started. Any adapter configuration commands and shell scripts need to account for this.

The commands contained on the Config tab of the adapter settings dialog are described in this document.

Deploy Command

When an adapter is deployed, any files specified in the Files tab of the adapter settings dialog will be copied to the directory where ClearBlade Edge was started. The deploy command, therefore, is optional. In order to prevent naming collisions resulting in overwritten files, it is recommended that an adapters files be copied to an adapter specific directory. The files can be copied using either a shell command or a shell script.

Note

If using a shell script to accomplish tasks needed for deployment, the shell script must be included as one of the adapter files in the Files tab of the adapter settings.

A best practice would be to provide an archive/zip file containing all the files required to execute and manage an adapter. The deploy command would the simply be a shell command to extract the contents of the archive, for example:

tar -xvzf MyAdapter.tar.gz -C /MyAdapter

A sample shell script, named deploy.sh is as follows:

#!/bin/bash
mkdir ShowTimeAdapter

mv start.sh ShowTimeAdapter
mv stop.sh ShowTimeAdapter
mv status.sh ShowTimeAdapter
mv deploy.sh ShowTimeAdapter
mv undeploy.sh ShowTimeAdapter
mv showTime ShowTimeAdapter

echo "ShowTimeAdapter Deployed"

In the Config tab of the adapter settings dialog, the deploy command specified to execute the deploy.sh shell script would be

./deploy.sh

Start-up Command

After an adapter has been deployed, it must be started on the Edge where it was deployed. The Start-up Command provides the mechanism that allows the ClearBlade Platform to start an adapter on ClearBlade Edge. The start-up command is a required command. If a start-up command is not specified on the Config tab of the adapter settings dialog, the adapter would need to be manually started by connecting to the gateway device (via ssh) and issuing an appropriate start command.

Note

If using a shell script to accomplish tasks needed for starting the adapter, the shell script must be included as one of the adapter files in the Files tab of the adapter settings.

A sample shell script, named start.sh is as follows:

#!/bin/bash
nohup ./ShowTimeAdapter/showTime > ./ShowTimeAdapter/showTime.log 2>&1 &

In the Config tab of the adapter settings, the start-up command specified to execute the start.sh shell script would be

./ShowTimeAdapter/start.sh

Note that the command takes into account the fact that the deploy script copied the start.sh file to a directory named ShowTimeAdapter. Since the shell script only contains one line, we easily could have specified the value of Start-up Command as

nohup ./ShowTimeAdapter/showTime > ./ShowTimeAdapter/showTime.log 2>&1 &

Stop Command

After an adapter is started, there may be a need to stop it occasionally. The Stop Command provides the mechanism that allows the ClearBlade Platform to stop an adapter running on ClearBlade Edge. The stop command is an optional command. If the Stop Command is not specified on the Config tab of the adapter settings dialog, the adapter would need to be manually stopped by connecting to the gateway device (via ssh) and issuing an appropriate stop command.

The stop command will most likely be a command that kills the adapter process, such as

ps -ef | grep showTime | grep -v grep | awk '{print $2}' | xargs kill

If a more sophisticated shutdown of the adapter is needed, shutdown logic can be incorporated into a shell script.

Note

If using a shell script to accomplish tasks needed for stopping the adapter, the shell script must be included as one of the adapter files in the Files tab of the adapter settings.

A sample shell script, named stop.sh is as follows:

#!/bin/bash
ps -ef | grep showTime | grep -v grep | awk '{print $2}' | xargs kill

In the Config tab of the adapter settings, the stop command specified to execute the stop.sh shell script would be

./ShowTimeAdapter/stop.sh

Note that the command takes into account the fact that the deploy script copied the stop.sh file to a directory named ShowTimeAdapter. Since the shell script only contains one line, we easily could have specified the value of Stop Command as

ps -ef | grep showTime | grep -v grep | awk '{print $2}' | xargs kill

Status Command

Various views and dialogs within the ClearBlade developers console display the status of the adapters. Unfortunately, it is not a trivial process to determine the status of the adapter. The Status Command provides the mechanism that allows the ClearBlade Platform to determine the status of an adapter running on ClearBlade Edge.

Therefore, a shell script that echoes the status of an adapter should be supplied. The shell script should account for and echo the following values:

  • Deployed
  • Running
  • Stopped

If the Status Command is not specified on the Config tab of the adapter settings dialog, the views in the developers console that display the status of an adapter will not be able to reliably display the status of an adapter. In these cases, the status will most likely be displayed as No Status Available.

Note

If using a shell script to accomplish tasks needed for stopping the adapter, the shell script must be included as one of the adapter files in the Files tab of the adapter settings.

A sample shell script, named status.sh is as follows:

#!/bin/bash
# If this script is executed, we know the adapter has been deployed. No need to test for for the "undeployed" status.
STATUS="Deployed"
if [ "ps -ef | grep showTime | grep -v grep" != "" ] ; then
    STATUS="Running"
else
    STATUS="Stopped"
fi

echo $STATUS

In the Config tab of the adapter settings, the status command specified to execute the status.sh shell script would be

./ShowTimeAdapter/status.sh

Note that the command takes into account the fact that the deploy script copied the status.sh file to a directory named ShowTimeAdapter.

Undeploy Command

If an adapter is no longer needed, the Undeploy Command can be used to remove the adapter files from the ClearBlade Edge. The undeploy command is an optional command. If the Undeploy Command is not specified on the Config tab of the adapter settings dialog, the default behavior of the ClearBlade platform is to remove the adapter files from the directory where Edge is running. The default undeploy behavior therefore would not delete any log files that were created or remove any files that were moved to adapter specific directories.

The undeply command will most likely be a command that deletes an adapter specific directory and any files contained within it, such as

rm -rf ./ShowTimeAdapter

If a more sophisticated undeployment/deletion of the adapter is needed, undeploy logic can be incorporated into a shell script.

Note

If using a shell script to accomplish tasks needed for deleting/undeploying the adapter, the shell script must be included as one of the adapter files in the Files tab of the adapter settings.

A sample shell script, named undeploy.sh is as follows:

#!/bin/bash
rm -rf ./ShowTimeAdapter

In the Config tab of the adapter settings, the undeploy command specified to execute the undeploy.sh shell script would be

./ShowTimeAdapter/undeploy.sh

Note that the command takes into account the fact that the deploy script copied the undeploy.sh file to a directory named ShowTimeAdapter. Since the shell script only contains one line, we easily could have specified the value of Undeploy Command as

rm -rf ./ShowTimeAdapter

Logs Command

While an adapter is running, it would be advantageous to be able to view any execution logs written by the adapter. The Logs Command provides the mechanism that allows the ClearBlade Platform to retrieve the contents of log files from an adapter running on ClearBlade Edge. The logs command is an optional command. If the Logs Command is not specified on the Config tab of the adapter settings dialog, any log files written by the adapter would need to be viewed manually (via ssh or sftp).

The log command will most likely be a cat or tail command that displays the contents of a file, such as

cat ./ShowTimeAdapter/showTime.log

In many cases, the Logs Command will be directly dependent on the Start-up Command piping output to a file, unless the adapter is written in such a manner that it creates its own log files.

If more sophistication is needed to read log files, the logic can be incorporated into a shell script.

Note

If using a shell script to accomplish tasks needed for displaying log files, the shell script must be included as one of the adapter files in the Files tab of the adapter settings.

A sample shell script, named log.sh is as follows:

#!/bin/bash
cat ./ShowTimeAdapter/showTime.log

In the Config tab of the adapter settings, the logs command specified to execute the logs.sh shell script would be

./ShowTimeAdapter/logs.sh

Note that the command takes into account the fact that the deploy script copied the logs.sh file to a directory named ShowTimeAdapter. Since the shell script only contains one line, we easily could have specified the value of Logs Command as

cat ./ShowTimeAdapter/showTime.log