Websocket

Guide to websocket communications with the Ardexa API

Last updated 1 year ago

Getting started

The Ardexa API uses socket.io (https://socket.io/) for websocket requests. There are client libraries available for a variety of programming languages. The examples listed here will use NodeJS.

To get started, we will issue a simple REMOTE SHELL request. You will need:

An API token with the Control Devices privilege
- For testing, you can simply use your current session token: (Your name) -> My Profile -> Version -> Copy to clipboard
The workgroup ID and device ID of the device
- These can be found under Manual Config -> General on the Devices page for the target device

Connect and authenticate

Here is an example connect function:

import io from 'socket.io-client'
const workgroupId = 'your-workgroup-id'

function connect () {
  return new Promise((resolve, reject) => {
    let pending = true
    const websocket = io(`https://app.ardexa.com`, {
      query: `token=${process.env.TOKEN}&orgName=${workgroupId}`,
      path: '/socket.io-client',
      forceNew: true,
      transports: ['websocket'],
    })
    websocket.once('connect', () => {
      console.log('SOCKET CONNECTED')
      if (pending) {
        resolve(websocket)
        pending = false
      }
    })
    websocket.once('connect_error', err => {
      console.error('Socket error', err, err.data)
      if (pending) {
        reject(err)
        pending = false
      }
    })
  })
}

All operations using socket.io are event driven, so in this example we have wrapped the connection events in a Promise to make things a little easier. The important parts to notice are:

The API token is read from an environment variable called TOKEN
The cloud is app.ardexa.com. Please update this to match your cloud URL.
The workgroupId is passed in at connection time. You must use a separate connection for each workgroup
The websocket will emit connect when successfully connected, or connect_error if there was a problem

Now that we're connected, we can issue a REMOTE SHELL by emitting (sending) the correct event type and listening for the responses

async function main () {
  const deviceId = 'your-device-id'
  const cmd = 'uptime'
  const websocket = await connect()
  websocket.once('device:cmd:reply', (item) => {
    console.log('REPLY:', item)
    disconnect(websocket)
  })
  websocket.once('device:cmd:rpc', (item) => {
    console.log('RPC:', item)
    if (item.error) disconnect(websocket)
  })
  websocket.emit('device:cmd', { deviceId, cmd })
}

device:cmd is emitted with the following parameters
- deviceId: the ID of the target device
- cmd: the command we want to run on that device
- requestId: optional. Will be returned in any subsequent replies. Useful for matching requset and response objects if you are running many concurrent requests
device:cmd:rpc is received first. This confirms that the API has received the request and it has been successfully processed. If there are errors, such as a permission problem, they will be delivered here and there will be no reply. Successful requests will be assigned a correlationId which can be used to match the reply/replies to the initial request
device:cmd:reply is received once the request has been fully processed by the edge device. For device:cmd, this includes the output of the command (stdout and stderr) as well as the return code.

Here is a sample of the output when the script is run from the command line:

SOCKET CONNECTED
RPC: { correlationId: '8c1c1b05-8c98-4010-af92-747511102415' }
REPLY: {
  stdout: ' 05:33:14 up 474 days,  1:21,  0 users,  load average: 0.00, 0.00, 0.00\n',
  stderr: '',
  returnCode: 0,
  correlationId: '8c1c1b05-8c98-4010-af92-747511102415'
}

Emitted events

device:stateChange

Sent when a device's online state changes (online/offline). Contains the cn (Common name), vhost (aka workgroup ID) and the latest online status

{
    "cn": "CN=3dcf4324-3c0a-40bc-8d13-5d5bbbcf229e,O=dev",
    "vhost": "dev",
    "online": false
}

device:new

Sent when a new device is created. Contains the id (aka Device ID), the cn and it's online status (which is always false)

{
    "id": "102b5359-eb59-479d-a471-552f7ca2c093",
    "cn": "CN=102b5359-eb59-479d-a471-552f7ca2c093,O=dev",
    "online": false
}

device:metaChange

Sent when there is a change to the agent configuration. Contains the device ID as the id property. The workgroup ID is the one used to connect the current socket.

{
    "id": "666170e2-d3b2-49b7-88fc-542e1a2c9732"
}

RPC events

Live data feed

device:feed

Get a live feed of data directly from the broker. The deviceId, table and source are mandatory. For CSV scenarios you can optionally include a specific field to only stream a single value (the default is to stream an array of values)

{
    "requestId": "b329c143-46fe-4654-a970-8c25aee2d34d",
    "deviceId": "666170e2-d3b2-49b7-88fc-542e1a2c9732",
    "table": "solar",
    "source": "inverter-01",
    "field": "AC Power"
}

The device:feed:rpc will include a feedId:

{
    "requestId": "b329c143-46fe-4654-a970-8c25aee2d34d",
    "feedId": "4cbe686d-303a-4081-84aa-aecff0f07c80"
}

The value prop will contain the value(s) requested:

{
    "feedId": "4cbe686d-303a-4081-84aa-aecff0f07c80",
    "event_time": "2023-08-09T03:55:37.000Z",
    "table": "solar",
    "source": "inverter-01",
    "device": "666170e2-d3b2-49b7-88fc-542e1a2c9732",
    "messageId": "71391",
    "value": 66920,
    "requestId": "b329c143-46fe-4654-a970-8c25aee2d34d"
}

device:feed:stop

Will stop an existing feed. Simply pass in the feedId received in the :rpc response

{
    "feedId": "4cbe686d-303a-4081-84aa-aecff0f07c80"
}

device:feed:stopAll

Takes no arguments, will stop all feeds associated with the current socket connection.

Agent configuration

device:testConfig

Send a config object (JSON) to the specified device ID for testing and validation. Since the destination format is YAML, but the request is using JSON, the API will pre-process the request to look for "anchors" in the config, specifically in the fields property. In the example below, example_fields is used as an anchor by the tail scenario.

{
    "requestId": "ed758e3c-d37c-48e5-a3f2-fe187904f64c",
    "deviceId": "666170e2-d3b2-49b7-88fc-542e1a2c9732",
    "config": {
        "example_fields": [
            {
                "meta": { "units": "$" },
                "name": "one",
                "expect": "integer"
            },
            {
                "meta": { "units": "@" },
                "name": "two",
                "expect": "integer"
            },
            {
                "meta": { "units": "!" },
                "name": "other one",
                "expect": "keyword"
            },
            {
                "name": "baleReady",
                "expect": "bool"
            }
        ],
        "amqp": {
            "cacertfile": "/etc/ardexa/keys/Ardexa CA chain - amqps.crt",
            "certfile": "/etc/ardexa/keys/client.crt",
            "keyfile": "/etc/ardexa/keys/client.key",
            "hostname": "minikube.local",
            "port": 30671
        },
        "debug": 1,
        "run": [
            {
                "command": "top -b -n2 | grep \"Cpu(s)\"|tail -n 1 | awk '{print $2 + $4}'",
                "frequency": 30,
                "expect": "decimal",
                "table": "data",
                "source": "cpu_usage",
                "meta": {
                    "units": "percentage",
                    "comment": "measures cpu usage"
                }
            }
        ],
        "tail": [
            {
                "file": "/tmp/junk.log",
                "table": "junk",
                "source": "file1",
                "expect": "csv",
                "fields": "example_fields"
            }
        ],
        "stdout": true,
    }
}

As the request is fairly determinate in terms of time taken, there is only a single :rpc response indicating success:

{
  "requestId": "ab76bc81-78d6-41db-bef3-1204240aeaf1",
  "result": "success"
}

Or failure:

{
    "requestId": "79da4cc6-7081-4595-84e9-82d9d05c807c",
    "result": "error",
    "error": {
        "message": "ERROR. 2147. Parse error: Failed to parse 'frequency': yaml-cpp: error at line 50, column 16: bad conversion LC: 2\nERROR. 2147. Parse error: Failed to parse 'frequency': 2156. Bad frequency LC: 2\n"
    }
}

device:applyConfig

Just like device:testConfig, except the configuration will be saved and the agent will be restarted

device:applyYamlConfig

Just like device:applyConfig, except the configuration is a String instead of an Object, and the string must be a YAML document.

Other

device:refreshMeta

Dynamically mapped scenarios (read: anything logged to /opt/ardexa/logs), can occasionally get out of sync with the cloud. To force a re-read and re-sync event, use this RPC request

{
    "requestId": "bd1ed0dc-0e46-4f2a-b466-9514222aa81a",
    "deviceId": "666170e2-d3b2-49b7-88fc-542e1a2c9732"
}

Will always succeed

{
    "requestId": "bd1ed0dc-0e46-4f2a-b466-9514222aa81a",
    "complete": true
}

Will be followed by a device:stateChange as the agent is restarted, and a device:metaChange as the metadata is re-synced

device:doUpgrade

Upgade the agent to the latest version

{
    "requestId": "71089965-c53d-4e66-a3f7-a3de03aa76a9",
    "deviceId": "666170e2-d3b2-49b7-88fc-542e1a2c9732"
}

Will emit a series of device:doUpgrade:reply events at each step of the process

{
    "status": "Arch detected: amd64",
    "complete": false,
    "requestId": "71089965-c53d-4e66-a3f7-a3de03aa76a9"
}

The final message in a successful series will set complete: true

{
    "status": "Complete",
    "complete": true,
    "requestId": "71089965-c53d-4e66-a3f7-a3de03aa76a9"
}

If there is an error, it will be reported and no further replies will be forthcoming

{
    "error": "Internal error occurred",
    "requestId": "71089965-c53d-4e66-a3f7-a3de03aa76a9"
}

device:sendArdexactl

Send a cooy of the ardexactl control script to the target device. This normally happens automatically if the script is required, e.g. device:doUpgrade, but there are situations where that's not the case, such as agent API logins.

{
    "requestId": "96f021d3-f866-4dec-819f-9a2035e91b12",
    "deviceId": "666170e2-d3b2-49b7-88fc-542e1a2c9732"
}

And the device:sendArdexactl:rpc response

{
    "requestId": "96f021d3-f866-4dec-819f-9a2035e91b12",
    "complete": true
}

device:sendArdpkg

Send a cooy of the ardpkg plugin management app to the target device. This normally happens automatically if the script is required, e.g. installing a plugin. This call can also be used to upgrade ardpkg to the latest version

{
    "requestId": "96f021d3-f866-4dec-819f-9a2035e91b12",
    "deviceId": "666170e2-d3b2-49b7-88fc-542e1a2c9732"
}

And the device:sendArdpkg:rpc response

{
    "requestId": "96f021d3-f866-4dec-819f-9a2035e91b12",
    "complete": true
}