Adapters
- Jeff Slavin (Unlicensed)
Introduction
An adapter is a custom software component 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 an adapter's administrative and executable assets. These files consist of executable code, supporting libraries, and shell scripts to administer adapters.
Learn how to create and configure an adapter.
Purpose
Adapters 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 protocols like BLE, CAN bus, ZMQ, AMQP, etc.
Commands
Once an adapter has been successfully deployed to an edge, it can be started, stopped, or restarted using the adapter page’s edge management portion, located within the ClearBlade Platform developers console. The adapter’s status on each edge is determined by the returned output of the status command from the adapter’s configuration, 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 must be specified in the Configuration section within the adapter’s settings to administer the adapter correctly. Commands are executed from the directory where the edge was started. The currently supported commands are:
Deploy command
An optional command or shell script will run after the files are installed on a ClearBlade Edge.
Start command
A command or shell script will be executed to start a ClearBlade Edge adapter. If a start command is not specified, the adapter must 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 Edge Management table’s Stopped tab.
Stop command
A command or shell script will stop the adapter on a ClearBlade Edge. The stop command is optional. If the stop command is not specified, the adapter must be manually stopped by connecting to the gateway device (via SSH) and issuing an appropriate stop command. An adapter can be stopped or restarted from the Edge Management table’s Running tab on one or multiple edges.
Status command
A command or shell script will determine the adapter's status on a ClearBlade Edge. A shell script that echoes an adapter’s status should be supplied. The shell script should account for and echo the deployed, running, and stopped values.
Undeploy command
A command or shell script will run to uninstall the adapter from a ClearBlade Edge. The undeploy command is optional. If the undeploy command is not specified, the ClearBlade Platform’s default behavior is to remove the adapter files from the directory where the edge is running. The default undeploy behavior would not delete any log files created or remove any files moved to adapter-specific directories.
Logs command
A command or shell script will retrieve any logs printed out by the adapter while running. The logs command is optional. If the logs command is not specified, any log files written by the adapter must be viewed manually (via SSH or SFTP). You can view the adapter logs, determined by executing the adapter configuration’s logs command, by clicking the logs column’s View button in the Edge Management table.
Parameter variables
Adapter parameter variables are predefined and 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 |
| Read |
System Key | CB_SYSTEM_KEY |
| Read |
System Secret | CB_SYSTEM_SECRET |
| Read |
Edge Name | CB_EDGE_NAME |
| Read |
Edge IP | CB_EDGE_IP |
| Read |
Adapters Directory | CB_ADAPTERS_ROOT_DIR |
| Read |
Service Account | CB_SERVICE_ACCOUNT |
| Read |
Service Account Token | CB_SERVICE_ACCOUNT_TOKEN |
| Read |
HTTP Port | CB_HTTP_PORT |
| Read |
Usage
Variables can be referenced from the command configuration using this syntax:
myAdapter ${PLATFORM_URL} ${SYSTEM_KEY} Service accounts
Users writing the adapter must know what user to run it as. If that user/device is a service account, we’ll provide the token for them automatically.
Start shell script example:
./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.