Skip to content

Commit e169aa7

Browse files
author
NEVSTOP
committed
feat(SDK/PythonClientAPI): 添加Python客户端API实现及示例
实现CSM-TCP-Router的Python客户端API，包含以下内容： 1. 核心客户端类tcp_router_client.py，支持同步/异步消息、状态订阅等功能 2. 示例代码example_usage.py展示API使用方法 3. 详细README文档说明功能特性及使用方式 4. 更新.gitignore忽略Python开发相关文件
1 parent aace325 commit e169aa7

File tree

4 files changed

+588
-1
lines changed

4 files changed

+588
-1
lines changed

‎.gitignore‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,69 @@
22
*.aliases
33
*.lvlps
44
/vip/*.vip
5-
*.bkp
5+
*.bkp
6+
7+
# Python
8+
__pycache__/
9+
*.py[cod]
10+
*$py.class
11+
12+
# Distribution / packaging
13+
build/
14+
dist/
15+
dist-egg/
16+
build-egg/
17+
*.egg-info/
18+
.installed.cfg
19+
*.egg
20+
21+
# Virtual environments
22+
.env
23+
.venv
24+
env/
25+
venv/
26+
ENV/
27+
env.bak/
28+
venv.bak/
29+
30+
# IDEs and editors
31+
.idea/
32+
.project
33+
.classpath
34+
.c9/
35+
*.launch
36+
.settings/
37+
*.sublime-workspace
38+
39+
# IDE - VSCode
40+
.vscode/*
41+
!.vscode/settings.json
42+
!.vscode/tasks.json
43+
!.vscode/launch.json
44+
!.vscode/extensions.json
45+
46+
# Testing
47+
.pytest_cache/
48+
.coverage
49+
.coverage.*
50+
.cache
51+
nosetests.xml
52+
coverage.xml
53+
*.cover
54+
.hypothesis/
55+
56+
# Misc
57+
*.py,cover
58+
*.log
59+
*.pid
60+
*.seed
61+
*.pid.lock
62+
63+
# OS generated files
64+
Thumbs.db
65+
.DS_Store
66+
.DS_Store?
67+
._*
68+
.Spotlight-V100
69+
.Trashes
70+
ehthumbs.db

‎SDK/PythonClientAPI/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
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: 初始版本，实现基本功能

‎SDK/PythonClientAPI/example_usage.py‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
import time
2+
from tcp_router_client import TcpRouterClient
3+
4+
"""CSM-TCP-Router Python客户端API使用示例"""
5+
6+
def main():
7+
# 创建客户端实例
8+
client = TcpRouterClient()
9+
10+
print("CSM-TCP-Router Python客户端API示例")
11+
print("================================")
12+
13+
# 示例1: 连接到服务器
14+
print("\n示例1: 连接到服务器")
15+
if client.connect("localhost", 30007):
16+
print("✅ 成功连接到服务器")
17+
else:
18+
print("❌ 连接服务器失败，请确保服务器已启动")
19+
return
20+
21+
# 示例2: Ping服务器
22+
print("\n示例2: Ping服务器")
23+
success, elapsed = client.ping(timeout=2)
24+
if success:
25+
print(f"✅ Ping成功，延迟: {elapsed*1000:.2f}ms")
26+
else:
27+
print("❌ Ping失败")
28+
29+
# 示例3: 发送同步命令并等待回复
30+
print("\n示例3: 发送同步命令并等待回复")
31+
# 列出所有CSM模块
32+
response = client.send_message_and_wait_for_reply("List")
33+
print(f"命令: List")
34+
print(f"回复: {response}")
35+
36+
# 列出特定模块的API
37+
# 注意：这里假设存在名为"AI"的模块，如果不存在，您需要修改为实际存在的模块名
38+
module_name = "AI"
39+
response = client.send_message_and_wait_for_reply(f"List API {module_name}")
40+
print(f"\n命令: List API {module_name}")
41+
print(f"回复: {response}")
42+
43+
# 示例4: 发送异步命令
44+
print("\n示例4: 发送异步命令")
45+
# 注意：这里的命令需要根据实际的CSM模块进行调整
46+
async_cmd = "API: Read Channels -> AI"
47+
success = client.post_message(async_cmd)
48+
print(f"命令: {async_cmd}")
49+
print(f"发送结果: {'✅ 成功' if success else '❌ 失败'}")
50+
51+
# 示例5: 发送无返回异步命令
52+
print("\n示例5: 发送无返回异步命令")
53+
# 注意：这里的命令需要根据实际的CSM模块进行调整
54+
no_rep_cmd = "API: Refresh ->| System"
55+
success = client.post_no_rep_message(no_rep_cmd)
56+
print(f"命令: {no_rep_cmd}")
57+
print(f"发送结果: {'✅ 成功' if success else '❌ 失败'}")
58+
59+
# 示例6: 订阅状态变化
60+
print("\n示例6: 订阅状态变化")
61+
# 状态变化回调函数
62+
def status_callback(status_data):
63+
print(f"📢 收到状态更新: {status_data}")
64+
65+
# 注册状态变化通知
66+
# 注意：这里假设存在名为"AI"的模块和"Status"状态，如果不存在，您需要修改为实际存在的模块名和状态名
67+
success = client.register_status_change("Status", "AI", status_callback)
68+
print(f"订阅 'Status@AI' 结果: {'✅ 成功' if success else '❌ 失败'}")
69+
70+
# 保持连接一段时间，等待状态更新
71+
print("\n等待5秒，观察状态更新...")
72+
time.sleep(5)
73+
74+
# 取消订阅
75+
success = client.unregister_status_change("Status", "AI")
76+
print(f"取消订阅 'Status@AI' 结果: {'✅ 成功' if success else '❌ 失败'}")
77+
78+
# 示例7: 等待服务器可用
79+
print("\n示例7: 等待服务器可用（演示用，当前已连接）")
80+
# 断开当前连接
81+
client.disconnect()
82+
print("已断开连接")
83+
84+
# 等待服务器可用
85+
print("等待服务器可用，最多等待10秒...")
86+
# 注意：如果服务器未运行，这个调用将会超时
87+
success = client.wait_for_server("localhost", 9999, timeout=10)
88+
print(f"服务器可用检查结果: {'✅ 服务器可用' if success else '❌ 服务器不可用'}")
89+
90+
# 重新连接（如果服务器可用）
91+
if success:
92+
client.connect("localhost", 9999)
93+
print("✅ 已重新连接到服务器")
94+
95+
# 示例8: 释放资源
96+
print("\n示例8: 释放资源")
97+
client.release()
98+
print("✅ 客户端资源已释放")
99+
100+
print("\n示例执行完毕")
101+
102+
if __name__ == "__main__":
103+
main()

0 commit comments

Comments
 (0)