|
| 1 | +# CSM-TCP-Router Python Client API |
| 2 | + |
| 3 | +这是一个Python版本的CSM-TCP-Router客户端API，实现了与LabVIEW版本相同的功能，可以连接到CSM-TCP-Router服务器，发送命令并接收响应。 |
| 4 | + |
| 5 | +## 功能特性 |
| 6 | + |
| 7 | +- 与CSM-TCP-Router服务器建立TCP连接 |
| 8 | +- 发送同步命令并等待回复 |
| 9 | +- 发送异步命令 |
| 10 | +- 发送无返回异步命令 |
| 11 | +- Ping服务器 |
| 12 | +- 订阅状态变化通知 |
| 13 | +- 等待服务器可用 |
| 14 | +- 完整的错误处理和线程安全设计 |
| 15 | + |
| 16 | +## 文件结构 |
| 17 | + |
| 18 | +- `tcp_router_client.py`: 主要的客户端API类实现 |
| 19 | +- `example_usage.py`: 使用示例代码 |
| 20 | +- `README.md`: 使用说明文档 |
| 21 | + |
| 22 | +## 使用方法 |
| 23 | + |
| 24 | +### 基本连接 |
| 25 | + |
| 26 | +```python |
| 27 | +from tcp_router_client import TcpRouterClient |
| 28 | + |
| 29 | +# 创建客户端实例 |
| 30 | +client = TcpRouterClient() |
| 31 | + |
| 32 | +# 连接到服务器 |
| 33 | +if client.connect("localhost", 9999): |
| 34 | + print("连接成功") |
| 35 | + # 执行操作... |
| 36 | + |
| 37 | + # 断开连接 |
| 38 | + client.disconnect() |
| 39 | +else: |
| 40 | + print("连接失败") |
| 41 | +``` |
| 42 | + |
| 43 | +### 发送同步命令 |
| 44 | + |
| 45 | +```python |
| 46 | +# 发送命令并等待回复 |
| 47 | +response = client.send_message_and_wait_for_reply("List") |
| 48 | +print(f"回复: {response}") |
| 49 | +``` |
| 50 | + |
| 51 | +### 发送异步命令 |
| 52 | + |
| 53 | +```python |
| 54 | +# 发送异步命令 |
| 55 | +async_cmd = "API: Read Channels -> AI" |
| 56 | +client.post_message(async_cmd) |
| 57 | + |
| 58 | +# 发送无返回异步命令 |
| 59 | +no_rep_cmd = "API: Refresh ->| System" |
| 60 | +client.post_no_rep_message(no_rep_cmd) |
| 61 | +``` |
| 62 | + |
| 63 | +### 订阅状态变化 |
| 64 | + |
| 65 | +```python |
| 66 | +# 定义状态变化回调函数 |
| 67 | +def status_callback(status_data): |
| 68 | + print(f"收到状态更新: {status_data}") |
| 69 | + |
| 70 | +# 注册状态变化通知 |
| 71 | +client.register_status_change("Status", "AI", status_callback) |
| 72 | + |
| 73 | +# 取消订阅 |
| 74 | +client.unregister_status_change("Status", "AI") |
| 75 | +``` |
| 76 | + |
| 77 | +### 等待服务器可用 |
| 78 | + |
| 79 | +```python |
| 80 | +# 等待服务器可用，最多等待30秒 |
| 81 | +success = client.wait_for_server("localhost", 9999, timeout=30) |
| 82 | +if success: |
| 83 | + print("服务器已可用") |
| 84 | + client.connect("localhost", 9999) |
| 85 | +``` |
| 86 | + |
| 87 | +### Ping服务器 |
| 88 | + |
| 89 | +```python |
| 90 | +# Ping服务器，检查连接状态 |
| 91 | +success, elapsed = client.ping() |
| 92 | +if success: |
| 93 | + print(f"Ping成功，延迟: {elapsed*1000:.2f}ms") |
| 94 | +``` |
| 95 | + |
| 96 | +## 通讯协议 |
| 97 | + |
| 98 | +Python客户端实现了与CSM-TCP-Router相同的通讯协议，数据包格式如下： |
| 99 | + |
| 100 | +``` |
| 101 | +| 数据长度(4B) | 版本(1B) | TYPE(1B) | FLAG1(1B) | FLAG2(1B) | 文本数据 | |
| 102 | +╰─────────────────────────── 包头 ──────────────────────────╯╰──── 数据长度字范围 ────╯ |
| 103 | +``` |
| 104 | + |
| 105 | +支持的数据包类型： |
| 106 | +- 信息数据包(info) - `0x00` |
| 107 | +- 错误数据包(error) - `0x01` |
| 108 | +- 指令数据包(cmd) - `0x02` |
| 109 | +- 同步响应数据包(resp) - `0x03` |
| 110 | +- 异步响应数据包(async-resp) - `0x04` |
| 111 | +- 订阅返回数据包(status) - `0x05` |
| 112 | + |
| 113 | +## 支持的指令集 |
| 114 | + |
| 115 | +### 1. CSM 消息指令集 |
| 116 | +由原有基于CSM开发的代码定义，支持： |
| 117 | +- 同步消息 (-@) |
| 118 | +- 异步消息 (->) |
| 119 | +- 无返回异步消息 (->|) |
| 120 | + |
| 121 | +### 2. CSM-TCP-Router 指令集 |
| 122 | +- `List` - 列出所有的CSM模块 |
| 123 | +- `List API`: 列出指定模块的所有API |
| 124 | +- `List State`: 列出指定模块的所有CSM状态 |
| 125 | +- `Help` - 显示模块的帮助文件 |
| 126 | +- `Refresh lvcsm`: 刷新缓存文件 |
| 127 | +- `Ping` - 测试服务器连接 |
| 128 | + |
| 129 | +## 注意事项 |
| 130 | + |
| 131 | +1. 确保在使用完客户端后调用`disconnect()`或`release()`方法释放资源 |
| 132 | +2. 回调函数将在接收线程中执行，避免在回调函数中执行长时间阻塞操作 |
| 133 | +3. 当网络连接异常断开时，客户端会自动将`connected`标志设为False |
| 134 | +4. 对于频繁发送消息的场景，建议使用连接池或重用同一个客户端实例 |
| 135 | + |
| 136 | +## 示例程序 |
| 137 | + |
| 138 | +请参考`example_usage.py`文件，其中包含了详细的使用示例。 |
| 139 | + |
| 140 | +## 依赖项 |
| 141 | + |
| 142 | +本客户端API仅使用Python标准库，无需安装额外依赖： |
| 143 | +- `socket`: 用于TCP通信 |
| 144 | +- `struct`: 用于解析数据包 |
| 145 | +- `threading`: 用于多线程处理 |
| 146 | +- `queue`: 用于线程间通信 |
| 147 | +- `json`: 用于数据序列化（预留） |
| 148 | +- `time`: 用于超时和延时 |
| 149 | +- `enum`: 用于定义数据包类型枚举 |
| 150 | + |
| 151 | +## 与LabVIEW版本对比 |
| 152 | + |
| 153 | +此Python版本实现了LabVIEW版本ClientAPI的所有核心功能： |
| 154 | +- `Obtain.vi` -> `__init__()` 和 `obtain()` |
| 155 | +- `Release.vi` -> `release()` |
| 156 | +- `Send Message and Wait for Reply.vi` -> `send_message_and_wait_for_reply()` |
| 157 | +- `Post Message.vi` -> `post_message()` |
| 158 | +- `Post No-Rep Message.vi` -> `post_no_rep_message()` |
| 159 | +- `Ping.vi` -> `ping()` |
| 160 | +- `Register Status Change.vi` -> `register_status_change()` |
| 161 | +- `Unregister Status Change.vi` -> `unregister_status_change()` |
| 162 | +- `Wait for Server.vi` -> `wait_for_server()` |
| 163 | + |
| 164 | +## 版本历史 |
| 165 | + |
| 166 | +- v1.0.0: 初始版本，实现基本功能 |
0 commit comments