# simple-net-trans

**Repository Path**: xiaoqinxing/simple-net-trans

## Basic Information

- **Project Name**: simple-net-trans
- **Description**: 网络传输库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Transmission 使用说明

本文档说明如何构建、测试和运行 `transmission` C++17 网络传输子系统。

## 环境要求

- Linux 主机。
- CMake 3.14 或更新版本。
- 支持 C++17 的编译器。
- 集成测试需要可用的本机 loopback 网络。
- 首次构建测试时，如果本地没有 GoogleTest 缓存，需要能访问网络供 CMake 拉取依赖。
- 可选：安装 `ffplay`，用于手动验证 TCP 视频播放。

## 项目结构

| 路径 | 用途 |
|---|---|
| `transmission/include/trans/` | `trans::` 命名空间下的公开头文件。 |
| `transmission/src/` | 库实现代码。 |
| `transmission/tests/` | 单元测试和 localhost 集成测试。 |
| `transmission/examples/` | 示例服务和客户端工具。 |
| `transmission/platform/` | HiSilicon 适配边界，由 `TRANS_ENABLE_HISI` 控制。 |
| `docs/design.md` | 设计和架构参考。 |

## 构建库和测试

在仓库根目录执行：

```bash
cmake -S transmission -B build -DTRANS_BUILD_TESTS=ON -DTRANS_ENABLE_HISI=OFF
cmake --build build
```

运行测试：

```bash
ctest --test-dir build --output-on-failure
```

主库目标是 `transmission`，构建产物为 build 目录下的 `libtransmission.a`。

## 构建示例程序

示例程序默认不构建，需要显式启用 `TRANS_BUILD_EXAMPLES=ON`：

```bash
cmake -S transmission -B build -DTRANS_BUILD_TESTS=ON -DTRANS_BUILD_EXAMPLES=ON -DTRANS_ENABLE_HISI=OFF
cmake --build build
```

会生成以下二进制：

| 二进制 | 用途 |
|---|---|
| `build/trans_board_server_example` | 模拟板端进程，提供控制、视频和日志行为。 |
| `build/trans_control_client` | 发送控制请求的命令行工具。 |
| `build/trans_udp_log_receiver` | UDP 日志接收命令行工具。 |

## 快速验证

启动模拟板端服务：

```bash
./build/trans_board_server_example --control-port 19091 --video-port 19090 --duration-ms 3000
```

在另一个终端查询状态：

```bash
./build/trans_control_client --port 19091 get-status
```

预期结果：客户端输出一行 JSON 响应，包含 `streaming`、`bitrate_kbps`、`fps`、`gop`、`idr_count` 等状态字段。

## 控制命令

控制客户端默认连接 TCP `9001` 端口，可通过 `--host` 和 `--port` 覆盖。

```bash
./build/trans_control_client --host 127.0.0.1 --port 9001 get-status
./build/trans_control_client --port 9001 start-stream --chn 0
./build/trans_control_client --port 9001 stop-stream --chn 0
./build/trans_control_client --port 9001 force-idr --chn 0
./build/trans_control_client --port 9001 set-bitrate --chn 0 --kbps 4096
./build/trans_control_client --port 9001 ping --id 7
```

命令分发器也支持 `set_fps` 和 `set_gop`。如果示例客户端没有提供独立快捷命令，可以使用 raw 模式发送：

```bash
./build/trans_control_client --port 9001 raw --json '{"type":"request","version":1,"id":1,"method":"set_fps","params":{"chn":0,"fps":30}}'
./build/trans_control_client --port 9001 raw --json '{"type":"request","version":1,"id":2,"method":"set_gop","params":{"chn":0,"gop":60}}'
```

## UDP 日志订阅

启动 UDP 日志接收器：

```bash
./build/trans_udp_log_receiver --port 19092 --count 1
```

在另一个终端启动模拟板端服务：

```bash
./build/trans_board_server_example --control-port 19093 --video-port 19094 --duration-ms 2500
```

通过控制通道订阅日志：

```bash
./build/trans_control_client --port 19093 subscribe-log --udp-port 19092 --level info
```

预期结果：UDP 接收器输出一个 JSON 日志包，例如示例 heartbeat 日志。

更新或取消日志订阅：

```bash
./build/trans_control_client --port 19093 set-log-level --level warn
./build/trans_control_client --port 19093 unsubscribe-log
```

日志级别由 transmission 库解析。通常使用小写值，例如 `debug`、`info`、`warn` 和 `error`。

## 视频播放

视频服务默认向 TCP `9000` 端口写入原始 Annex-B 字节流。示例服务只发送用于传输测试的模拟 Annex-B 风格数据；生产板端集成应发布真实 H.264/H.265 VENC 输出。

真实 H.264 流播放示例：

```bash
ffplay -fflags nobuffer -flags low_delay -f h264 tcp://127.0.0.1:9000
```

真实 H.265/HEVC 流播放示例：

```bash
ffplay -fflags nobuffer -flags low_delay -f hevc tcp://127.0.0.1:9000
```

使用示例服务时，建议优先做控制和日志 smoke test；因为示例视频负载不是完整编码视频序列，不能保证可视化播放。

## 示例服务参数

```bash
./build/trans_board_server_example [--host 127.0.0.1] [--control-port 9001] [--video-port 9000] [--duration-ms 0] [--no-video] [--no-logs]
```

常见用法：

```bash
./build/trans_board_server_example
./build/trans_board_server_example --control-port 19091 --video-port 19090 --duration-ms 5000
./build/trans_board_server_example --no-video
./build/trans_board_server_example --no-logs
```

`--duration-ms 0` 表示一直运行，直到按下 `Ctrl+C` 或收到终止信号。

## 板端/交叉编译

HiSilicon 板端构建通常关闭主机测试，并启用 HiSilicon 适配边界：

```bash
cmake -S transmission -B build-board -DTRANS_BUILD_TESTS=OFF -DTRANS_ENABLE_HISI=ON -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain.cmake
cmake --build build-board
```

当前 HiSilicon adapter 仍是桩边界。生产板端构建还需要实现基于 MPP 的 `PlatformAdapter`，并添加板端入口，将 VENC Annex-B 输出送入 `VideoStreamServer`。

## 常见问题

| 现象 | 排查方式 |
|---|---|
| CMake 无法拉取 GoogleTest | 确认网络可用；非测试构建可使用 `-DTRANS_BUILD_TESTS=OFF`。 |
| 测试绑定 socket 失败 | 确认 localhost 网络可用，并检查环境是否限制端口绑定。 |
| 控制客户端提示 `failed to connect` | 确认服务端正在运行，并确认 `--host`、`--port` 与服务端输出一致。 |
| UDP 接收器超时 | 先启动接收器再订阅，确认 `--udp-port` 一致，并确认服务端未使用 `--no-logs`。 |
| `ffplay` 使用示例服务时没有有效画面 | 示例服务发送的是模拟数据，不是完整编码流；请使用真实 VENC 输出验证播放。 |
| 端口被占用 | 更换 `--control-port`、`--video-port` 或 UDP 接收器 `--port`。 |

## 开发注意事项

- 将 socket 无关逻辑放在 `transmission/src/` 下的小模块中，并补充测试。
- 将板端 SDK 调用隔离在 `PlatformAdapter` 后面。
- 不要在同一个端口混用视频、控制或日志流量。
- 优先使用有界队列和明确的丢弃/断连策略，不要无限缓冲。
- 交付变更前运行 `ctest --test-dir build --output-on-failure`。