API Reference
Glossary of Terms
Term | Description |
---|---|
Allxon Cloud | The backend servers of Allxon service; both Allxon Portal and Allxon Agent are connected to Allxon Cloud. |
Allxon Portal | The frontend servers of Allxon service. |
Allxon Agent | An agent application that communicates between edge devices and Allxon Cloud. |
Plugin | A software application that extends the functionalities of Allxon service. A plugin sends collected data from modules to Allxon Cloud via Allxon Agent. It also sends commands from Allxon Portal to modules via Allxon Agent. |
Module | A hardware component (e.g. GPU, SSD, fan) or a software application (e.g. remote console utilities). A plugin collects data from a module or sends commands to a module. |
MQTT Broker | Allxon Agent connects to a MQTT broker hosted by Allxon Cloud. All the data exchange between Allxon Agents and Allxon Cloud go through this channel. |
WebSocket Server | A plugin connects to a WebSocket server hosted within an Allxon Agent. The plugin sends and receives data to/from Allxon Cloud with Allxon Octo APIs through this channel. |
Allxon Octo API | The Application Programming Interface used to communicate between Allxon Agent and plugins. |
Allxon Octo SDK | The Software Development Kit provided by Allxon, which helps developers to build plugins and verify Allxon Octo APIs. |
App GUID | A unique identifier assigned by Allxon to each plugin in UUIDv4 format. |
Access Key | A secret key assigned by Allxon to each plugin for message signing. |
Allxon Octo API
Allxon Octo API adopts JSON-RPC 2.0 specification over WebSocket. To communicate with Allxon Agent, you need to create a WebSocket connection wss://localhost:55688 from the plugin. Then send/receive requests in the JSON format via the API.
Each API maximum payload size is 5 KB.
JSON-RPC batch is not supported.
How to Read the API
- If the API name starts with
notify...
, it's a JSON-RPC Notification Request. - A bracketed JSON Key represents a JSON Type. The types are as follows: Object, Array, String, Number, Bool, Null
- If a JSON Key is not bracketed, the JSON Type is String.
"v2/notifyPluginUpdate"
Direction: Plugin → Agent
{
"jsonrpc": "2.0",
"method": "v2/notifyPluginUpdate",
"params": {
"appGUID": "...",
"epoch": "...",
"appName": "...",
"displayName": "...",
"type": "...",
"sdk": "...",
"version": "...",
"startCommand": "...",
"stopCommand": "...",
"modules": [
{
"moduleName": "...",
"displayName": "...",
"description": "...",
"properties": [ ... ],
"states": [ ... ],
"metrics": [ ... ],
"events": [ ... ],
"commands": [ ... ],
"alarms": [ ... ],
"configs": [ ... ]
}
]
}
}
$.params
Name | Type | Required | Description |
---|---|---|---|
"appGUID" | String | The GUID of the plugin. | |
"appName" | String | The unique plugin name in string format. The name must match the regular expression1. | |
"epoch" | String | The current Epoch Time in seconds. | |
"displayName" | String | The plugin name displayed on the plugIN card. | |
"type" | String | "ib" for in-band plugin."oob" for out-of-band plugin. | |
"sdk" | String | The version of Allxon Octo SDK, which follows semantic version rule. | |
"version" | String | The version of a plugin, which uses a sequence of three digits (Major.Minor.Patch). It must match the regular expression2. | |
"startCommand" | String | A Command to execute when plugin starts. | |
"stopCommand" | String | A Command to execute when plugin stops. | |
"modules" | Array | A set of hardware or software modules controlled by this plugin. |
$.params.modules[*]
Name | Type | Required | Description |
---|---|---|---|
"moduleName" | String | The module name unique within the plugin and having a string format of no longer than 64 characters. The name must match the regular expression. | |
"displayName" | String | The module name displayed on the plugin tab of the device page. | |
"description" | String | The description of the module. | |
"properties" | Array | This is used to upload the static information of the module, such as the firmware version and hardware configuration. | |
"states" | Array | This is used to upload the dynamic states of the module, such as the power state. | |
"metrics" | Array | This is used to upload metrics of the module, such as temperature and voltage. | |
"events" | Array | This is used to upload events/activities of the module, such as intrusion detection. | |
"commands" | Array | This is used to enable function calls of the module, such as power cycling and hardware configuration. | |
"alarms" | Array | This is used to handle alerts of the module, such as alerts for CPU and system temperature. | |
"configs" | Array | This is used to handle the remote configurations of the module, such as scheduling. |
$.params.modules[*].properties[*]
{
"name": "...",
"displayName": "...",
"displayCategory": "...",
"description": "...",
"displayType": "...",
"value": "..."
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The property name unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayName" | String | The display name of each property field. | |
"displayCategory" | String | The name of the Category tab displayed on a card. Properties with the same displayCategory are categorized under the same tab. | |
"description" | String | The description of the property. | |
"displayType" | String | "string" | "table" | "link" | |
"value" | Object | Array | String | The type of "value" depends on the "displayType" . |
"displayType":"string"
in "properties"
In Properties, if the "displayType"
is set to "string"
, the type of "value"
must be String.
Here is an example:
{
...
"properties": [
{
"name": "property1",
"displayType": "string",
"value": "my string",
...
},
...
]
}
The Properties card displays as follows:
"displayType":"link"
in "properties"
If the "displayType"
is set to link
, the type of "value"
must be Object and must follow the format below.
Name | Type | Required | Description |
---|---|---|---|
"url" | String | A link to an external resource. | |
"alias" | String | An alias name for this URL. |
Here is an example:
{
...
"properties": [
{
"name": "property1",
"displayType": "link",
"value": {
"url": "https://www.google.com",
"alias": "Google Site"
},
...
},
...
]
}
The Properties card displays as follows:
"displayType":"table"
in "properties"
When the "displayType"
is set to table
, the type of "value"
must be Array.
Here is an example:
{
...
"properties": [
{
"name": "property1",
"displayType": "table",
"value": [
{
"header1": "row1 column1",
"header2": "row1 column2"
},
{
"header1": "row2 column2",
"header2": "row2 column2"
},
...
],
...
},
...
]
}
The Properties card displays as follows:
Click the table icon to view details.
$.params.modules[*].states[*]
{
"name": "...",
"displayName": "...",
"displayCategory": "...",
"description": "...",
"displayType": "..."
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The state name unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayName" | String | The field name displayed under the state. | |
"displayCategory" | String | The name of the Category tab displayed on a card. States with the same displayCategory are categorized under the same tab. | |
"description" | String | The description of the state. | |
"displayType" | String | "string" | "table" | "link" |
$.params.modules[*].metrics[*]
{
"name": "...",
"displayName": "...",
"displayCategory": "...",
"description": "...",
"displayUnit": "...",
"displayType": "..."
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The name of the set of metrics, which is unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1.1. | |
"displayName" | String | The field name displayed under the metrics. | |
"displayCategory" | String | The name of the Category tab displayed on a card. Metrics with the same displayCategory are categorized under the same tab. | |
"description" | String | The description of the metric. | |
"displayUnit" | String | Depending on "displayType" | If the "displayType" is "custom" , the display unit should be entered. |
"displayType" | String | "temperature" | "custom" |
$.params.modules[*].events[*]
{
"name": "...",
"displayName": "...",
"displayCategory": "...",
"description": "..."
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The event name unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayName" | String | The field name displayed under the event | |
"displayCategory" | String | The name of the Category tab displayed within a card. Events with the same displayCategory are categorized under the same tab. | |
"description" | String | The description of the event. |
$.params.modules[*].commands[*]
{
"name": "...",
"displayCategory": "...",
"displayName": "...",
"description": "...",
"type": "...",
"params": [
{
"name": "...",
"displayName": "...",
"description": "...",
"displayType": "...",
"required": true | false,
"requiredOn": "...",
"defaultValue": "...",
"displayMask": "...",
"valueEncoding": "..."
}, ...
]
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The command name unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayCategory" | String | The name of the Category tab displayed on a card. Commands with the same displayCategory are categorized under the same tab. | |
"displayName" | String | The field name under the command. | |
"description" | String | The description of the command. | |
"type" | String | "asynchronous" | |
"params" | Array | (No need to set this item if this command has no parameters.) |
$.params.modules[*].commands[*].params[*]
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The command parameter name unique within the command and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayName" | String | The field name under the command parameter. | |
"description" | String | The description of the command parameter. | |
"displayType" | String | "string" | "text" | "datetime" | "switch" | "checkbox" | "list" | "tos" | |
"required" | Bool | Indicates if this parameter is mandatory or not. | |
"requiredOn" | String | Indicates if this parameter is mandatory on the other parameter. | |
"displayValues" | String | Array | Related to the "displayType" . | |
"defaultValue" | String | The default value of this parameter. | |
"displayFormat" | String | Depending on "displayType" | A property for the "datetime" displayType. Refer to the datetime format. |
"valueFromProperty" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) | |
"displayMask" | Bool | (Not implemented in the Portal yet.) | |
"valueEncoding" | String | Advance | |
"displayOnProperty" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) |
$.params.modules[*].alarms[*]
{
"name": "...",
"displayCategory": "...",
"displayName": "...",
"description": "...",
"params": [
{
"name": "...",
"displayName": "...",
"description": "...",
"displayType": "...",
"required": true | false,
"displayValues": "...",
"defaultValue": "...",
"displayFormat": "...",
"valueFromProperty": "...",
"displayMask": "...",
"valueEncoding": "..."
}, ...
]
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The alarm name unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayCategory" | String | The name of the category tab displayed on a card.Alarms with the same displayCategory are categorized under the same tab. | |
"displayName" | String | The field name displayed under the alarm. | |
"description" | String | The description of the alarm. | |
"params" | Array | (No need to set this item if this alarm has no parameters.) |
$.params.modules[*].alarms[*].params[*]
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The parameter name unique within the alarm and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayName" | String | The field name displayed under the alarm parameter. | |
"description" | String | The description of the alarm parameter. | |
"displayType" | String | "string" | "datetime" | "switch" | "checkbox" | "list" | "temperature" | |
"required" | Bool | Indicates if this parameter is mandatory or not. | |
"displayValues" | String | Related to the "displayType" . | |
"defaultValue" | String | The default value of this parameter. | |
"displayFormat" | String | Depending on "displayType" | A required property if the displayType is "datetime" . Refer to the datetime format. |
"valueFromProperty" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) | |
"displayMask" | Bool | A property for the "string" displayType, indicating if the string inputs are masked or not. | |
"valueEncoding" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) |
$.params.modules[*].configs[*]
{
"name": "...",
"displayCategory": "...",
"displayName": "...",
"description": "...",
"params": [
{
"name": "...",
"displayName": "...",
"description": "...",
"displayType": "...",
"required": true | false,
"displayValues": "...",
"defaultValue": "...",
"displayFormat": "...",
"valueFromProperty": "...",
"displayMask": "...",
"valueEncoding": "..."
}, ...
]
}
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The config name unique within the module and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayCategory" | String | The name of the category tab displayed on a card. Configs with the same displayCategory are categorized under the same tab. | |
"displayName" | String | TThe field name displayed under the config. | |
"description" | String | The description of the config. | |
"params" | Array | (No need to set this item if this config has no parameters.) |
$.params.modules[*].configs[*].params[*]
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The command parameter name unique within the config and having a string format of no longer than 32 characters. The name must match the regular expression1. | |
"displayName" | String | The field name under the config parameter. | |
"description" | String | The description of the config parameter. | |
"displayType" | String | "string" | "datetime" | "switch" | "checkbox" | "list" | "temperature" | |
"required" | Bool | Indicates if this parameter is mandatory or not. | |
"displayValues" | String | Related to the "displayType" | |
"defaultValue" | String | Default value of this parameter. | |
"displayFormat" | String | Depending on "displayType" | A property for the "datetime" displayType. Refer to the datetime format. |
"valueFromProperty" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) | |
"displayMask" | Bool | A property for the "string" displayType, indicating if the string inputs are masked or not. | |
"valueEncoding" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) |
"v2/notifyPluginCommand"
Direction: Agent → Plugin
{
"jsonrpc": "2.0",
"method": "v2/notifyPluginCommand",
"params": {
"serialNumber": "...",
"appGUID": "...",
"epoch": "...",
"commandId": "...",
"commandSource": "...",
"moduleName": "...",
"commands": [ ... ]
}
}
$.params
Name | Type | Required | Description |
---|---|---|---|
"serialNumber" | String | (This function is only used in special scenarios. Contact your Allxon representative for instructions.) The serial number of the device behind a gateway, only required when sending commands to devices behind a gateway. | |
"appGUID" | String | The GUID of the plugin. | |
"epoch" | String | The current Epoch Time in seconds. | |
"commandId" | String | The assistId in MQTT message. | |
"commandSource" | String | "remote" | |
"moduleName" | String | The name of the module. The name must match the regular expression1. | |
"commands" | Array | A set of modules. |
$.params.commands[*]
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The name of the command. The name must match the regular expression1. | |
"params" | Array | A set of name and value pairs for the command. |
$.params.commands[*].params[*]
Name | Type | Required | Description |
---|---|---|---|
"name" | String | The name of the parameter. The name must match the regular expression1. | |
"value" | String | Bool | The type of "value" depends on the "displayType" in the command parameter part of "v2/notifyPluginUpdate" . More details.... |
"displayType":"string"
in "commands"
Based on the "displayType":"string"
defined in "v2/notifyPluginUpdate"
, the Commands card displays a text box for the user to enter a string parameter.
See the JSON example below:
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "stringParam",
"displayType": "string",
"required": false,
...
}
],
...
}
],
}
With this setting, the user can enter a string parameter, such as "foo" in the example below, and execute the command.
Then "v2/notifyPluginCommand"
is sent out, carrying the command of "value": "foo"
.
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "stringParam",
"value": "foo"
}
]
}
]
}
"displayType":"datetime"
in "commands"
If "v2/notifyPluginUpdate"
has "displayType":"datetime"
, you must define "displayFormat"
by using one of the following formats:
"YYYY-MM-DD"
"HH:MM"
"YYYY-MM-DD HH:MM"
Then the Commands card on the Portal displays a corresponding field. Here is an example showing the field with "displayFormat"
being "HH:MM"
See the JSON example below:
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "dateParam",
"displayType": "datetime",
"required": false,
"displayFormat": "HH:MM",
...
}
],
...
}
],
}
When the user selects a time, for example “12:00”, and executes the command, "v2/notifyPluginCommand"
is sent out. The value in the command follows the format of "displayFormat": "HH:MM"
See the JSON example below:
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "dateParam",
"value": "12:00"
}
]
}
]
}
"displayType":"text"
in "commands"
If you set "displayType"
to "text"
in "v2/notifyPluginUpdate"
, the "value"
in the command can contain multiple lines of parameters. The Commands card on the Portal displays a text parameter field.
See the JSON example below:
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "textParam",
"displayType": "text",
"required": false,
...
}
],
...
}
],
}
Here is an example of how this works:
The user enters “hello world” in two lines and executes the command.
This sends out "v2/notifyPluginCommand"
with "value":"hello\nworld"
.
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "dateParam",
"value": "hello\nworld"
}
]
}
]
}
"displayType":"switch"
in "commands"
The switch function is used to switch between two parameters. The Commands card displays a toggle button for the user to make the change, as shown below.
If you set "displayType"
to "switch"
in "v2/notifyPluginUpdate"
, you must define "displayValues"
as a size 2 Array, with index 0 representing false and index 1 representing true.
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "switchParam",
"displayType": "switch",
"displayValues": [
"offValue",
"onValue"
],
"defaultValue": "offValue",
"required": false,
...
}
],
...
}
],
}
After the user executes the command, "v2/notifyPluginCommand"
is sent out. The value in the command follows the "displayValues"
defined in "v2/notifyPluginUpdate"
.
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "switchParam",
"value": "offValue"
}
]
}
]
}
"displayType":"checkbox"
in "commands"
The Commands card displays a checkbox for the user to enable or disable this parameter.
If you set "displayType"
to "checkbox"
in "v2/notifyPluginUpdate"
, you must define "displayValues"
as a size 2 Array, with index 0 representing false and index 1 representing true.
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "checkboxParam",
"displayType": "checkbox",
"displayValues": [
"offValue",
"onValue"
],
"defaultValue": "offValue",
"required": false,
...
}
],
...
}
],
}
After the user executes the command, "v2/notifyPluginCommand"
is sent out. The value in the command follows the "displayValue"
defined in "v2/notifyPluginUpdate"
.
{
...
"commands": [
{
"name": "command1",
"params": [
{
"name": "checkboxParam",
"value": "offValue"
}
]
}
]
}