# ws2serial

**Repository Path**: AdvLoveLace/ws2serial

## Basic Information

- **Project Name**: ws2serial
- **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-06-02
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ws2serial

WebSocket 数据订阅 → 串口转发工具

连接指定的 WebSocket 服务订阅实时数据，并将收到的每条消息（自动去除 `assets` 字段）透传到物理串口设备。

## 工作原理

```
┌─────────────────┐     WebSocket      ┌──────────────┐     Serial      ┌──────────┐
│  ws://172.20... │ ──────────────────> │  ws2serial   │ ──────────────> │ /dev/tty │
│  traffic_tunnel │    订阅实时事件     │  (本工具)     │   透传原始消息   │  USB0    │
└─────────────────┘                    └──────────────┘                 └──────────┘
```

---

## 方式一：离线部署（推荐）

> 适用于 Linux 无网环境，需要 Linux 上已有 Python 3.9+

### Windows 上准备（有网的开发机）

```powershell
cd .\ws2serial
.\export.ps1
```

此脚本会自动：

1. 下载 Linux aarch64 版 `uv` 二进制文件
2. 下载 Linux aarch64 平台的 Python 依赖包（.whl）
3. 打包为 `ws2serial.tar.gz`

### 拷贝到 Linux

将 `ws2serial.tar.gz` 拷贝到 Linux 机器（U 盘 / SCP 等）。

### Linux 上部署运行

```bash
tar -xzf ws2serial.tar.gz
cd ws2serial
chmod +x setup.sh run.sh
./setup.sh    # 首次安装 uv + venv + 依赖 + 注册 systemd 服务
./run.sh      # 或直接前台运行（不经过服务）
```

`setup.sh` 自动完成：安装 `uv` → 创建虚拟环境 → 安装依赖 → **注册 systemd 服务**。
`run.sh` 读取环境变量直接启动程序。

### systemd 服务管理

`setup.sh` 会自动安装服务到 `/etc/systemd/system/ws2serial.service`。

```bash
sudo systemctl enable ws2serial     # 开机自启
sudo systemctl start ws2serial      # 立即启动
sudo systemctl status ws2serial     # 查看状态
sudo systemctl restart ws2serial    # 重启
sudo journalctl -u ws2serial -f     # 查看日志
```

**修改配置参数**（两种方式任选其一）：

方式 A — 覆盖环境变量：

```bash
sudo systemctl edit ws2serial
# 在弹出的编辑器中写入：
# [Service]
# Environment="SERIAL_PORT=/dev/ttyUSB1"
# Environment="BAUD_RATE=9600"
```

方式 B — 创建 env 文件：

```bash
cat > ws2serial.env << 'EOF'
SERIAL_PORT=/dev/ttyUSB1
BAUD_RATE=9600
WS_URL=ws://your-server:9901/scv/api/traffic_tunnel/subscribe
LOG_LEVEL=DEBUG
RECONNECT_INTERVAL=5.0
ADD_NEWLINE=true
EOF
sudo systemctl restart ws2serial
```

**卸载服务**：

```bash
sudo systemctl stop ws2serial
sudo systemctl disable ws2serial
sudo rm /etc/systemd/system/ws2serial.service
sudo systemctl daemon-reload
```

---

## 方式二：直接运行（Linux 有网）

```bash
# 安装 uv（一次性）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 运行
uv run ws2serial --serial /dev/ttyUSB0
```

`uv` 自动创建虚拟环境并安装依赖，无需手动 `pip install`。

---

## 方式三：传统 pip 运行（有网 / 已有依赖）

```bash
pip3 install -r requirements.txt
python3 ws2serial.py --serial /dev/ttyUSB0
```

---

## 命令行参数

| 参数                   | 必需 | 默认值   | 说明                                |
| ---------------------- | :--: | -------- | ----------------------------------- |
| `--serial` / `-s`      |  是  | —        | 串口设备路径                        |
| `--baud` / `-b`        |  否  | `115200` | 波特率                              |
| `--url`                |  否  | 见下方   | WebSocket 订阅地址                  |
| `--bytesize`           |  否  | `8`      | 数据位 (5/6/7/8)                    |
| `--parity`             |  否  | `N`      | 校验位 (N/E/O/M/S)                  |
| `--stopbits`           |  否  | `1.0`    | 停止位 (1.0/1.5/2.0)                |
| `--timeout`            |  否  | `1.0`    | 串口读写超时(秒)                    |
| `--reconnect-interval` |  否  | `3.0`    | WebSocket 断线重连间隔(秒)          |
| `--add-newline`        |  否  | 否       | 每条消息末尾追加换行符              |
| `--log-level`          |  否  | `INFO`   | 日志级别 (DEBUG/INFO/WARNING/ERROR) |
| `--log-file`           |  否  | —        | 日志文件路径                        |

默认 WebSocket 地址：`ws://172.20.40.100:9901/scv/api/traffic_tunnel/subscribe?sub_types=event`

---

## 环境变量参考

适用于离线部署方式：

| 变量                 | 默认值         | 说明               |
| -------------------- | -------------- | ------------------ |
| `SERIAL_PORT`        | `/dev/ttyUSB0` | 串口设备路径       |
| `BAUD_RATE`          | `115200`       | 波特率             |
| `WS_URL`             | 见上方         | WebSocket 订阅地址 |
| `LOG_LEVEL`          | `INFO`         | 日志级别           |
| `RECONNECT_INTERVAL` | `3.0`          | 重连间隔(秒)       |
| `ADD_NEWLINE`        | `false`        | 是否追加换行符     |

---

## 数据格式处理

收到 WebSocket 消息后，脚本会自动去除 `assets` 字段，其余 JSON 内容完整转发到串口：

```json
// 原始消息
{ "id":"...", "tunnel_id":"section", ..., "assets":[...] }

// 转发到串口（assets 已移除）
{ "id":"...", "tunnel_id":"section", ... }
```

---

## 故障排查

### 串口权限问题

```bash
sudo usermod -aG dialout $USER
# 重新登录后生效
```

### 验证串口通信

```bash
minicom -D /dev/ttyUSB0 -b 115200
# 或
screen /dev/ttyUSB0 115200
```

### 常见问题

| 现象                | 可能原因             | 解决                             |
| ------------------- | -------------------- | -------------------------------- |
| `Permission denied` | 无串口权限           | `sudo usermod -aG dialout $USER` |
| WebSocket 反复重连  | 网络不通或服务未启动 | `curl` 测试目标地址可达性        |
| 串口乱码            | 波特率不匹配         | 确认对端设备波特率               |