139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# DataRouter
|
|
|
|
轻量级 C 语言数据路由库。发送能力和接收能力分开声明，端口绑定 `send_type` + `recv_type` + handler 列表。发送时自动广播到所有匹配端口，接收时 `dr_port_dispatch()` 自动路由到对应回调。
|
|
|
|
## 概念
|
|
|
|
| 术语 | 说明 |
|
|
|------|------|
|
|
| **发送能力** | 编译期声明的可发送报文类型，生成 `dr_send_<id>(data, len)` |
|
|
| **接收能力** | 编译期声明的可接收报文类型，生成 `dr_on_recv_<id>(port, data, len)` |
|
|
| **端口** | 运行期连接点，包含 `send_type` + `recv_type` + handler 列表 |
|
|
| **Handler** | 用户实现的物理外设发送函数，一个端口可注册多个（默认上限 4） |
|
|
| **Dispatch** | `dr_port_dispatch(port, data, len)` 根据端口的 `recv_type` 自动路由到回调 |
|
|
|
|
## 快速开始
|
|
|
|
### 1. 声明能力
|
|
|
|
创建自己的 `datarouter_config.h`（可参考 `datarouter_config_template.h`）：
|
|
|
|
```c
|
|
#define DR_SEND_CAPABILITIES \
|
|
DR_SEND(sensor, "Sensor data report") \
|
|
DR_SEND(status, "Device status report")
|
|
|
|
#define DR_RECV_CAPABILITIES \
|
|
DR_RECV(rtcm, "RTCM correction data") \
|
|
DR_RECV(command, "Remote control command")
|
|
```
|
|
|
|
### 2. 实现 handler 和回调
|
|
|
|
```c
|
|
static void uart_write(uint32_t port_id, const void *data, size_t len) {
|
|
HAL_UART_Transmit(&huart1, data, len, 1000);
|
|
}
|
|
|
|
void dr_on_recv_rtcm(uint32_t port_id, const void *data, size_t len) {
|
|
apply_rtcm_correction(data, len);
|
|
}
|
|
```
|
|
|
|
### 3. 创建端口
|
|
|
|
```c
|
|
dr_init();
|
|
|
|
dr_port_t uart = dr_port_create();
|
|
dr_port_set_send_type(uart, DR_SEND_sensor);
|
|
dr_port_set_recv_type(uart, DR_RECV_rtcm);
|
|
dr_port_add_handler(uart, uart_write);
|
|
dr_port_add_handler(uart, tcp_write);
|
|
|
|
/* 发送：自动广播到所有 send_type=sensor 的端口 */
|
|
dr_send_sensor("temperature:25.3", 16);
|
|
|
|
/* 接收：外设中断中一行 dispatch，自动调 dr_on_recv_rtcm() */
|
|
dr_port_dispatch(uart, data, len);
|
|
```
|
|
|
|
## API 一览
|
|
|
|
### 初始化
|
|
|
|
```c
|
|
void dr_init(void);
|
|
void dr_reset(void);
|
|
```
|
|
|
|
### 端口管理
|
|
|
|
```c
|
|
dr_port_t dr_port_create(void);
|
|
void dr_port_delete(dr_port_t port);
|
|
|
|
void dr_port_set_send_type(port, int cap_id);
|
|
int dr_port_get_send_type(port);
|
|
void dr_port_set_recv_type(port, int cap_id);
|
|
int dr_port_get_recv_type(port);
|
|
|
|
int dr_port_add_handler(port, handler);
|
|
int dr_port_remove_handler(port, handler);
|
|
void dr_port_clear_handlers(port);
|
|
int dr_port_handler_count(port);
|
|
|
|
void dr_port_dispatch(port, data, len); /* 自动路由接收 */
|
|
```
|
|
|
|
### 发送触发
|
|
|
|
```c
|
|
int dr_send_sensor(const void *data, size_t len); // 0 成功
|
|
int dr_send_status(const void *data, size_t len); // -1 未初始化
|
|
// -2 无匹配端口
|
|
```
|
|
|
|
### 接收回调
|
|
|
|
```c
|
|
void dr_on_recv_rtcm(uint32_t port_id, const void *data, size_t len);
|
|
void dr_on_recv_command(uint32_t port_id, const void *data, size_t len);
|
|
```
|
|
|
|
### 能力元数据
|
|
|
|
```c
|
|
int dr_send_cap_count(void);
|
|
const char *dr_send_cap_name(int cap_id);
|
|
const char *dr_send_cap_desc(int cap_id);
|
|
|
|
int dr_recv_cap_count(void);
|
|
const char *dr_recv_cap_name(int cap_id);
|
|
const char *dr_recv_cap_desc(int cap_id);
|
|
```
|
|
|
|
## 路由模型
|
|
|
|
```
|
|
发送：dr_send_sensor("temp:25.3", 9)
|
|
│
|
|
├─→ port A (send_type=sensor) handlers = [uart_write, tcp_write]
|
|
└─→ port B (send_type=sensor) handlers = [can_write]
|
|
|
|
接收：dr_port_dispatch(uart1, data, len)
|
|
│
|
|
└─→ uart1.recv_type = DR_RECV_rtcm
|
|
└─→ dr_on_recv_rtcm(uart1, data, len) ← 查表调用
|
|
```
|
|
|
|
## 测试
|
|
|
|
```bash
|
|
cmake --build build
|
|
ctest --test-dir build
|
|
./build/test_datarouter
|
|
```
|
|
|
|
当前 24 个测试用例，覆盖端口管理、send_type/recv_type、handler、自动广播、dispatch、能力元数据。
|