API

Neuron provide a series of API services for IIoT platform, to query the basic information, to control gateway behaviors or to setup the polling configuration. IIoT platform can initiate the communication by sending request message to Neuron. By return, Neuron would send back the required information or execute the deserved action. If there is error, a error code would be returned to tell the reason of failure.

Value

Data Type

• BYTE = 2
• INT8 = 3
• INT16 = 4
• INT32 = 5
• INT64 = 6
• UINT8 = 7
• UINT16 = 8
• UINT32 = 9
• UINT64 = 10
• FLOAT = 11
• DOUBLE = 12
• BOOL = 13
• BIT = 14
• STRING = 15

Data Attribute

• READ = 0x01

• WRITE = 0x02

• SUBSCRIBE = 0x04

Node Type

• DRIVER = 1
• WEB = 2
• MQTT = 3
• DRIVERX = 4
• APP = 5

Plugin Kind

• STATIC = 0
• SYSTEM = 1
• CUSTOM = 2

Node CTL

• START = 0
• STOP = 1

Node State

• IDLE = 0
• INIT = 1
• READY = 2
• RUNNING = 3
• STOPPED = 4

Node Link State

• DISCONNECTED = 0
• CONNECTING = 1
• CONNECTED = 2

Ping

POST /api/v2/ping

Request Headers

Authorization Bearer \

Response Status

• 200 OK

Login

POST /api/v2/login

Request Headers

Content-Type application/json

Response Status

• 200 OK

Body

{
    "name": "admin",
    "pass": "0000"
}

Response

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzcyODcxNjMsImlhdCI6MTYzNzIwMDc2MywiaXNzIjoiRU1RIFRlY2hub2xvZ2llcyBDby4sIEx0ZCBBbGwgcmlnaHRzIHJlc2VydmVkLiIsInBhc3MiOiIwMDAwIiwidXNlciI6ImFkbWluIn0.2EZzPC9djErrCeYNrK2av0smh-eKxDYeyu7cW4MyknI"
}

Add Node

POST /api/v2/node

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 400
  • 2001 node type invalid
• 404
  • 2301 plugin library not found
• 409
  • 2002 node exist

Body

{
    //node type
    "type": 1,
    //node name
    "name": "modbus-tcp-node",
    //plugin name
    "plugin_name": "modbus-plugin-tcp"
}

Response

{
    "error": 0
}

Del Node

Delete /api/v2/node

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2003 node not exist

Body

{
    //node id
    "id": 7
}

Response

{
    "error": 0
}

Update Node(Not Implemented)

PUT /api/v2/node

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2003 node exist

Body

{
    //node id
    "id": 1,
    //node name
    "name": "modbus-tcp-node"
}

Response

{
    "error": 0
}

Get Node

GET /api/v2/node

Request Params

type required

Request Headers

Authorization Bearer \

Response Status

• 200 OK

Response

{
    "nodes": [
        {
            //node name
            "name": "sample-driver-adapter",
            //node id
            "id": 1,
            "plugin_id": 1
        },
        {
            "name": "modbus-tcp-adapter",
            "id": 4,
            "plugin_id": 2
        },
        {
            "name": "opcua-adapter",
            "id": 6,
            "plugin_id": 3
        },
        {
            "name": "modbus-tcp-test",
            "id": 7,
            "plugin_id": 4
        }
    ]
}

Add Group Config

POST /api/v2/gconfig

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2003 node not exist
• 409
  • 2103 group config conflict

Body

{
    //group config name
    "name": "gconfig1",
    //node id
    "node_id": 4,
    //read/upload interval(ms)
    "interval": 10000
}

Response

{
    "error": 0
}

Del Group Config

DELETE /api/v2/gconfig

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 412
  • 2102 group config in use
• 404
  • 2003 node not exist
  • 2101 group config not exist

Body

{
    //node id
    "node_id": 4,
    //group config name
    "name": "gconfig1"
}

Response

{
    "error": 0
}

Update Group Config(Not Implemented)

PUT /api/v2/gconfig

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2101 group config not exist

Body

{
    //group config name
    "name": "modbus-tcp-config1",
    //read/upload interval(ms)
    "interval": 20000,
    //node id
    "node_id": 4
}

Response

{
    "error": 0
}

Get Group Config

GET /api/v2/gconfig

Request Params

node_id required

Request Headers

Authorization Bearer \

Response Status

• 200 OK

Response

