更新文档

pages/src/content/docs/guides/about.md

@@ -16,3 +16,14 @@ DriverBox 是一款支持泛化协议接入的边缘网关框架， 以插件化
 
 
 
+## 名词解释
+
+### 虚拟设备
+虚拟设备是 DriverBox 框架提供的一种设备通讯方式模拟能力。
+使用户可在无需对接真实设备的情况下，进行本地设备配置和调试。
+
+开启虚拟设备模式，只需将 connections 中的 `virtual` 配置项设置为 `true`。
+
+现以支持以下几种通讯插件：
+- Bacnet
+- [Modbus](/plugins/modbus/#虚拟设备)

pages/src/content/docs/plugins/modbus.md

@@ -21,7 +21,7 @@ modbus插件用于连接modbus设备，支持 rtu、tcp、udp、tcp+tls 等通
 | batchReadLen  | 选填 | int    | 支持连续读的字节数。                                                                                                    |   
 | batchWriteLen | 选填 | int    | 支持连续写的字节数。                                                                                                    |   
 | retry         | 选填 | int    | 执行写操作出现失败时的重试次数，默认：3                                                                                          |
-| virtual       | 选填 | bool   | 是否启用虚拟模式，默认：false                                                                                             |
+| virtual       | 选填 | bool   | 是否启用虚拟模式，默认：false 。详见：[虚拟设备](#虚拟设备)                                                                               |
 
 ### 示例
 
@@ -131,5 +131,139 @@ rawType 适用于寄存器类型为：`INPUT_REGISTER`、`HOLDING_REGISTER` 的
 | float64 |         ||✔|          
 
 ## 性能优化
+todo
 
-## 虚拟设备
+## 虚拟设备
+启用 modbus 虚拟模式，一方面要将 virtual 配置项设置为 true。
+另一方面，要在 config.json 的同级目录下创建用于提供虚拟设备能力的 lua 脚本：`converter.lua`，并按以下步骤进行操作：
+
+### 第一步：初始化脚本内容
+脚本内容可从`res/library/template/modbus_virtual.lua`中拷贝。
+
+### 第二步：初始化寄存器值
+modbus 虚拟设备的寄存器值皆为 0，需要在 `converter.lua` 脚本中为设备添加初始值。
+脚本的添加内容处于 initSlave 方法的 `Begin--End` 注释之间（**其余地方不作调整**）。
+
+```lua
+<!--converter.lua-->
+-- 初始化指定从机
+function initSlave(slaveId, holdingRegister, coil, discreteInput, inputRegister)
+    slaves[slaveId] = {
+        [HOLDING_REGISTER] = initRegisters(holdingRegister),
+        [COIL] = initRegisters(coil),
+        [DISCRETE_INPUT] = initRegisters(discreteInput),
+        [INPUT_REGISTER] = initRegisters(inputRegister)
+    }
+
+    -- 调用 mockWrite 方法初始化模拟数据
+    -- Begin：以下需要开发者根据实际情况作修改
+
+
+    -- End：以上需要开发者根据实际情况作修改
+
+    return slaves[slaveId]
+end
+```
+**示例**
+
+以某品牌空调网关为例，所有内机处于同一个从机地址的不同寄存器区域。
+各内机的点位有着相同的偏移量，通过以下脚本模拟出 100 台内机，并设置开关、模式、风速、温度等状态值。
+```lua
+<!--converter.lua-->
+-- 初始化指定从机
+function initSlave(slaveId, holdingRegister, coil, discreteInput, inputRegister)
+    slaves[slaveId] = {
+        [HOLDING_REGISTER] = initRegisters(holdingRegister),
+        [COIL] = initRegisters(coil),
+        [DISCRETE_INPUT] = initRegisters(discreteInput),
+        [INPUT_REGISTER] = initRegisters(inputRegister)
+    }
+
+    -- 调用 mockWrite 方法初始化模拟数据
+    -- Begin：以下需要开发者根据实际情况作修改
+    for i = 1, 100 do
+        --print("初始化第"..i.."台内机模拟数据")
+        mockWrite(slaveId, HOLDING_REGISTER, 40078 + (i - 1) * 91, { 1, 2, 2, 0, 16 })
+    end
+
+    -- End：以上需要开发者根据实际情况作修改
+
+    return slaves[slaveId]
+end
+```
+### 第三步：编写控制逻辑（可选）
+对于点位读写分离的场景，需要开发者编写控制逻辑，以实现对模拟数据的更新。例如：开关点位的读操作处于寄存器地址 40001，而写操作处于 40002。
+
+脚本的添加内容处于 mockWrite 方法的 Begin--End 注释之间（其余地方不作调整）。
+```lua
+<!--converter.lua-->
+--模拟modbus读写
+-- slaveId 从机id
+-- primaryTable 寄存器类型：HOLDING_REGISTER,COIL,DISCRETE_INPUT,INPUT_REGISTER
+-- address 寄存器地址
+-- value 值，byte数组
+function mockWrite(slaveId, primaryTable, address, value)
+    if address < 1 or address > 65535 then
+        error("Invalid register address")
+    end
+    -- 寻找从机
+    slave = slaves[slaveId]
+    if slaves[slaveId] == nil then
+        slave = initSlave(slaveId, 65535, 65535, 65535, 65535);
+    end
+
+    tableData = slave[primaryTable]
+    --从address开始填充数据value
+    for i = 1, #value do
+        tableData[address + i - 1] = value[i]
+    end
+
+    -- 对于读写点分离的情况，需要手动填写读点位数值
+    -- Begin：以下需要开发者根据实际情况作修改
+
+    -- End：以上需要开发者根据实际情况作修改
+end
+```
+
+**示例**
+<!--converter.lua-->
+```lua
+function mockWrite(slaveId, primaryTable, address, value)
+   if address < 1 or address > 65535 then
+      error("Invalid register address")
+   end
+   -- 寻找从机
+   slave = slaves[slaveId]
+   if slaves[slaveId] == nil then
+      slave = initSlave(slaveId, 65535, 65535, 65535, 65535);
+   end
+
+   tableData = slave[primaryTable]
+   --从address开始填充数据value
+   for i = 1, #value do
+      tableData[address + i - 1] = value[i]
+   end
+
+   -- 对于读写点分离的情况，需要手动填写读点位数值
+   -- Begin：以下需要开发者根据实际情况作修改
+   for i = 1, #value do
+      offset = (address + i - 1 - 40000) % 91
+      if offset == 78 then
+         -- 开关
+         tableData[address + i - 77] = value[i]
+      elseif offset == 79 then
+         -- 模式
+         tableData[address + i - 77] = value[i]
+      elseif offset == 80 then
+         -- 风速
+         tableData[address + i - 77] = value[i]
+      elseif offset == 82 then
+         -- 温度
+         tableData[address + i - 75] = value[i]
+      end
+   end
+   -- End：以上需要开发者根据实际情况作修改
+end
+```
+
+如此，便实现了 100 台空调内机设备的生成，且可以进行正常的模式控制。

res/library/template/modbus_virtual.lua

@@ -63,7 +63,6 @@ function mockWrite(slaveId, primaryTable, address, value)
     -- Begin：以下需要开发者根据实际情况作修改
 
     -- End：以上需要开发者根据实际情况作修改
-
 end
 
 -- （勿动）模拟modbus读