Update the readme with architecture designing and features

README-CN.md

@@ -6,17 +6,46 @@ Neuron是一个工业物联网（IIoT）边缘工业网关，用于现代大数
 
 2.0版本删除1.x版本不必要的功能，聚焦在工业协议的数据采集和转发的功能上。Neuron 2.0支持同时采集多台设备的数据
 
-## 功能
+## 设计目标和功能
+
+Neuron的设计目标是专注于工业物联网的数据采集、转发和汇聚，支持多种工业协议。将各种不同的工业设备的数据转换为MQTT消息，将这些独立的设备通过neuron融入到工业物联网的大系统中，可以在远端直接控制和获取信息。我们希望Neuron可以在低端嵌入式linux设备中运行，因此其有极少的内存占用，极低的CPU占用。同时Neuron也可以运行在有较大内存的linux主机中，以支持大量的连接设备和海量的数据点位，因此其具有良好的可伸缩性。
+
+Neuron有如下主要的功能和特性：
 
 - 插件化的南向设备驱动和北向应用；
-- 支持同时连接大量不同协议的设备；
-- 和EMQ的其他产品高度融合，包括eKuiper、EMQX、Fabric等；
+- 内置有轻量级的web server，可以通过浏览器来配置和控制、监听设备；
+- 可替换的MQTT客户端，可以通过MQTT接口来控制和读写设备；
+- 支持同时连接大量不同协议的工业设备；
+- 和EMQ的其他产品高度融合，包括eKuiper、EMQX、Fabric、NanoMQ等；
 - 支持Neuron运行期更新设备驱动；
 
 功能的完整列表，请参阅[应用和驱动使用介绍](https://github.com/neugates/nep/blob/main/docs/neuron2.x-driver.md)。
 
 获取更多信息，请访问[官网](https://www.emqx.com/zh/products/neuron)。
 
+## 架构设计
+
+现代的CPU的大都已经是多核心的了，包括用在嵌入式系统中的比较低端的ARM和Risc-V架构的CPU，都有多核心的芯片。因此我们需要能够充分的利用这些多核心的CPU，也即Neuron需要能够具有非常好的多核多线程性能。为此，我们使用了nng这个基础消息库，这是一个多线程的IO处理和消息处理的异步并发库，能够充分利用CPU的多个核心 。
+
+我们采用了星型总线这一组织形式，有一个消息路由中心，这个消息路由以nng为基础来提供一个高效率的消息转发。消息的发送和接收是线程间通讯，通过使用共享buffer和智能指针，没有任何的内存拷贝，具有非常高的效率。围绕着这个路由中心，是各个具体功能的节点，由adapter和plugin组成。这些节点可以是内置固有的，比如轻量级的web server，也可以是动态增加的，比如各种设备驱动、MQTT客户端、eKuiper接口等。这样的设计隔离了各个设备驱动和北向应用的功能模块之间的耦合，另外采用订阅-发布机制来实现数据流的分发和聚合，使得Neuron有着极大的灵活性。用户可以根据现场的工作情况动态的增加和减少设备驱动的节点，具有良好的可配置性。另外，当运行Neuron的硬件CPU性能好，核心多，内存大时，Neuron能支持更多的设备驱动节点，海量的数据点位，更大的数据吞吐量，更低的响应时间。具有良好的系统可伸缩性。
+
+Neuron采用了插件机制来支持变化多端的用户功能需求，用户可以根据应用场景的功能需求动态的加载不同功能的插件，得到有不同功能的节点。当设备驱动有bug修复，需要升级时，也可以动态的更新新插件来解决问题，升级新功能。每个节点的运行是独立的，当升级一个节点的插件时，不会影响其他节点的运行，Neuron也不需要重新启动。
+
+Neuron的总体架构概览如下图所示：
+
+![arch-overview](docs/pictures/neuron-arch-overview.png)
+
+Neuron的总线拓扑结构和数据流的分散/汇聚如下图所示：
+
+![neuron-bus-topo](docs/pictures/neuron-bus-topo.png)
+
+![neuron-dataflow](docs/pictures/neuron-dataflow.png)
+
+Neuron的层次结构图如下图所示：
+
+![neuron-layers](docs/pictures/neuron-layers.png)
+
+
 ## 安装
 
 [脚本安装依赖库](https://github.com/neugates/neuron/blob/main/install-libs.sh)
@@ -37,14 +66,18 @@ git clone https://github.com/neugates/neuron.git
 git submodule update --init
 # build
 cd neuron && mkdir build 
+cd build
 cmake .. && make
+cd -
 ```
 
 ## 快速开始
 
 ```shell
 # Start neuron
+cd build
 ./neuron
+cd -
 ```
 
 ## 测试
@@ -54,6 +87,19 @@ cmake .. && make
 ```shell
 cd build
 ctest --output-on-failure
+cd -
 ```
 
+## 功能测试
+
+```shell
+mosquitto -v &
+pip3 install -r ft/requirements.txt
+python3 -m robot -P ft/ --variable neuron_api:http -d ft/http_reports ft
+python3 -m robot -P ft/ --variable neuron_api:mqtt -d ft/mqtt_reports ft
+
+```
+
+
+
 ## 社区

README.md

@@ -6,9 +6,15 @@ Neuron is a Industrial IoT (IIoT) edge industrial gateway for modern big data te
 
 Version 2.0 removes unnecessary features from version 1.x and focuses on data acquisition and forwarding of industrial protocols.Neuron 2.0 support simultaneous connection of a large number of devices with different protocols.
 
-## Feature
+## Design and Features
+
+The design goal of Neuron is to focus on data collection, forwarding and aggregation of the Industrial Internet of Things, and to support multiple industrial protocols. Convert the data of various industrial device into MQTT messages, integrate these independent device into the large industrial Internet of Things system through neuron, and the user can control industrial device and obtain information from it at the remote end. We hope that Neuron can run in low-end embedded linux devices, so it has very little memory footprint and very low CPU footprint. Otherwise, Neuron can also run on a Linux workstation with larger memory to support a large number of connected devices and a large number of data points, so it has good scalability.
+
+Neuron has the following important features:
 
 - Plugged-in southbound driver and northbound application;
+- A light-weigh built-in web server, the user can configure, control and monitor device through browser.
+- A replaceable MQTT Client, the user can control and read/write device by MQTT message.
 - Support simultaneous connection of a large number of devices with different protocols;
 - Highly integrated with other EMQ products,including eKuiper, EMQX, Fabric;
 - Support updating device drivers during Neuron runtime;
@@ -17,6 +23,28 @@ For full list of new features,plfaase read [Instructions for application and dri
 
 For more information,please visit [Homepage](https://www.emqx.com/zh/products/neuron)。
 
+## Architecture design
+
+Most modern CPUs are already multi-core, even the lower-end ARM and Risc-V architecture CPUs used in embedded systems, all of which have multi-core chips. Therefore, we need to be able to make full use of these multi-core CPUs, that is, Neuron needs to have very good multi-core and multi-thread performance. We use library nng, which is an asynchronous concurrent library for multi-threaded IO processing and message passing, which can make full use of the multiple cores of the CPU.
+
+We use the star bus mode as an organizational form, and there is a message routing center. This message routing is based on nng to provide a high-efficiency message forwarding. The sending and receiving of messages is communication between threads. By using shared buffers and smart pointers, there is no memory copy, which is very efficient. Around this routing center are nodes, every node include adapter and plugin. These nodes can be built-in with neuron, such as a lightweight web server, or they can be dynamically added, such as various device drivers, MQTT clients, eKuiper interface, and so on. By this design, it isolates the coupling between each device driver and northbound application. In addition, the subscription-publishing mechanism is used to realize the scattering and gathering of data streams, which makes Neuron extremely flexible. User can dynamically increase and decrease device-driven node according to the working load of the site, with good configurability. In addition, when the hardware CPU running Neuron has good performance, more cores, and large memory, Neuron can support more device driver nodes, massive data points, greater data throughput, and lower response time. Has good system scalability.
+
+Neuron use a plugged-in mechanism to support changing user functional requirements. Users can dynamically load plug-ins with different functional according to the functional requirements of the application scenario. When the device driver has a bug fix and needs to be upgraded, you can also dynamically update the new plug-in to solve the problem and get the new feature. The running state of each node is independent. When the plug-in of one node is upgraded, it will not affect the runing state of other nodes, and Neuron does not need to be restarted.
+
+An overview of Neuron's architecture is shown in the figure below:
+
+![arch-overview](docs/pictures/neuron-arch-overview.png)
+
+The topology of bus in Neuron and the scattering/gathering of data flow are shown in the figure below:
+
+![neuron-bus-topo](docs/pictures/neuron-bus-topo.png)
+
+![neuron-dataflow](docs/pictures/neuron-dataflow.png)
+
+The hierarchical layer diagram of Neuron is shown in the figure below:
+
+![neuron-layers](docs/pictures/neuron-layers.png)
+
 ## Installation
 
 [Script to install dependent libraries](https://github.com/neugates/neuron/blob/main/install-libs.sh)
@@ -37,14 +65,18 @@ git clone https://github.com/neugates/neuron.git
 git submodule update --init
 # build
 cd neuron && mkdir build 
+cd build
 cmake .. && make
+cd -
 ```
 
 ## Quick Start
 
 ```shell
 # Start neuron
+cd build
 ./neuron
+cd -
 ```
 
 ## Test
@@ -52,7 +84,19 @@ cmake .. && make
 To test everying in one go
 
 ```shell
+cd build
 ctest --output-on-failure
+cd -
+```
+
+## Functional test
+
+```shell
+mosquitto -v &
+pip3 install -r ft/requirements.txt
+python3 -m robot -P ft/ --variable neuron_api:http -d ft/http_reports ft
+python3 -m robot -P ft/ --variable neuron_api:mqtt -d ft/mqtt_reports ft
+
 ```
 
 ## Community