HTTP 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

Baud

  • 115200 = 0
  • 57600 = 1
  • 38400 = 2
  • 19200 = 3
  • 9600 = 4

Parity

  • NONE = 0
  • ODD = 1
  • EVEN = 2
  • MARK = 3
  • SPACE = 4

Stop

  • Stop_1 = 0
  • Stop_2 = 1

Data

  • Data_5 = 0
  • Data_6 = 1
  • Data_7 = 2
  • Data_8 = 3

Data Type

  • INT8 = 1
  • UINT8 = 2
  • INT16 = 3
  • UINT16 = 4
  • INT32 = 5
  • UINT32 = 6
  • INT64 = 7
  • UINT64 = 8
  • FLOAT = 9
  • DOUBLE = 10
  • BIT = 11
  • BOOL = 12
  • STRING = 13
  • BYTES = 14
  • ERROR = 15
  • WORD = 16
  • DWORD = 17
  • LWORD = 18

Data Attribute

  • READ = 0x01

  • WRITE = 0x02

  • SUBSCRIBE = 0x04

Node Type

  • DRIVER = 1
  • APP = 2

Plugin Kind

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

Node CTL

  • START = 0
  • STOP = 1

Node State

  • INIT = 1
  • READY = 2
  • RUNNING = 3
  • STOPPED = 4
  • DISCONNECTED = 0
  • CONNECTED = 1

Ping

POST /api/v2/ping

Request Headers

Authorization Bearer <token>

Response Status

  • 200 OK

Login

POST /api/v2/login

Request Headers

Content-Type application/json

Response Status

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

Body

  1. {
  2. "name": "admin",
  3. "pass": "0000"
  4. }

