# Configuration

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.

# Ping

POST /api/v2/ping

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK

POST /api/v2/login

# Request Headers

Content-Type application/json

# Response Status

200 OK
401
- 1004, 缺少令牌
- 1005, 解码令牌错误
403
- 1006, 令牌过期
- 1007, 验证令牌错误
- 1008, 无效令牌

# Body

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

1
2
3
4

# Response

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

1
2
3

# Password

POST /api/v2/password

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
401
- 1004 missing token
- 1005 decoding token error
- 1012 password length too short or too long
- 1013 duplicate password
403
- 1006 expired token
- 1007 validate token error
- 1008 invalid token

# Body

{
    "name": "admin",
    "old_pass": "01234",
    "new_pass": "56789"
}

1
2
3
4
5

# Response

{
    "error": 0
}

1
2
3

# Add Node

POST /api/v2/node

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

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

# Body

{
    //node name
    "name": "modbus-tcp-node",
    //plugin name
    "plugin": "Modbus TCP"
}

1
2
3
4
5
6

# Response

{
    "error": 0
}

1
2
3

# Del Node

Delete /api/v2/node

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2003 node not exist

# Body

{
    //node name
    "name": "modbus-tcp-node"
}

1
2
3
4

# Response

{
    "error": 0
}

1
2
3

# Update Node(Not Implemented)

PUT /api/v2/node

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2003 node exist

# Body

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

1
2
3
4
5
6

# Response

{
    "error": 0
}

1
2
3

# Get Node

GET /api/v2/node

# Request Params

type required

plugin optional

node optional

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK

# Response

