Merge pull request #19 from YuyueBalabala/main-api-en

doc: add en_US api doc and modify en_US directory.
emqx · Nov 14, 2023 · 6d76b0b · 6d76b0b
2 parents 6a6d5c4 + 3c7b165
commit 6d76b0b
Show file tree

Hide file tree

Showing 11 changed files with 862 additions and 41 deletions.
diff --git a/directory.json b/directory.json
@@ -692,7 +692,7 @@
         }
       ]
       },
-      {
+    {
         "title": "HTTP API",
         "path": "api/api",
         "collapsed": true,
@@ -715,7 +715,7 @@
           }
         ]
       },
-      {
+    {
         "title": "运维指南",
         "path": "admin/introduction",
         "url": "",
@@ -744,17 +744,22 @@
         "path": "release_history/release_history"
       }
     ],
-    "en": [
+  "en": [
     {
-      "title": "产品概览",
+      "title": "Product Overview",
       "path": "./",
+      "collapsed": true,
       "children": [
         {
-          "title": "数采插件列表",
+          "title": "Architecture",
+          "path": "introduction/architecture"
+        },
+        {
+          "title": "List of Data Collection Plugins",
           "path": "introduction/plugin-list/plugin-list"
         },
         {
-          "title": "许可证政策",
+          "title": "Licensing Policy",
           "path": "introduction/license/license-policy"
         }
       ]
@@ -769,21 +774,21 @@
       "collapsed": true,
       "children": [
         {
-          "title": "使用 .tar.gz 包安装",
+          "title": "Installation with .tar.gz Package",
           "path": "installation/tar.gz"
         },
         {
           "title": "Docker",
           "path": "installation/docker"
         },
         {
-          "title": "申请和安装许可证",
+          "title": "Application and Installation License",
           "path": "installation/license_setting"
         }
       ]
     },
     {
-      "title": "数据采集",
+      "title": "Data Collection",
       "path": "configuration/introduction",
       "collapsed": true,
       "children": [
@@ -1156,17 +1161,17 @@
           ]
         },
         {
-          "title": "连接南向设备",
+          "title": "Connecting Southbound Equipment",
           "path": "configuration/groups-tags/groups-tags",
           "collapsed": true,
           "children": [
             {
-              "title": "基于模板配置",
+              "title": "Template-based Configuration",
               "path": "configuration/templates/templates",
               "url": "https://raw.githubusercontent.com/emqx/neuron-docs/master/en_US/configuration/templates/templates.md"
             },
             {
-              "title": "批量点位配置",
+              "title": "Batch Tag Configuration",
               "path": "configuration/import-export/import-export",
               "url": "https://raw.githubusercontent.com/emqx/neuron-docs/master/en_US/configuration/import-export/import-export.md"
             }
@@ -1255,25 +1260,26 @@
           ]
         },
         {
-          "title": "订阅南向数据",
+          "title": "Subscribe to Southbound Data",
           "path": "configuration/subscription"
         },
         {
-          "title": "管理插件模块",
+          "title": "Managing Plug-in Modules",
           "path": "configuration/ecp_edge_plugin"
         },
         {
-          "title": "数据监控",
+          "title": "Data Monitoring",
           "path": "admin/monitoring"
         }
       ]
     },
     {
-      "title": "数据流处理",
+      "title": "Data Stream Processing",
       "path": "streaming-processing/overview",
+      "collapsed": true,
       "children": [
         {
-          "title": "数据源",
+          "title": "Data Sources",
           "path": "streaming-processing/source",
           "collapsed": true,
           "children": [
@@ -1326,24 +1332,24 @@
           ]
         },
         {
-          "title": "规则管理",
+          "title": "Rule Management",
           "path": "streaming-processing/rules"
         },
         {
-          "title": "规则管道",
+          "title": "Rules Pipeline",
           "path": "streaming-processing/rule_pipeline"
         },
         {
-          "title": "数据汇（Sink）",
+          "title": "Sink",
           "path": "streaming-processing/sink/sink",
           "collapsed": true,
           "children": [
             {
-              "title": "数据模版",
+              "title": "Data Templates",
               "path": "streaming-processing/sink/data_template"
             },
             {
-              "title": "内置插件",
+              "title": "Built-in Plugins",
               "children": [
                 {
                   "title": "MQTT Sink",
@@ -1366,11 +1372,11 @@
                   "path": "streaming-processing/sink/redis"
                 },
                 {
-                  "title": "文件 Sink",
+                  "title": "File Sink",
                   "path": "streaming-processing/sink/file"
                 },
                 {
-                  "title": "内存 Sink",
+                  "title": "Memory Sink",
                   "path": "streaming-processing/sink/memory"
                 },
                 {
@@ -1384,7 +1390,7 @@
               ]
             },
             {
-              "title": "预定义插件",
+              "title": "Predefined Plugins",
               "children": [
                 {
                   "title": "SQL Sink",
@@ -1419,24 +1425,48 @@
           ]
         },
         {
-          "title": "扩展",
+          "title": "Extensions",
           "path": "streaming-processing/extension",
           "children":[
             {
-              "title": "外部服务",
+              "title": "External Services",
               "path": "streaming-processing/external_func"
             }
           ]
         },
         {
-          "title": "配置管理",
+          "title": "Configuration Management",
           "path": "streaming-processing/config"
         }
       ]
       },
-      {
+    {
+      "title": "HTTP API",
+      "path": "api/api",
+      "collapsed": true,
+      "children": [
+        {
+          "title": "JWT Authentication",
+          "path": "api/jwt"
+        },
+        {
+          "title": "Description of data types for data collection functions",
+          "path": "api/data-type"
+        },
+        {
+          "title": "Description of the data collection function error code",
+          "path": "api/error-code"
+        },
+        {
+          "title": "API Documentation",
+          "path": "https://docs.emqx.com/en/neuronex/latest/api/api-docs.html"
+        }
+      ]
+    },
+    {
         "title": "Operations Guide",
         "path": "admin/introduction",
+        "collapsed": true,
         "children": [
           {
             "title": "Configuration Management",
@@ -1447,14 +1477,14 @@
             "path": "admin/log-management"
           },
           {
-            "title": "修改密码",
+            "title": "Change Password",
             "path": "admin/password"
           }
         ]
-      },
-      {
-        "title": "发版历史",
+    },
+    {
+        "title": "Publishing History",
         "path": "release_history/release_history"
-      }
+    }
     ]
   }
diff --git a/en_US/api/api.md b/en_US/api/api.md
@@ -0,0 +1,16 @@
+# HTTP API
+
+NeuronEX provides management and monitoring REST APIs that conform to the OpenAPI (Swagger) 3.1 specification.
+
+Once the NeuronEX service is started, you can access http://localhost:8085/api-docs/index.html to view the API documentation. You can also try executing some of the APIs directly in the Swagger UI.
+
+This section will guide you on how to get started with the NeuronEX REST API quickly.
+
+[JWT authentication:](./jwt.md) The API uses JWT authentication to ensure secure communication and authentication between IIoT platforms or monitoring applications and NeuronEX devices. This enhances the overall security of the system.
+
+[Data type description:](./data-type.md) To ensure that data is represented and interpreted clearly and consistently, the API describes the data types used. This facilitates seamless integration and analysis of data in IIoT platforms or monitoring applications.
+
+[Data collection function error code description:](./error-code.md) The API includes comprehensive error code descriptions that provide information about the nature and cause of the errors encountered. This helps with effective troubleshooting and issue resolution.
+
+[API documentation:](https://docs.emqx.com/en/neuronex/latest/api/api-docs.html) Includes the relevant APIs for system, data collection, and data statistics functions.
+
diff --git a/en_US/api/data-type.md b/en_US/api/data-type.md
@@ -0,0 +1,116 @@
+# Data collection function data types
+
+## Concepts
+
+### Node
+
+In NeuronEX, each node can connect to a device or a northbound application.
+
+* In the device node, you can add and manage device tags.
+* In the northbound node, you can select the data groups that you need to subscribe to.
+
+### Group
+
+You can create multiple data groups under each node to categorize tags. For example, if a device is connected to multiple temperature sensors and multiple humidity sensors, you can create two data groups, temperature and humidity to categorize the collected tags. NeuronEX uploads the collected data to the northbound application by group.
+
+### Tag
+
+You can create multiple collection tags under each group. For example, if a temperature sensor collects multiple temperature values, each temperature value is a tag.
+
+### Plugin
+
+In NeuronEX, each plugin corresponds to an implementation of a protocol. For example, one Modbus TCP protocol corresponds to one plugin, and the MQTT protocol corresponds to one plugin.
+
+## Data types
+
+* 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
+
+## Serial port
+
+### Baud rate
+
+* 115200 = 0
+* 57600  = 1
+* 38400  = 2
+* 19200  = 3
+* 9600   = 4
+* 4800   = 5
+* 2400   = 6
+* 1800   = 7
+* 1200   = 8
+* 600    = 9
+
+### Parity
+
+* NONE   = 0
+* ODD    = 1
+* EVEN   = 2
+* MARK   = 3
+* SPACE  = 4
+
+### Stop bit
+
+* Stop_1 = 0
+* Stop_2 = 1
+
+### Data bits
+
+* Data_5 = 0
+* Data_6 = 1
+* Data_7 = 2
+* Data_8 = 3
+
+## Tag attributes
+
+* READ = 0x01
+
+* WRITE = 0x02
+
+* SUBSCRIBE = 0x04
+
+## Node
+
+### Node type
+
+* DRIVER = 1
+* APP = 2
+
+### Node control
+
+* START = 0
+* STOP = 1
+
+### Node status
+
+* INIT = 1
+* READY = 2
+* RUNNING = 3
+* STOPPED = 4
+
+### Node connection status
+
+* DISCONNECTED = 0
+* CONNECTED = 1
+
+## Plugin type
+
+* STATIC = 0
+* SYSTEM = 1
+* CUSTOM = 2