{
    "group_configs": [
        {
            //group config name
            "name": "config_modbus_tcp_sample_2",
            //read/upload interval(ms)
            "interval": 2000,
            //pipe count
            "pipe_count": 1,
            //tag count
            "tag_count": 0
        },
        {
            "name": "gconfig1",
            "interval": 10000,
            "pipe_count": 0,
            "tag_count": 0
        }
    ]
}

Add Tag

POST /api/v2/tags

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 206
  • 2202 tag name conflict
  • 2203 tag attribute not support
  • 2204 tag type not support
  • 2205 tag address format invalid
• 404
  • 2003 node not exist

Body

{
   //node id
    "node_id": 4,
   //group config name
    "group_config_name": "config_modbus_tcp_sample_2",
    "tags": [
        {
           //tag name
            "name": "tag1",
           //tag address
            "address": "1!400001",
           //tag attribute
            "attribute": 1,
           //tag type
            "type": 4
        },
        {
            "name": "tag2",
            "address": "1!00001",
            "attribute": 3,
            "type": 14
        },
        {
            "name": "tag3",
            "address": "1!400009",
            "attribute": 3,
            "type": 11
        }
    ]
}

Response

{
    "error": 0
}

Get Tag

GET /api/v2/tags

Request Params

node_id requred

group_config_name optional

Request Headers

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2003 node not exist

Response

{
    "tags": [
        {
            //tag name
            "name": "tag1",
            //tag type
            "type": 4,
            //tag address
            "address": "1!400001",
            //tag attribute
            "attribute": 1,
            //tag group config name
            "group_config_name": "config_modbus_tcp_sample_2",
            //tag id
            "id": 1
        },
        {
            "name": "tag2",
            "type": 14,
            "address": "1!00001",
            "attribute": 3,
            "group_config_name": "config_modbus_tcp_sample_2",
            "id": 4
        },
        {
            "name": "tag3",
            "type": 11,
            "address": "1!400009",
            "attribute": 3,
            "group_config_name": "config_modbus_tcp_sample_2",
            "id": 5
        }
    ]
}

Update Tag

PUT /api/v2/tags

Request Headers

Content-Type application/json

Authorization Bearer \

Response status

• 200 OK
• 206
  • 2201 tag not exist
  • 2202 tag name conflict
  • 2203 tag attribute not support
  • 2204 tag type not support
  • 2205 tag address format invalid
• 404
  • 2003 node not exist
  • 2101 group config not exist

Body

{
    //node id
    "node_id": 4,
    "tags": [
        {
            //tag id
            "id": 4,
            //tag name
            "name": "tag1",
            //tag type
            "type": 6,
            //tag attribute
            "attribute": 0,
            //tag address
            "address": "1!400001"
        },
        {
            "id": 5,
            "name": "tag2",
            "type": 6,
            "attribute": 0,
            "address": "1!400002"
        }
    ]
}

Response

{
    "error": 0
}

Del Tag

DELETE /api/v2/tags

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2003 node not exist

Body

{
    //group config name
    "group_config_name": "config_modbus_tcp_sample_2",
    //node id
    "node_id": 4,
    //tag ids
    "ids": [
        4,
        5
    ]
}

Response

{
    "error": 0
}

Add Plugin

POST /api/v2/plugin

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK

• 400

  • 2302 library info invalid

• 404

  • 2201 library not found

• 409

  • 2203 library name conflict

Body

{
    //plugin library name
    "lib_name": "plugin_name.so"
}

Response

{
    "error": 0
}

Del Plugin

DELETE /api/v2/plugin

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK

Body

{
    //plugin id
    "id": 1
}

Response

{
    "error": 0
}

Get Plugin

GET /api/v2/plugin

Request Params

plugin_id optional

Request Headers

Authorization Bearer \

Response Status

• 200 OK

Response

{
    "plugin_libs": [
        {
            //plugin id
            "id": 1,
            //plugin kind
            "kind": 1,
            //node type
            "node_type": 1,
            //plugin name
            "name": "plugin_name",
            //plugin library name
            "lib_name": "plugin_lib_name"
        }
    ]
}

Subscribe

POST /api/v2/subscribe

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2101 group config not exist

Body

{
    //src node id
    "src_node_id": 4,
    //dst node id
    "dst_node_id": 5,
    //src node group config name
    "name": "gconfig1"
}

Response

{
    "error": 0
}

UnSubscribe

DELETE /api/v2/subscribe

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 404
  • 2101 group config not exist

Body

{
    //src node id
    "src_node_id": 4,
    //dst node id
    "dst_node_id": 5,
    //src node group config name
    "name": "gconfig1"
}

Response

{
    "error": 0
}

Read Tag

POST /api/v2/read

Request Headers

Content—Type application/json

Response Status

• 200

Body

