# bblood

**Repository Path**: script2000/bblood

## Basic Information

- **Project Name**: bblood
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BrainFlow Bridge — 脑血流数据串口 / TCP 中转服务

## 概述

BrainFlow Bridge 是一款无 GUI 的后台常驻服务，运行在医疗上位机上，负责：
- 从 **STM32 + LDC1612** 通过串口（115200-8N1）采集双通道脑血流数据
- 解析固定格式的文本行，封装为 JSON
- 通过 TCP（127.0.0.1:8899）广播给局域网内的监护 UI 客户端

包含两个变体：

| 变体 | 可执行文件 | 用途 |
|------|-----------|------|
| **Serial** (`brainflow-bridge`) | 读取真实串口设备 | 生产环境部署 |
| **Mock** (`brainflow-mock`) | 算法生成正弦波+噪声模拟数据 | UI 开发调试、演示 |

┌──────────────────┐     串口(115200-8N1)      ┌──────────────────────────┐     TCP 127.0.0.1:8899     ┌───────────────────┐
│ STM32 + LDC1612  │ ────────────────────────→ │  BrainFlow Bridge       │ ──────────────────────────→ │  监护 UI 客户端    │
│ (下位采集设备)     │    文本行数据              │  (serial ｜ mock 变体)    │     Line-delimited JSON     │  (Qt Widgets)      │
└──────────────────┘                          └──────────────────────────┘                             └───────────────────┘
                                                           │
                                                           │ TCP
                                                           ▼
                                                  ┌───────────────────┐
                                                  │ 调试工具 / 日志     │
                                                  └───────────────────┘

## 快速开始

### 前提条件

| 要求 | 说明 |
|------|------|
| 操作系统 | Windows 10+ 或 Linux (x86_64) |
| Qt 版本 | Qt 6.5+ |
| 编译器 | Clang 22+ |
| Pixi | 包管理器，用于自动安装 CMake/Ninja/Clang/Qt |

### 安装 Pixi

**Windows (PowerShell):**
```powershell
powershell -c "irm -Uri https://pixi.sh/install.ps1 | iex"
```

**Linux / macOS:**
```bash
curl -fsSL https://pixi.sh/install.sh | bash
```

### 编译

```bash
cd server_blood

# 完整构建（服务 + 监控客户端）
pixi run build

# 仅构建服务
pixi run build-server

# 仅构建监控客户端
pixi run build-monitor
```

### 运行服务

```bash
# Windows — 指定串口号运行（服务启动后 TCP 即开始监听 8899）
pixi run run-windows -- COM3

# Linux
pixi run run-linux -- /dev/ttyACM0

# 可选：使用非默认端口
pixi run run-windows -- COM5 --port=8899
```

### 运行 Mock 服务（无需串口硬件）

```bash
# Windows
pixi run run-mock-windows

# Linux
pixi run run-mock-linux
```

Mock 服务在 127.0.0.1:8899 监听，每 100ms 生成一组正弦波+噪声模拟数据，输出格式与 Serial 变体完全一致。

### 监控客户端

```bash
pixi run run-monitor
```

## 项目结构

```
server_blood/
├── pixi.toml                   # Pixi 包管理 + 运行任务
├── README.md                   # 本文件
├── server/                     # 中转服务（两个变体共享 brainflow-core 库）
│   ├── CMakeLists.txt
│   ├── include/
│   │   ├── BrainFlowData.h     # 数据模型（共享）
│   │   └── TcpBroadcastServer.h# TCP 广播服务器（共享）
│   ├── src/
│   │   └── TcpBroadcastServer.cpp
│   ├── serial/                 # Serial 变体
│   │   ├── include/SerialWorker.h
│   │   ├── src/SerialWorker.cpp
│   │   └── main.cpp
│   └── mock/                   # Mock 变体
│       ├── include/MockDataGenerator.h
│       ├── src/MockDataGenerator.cpp
│       └── main.cpp
│
├── monitor/                    # 监护 UI 客户端（独立子项目）
│   ├── CMakeLists.txt
│   ├── include/
│   │   ├── MainWindow.h
│   │   └── qcustomplot.h
│   ├── src/
│   │   ├── MainWindow.cpp
│   │   ├── main.cpp
│   │   └── qcustomplot.cpp
│   └── README.md
│
└── build/
    ├── server/                 # brainflow-bridge.exe + brainflow-mock.exe
    └── monitor/                # brainflow-monitor.exe
```

