# TestWorks 设备驱动 API 文档
本文档提供 TestWorks 平台中三种设备驱动的公共接口说明，适用于二次开发与集成调用。
## 1. PanasonicDevice（松下 PLC 串口通信）
**命名空间：** `TestWorks.Device.Panasonic`
**实现接口：** `IPLC`
提供基于 Mewtocol 协议的松下 PLC 串口读写操作，支持位（R）和字（DT）的多种数据类型。
### 1.1 属性
| 名称 | 类型 | 描述 |
|——|——|——|
| `Name` | `string` | 设备实例名称 |
| `IsConnected` | `bool` | 当前是否已建立通信连接（只读） |
| `LogService` | `ILogService` | 日志服务注入接口，用于记录操作信息 |
### 1.2 构造函数
“`csharp
public PanasonicDevice(PanasonicConfig config, string name)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `config` | `PanasonicConfig` | 串口配置对象（包含 PortName, BaudRate, DataBits, StopBits, Parity） |
| `name` | `string` | 设备唯一标识名称 |
—
### 1.3 方法
#### Connect()
建立与 PLC 的串口连接，并执行一次测试读取（R1）以验证通信。
“`csharp
public bool Connect()
“`
| 返回 | 说明 |
|——|——|
| `bool` | `true` 表示连接成功且通信正常；`false` 表示失败 |
**异常：** 捕获所有异常并记录日志，不向外抛出。
—
#### Disconnect()
关闭当前串口连接并释放资源。
“`csharp
public void Disconnect()
“`
—
#### GetR(string address)
读取单个 R 位（继电器/内部位）的值。
“`csharp
public bool? GetR(string address)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `address` | `string` | 地址，如 “R1″、”R100” |
| 返回 | 说明 |
|——|——|
| `bool?` | `true`/`false` 表示读取成功；`null` 表示读取失败或未连接 |
**示例：**
“`csharp
bool? value = device.GetR(“R10″);
if (value.HasValue) {
Console.WriteLine($”R10 = {value.Value}”);
}
“`
—
#### SetR(string address, bool val)
写入单个 R 位的值。
“`csharp
public bool SetR(string address, bool val)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `address` | `string` | 地址，如 “R1” |
| `val` | `bool` | 要写入的值 |
| 返回 | 说明 |
|——|——|
| `bool` | `true` 表示写入成功；`false` 表示失败 |
—
#### ReadDTInt16(string address)
读取 DT 数据寄存器（16 位有符号整数）。
“`csharp
public short? ReadDTInt16(string address)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `address` | `string` | 地址，如 “DT100” |
| 返回 | 说明 |
|——|——|
| `short?` | 成功返回数值，失败返回 `null` |
—
#### ReadDTInt32(string address)
读取 DT 数据寄存器（32 位有符号整数）。
“`csharp
public int? ReadDTInt32(string address)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `address` | `string` | 地址，如 “DT200” |
| 返回 | 说明 |
|——|——|
| `int?` | 成功返回数值，失败返回 `null` |
—
#### ReadDTFloat(string address)
读取 DT 数据寄存器（单精度浮点数）。
“`csharp
public float? ReadDTFloat(string address)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `address` | `string` | 地址，如 “DT300” |
| 返回 | 说明 |
|——|——|
| `float?` | 成功返回数值，失败返回 `null` |
—
#### WriteDTInt16(string address, short val)
写入 DT 数据寄存器（16 位有符号整数）。
“`csharp
public bool WriteDTInt16(string address, short val)
“`
—
#### WriteDTInt32(string address, int val)
写入 DT 数据寄存器（32 位有符号整数）。
“`csharp
public bool WriteDTInt32(string address, int val)
“`
—
#### WriteDTFloat(string address, float val)
写入 DT 数据寄存器（单精度浮点数）。
“`csharp
public bool WriteDTFloat(string address, float val)
“`
—
## 2. CommonSerialDevice（通用串口设备）
**命名空间：** `TestWorks.Device.CommonSerial`
**继承自：** `DeviceBase`（提供 `Name`, `IsConnected`, `LogService` 等基础成员）
提供通用的串口收发功能，支持发送命令并等待响应，内置重试机制。
### 2.1 属性
| 名称 | 类型 | 描述 |
|——|——|——|
| `SerialConfig` | `CommonSerialConfig` | 当前串口配置（只读） |
| `Name` | `string` | 设备名称（继承自基类） |
| `IsConnected` | `bool` | 连接状态（继承自基类） |
| `LogService` | `ILogService` | 日志服务（继承自基类） |
### 2.2 构造函数
“`csharp
public CommonSerialDevice(CommonSerialConfig config, string name)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `config` | `CommonSerialConfig` | 串口配置（端口、波特率、校验位等） |
| `name` | `string` | 设备名称 |
—
### 2.3 方法
#### Connect()
打开串口。
“`csharp
public override bool Connect()
“`
| 返回 | 说明 |
|——|——|
| `bool` | `true` 成功打开串口，`false` 失败 |
—
#### Disconnect()
关闭串口。
“`csharp
public override void Disconnect()
“`
—
#### UpdateConfig(object newConfig)
更新串口配置，若当前已连接则自动重连。
“`csharp
public override void UpdateConfig(object newConfig)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `newConfig` | `CommonSerialConfig` | 新配置对象 |
—
#### SendAndReceive(string command, int timeout = 500, int DelayRead = 20, string lineEnding = “\r\n”)
发送命令并等待接收响应数据（**同步阻塞**）。
“`csharp
public string SendAndReceive(string command, int timeout = 500, int DelayRead = 20, string lineEnding = “\r\n”)
“`
| 参数 | 类型 | 默认值 | 说明 |
|——|——|——–|——|
| `command` | `string` | – | 要发送的命令字符串（若不以换行符结尾，自动追加 `lineEnding`） |
| `timeout` | `int` | 500 | 等待接收数据的超时时间（毫秒） |
| `DelayRead` | `int` | 20 | 检测到数据后额外延时（毫秒），确保数据完整 |
| `lineEnding` | `string` | `”\r\n”` | 命令结尾附加的换行符 |
| 返回 | 说明 |
|——|——|
| `string` | 接收到的响应字符串（已去除换行符和末尾的 `$` 字符），若超时或失败返回 `null` 或 `string.Empty` |
**示例：**
“`csharp
string response = device.SendAndReceive(“AT”, timeout: 1000);
if (!string.IsNullOrEmpty(response)) {
Console.WriteLine($”响应: {response}”);
}
“`
—
#### SendAndReceiveTry(string command, int timeout = 500, int DelayRead = 20, string lineEnding = “\r\n”, string lineStart = “ok”, int tryTimes = 3)
发送命令，若响应内容不以指定前缀开头则自动重试。
“`csharp
public string SendAndReceiveTry(string command, int timeout = 500, int DelayRead = 20, string lineEnding = “\r\n”, string lineStart = “ok”, int tryTimes = 3)
“`
| 参数 | 类型 | 默认值 | 说明 |
|——|——|——–|——|
| `command` | `string` | – | 要发送的命令 |
| `timeout` | `int` | 500 | 单次超时（毫秒） |
| `DelayRead` | `int` | 20 | 数据延时读取 |
| `lineEnding` | `string` | `”\r\n”` | 换行符 |
| `lineStart` | `string` | `”ok”` | 期望响应起始字符串（不区分大小写） |
| `tryTimes` | `int` | 3 | 最大重试次数（含首次） |
| 返回 | 说明 |
|——|——|
| `string` | 最后一次响应结果（即使不符合前缀也返回） |
—
## 3. BekenDevice（博通芯片烧录工具）
**命名空间：** `TestWorks.Device.Beken`
**实现接口：** `IChip`
封装 `bk_loader.exe` 命令行工具，提供固件烧录、擦除、读取等操作。
### 3.1 属性
| 名称 | 类型 | 描述 |
|——|——|——|
| `Name` | `string` | 设备名称 |
| `IsConnected` | `bool` | 是否已准备就绪（实际检查 `bk_loader.exe` 版本） |
| `IsBusy` | `bool` | 是否正在执行烧录/擦除等耗时操作（只读） |
| `ProgressValue` | `int` | 当前操作进度（0~100） |
| `StatusText` | `string` | 当前状态描述文本 |
| `LogService` | `ILogService` | 日志服务接口 |
### 3.2 构造函数
“`csharp
public BekenDevice(BekenConfig config, string name)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `config` | `BekenConfig` | 包含端口、波特率、固件列表等配置 |
| `name` | `string` | 设备名称 |
**注意：** 构造函数会校验 `Tools\bk_loader.exe` 是否存在，并初始化内部服务。
—
### 3.3 方法
#### Connect()
检查 `bk_loader.exe` 版本，版本为 `2.1.12.2` 视为成功。
“`csharp
public bool Connect()
“`
| 返回 | 说明 |
|——|——|
| `bool` | `true` 表示工具版本匹配，可用于后续操作 |
—
#### Disconnect()
释放内部资源。
“`csharp
public void Disconnect()
“`
—
#### Download()
执行固件烧录（异步操作，但方法内部同步等待完成）。
“`csharp
public bool Download()
“`
| 返回 | 说明 |
|——|——|
| `bool` | `true` 烧录成功，`false` 失败 |
**前置条件：** 配置中至少包含一个固件条目（`FirmwareEntries` 非空）。
**行为：** 方法会阻塞当前线程直到烧录完成，期间更新 `ProgressValue` 和 `StatusText`。
—
#### Erase()
擦除芯片 Flash。
“`csharp
public bool Erase()
“`
| 返回 | 说明 |
|——|——|
| `bool` | 成功返回 `true` |
—
#### Read()
读取芯片 Flash 内容并保存为 `read_back.bin`（路径固定）。
“`csharp
public bool Read()
“`
| 返回 | 说明 |
|——|——|
| `bool` | 成功返回 `true` |
—
#### WriteKey()
写入 AES 密钥和随机数配置文件（`aes.json`, `random.json`）。
“`csharp
public bool WriteKey()
“`
| 返回 | 说明 |
|——|——|
| `bool` | 成功返回 `true` |
—
#### UpdateConfig(object newConfig)
更新配置并自动重连。
“`csharp
public void UpdateConfig(object newConfig)
“`
| 参数 | 类型 | 说明 |
|——|——|——|
| `newConfig` | `BekenConfig` | 新配置对象 |
—
## 附录：通用依赖说明
– **日志服务**：所有设备均支持注入 `ILogService` 实现，用于记录操作日志、错误信息。
– **配置对象**：各设备对应的配置类（`PanasonicConfig`, `CommonSerialConfig`, `BekenConfig`）应包含序列化/反序列化支持，通常由上层 UI 提供。
– **线程安全**：`CommonSerialDevice` 的 `SendAndReceive` 是同步方法，注意不要在 UI 线程中长时间阻塞；`BekenDevice` 内部使用 `DispatcherFrame` 处理 UI 消息，适合在 WPF 环境调用。
—
**文档版本：** 1.0
**更新日期：** 2026-07-22
