Adapters

Introduction

An Adapter is a custom software component that is deployed on IoT Gateway devices executing the ClearBlade Edge.

Each Adapter consists of a name, a small number of administrative commands, and a small number of files comprising the administrative and executable assets of an adapter. The files comprising an adapter will consist of executable code and supporting libraries as well as shell scripts used to administer adapters.

To learn how to create and configure an adapter, click here

Purpose

To serve as a proxy between the ClearBlade platform and IoT devices that cannot directly communicate with the ClearBlade Platform. ClearBlade provides various adapters out-of-the-box for different type of protocols like BLE, Modbus, Bacnet, Canbus, ZMQ, AMQP, xDot etc. Checkout ClearBlade’s Github

Commands

Once an adapter has been successfully deployed to an Edge, it can be started, stopped, or restarted using Edge Management portion of the adapter’s page, located within the ClearBlade Platform developers console. The status of the adapter on each edge is determined by the returned output of the status command from the adapter’s configuration, either “Running” or “Stopped”.If the adapter is not successfully deployed to an edge, the edge will be found in the Disconnected Edges table.

Shell commands or scripts need to be specified in the Configuration section within the adapter’s settings so that the adapter can be correctly administered. Commands are executed from the directory where the Edge was started. The currently supported commands are:

• Deploy Command
• Start Command
• Stop Command
• Status Command
• Undeploy Command
• Logs Command

Deploy Command

A command or shell script that will be run after the files are installed on a ClearBlade Edge. This is an optional command.

Start Command

A command or shell script that will be executed to start the adapter on a ClearBlade Edge.If a start command is not specified , the adapter would need to be manually started by connecting to the gateway device (via ssh) and issuing an appropriate start.An adapter can be started on one or multiple edges from the Stopped tab of the Edge Management table.

Stop Command

A command or shell script that will be run to stop the adapter on a ClearBlade Edge.The stop command is an optional command.If the Stop Command is not specified, the adapter would need to be manually stopped by connecting to the gateway device (via ssh) and issuing an appropriate stop command.An adapter can be stopped or restarted on one or multiple edges from the Running tab of the Edge Management table.

Status Command

A command or shell script that will be run to determine the status of the adapter on a specific ClearBlade Edge. 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

Undeploy Command

A command or shell script that will be run to uninstall the adapter from a ClearBlade Edge. The undeploy command is an optional command. If the Undeploy Command is not specified 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.

Logs Command

A command or shell script that will be used to retrieve any logs printed out by the adapter while it is running.The logs command is an optional command. If the Logs Command is not specified, any log files written by the adapter would need to be viewed manually (via ssh or sftp).You can view the adapter logs, determined by executing the Logs command in the adapter configuration by clicking the View button of the logs column in the Edge Management table.

Parameter Variables

Adapter parameter variable are predefined variables that can be used in adapter commands. This helps with making adapters functional with fewer configuration changes.

Adapter Variables List

Name	Variable	Usage	Access
Platform URL	CB_PLATFORM_IP	${CB_PLATFORM_IP}	Read
System Key	CB_SYSTEM_KEY	${CB_SYSTEM_KEY}	Read
System Secret	CB_SYSTEM_SECRET	${CB_SYSTEM_SECRET}	Read
Edge Name	CB_EDGE_NAME	${CB_EDGE_NAME}	Read
Edge IP	CB_EDGE_IP	${CB_EDGE_IP}	Read
Adapters Directory	CB_ADAPTERS_ROOT_DIR	${CB_ADAPTERS_ROOT_DIR}	Read
Service Account	CB_SERVICE_ACCOUNT	${CB_SERVICE_ACCOUNT}	Read
Service Account Token	CB_SERVICE_ACCOUNT_TOKEN	${CB_SERVICE_ACCOUNT_TOKEN}	Read
HTTP Port	CB_HTTP_PORT	${CB_HTTP_PORT}	Read

Usage

Variables can be referenced from the command configuration using the following syntax:

myAdapter ${PLATFORM_URL} ${SYSTEM_KEY} 

Service Accounts

It is important for user writing the adapter to know what user they need to run the adapter as. If that user/device is a service account, we’ll provide the token for them automatically.

Example for start shell script:

./start.sh -cb_service_account=hello@clearblade.com

If a service account is specified on the command line, the edge will supply the CB_SERVICE_ACCOUNT_TOKEN in the adapter’s environment

For more information about service accounts, click here