Skip to content

Commit 20aa18c

Browse files
nevstopnevstopCopilotKivenJiaCopilot
authored
Dev_2026Q1 (#27)
* [add] #23 Export "Net Address" for bind server to network adapter. * [update] 更新数据包类型定义，添加指令响应和订阅中断广播返回数据包 * docs: sync EN/ZH protocol and README files; document info packet lifecycle events (#24) * Initial plan * 完善 Protocol.v0.(zh-cn).md: 添加 cmd-resp 握手说明和通信流程图 Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * 根据审查意见更新 Protocol.v0.(zh-cn).md：修正包类型值、同步流程和异步流程图 Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * 根据审查意见修正 cmd-resp 注释、同步流程说明及异步流程图逻辑 Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * 统一 error 包描述，修正异步无返回流程文字与图表一致性 Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * Add info packet documentation for connection/disconnection events Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * Sync EN/ZH protocol and README files for consistency Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> * 25 and 26 bug multi client cannot receive msg concurrently (#28) * #25 Completed the issues fix. Co-Authored-By: NEVSTOP <8196752+nevstop@users.noreply.github.com> * #26 Back-up >> works on interrupt * #26 Completed the interrupt mode and new Example 6 for demo this feature * change after code review --------- Co-authored-by: NEVSTOP <8196752+nevstop@users.noreply.github.com> Co-authored-by: nevstop <nevstop@NEVSTOP-LAB> * Update CSM-TCP-Router.lvcsm 删除这个文件, 并 ignore Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Sync and improve README (en/zh-cn) content and language Agent-Logs-Url: https://github.com/NEVSTOP-LAB/CSM-TCP-Router-App/sessions/62cc62ad-c940-4e13-9a74-7c924ca9d168 Co-authored-by: nevstop <8196752+nevstop@users.noreply.github.com> --------- Co-authored-by: nevstop <nevstop@NEVSTOP-LAB> Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: Kiven GiveUp <316979271@qq.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 37cdcb0 commit 20aa18c

15 files changed

+313
-45
lines changed

‎.doc/Protocol.v0.(en).md‎

Lines changed: 126 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,11 @@ This field defines the type of the data packet and is an enumerated value. The s
2424
- Information Packet (`info`) - `0x00`
2525
- Error Packet (`error`) - `0x01`
2626
- Command Packet (`cmd`) - `0x02`
27-
- Synchronous Response Packet (`resp`) - `0x03`
28-
- Asynchronous Response Packet (`async-resp`) - `0x04`
29-
- Subscription Status Packet (`status`) - `0x05`
27+
- Command Response Packet (`cmd-resp`) - `0x03`
28+
- Synchronous Response Packet (`resp`) - `0x04`
29+
- Asynchronous Response Packet (`async-resp`) - `0x05`
30+
- Subscription Normal Broadcast Packet (`status`) - `0x06`
31+
- Subscription Interrupt Broadcast Packet (`interrupt`) - `0x07`
3032

3133
### FLAG1 (1 Byte)
3234

@@ -42,6 +44,22 @@ Similar to FLAG1, this field is reserved for future use to describe additional a
4244

4345
The content of an information packet is plain text containing informational data.
4446

47+
The server sends an `info` packet to the client in two specific situations:
48+
49+
- **On Connection**: When a client successfully connects to the server, the server sends a welcome `info` packet:
50+
51+
```
52+
Welcome to the CSM TCP Router Server
53+
API: "list", "list api", "list states", "help"
54+
type "bye" to close connection from Server side.
55+
```
56+
57+
- **On Disconnection**: When the connection is closed from the server side, the server sends a goodbye `info` packet:
58+
59+
```
60+
Good bye.
61+
```
62+
4563
### Error Packet (`error`)
4664

4765
The content of an error packet is plain text describing an error, formatted as per the CSM Error format.
@@ -89,6 +107,20 @@ The content of a command packet is a command in the CSM local command format. It
89107
>
90108
> When module `A` sends a `Status`, the client will automatically receive a `status` packet.
91109
110+
### Command Response Packet (`cmd-resp`)
111+
112+
Except for synchronous messages (`-@`), all other command packets (`cmd`) receive a handshake response after being received and processed by the server:
113+
114+
- **Normal case**: A `cmd-resp` packet is returned, indicating the command has been accepted and triggered for execution.
115+
- **Error case**: An `error` packet is returned, indicating the command was not accepted or an error occurred during execution (e.g., the target module does not exist, execution failed, etc.).
116+
117+
> [!NOTE]
118+
> `cmd-resp` is a handshake acknowledgment of the command, indicating that the command has been accepted and execution has started. It does not contain business response data.
119+
> Business response data is returned via `resp` or `async-resp` packets.
120+
>
121+
> Synchronous messages (`-@`) do not have a `cmd-resp` handshake; upon completion, they directly return `resp` or `error`.
122+
>
123+
92124
### Synchronous Response Packet (`resp`)
93125
94126
After executing a synchronous command, the TCP router sends a response packet back to the client.
@@ -102,3 +134,94 @@ After executing an asynchronous command, the TCP router sends a response packet
102134
When a client subscribes to the status of a CSM module, it will automatically receive this packet whenever the status changes.
103135
104136
The packet format is: `Status Name >> Status Data <- Sending Module`.
137+
138+
## Communication Flow
139+
140+
### Synchronous Message Flow (`-@`)
141+
142+
After the client sends a synchronous command, it **must wait** for the server to return a response: either a `resp` (synchronous response data) or an `error` (error message). Synchronous messages do not have a `cmd-resp` handshake packet.
143+
144+
```mermaid
145+
sequenceDiagram
146+
participant C as Client
147+
participant S as TCP-Router Server
148+
149+
C->>S: cmd (synchronous message -@)
150+
alt Command executed successfully
151+
S-->>C: resp (synchronous response data)
152+
else Command execution failed
153+
S-->>C: error (error message)
154+
end
155+
```
156+
157+
### Asynchronous Message Flow (`->`)
158+
159+
After the client sends an asynchronous command, the server first returns a confirmation packet: either `cmd-resp` (command accepted) or `error` (command not accepted or execution error). Upon receiving `cmd-resp`, the client **does not need to wait** for the business response and can continue sending other commands; after asynchronous processing is complete, the server returns an `async-resp` packet.
160+
161+
```mermaid
162+
sequenceDiagram
163+
participant C as Client
164+
participant S as TCP-Router Server
165+
166+
C->>S: cmd (asynchronous message ->)
167+
alt Command accepted
168+
S-->>C: cmd-resp (command accepted)
169+
Note over S: Processing asynchronously...
170+
S-->>C: async-resp (asynchronous response data)
171+
else Not accepted or execution error
172+
S-->>C: error (error message)
173+
end
174+
```
175+
176+
### Asynchronous Without Return Flow (`->|`)
177+
178+
After the client sends an asynchronous without return command, the server first returns a confirmation packet: either `cmd-resp` (command accepted) or `error` (command not accepted or execution error). Once the command is accepted, **no** business response packet will be returned after processing is complete.
179+
180+
```mermaid
181+
sequenceDiagram
182+
participant C as Client
183+
participant S as TCP-Router Server
184+
185+
C->>S: cmd (asynchronous without return ->|)
186+
alt Command accepted
187+
S-->>C: cmd-resp (command accepted)
188+
else Not accepted or execution error
189+
S-->>C: error (error message)
190+
end
191+
```
192+
193+
### Subscribe/Unsubscribe Flow (`<register>` / `<unregister>`)
194+
195+
After the client sends a subscribe or unsubscribe command, the server returns a `cmd-resp` handshake confirmation. Once subscribed, whenever the subscribed module emits a status, the client continuously receives `status` packets (normal broadcast) or `interrupt` packets (interrupt broadcast), until unsubscribed.
196+
197+
> [!NOTE]
198+
> Both `status` and `interrupt` subscription broadcast types are supported:
199+
> - `status` (`0x06`): Normal broadcast, subscribes to regular status changes of the module
200+
> - `interrupt` (`0x07`): Interrupt broadcast, subscribes to interrupt events triggered by the module
201+
>
202+
203+
```mermaid
204+
sequenceDiagram
205+
participant C as Client
206+
participant S as TCP-Router Server
207+
participant M as CSM Module
208+
209+
C->>S: cmd (<register> subscribe)
210+
alt Subscription successful
211+
S-->>C: cmd-resp (subscription accepted)
212+
Note over M,S: When module status changes...
213+
M->>S: Normal status broadcast
214+
S-->>C: status (status data)
215+
M->>S: Interrupt broadcast
216+
S-->>C: interrupt (interrupt data)
217+
else Subscription failed
218+
S-->>C: error (error message)
219+
end
220+
221+
C->>S: cmd (<unregister> unsubscribe)
222+
alt Unsubscription successful
223+
S-->>C: cmd-resp (unsubscription accepted)
224+
else Unsubscription failed
225+
S-->>C: error (error message)
226+
end
227+
```

‎.doc/Protocol.v0.(zh-cn).md‎

Lines changed: 127 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,11 @@ CSM-TCP-Router 中 TCP 数据包格式定义如下：
2424
- 信息数据包(info) - `0x00`
2525
- 错误数据包(error) - `0x01`
2626
- 指令数据包(cmd) - `0x02`
27-
- 同步响应数据包(resp) - `0x03`
28-
- 异步响应数据包(async-resp) - `0x04`
29-
- 订阅返回数据包(status) - `0x05`
27+
- 指令响应数据包(cmd-resp) - `0x03`
28+
- 同步响应数据包(resp) - `0x04`
29+
- 异步响应数据包(async-resp) - `0x05`
30+
- 订阅普通广播返回数据包(status) - `0x06`
31+
- 订阅中断广播返回数据包(interrupt) - `0x07`
3032

3133
### FLAG1类型(1字节)
3234

@@ -42,6 +44,22 @@ FLAG2用于描述数据包的属性, 保留字段。
4244

4345
info 数据包的数据内容为提示信息内容，纯文本格式。
4446

47+
服务端会在以下两种情况下向客户端发送 `info` 数据包：
48+
49+
- **连接时**：客户端成功连接到服务器后，服务端发送欢迎 `info` 数据包：
50+
51+
```
52+
Welcome to the CSM TCP Router Server
53+
API: "list", "list api", "list states", "help"
54+
type "bye" to close connection from Server side.
55+
```
56+
57+
- **断开连接时**：当连接从服务端侧关闭时，服务端发送告别 `info` 数据包：
58+
59+
```
60+
Good bye.
61+
```
62+
4563
### 错误数据包(error)
4664

4765
error 数据包的数据内容为错误信息内容，为纯文本格式，文本格式定为 CSM Error 格式。
@@ -93,16 +111,121 @@ error 数据包的数据内容为错误信息内容，为纯文本格式，文
93111
> 当 A 模块发出 Status 后，client 将自动收到 `status` 数据包
94112
>
95113
114+
### 指令响应数据包(cmd-resp)
115+
116+
除同步消息(-@)外，其他指令数据包(cmd)在被服务端接收并处理后，都会有一个握手返回：
117+
118+
- **正常情况**：返回 `cmd-resp` 数据包，表示指令已被接受并触发执行。
119+
- **错误情况**：返回 `error` 数据包，表示指令未被接受或执行出现错误（如目标模块不存在、执行失败等）。
120+
121+
> [!NOTE]
122+
> `cmd-resp` 是对指令的握手确认，表示指令已被接受并开始执行，不包含业务响应数据。
123+
> 业务响应数据由 `resp` 或 `async-resp` 数据包返回。
124+
>
125+
> 同步消息(-@)没有 `cmd-resp` 握手，执行完成后直接返回 `resp` 或 `error`。
126+
>
127+
96128
### 同步响应数据包(resp)
97129
98130
当执行完毕同步消息指令后，tcp-router 将 response 返回给 client.
99131
100132
### 异步响应数据包(async-resp)
101133
102-
当执行完毕同步消息指令后，tcp-router 将 response 返回给 client. 格式为："`Response数据` <- `异步消息原文`"
134+
当执行完毕异步消息指令后，tcp-router 将 response 返回给 client. 格式为："`Response数据` <- `异步消息原文`"
103135
104136
### 订阅返回数据包(status)
105137
106138
Client 订阅了CSM模块的状态，当状态发生时，client 会自动收到此数据包。
107139
108140
数据包格式为 "状态名 >> `状态数据` <- 发送模块"
141+
142+
## 通信流程
143+
144+
### 同步消息流程 (`-@`)
145+
146+
客户端发送同步指令后，**必须等待**服务端返回响应：要么收到 `resp`（同步业务响应数据），要么收到 `error`（错误信息）。同步消息没有 `cmd-resp` 握手包。
147+
148+
```mermaid
149+
sequenceDiagram
150+
participant C as Client
151+
participant S as TCP-Router Server
152+
153+
C->>S: cmd (同步消息 -@)
154+
alt 指令执行成功
155+
S-->>C: resp (同步响应数据)
156+
else 指令执行失败
157+
S-->>C: error (错误信息)
158+
end
159+
```
160+
161+
### 异步消息流程 (`->`)
162+
163+
客户端发送异步指令后，服务端首先返回确认包：要么是 `cmd-resp`（指令已接受），要么是 `error`（指令未被接受或执行出现错误）。若收到 `cmd-resp`，客户端**无需等待**业务响应，可继续发送其他指令；服务端异步处理完毕后，返回 `async-resp` 数据包。
164+
165+
```mermaid
166+
sequenceDiagram
167+
participant C as Client
168+
participant S as TCP-Router Server
169+
170+
C->>S: cmd (异步消息 ->)
171+
alt 指令已接受
172+
S-->>C: cmd-resp (指令已接受)
173+
Note over S: 异步处理中...
174+
S-->>C: async-resp (异步响应数据)
175+
else 未被接受或执行出错
176+
S-->>C: error (错误信息)
177+
end
178+
```
179+
180+
### 异步无返回消息流程 (`->|`)
181+
182+
客户端发送异步无返回指令后，服务端首先返回确认包：要么是 `cmd-resp`（指令已接受），要么是 `error`（指令未被接受或执行出现错误）。指令被接受后，业务处理完成后**不会**返回业务响应数据包。
183+
184+
```mermaid
185+
sequenceDiagram
186+
participant C as Client
187+
participant S as TCP-Router Server
188+
189+
C->>S: cmd (异步无返回消息 ->|)
190+
alt 指令已接受
191+
S-->>C: cmd-resp (指令已接受)
192+
else 未被接受或执行出错
193+
S-->>C: error (错误信息)
194+
end
195+
```
196+
197+
### 订阅/注销流程 (`<register>` / `<unregister>`)
198+
199+
客户端发送订阅或注销指令后，服务端返回 `cmd-resp` 握手确认。订阅成功后，每当被订阅模块发出状态，客户端会持续收到 `status` 数据包（普通广播）或 `interrupt` 数据包（中断广播），直到取消订阅。
200+
201+
> [!NOTE]
202+
> `status` 和 `interrupt` 两种订阅广播类型均受支持：
203+
> - `status`（`0x06`）：普通广播，订阅模块的常规状态变化
204+
> - `interrupt`（`0x07`）：中断广播，订阅模块触发的中断事件
205+
>
206+
207+
```mermaid
208+
sequenceDiagram
209+
participant C as Client
210+
participant S as TCP-Router Server
211+
participant M as CSM 模块
212+
213+
C->>S: cmd (<register> 订阅)
214+
alt 订阅成功
215+
S-->>C: cmd-resp (订阅已接受)
216+
Note over M,S: 模块状态变化时...
217+
M->>S: 普通状态广播
218+
S-->>C: status (状态数据)
219+
M->>S: 中断广播
220+
S-->>C: interrupt (中断数据)
221+
else 订阅失败
222+
S-->>C: error (错误信息)
223+
end
224+
225+
C->>S: cmd (<unregister> 取消订阅)
226+
alt 取消成功
227+
S-->>C: cmd-resp (取消订阅已接受)
228+
else 取消失败
229+
S-->>C: error (错误信息)
230+
end
231+
```

‎CSM-TCP-Router.lvcsm‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ Item 26 = "DoSth: DoB"
4242
VIName = "HAL-DIO.vi"
4343

4444
[CSMVI.HAL-DIO.vi]
45-
Path = "<AppDir>/Server/CSM_Modules/HAL-DIO.vi"
45+
Path = "<AppDir>/src/Server/CSM_Modules/HAL-DIO.vi"
4646

4747
[CSMAPI.HAL-DIO.vi]
4848
Item 0 = "Turn On"
@@ -126,8 +126,8 @@ Item 27 = "action: loop check"
126126
Item 28 = "action: end loop"
127127

128128
[CSM Debug Console]
129-
Response Timeout(s) = 30
130-
History Length = 50
129+
Response Timeout(s) = 30
130+
History Length = 50
131131
Periodic Enable = TRUE
132132
Periodic threashold(#/s) = 0.500000
133133
Periodic Check Peroid(s) = 3.000000
@@ -219,4 +219,13 @@ doc = "DIO Module with 8 Channels.%0AAPI:%0A1. TurnOn %3E%3E ChannelIndex %2F%2F
219219
doc = "Measurement Module.%0AAPI: %0A1. Sweep %3E%3E Start%3BStop%3BStep%3BInterval %2F%2F sweep current with specified parameters.%0A2. Measure %2F%2F Return voltage and current at the same time."
220220

221221
[CSMModule.Measure2]
222-
VIName = "MAL-TEST.vi"
222+
VIName = "MAL-TEST.vi"
223+
224+
[CSMStatus.HAL-AI.vi]
225+
Item 0 = "Error Occurred@Error Handler"
226+
227+
[CSMStatus.HAL-DIO.vi]
228+
Item 0 = "Error Occurred@Error Handler"
229+
230+
[DebugConsole.historyView]
231+
History Length = 50

‎CSM-TCP-Router.vipb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
<VI_Package_Builder_Settings Version="2020.1" Created_Date="2023-09-27 14:21:53" Modified_Date="2026-01-26 15:46:53" Creator="liyao" Comments="" ID="9be59efe978fc03e0dca4e48f00eb858">
1+
<VI_Package_Builder_Settings Version="2020.1" Created_Date="2023-09-27 14:21:53" Modified_Date="2026-03-16 16:40:38" Creator="liyao" Comments="" ID="d7994e1d8355f1a11a3780dc872b3bc2">
22
<Library_General_Settings>
33
<Package_File_Name>NEVSTOP_lib_CSM_TCP_Router_Example</Package_File_Name>
4-
<Library_Version>2025.12.0.5</Library_Version>
4+
<Library_Version>2026.1.0.5</Library_Version>
55
<Auto_Increment_Version>false</Auto_Increment_Version>
66
<Library_Source_Folder>src</Library_Source_Folder>
77
<Library_Output_Folder>vip</Library_Output_Folder>
@@ -74,7 +74,7 @@
7474
<Copyright/>
7575
<Packager>NEVSTOP</Packager>
7676
<URL>https://github.com/NEVSTOP-LAB/CSM-TCP-Router-App</URL>
77-
<Release_Notes/>
77+
<Release_Notes>[add] #23 Export "Net Address" for bind server to network adapter.</Release_Notes>
7878
</Description>
7979
<Destinations>
8080
<Toolkit_VIs>

0 commit comments

Comments
 (0)