## TCP 协议规范

### 连接参数

| 参数 | 值 |
|------|-----|
| 地址 | `127.0.0.1`（仅本地回环） |
| 端口 | `8899`（可配置） |
| 传输协议 | TCP |
| 编码 | UTF-8 |

### JSON 数据格式 (Line-delimited JSON)
每条消息为单行 JSON，以 `\n` 结尾。客户端按行读取 JSON：

```json
{"type":"data","timestamp":"2026-07-10T18:20:05.384","raw_ch1":268435452,"raw_ch2":268435450,"flow_ch1":2.500000,"flow_ch2":2.499997,"protocol_version":"1.0"}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | string | 固定值 `"data"` |
| `timestamp` | string | ISO 8601，含毫秒 |
| `raw_ch1` | number | LDC1612 通道 1 原始值（28-bit，0 ~ 0x0FFFFFFF） |
| `raw_ch2` | number | LDC1612 通道 2 原始值 |
| `flow_ch1` | number | 通道 1 脑血流计算值（经 `raw * 40 / 2^28` 换算） |
| `flow_ch2` | number | 通道 2 脑血流计算值 |
| `protocol_version` | string | 协议版本号，用于客户端向后兼容 |

### 串口数据格式

来源于 STM32 固件中的 `printf` 调用：

```c
printf("RAW:0x%08lX 0x%08lX | ch1=%.6f, ch2=%.6f\r\n", raw0, raw1, ch1[1], ch2[1]);
```

真实输出示例：

```
RAW:0x0FFFFFFC 0x0FFFFFFA | ch1=2.500000, ch2=2.499997
```

| 字段 | 格式 | 说明 |
|------|------|------|
| RAW 值 | `0x%08lX` | u32 十六进制（28-bit 有效） |
| ch1 | `%.6f` | 通道 1 脑血流计算值（6 位小数） |
| ch2 | `%.6f` | 通道 2 脑血流计算值（6 位小数） |
| 分隔符 | 竖线 `\|` | 分隔 RAWs 与通道值 |

## 运行状态说明

正常启动后的控制台日志示例：

```
[2026-07-10 18:20:05.382] [INFO] 脑血流数据中转服务启动  串口: COM3  TCP端口: 8899  Qt版本: 6.9.2
[2026-07-10 18:20:05.384] [INFO] [TcpServer] 监听 127.0.0.1:8899 (仅本地回环)
[2026-07-10 18:20:05.384] [INFO] [TcpServer] 服务已启动 → 127.0.0.1:8899
[2026-07-10 18:20:05.384] [INFO] [Main] 服务已就绪，等待串口数据和客户端连接…
[2026-07-10 18:20:05.384] [INFO] [SerialWorker] 启动 COM3 @ 115200-8N1
[2026-07-10 18:20:05.384] [INFO] [SerialWorker] 串口 COM3 已成功打开
```

串口丢失或未连接时自动进入指数退避重连（2s → 4s → 8s → 16s → 30s 封顶）。

## 异常与容错

### 数据校验

串口解析时执行以下校验，不满足任一条件的数据帧将被静默丢弃：

| 校验项 | 规则 |
|--------|------|
| 空行 / 注释行 | 跳过空白行及以 `#` 或 `//` 开头的行 |
| 正则匹配 | 必须匹配格式 `RAW:0xHHHHHHHH 0xHHHHHHHH \| ch1=F, ch2=F` |
| RAW 值范围 | 0 ~ 4.29×10⁹（u32 范围） |
| 流量值范围 | -1000.0 ~ 1000.0 |

### 串口自动重连

串口断开或打开失败时，自动进入指数退避重连策略：

| 重试次数 | 等待时间 |
|----------|----------|
| 第 1 次 | 2 秒 |
| 第 2 次 | 4 秒 |
| 第 3 次 | 8 秒 |
| 第 4 次 | 16 秒 |
| 第 5 次及以上 | 30 秒（封顶） |

## 配置

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `<串口号>` | 串口设备路径（必填，位置参数） | — |
| `--port=<N>` | TCP 监听端口 | `8899` |

示例：

```bash
# 最小启动
pixi run run-windows -- COM3

# 自定义 TCP 端口
pixi run run-windows -- COM5 --port=9999
```