{
    //node name
    "node_name": "modbus-tcp-1",
    //group config name
    "group_name": "config_modbus_tcp_sample_2"
}

Response

{
    "tags": [
        {
            //tag nmae
            "name": "data1",
            //tag value
            "value": 1,
        },
        {
            "name": "data2",
            "error": 2014
        },
        {
            "name": "data3",
            "value": true,
        }
    ]
}

Note The value is displayed only when the value is read correctly, when the value is read incorrectly, the error code is displayed, not the value.

Write Tag

POST /api/v2/write

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK

Body

{
    "node_name": "modbus-tcp-1",
    "group_name": "config_modbus_tcp_sample_2",
    "tag_name": "tag1",
    "value": 1234
}

Response

{
    "error": 0
}

Get Plugin Schema

GET /api/v2/schema

Request Params

plugin_name required

Response Status

• 200 OK

Response

{
 "tag_type": [
  4,
  5,
  6,
  7,
  8,
  9,
  10,
  11,
  14
 ],
 "params": [
  "host",
  "port",
  "mode",
  "baud_rate",
  "real_param"
 ],
 "host": {
  "name": "host",
  "description": "host",
  "type": "string",
  "default": "127.0.0.1",
  "valid": {
   "length": 30
  }
 },
 "port": {
  "name": "port",
  "description": "port",
  "type": "int",
  "default": 502,
  "valid": {
   "min": 1024,
   "max": 65535
  }
 },
 "mode": {
  "name": "mode",
  "description": "mode",
  "type": "bool",
  "default": false,
  "valid": {}
 },
 "baud_rate": {
  "name": "baud rate",
  "description": "port",
  "type": "int",
  "default": 9600,
  "valid": {
   "value": [
    9600,
    112800
   ]
  }
 },
 "real_param": {
  "name": "real param",
  "description": "real",
  "type": "real",
  "default": 11.22,
  "valid": {
   "min": 1.1,
   "max": 20.2
  }
 },
 "ca": {
  "name": "ca",
  "description": "",
  "attribute": "optional",
  "type": "file",
  "condition": {
   "field": "mode",
   "value": true
  },
  "valid": {
   "length": 1024
  }
 }
}

Node Setting

POST /api/v2/node/setting

Request Headers

Content-Type application/json

Authorization Bearer \

Response Status

• 200 OK
• 400
  • 2003 node not exist
  • 2004 node setting invalid

Body

//The parameter fields in json fill in different fields according to different plugins
{
    //node id
    "node_id": 123,
    "params": {
        "param1": 1,
        "param2": "1.1.1.1",
        "param3": true,
        "param4": 11.22
    }
}

Response

{
    "error": 0
}

Get Node Setting

GET /api/v2/node/setting

Request Params

node_id required

Request Headers

Authorization Bearer \

Response Status

• 200 OK
  • 2005 node setting not found
• 404
  • 2003 node not exist

Response

//The parameter fields in json fill in different fields according to different plugins
{
    "node_id": 4,
    "params": {
        "param1": "1.1.1.1",
        "param2": 502
    }
}

Node CTL

POST /api/v2/node/ctl

Request Headers

Content-Type application/json

Authorization Bearer \

Request Status

• 200 OK
• 409
  • 2006 node not ready
  • 2007 node is running
  • 2008 node not running
  • 2009 node is stopped

Body

{
    //node id
    "id": 4,
    //0 start, 1 stop
    "cmd": 0
}

Response

{
    "error": 0
}

Get Node State

GET /api/v2/node/state

Request Params

node_id required

Request Headers

Authorization Bearer \

Response Status

• 200 OK

Response

{
    //running state
    "running": 2,
    //link state
    "link": 1
}

Get Subscribe Group Config

GET /api/v2/subscribe

Request Params

node_id required

Request Headers

Authorization Bearer \

Response Status

• 200
• 400

Response

{
    "groups": [
        {
            //node id
            "node_id": 1,
            //group config name
            "group_config_name": "g1name"
        },
        {
            "node_id": 2,
            "group_config_name": "g2name"
        }
    ]
}

Get Log

GET /api/v2/log

Request Params

since required, UTC timestamp

until required, UTC timestamp, with since forms the interval [since, until)

level optional, log level, should be one of trace, debug, info, warn, error, fatal

page required

page_size required, should be in range [200, 10000]

Request Headers

Authorization Bearer \

Response Status

• 200
• 400
  • 1003 param is wrong

Response

{
    "error": 0,
    "rows": [
        "2022-02-11 15:30:57 WARN  [neuron] src/main.c:90: recv sig: 2"
    ]
}