{
    "nodes": [
        {
            //node name
            "name": "sample-driver-adapter",
            //plugin name
            "plugin": "Modbus TCP"
        },
        {
            "name": "modbus-tcp-adapter",
            "plugin": "Modbus TCP"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Node Setting

POST /api/v2/node/setting

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# 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 name
    "node": "modbus-node",
    "params": {
        "param1": 1,
        "param2": "1.1.1.1",
        "param3": true,
        "param4": 11.22
    }
}

1
2
3
4
5
6
7
8
9
10
11

TIP

Please refer to Plugin Setting for the configuration parameters of each plugin.

# Response

{
    "error": 0
}

1
2
3

# Get Node Setting

GET /api/v2/node/setting

# Request Params

node required

# Request Headers

Authorization Bearer <token>

# 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": "modbus-node",
    "params": {
        "param1": "1.1.1.1",
        "param2": 502
    }
}

1
2
3
4
5
6
7
8

# Node CTL

POST /api/v2/node/ctl

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Request Status

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

# Body

{
    //node name
    "node": "modbus-node",
    //0 start, 1 stop
    "cmd": 0
}

1
2
3
4
5
6

# Response

{
    "error": 0
}

1
2
3

# Get Node State

GET /api/v2/node/state

# Request Params

node optional

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK

# Response

{
    "states": [
        {
            // node name
            "node": "modbus-node1",
            //running state
            "running": 2,
            //link state
            "link": 1,
            //average round trip time communicating with devices
            "rtt": 100
        },
        {
            "node": "modbus-node2",
            "running": 1,
            "link": 0,
            "rtt": 9999
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Add Group

POST /api/v2/group

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2003 node not exist
409
- 2103 group not allow

# Body

{
    //group name
    "name": "gconfig1",
    //node name
    "node": "modbus-node",
    //read/upload interval(ms)
    "interval": 10000
}

1
2
3
4
5
6
7
8

# Response

{
    "error": 0
}

1
2
3

# Del Group

DELETE /api/v2/group

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
412
- 2101 group already subscribed
404
- 2003 node not exist
- 2106 group not exist

# Body

{
    //node name
    "node": "modbus-node",
    //group name
    "group": "gconfig1"
}

1
2
3
4
5
6

# Response

{
    "error": 0
}

1
2
3

# Update Group

PUT /api/v2/group

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2106 group not exist

# Body

{
    //group name
    "group": "gconfig1",
    //node name
    "node": "modbus-node",
    //read/upload interval(ms)
    "interval": 10000
}

1
2
3
4
5
6
7
8

# Response

{
    "error": 0
}

1
2
3

# Get Group

GET /api/v2/group

# Request Params

node optional

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK

# Response

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Add Tag

POST /api/v2/tags

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# 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 name
    "node": "modbus-node",
   //group name
    "group": "config_modbus_tcp_sample_2",
    "tags": [
        {
           //tag name
            "name": "tag1",
           //tag address
            "address": "1!400001",
           //tag attribute
            "attribute": 8,
           //tag type
            "type": 4,
           //optional, float/double precision, optional(0-17)
            "precision": 0,
           //optional, decimal
            "decimal": 0,
           //optional, description
           "description": "",
           //optional, when the attribute is static,the value field needs to be added.
           "value": 12
        },
        {
            "name": "tag2",
            "address": "1!00001",
            "attribute": 3,
            "type": 3,
            "decimal": 0.01
        },
        {
            "name": "tag3",
            "address": "1!400009",
            "attribute": 3,
            "type": 9,
            "precision": 3
        },
        {
            "name": "static_tag",
            "address": "",
            "attribute": 10,
            "type": 1,
            "description": "It is a static tag",
            "value": 42
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# Response

{
    "index": 1,
    "error": 0
}

1
2
3
4

# Get Tag

GET /api/v2/tags

# Request Params

node required

group required

name optional

# Request Headers

Authorization Bearer <token>

# 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": 8,
            //description
            "description": "",
            //float/double precision
            "precision": 0,
            //decimal
            "decimal": 0,
            //optional, when the attribute is static
            "value": 12
        },
        {
            "name": "tag2",
            "type": 14,
            "address": "1!00001",
            "attribute": 3,
            "description": "",
            "precison": 0,
            "decimal": 0,
        },
        {
            "name": "tag3",
            "type": 11,
            "address": "1!400009",
            "attribute": 3,
            "description": "",
            "precison": 0,
            "decimal": 0,
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# Update Tag

PUT /api/v2/tags

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# 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
- 2106 group not exist

# Body

{
    //node name
    "node": "modbus-tcp-test",
    //group name
    "group": "group1",
    "tags": [
        {
            //tag name
            "name": "tag1",
            //tag type
            "type": 8,
            //tag attribute
            "attribute": 0,
            //tag address
            "address": "1!400001",
            //description
            "description":"",
            //float/double precison
            "precision": 0,
            //decimal
            "decimal": 0,
            //optional, when the attribute is static,the value field needs to be added.
            "value": 12
        },
        {
            "name": "tag2",
            "type": 6,
            "attribute": 0,
            "address": "1!400002",
            "description":"",
            "precison": 0,
            "decimal": 0,
        },
        {
            "name": "static_tag",
            "address": "",
            "attribute": 10,
            "type": 8,
            "description":"",
            "precison": 0,
            "decimal": 0,
            "value": 42
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# Response

{
    "error": 0,
    "index": 1
}

1
2
3
4

# Del Tag

DELETE /api/v2/tags

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2003 node not exist

# Body

{
    //group name
    "group": "config_modbus_tcp_sample_2",
    //node name
    "node": "modbus-node",
    //tag name
    "tags": [
        "tag1",
        "tag2"
    ]
}

1
2
3
4
5
6
7
8
9
10
11

# Response

{
    "error": 0
}

1
2
3

# Add Plugin

POST /api/v2/plugin

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
400
- 2302 library info invalid

# Body

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

1
2
3
4

# Response

{
    "error": 0
}

1
2
3

# Del Plugin

DELETE /api/v2/plugin

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK

# Body

{
    //plugin name
   "plugin": "modbus-tcp"
}

1
2
3
4

# Response

{
    "error": 0
}

1
2
3

# Get Plugin

GET /api/v2/plugin

# Request Params

plugin optional

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK

# Response

{
    "plugins": [
        {
            //plugin kind
            "kind": 1,
            //node type
            "node_type": 1,
            //plugin name
            "name": "Modbus TCP",
            //plugin library name
            "library": "libplugin-modbus-tcp.so",
            "description": "description",
            "description_zh": "描述",
            "schema": "modbus-tcp"
        },
        {
            "kind": 1,
            "node_type": 2,
            "name": "MQTT",
            "library": "libplugin-mqtt.so",
            "description": "Neuron northbound MQTT plugin bases on NanoSDK.",
            "description_zh": "基于 NanoSDK 的 Neuron 北向应用 MQTT 插件",
            "schema": "mqtt"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Get Plugin Schema

GET /api/v2/schema

# Request Params

schema_name required

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK

# Response

{
    "tag_regex": [
        {
            "type": 3,
            "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$"
        },
        {
            "type": 4,
            "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$"
        },
        {
            "type": 5,
            "regex": "^[0-9]+![3-4][0-9]+(#BB|#BL|#LL|#LB|)$"
        },
        {
            "type": 6,
            "regex": "^[0-9]+![3-4][0-9]+(#BB|#BL|#LL|#LB|)$"
        },
        {
            "type": 7,
            "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$"
        },
        {
            "type": 8,
            "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$"
        },
        {
            "type": 9,
            "regex": "^[0-9]+![3-4][0-9]+(#BB|#BL|#LL|#LB|)$"
        },
        {
            "type": 10,
            "regex": "^[0-9]+![3-4][0-9]+(#B|#L|)$"
        },
        {
            "type": 11,
            "regex": "^[0-9]+!([0-1][0-9]+|[3-4][0-9]+\\.([0-9]|[0-1][0-5]))$"
        },
        {
            "type": 13,
            "regex": "^[0-9]+![3-4][0-9]+\\.[0-9]+(H|L|)$"
        }
    ],
    "group_interval": 1000,
    "connection_mode": {
        "name": "Connection Mode",
        "name_zh": "连接模式",
        "description": "Neuron as the client, or as the server",
        "description_zh": "Neuron 作为客户端或服务端",
        "attribute": "required",
        "type": "map",
        "default": 0,
        "valid": {
            "map": [
                {
                    "key": "Client",
                    "value": 0
                },
                {
                    "key": "Server",
                    "value": 1
                }
            ]
        }
    },
    "interval": {
        "name": "Send Interval",
        "name_zh": "指令发送间隔",
        "description": "Send reading instruction interval(ms)",
        "description_zh": "发送读指令时间间隔，单位为毫秒",
        "attribute": "required",
        "type": "int",
        "default": 20,
        "valid": {
            "min": 0,
            "max": 3000
        }
    },
    "host": {
        "name": "IP Address",
        "name_zh": "IP地址",
        "description": "Local IP in server mode, remote device IP in client mode",
        "description_zh": "服务端模式中填写本地 IP，客户端模式中填写目标设备 IP",
        "attribute": "required",
        "type": "string",
        "valid": {
            "regex": "/^((2[0-4]\\d|25[0-5]|[01]?\\d\\d?)\\.){3}(2[0-4]\\d|25[0-5]|[01]?\\d\\d?)$/",
            "length": 30
        }
    },
    "port": {
        "name": "Port",
        "name_zh": "端口号",
        "description": "Local port in server mode, remote device port in client mode",
        "description_zh": "服务端模式中填写本地端口号，客户端模式中填写远程设备端口号",
        "attribute": "required",
        "type": "int",
        "default": 502,
        "valid": {
            "min": 1,
            "max": 65535
        }
    },
    "timeout": {
        "name": "Connection Timeout",
        "name_zh": "连接超时时间",
        "description": "Connection timeout(ms)",
        "description_zh": "连接超时时间，单位为毫秒",
        "attribute": "required",
        "type": "int",
        "default": 3000,
        "valid": {
            "min": 1000,
            "max": 65535
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

POST /api/v2/subscribe

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2106 group not exist

# Body

{
    //app name
    "app": "mqtt",
    //driver name
    "driver": "modbus-tcp",
    //driver node group name
    "group": "group-1",
    //optional, when using the MQTT plugin, the topic field needs to be added
    "params": {
        "topic": "/neuron/mqtt/group-1"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

# Response

{
    "error": 0
}

1
2
3

# UnSubscribe

DELETE /api/v2/subscribe

# Request Headers

Content-Type application/json

Authorization Bearer <token>

# Response Status

200 OK
404
- 2106 group not exist

# Body

{
    //app name
    "app": "mqtt",
    //driver name
    "driver": "modbus-tcp",
    //driver node group name
    "group": "group-1",
    //optional, when using the MQTT plugin, the topic field needs to be added
    "params": {
        "topic": "/neuron/mqtt/group-1"
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

# Response

{
    "error": 0
}

1
2
3

GET /api/v2/subscribe

# Request Params

app required

# Request Headers

Authorization Bearer <token>

# Response Status

# Response

{
    "groups": [
        {
            //driver name
            "driver": "modbus-tcp",
            //group name
            "group": "group-1",
            //when using the MQTT plugin, the topic field needs to be added
            "params": {
                "topic": "/neuron/mqtt/group-1"
            }
        },
        {
            //driver name
            "driver": "modbus-tcp",
            //group name
            "group": "group-2",
            //when using the MQTT plugin, the topic field needs to be added
            "params": {
                "topic": "/neuron/mqtt/group-2"
            }
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Get Version

GET /api/v2/version

# Request Headers

Authorization Bearer <token>

# Response Status

200
500
- 1001 internal error

# Response

{
    "build_date": "2022-06-01",
    "revision": "99e2184+dirty", // dirty indicates uncommit changes
    "version": "2.4.0"
}

1
2
3
4
5

# Upload License

POST /api/v2/license

# Request Headers

Authorization Bearer <token>

# Response Status

200
- 0 OK
- 2402 license expired
400
- 2401 license invalid
500
- 1001 internal error

# Body

{
    "license": "-----BEGIN CERTIFICATE-----\nMIID2TCCAsGgAwIBAgIEATSJqjA....."
}

1
2
3

# Response

{
    "error": 2401
}

1
2
3

# Get License Info

GET /api/v2/license

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK
404
- 2400 license not found
500
- 1001 internal error

# Response

{
    "valid_until": "2023-03-15 08:11:19",
    "valid_since": "2022-03-15 08:11:19",
    "valid": false,
    "max_nodes": 1,
    "max_node_tags": 1,
    "used_nodes": 12,
    "used_tags": 846,
    "license_type": "retail",
    "error": 0,
    "enabled_plugins": [
        "MODBUS TCP Advance",
        "OPC UA"
    ],
    "hardware_token": "I+kZidSifiyVSbz0/EgcM6AcefnlfR4IU19ZZUnTS18=",
    "object": "emq",
    "email_address": "emq@emqx.io"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Download log files

GET /api/v2/logs

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK
404
- 1011 file not exist
- 1014 command execution failed
500
- 1001 internal error

# Response

Response if there is an error returned:

{
    "error": 1014
}

1
2
3

# Update node log level

PUT /api/v2/log/level

# Request Headers

Authorization Bearer <token>

# Response Status

200 OK
404
- 2003 node not exist
500
- 1001 internal error
- 1010 is busy

# Body

{
    "node_name": "modbus-tcp"
}

1
2
3

# Response

{
    "error": 0
}

1
2
3

TIP

Call the api to modify the log level of the node to debug, and automatically switch to the default level in about ten minutes.

# Download File

GET /api/v2/file

# Request Headers

Authorization Bearer <token>

# Request Params

file_path Required, absolute path of the file

# Response Status

404
- 1011 file not exist
- 4101 file open failure
- 4102 file read failure

# Response

Return the contents of the file and download the file, when responding correctly.

Return the error code, when an error response occurs.

{
    "error": 1011
}

1
2
3

# Get file list information

GET /api/v2/file/info

# Request Headers

Authorization Bearer <token>

# Request Params

dir_path Required, absolute path of the directory.

# Response Status

404
- 1011 file not exist
- 4101 file open failure

# Response

Response to the file name, size, creation time and update time, when responding correctly.

{
    "files": [
        {
            "name": "neuron",
            "size": 4096,
            "ctime": "Wed Jan  4 02:38:12 2023",
            "mtime": "Mon Dec 26 09:48:42 2022"
        },
        {
            "name": "test.txt",
            "size": 13,
            "ctime": "Wed Jan  4 02:38:12 2023",
            "mtime": "Mon Dec 26 09:48:42 2022"
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Response to the error code, when an error response occurs.

{
    "error": 1011
}

1
2
3

← Data Type Metrics →

# Configuration

# Ping

# Request Headers

# Response Status

# Login

# Request Headers

# Response Status

# Body

# Response

# Password

# Request Headers

# Response Status

# Body

# Response

# Add Node

# Request Headers

# Response Status

# Body

# Response

# Del Node

# Request Headers

# Response Status

# Body

# Response

# Update Node(Not Implemented)

# Request Headers

# Response Status

# Body

# Response

# Get Node

# Request Params

# Request Headers

# Response Status

# Response

# Node Setting

# Request Headers

# Response Status

# Body

# Response

# Get Node Setting

# Request Params

# Request Headers

# Response Status

# Response

# Node CTL

# Request Headers

# Request Status

# Body

# Response

# Get Node State

# Request Params

# Request Headers

# Response Status

# Response

# Add Group

# Request Headers

# Response Status

# Body

# Response

# Del Group

# Request Headers

# Response Status

# Body

# Response

# Update Group

# Request Headers

# Response Status

# Body

# Response

# Get Group

# Request Params

# Request Headers

# Response Status

# Response

# Add Tag

# Request Headers

# Response Status

# Body

# Response

# Get Tag