Response

  1. {
  2. "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzcyODcxNjMsImlhdCI6MTYzNzIwMDc2MywiaXNzIjoiRU1RIFRlY2hub2xvZ2llcyBDby4sIEx0ZCBBbGwgcmlnaHRzIHJlc2VydmVkLiIsInBhc3MiOiIwMDAwIiwidXNlciI6ImFkbWluIn0.2EZzPC9djErrCeYNrK2av0smh-eKxDYeyu7cW4MyknI"
  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

  1. {
  2. "name": "admin",
  3. "old_pass": "01234",
  4. "new_pass": "56789"
  5. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //node name
  3. "name": "modbus-tcp-node",
  4. //plugin name
  5. "plugin": "modbus-plugin-tcp"
  6. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //node name
  3. "name": "modbus-tcp-test"
  4. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //node id
  3. "id": 1,
  4. //node name
  5. "name": "modbus-tcp-node"
  6. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. "nodes": [
  3. {
  4. //node name
  5. "name": "sample-driver-adapter",
  6. //plugin name
  7. "plugin": "modbus-tcp"
  8. },
  9. {
  10. "name": "modbus-tcp-adapter",
  11. "plugin": "modbus-tcp"
  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

  1. //The parameter fields in json fill in different fields according to different plugins
  2. {
  3. //node name
  4. "node": "modbus-node",
  5. "params": {
  6. "param1": 1,
  7. "param2": "1.1.1.1",
  8. "param3": true,
  9. "param4": 11.22
  10. }
  11. }

TIP

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

Response

  1. {
  2. "error": 0
  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

  1. //The parameter fields in json fill in different fields according to different plugins
  2. {
  3. "node": "modbus-node",
  4. "params": {
  5. "param1": "1.1.1.1",
  6. "param2": 502
  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

  1. {
  2. //node name
  3. "node": "modbus-node",
  4. //0 start, 1 stop
  5. "cmd": 0
  6. }

Response

  1. {
  2. "error": 0
  3. }

Get Node State

GET /api/v2/node/state

Request Params

node optional

Request Headers

Authorization Bearer <token>

Response Status

  • 200 OK

Response

  1. {
  2. //running state
  3. "running": 2,
  4. //link state
  5. "link": 1,
  6. //average round trip time communicating with devices
  7. "average_rtt": 100
  8. }
  9. {
  10. "states": [
  11. {
  12. "node": "modbus-node1",
  13. "running": 2,
  14. "link": 1,
  15. "average_rtt": 100
  16. },
  17. {
  18. "node": "modbus-node2",
  19. "running": 1,
  20. "link": 0,
  21. "average_rtt": 9999
  22. }
  23. ]
  24. }

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

  1. {
  2. //group name
  3. "name": "gconfig1",
  4. //node name
  5. "node": "modbus-node",
  6. //read/upload interval(ms)
  7. "interval": 10000
  8. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //node name
  3. "node": "modbus-node",
  4. //group name
  5. "group": "gconfig1"
  6. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //group name
  3. "group": "gconfig1",
  4. //node name
  5. "node": "modbus-node",
  6. //read/upload interval(ms)
  7. "interval": 10000
  8. }

Response

  1. {
  2. "error": 0
  3. }

Get Group

GET /api/v2/group

Request Params

node optional

Request Headers

Authorization Bearer <token>

Response Status

  • 200 OK

Response

  1. {
  2. "groups": [
  3. {
  4. //group name
  5. "name": "config_modbus_tcp_sample_2",
  6. //read/upload interval(ms)
  7. "interval": 2000,
  8. //tag count
  9. "tag_count": 0
  10. },
  11. {
  12. "name": "gconfig1",
  13. "interval": 10000,
  14. "tag_count": 0
  15. }
  16. ]
  17. }
  1. {
  2. "groups": [
  3. {
  4. //node name
  5. "driver": "modbus",
  6. //group name
  7. "group": "group1",
  8. "tag_count": 1,
  9. "interval": 1000
  10. },
  11. {
  12. "driver": "modbus",
  13. "group": "group2",
  14. "tag_count": 0,
  15. "interval": 100
  16. },
  17. {
  18. "driver": "modbus1",
  19. "group": "group",
  20. "tag_count": 0,
  21. "interval": 10001
  22. }
  23. ]
  24. }

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

  1. {
  2. //node name
  3. "node": "modbus-node",
  4. //group name
  5. "group": "config_modbus_tcp_sample_2",
  6. "tags": [
  7. {
  8. //tag name
  9. "name": "tag1",
  10. //tag address
  11. "address": "1!400001",
  12. //tag attribute
  13. "attribute": 1,
  14. //tag type
  15. "type": 4,
  16. //float/double precision, optional(0-17)
  17. "precision": 3,
  18. //decimal
  19. "decimal": 1
  20. },
  21. {
  22. "name": "tag2",
  23. "address": "1!00001",
  24. "attribute": 3,
  25. "type": 14
  26. },
  27. {
  28. "name": "tag3",
  29. "address": "1!400009",
  30. "attribute": 3,
  31. "type": 11
  32. }
  33. ]
  34. }

Response

  1. {
  2. "index": 1,
  3. "error": 0
  4. }

Get Tag

GET /api/v2/tags

Request Params

node required

group required

name name

Request Headers

Authorization Bearer <token>

Response Status

  • 200 OK
  • 404
    • 2003 node not exist

Response

  1. {
  2. "tags": [
  3. {
  4. //tag name
  5. "name": "tag1",
  6. //tag type
  7. "type": 4,
  8. //tag address
  9. "address": "1!400001",
  10. //tag attribute
  11. "attribute": 1,
  12. //float/double precision
  13. "precision": 1,
  14. //decimal
  15. "decimal": 0.1
  16. },
  17. {
  18. "name": "tag2",
  19. "type": 14,
  20. "address": "1!00001",
  21. "attribute": 3
  22. },
  23. {
  24. "name": "tag3",
  25. "type": 11,
  26. "address": "1!400009",
  27. "attribute": 3
  28. }
  29. ]
  30. }

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

  1. {
  2. //node name
  3. "node": "modbus-tcp-test",
  4. //group name
  5. "group": "group1",
  6. "tags": [
  7. {
  8. //tag name
  9. "name": "tag1",
  10. //tag type
  11. "type": 6,
  12. //tag attribute
  13. "attribute": 0,
  14. //tag address
  15. "address": "1!400001",
  16. //float/double precison
  17. "precision": 1,
  18. //decimal
  19. "decimal": 0.001
  20. },
  21. {
  22. "name": "tag2",
  23. "type": 6,
  24. "attribute": 0,
  25. "address": "1!400002"
  26. }
  27. ]
  28. }

Response

  1. {
  2. "error": 0
  3. }

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

  1. {
  2. //group name
  3. "group": "config_modbus_tcp_sample_2",
  4. //node name
  5. "node": "modbus-node",
  6. //tag name
  7. "tags": [
  8. "tag1",
  9. "tag2"
  10. ]
  11. }

Response

  1. {
  2. "error": 0
  3. }

Read Tag

POST /api/v2/read

Request Headers

Content—Type application/json

Authorization Bearer <token>

Response Status

  • 200

Body

  1. {
  2. //node name
  3. "node": "modbus-tcp-1",
  4. //group name
  5. "group": "config_modbus_tcp_sample_2"
  6. }

Response

  1. {
  2. "tags": [
  3. {
  4. //tag nmae
  5. "name": "data1",
  6. //tag value
  7. "value": 1,
  8. },
  9. {
  10. "name": "data2",
  11. "error": 2014
  12. },
  13. {
  14. "name": "data3",
  15. "value": true,
  16. }
  17. ]
  18. }

TIP

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 <token>

Response Status

  • 200 OK

Body

  1. {
  2. "node": "modbus-tcp-1",
  3. "group": "config_modbus_tcp_sample_2",
  4. "tag": "tag1",
  5. "value": 1234
  6. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //plugin library name
  3. "library": "plugin_name.so"
  4. }

Response

  1. {
  2. "error": 0
  3. }

Del Plugin

DELETE /api/v2/plugin

Request Headers

Content-Type application/json

Authorization Bearer <token>

Response Status

  • 200 OK

Body

  1. {
  2. //plugin name
  3. "plugin": "modbus-tcp"
  4. }

Response

  1. {
  2. "error": 0
  3. }

Get Plugin

GET /api/v2/plugin

Request Params

plugin optional

Request Headers

Authorization Bearer <token>

Response Status

  • 200 OK

Response

  1. {
  2. "plugins": [
  3. {
  4. //plugin kind
  5. "kind": 1,
  6. //node type
  7. "node_type": 1,
  8. //plugin name
  9. "name": "plugin_name",
  10. //plugin library name
  11. "library": "plugin_lib_name",
  12. "description": "description",
  13. "description_zh": "描述"
  14. }
  15. ]
  16. }

Subscribe

POST /api/v2/subscribe

Request Headers

Content-Type application/json

Authorization Bearer <token>

Response Status

  • 200 OK
  • 404
    • 2106 group not exist

Body

  1. {
  2. //app name
  3. "app": "mqtt-node",
  4. //driver name
  5. "driver": "modbus-node",
  6. //driver node group name
  7. "group": "gconfig1"
  8. }

Response

  1. {
  2. "error": 0
  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

  1. {
  2. //app name
  3. "app": "mqtt-node",
  4. //driver name
  5. "driver": "driver-node",
  6. //driver node group name
  7. "group": "gconfig1"
  8. }

Response

  1. {
  2. "error": 0
  3. }

Get Plugin Schema

GET /api/v2/schema

Request Params

plugin_name required

Request Headers

Authorization Bearer <token>

Response Status

  • 200 OK

Response

  1. {
  2. "tag_type": [
  3. 4,
  4. 5,
  5. 6,
  6. 7,
  7. 8,
  8. 9,
  9. 10,
  10. 11,
  11. 14
  12. ],
  13. "params": [
  14. "host",
  15. "port",
  16. "mode",
  17. "baud_rate",
  18. "real_param"
  19. ],
  20. "host": {
  21. "name": "host",
  22. "description": "host",
  23. "type": "string",
  24. "default": "127.0.0.1",
  25. "valid": {
  26. "length": 30
  27. }
  28. },
  29. "port": {
  30. "name": "port",
  31. "description": "port",
  32. "type": "int",
  33. "default": 502,
  34. "valid": {
  35. "min": 1024,
  36. "max": 65535
  37. }
  38. },
  39. "mode": {
  40. "name": "mode",
  41. "description": "mode",
  42. "type": "bool",
  43. "default": false,
  44. "valid": {}
  45. },
  46. "baud_rate": {
  47. "name": "baud rate",
  48. "description": "port",
  49. "type": "int",
  50. "default": 9600,
  51. "valid": {
  52. "value": [
  53. 9600,
  54. 112800
  55. ]
  56. }
  57. },
  58. "real_param": {
  59. "name": "real param",
  60. "description": "real",
  61. "type": "real",
  62. "default": 11.22,
  63. "valid": {
  64. "min": 1.1,
  65. "max": 20.2
  66. }
  67. },
  68. "ca": {
  69. "name": "ca",
  70. "description": "",
  71. "attribute": "optional",
  72. "type": "file",
  73. "condition": {
  74. "field": "mode",
  75. "value": true
  76. },
  77. "valid": {
  78. "length": 1024
  79. }
  80. }
  81. }

Get Subscribe Group

GET /api/v2/subscribe

Request Params

app required

Request Headers

Authorization Bearer <token>

Response Status

  • 200
  • 400

Response

  1. {
  2. "groups": [
  3. {
  4. //driver name
  5. "driver": "modbus-node",
  6. //group name
  7. "group": "g1name"
  8. },
  9. {
  10. "driver": "modbus-node",
  11. "group": "g2name"
  12. }
  13. ]
  14. }

Get Version

GET /api/v2/version

Request Headers

Authorization Bearer <token>

Response Status

  • 200
  • 500
    • 1001 internal error

Response

  1. {
  2. "build_date": "2022-06-01",
  3. "revision": "99e2184+dirty", // dirty indicates uncommit changes
  4. "version": "2.0.1"
  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

  1. {
  2. "license": "-----BEGIN CERTIFICATE-----\nMIID2TCCAsGgAwIBAgIEATSJqjA....."
  3. }

Response

  1. {
  2. "error": 2401
  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

  1. {
  2. "error": 0,
  3. "license_type": "trial",
  4. "max_nodes": 1000,
  5. "max_node_tags": 20000,
  6. "valid": true,
  7. "valid_since": "2022-03-30 09:10:40",
  8. "valid_until": "2023-03-30 09:10:40",
  9. "enabled_plugins": ["modbus-rtu", "opcua", "s7comm"]
  10. }

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:

  1. {
  2. "error": 1014
  3. }

Update node log level

PUT /api/v2/level

Request Headers

Authorization Bearer <token>

Response Status

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

Body

  1. {
  2. "node_name": "modbus-tcp"
  3. }

Response

  1. {
  2. "error": 0
  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.

Get Metrics

GET /api/v2/metrics

Request Headers

Authorization Bearer <token>

Request Params

category optional, one of global, driver and app node optional, filter with node name, only meaningful when category=driver or category=app

Response Status

  • 200 OK
  • 400 Bad request
  • 500 Internal server error

Response

  1. # HELP core_dumped Whether there is any core dump
  2. # TYPE core_dumped gauge
  3. core_dumped 0
  4. # HELP uptime_seconds Uptime in seconds
  5. # TYPE uptime_seconds counter
  6. uptime_seconds 314
  7. # HELP north_nodes_total Number of north nodes
  8. # TYPE north_nodes_total gauge
  9. north_nodes_total 1
  10. # HELP north_running_nodes_total Number of north nodes in running state
  11. # TYPE north_running_nodes_total gauge
  12. north_running_nodes_total 1
  13. # HELP north_disconnected_nodes_total Number of north nodes disconnected
  14. # TYPE north_disconnected_nodes_total gauge
  15. north_disconnected_nodes_total 1
  16. # HELP south_nodes_total Number of south nodes
  17. # TYPE south_nodes_total gauge
  18. south_nodes_total 1
  19. # HELP south_running_nodes_total Number of south nodes in running state
  20. # TYPE south_running_nodes_total gauge
  21. south_running_nodes_total 0
  22. # HELP south_disconnected_nodes_total Number of south nodes disconnected
  23. # TYPE south_disconnected_nodes_total gauge
  24. south_disconnected_nodes_total 1
  25. # HELP send_msgs_total Total number of messages sent
  26. # TYPE send_msgs_total counter
  27. send_msgs_total{node="data-stream-processing"} 0
  28. # HELP send_msg_errors_total Total number of errors sending messages
  29. # TYPE send_msg_errors_total counter
  30. send_msg_errors_total{node="data-stream-processing"} 0
  31. # HELP recv_msgs_total Total number of messages received
  32. # TYPE recv_msgs_total counter
  33. recv_msgs_total{node="data-stream-processing"} 0
  34. # HELP last_rtt_ms Last request round trip time in milliseconds
  35. # TYPE last_rtt_ms gauge
  36. last_rtt_ms{node="modbus"} 9999
  37. # HELP send_bytes Total number of bytes sent
  38. # TYPE send_bytes gauge
  39. send_bytes{node="modbus"} 0
  40. # HELP recv_bytes Total number of bytes received
  41. # TYPE recv_bytes gauge
  42. recv_bytes{node="modbus"} 0
  43. # HELP tag_reads_total Total number of tag reads including errors
  44. # TYPE tag_reads_total counter
  45. tag_reads_total{node="modbus"} 0
  46. # HELP tag_read_errors_total Total number of tag read errors
  47. # TYPE tag_read_errors_total counter
  48. tag_read_errors_total{node="modbus"} 0
  49. # HELP group_tags_total Total number of tags in the group
  50. # TYPE group_tags_total gauge
  51. group_tags_total{node="modbus",group="grp"} 1
  52. # HELP group_last_send_msgs Number of messages sent on last group timer invocation
  53. # TYPE group_last_send_msgs gauge
  54. group_last_send_msgs{node="modbus",group="grp"} 0
  55. # HELP group_last_timer_ms Time in milliseconds consumed on last group timer invocation
  56. # TYPE group_last_timer_ms gauge
  57. group_last_timer_ms{node="modbus",group="grp"} 0