# serial-network-forwarder

**Repository Path**: wujin-alex/serial-network-forwarder

## Basic Information

- **Project Name**: serial-network-forwarder
- **Description**: 用于串口与网络之间的通信转发，包括串口转TCP、串口转UDP单播、串口转UDP组播
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# serial_to_udp.py — 串口转UDP单播

**单向**转发工具：从串口读取数据，通过 UDP 单播发送到一个或多个远端目标。

**在实际使用过程中一定要先确认远端目标IP地址，并进行修改！**

```bash
# 单个 UDP 目标
python serial_to_udp.py --serial COM3 --target 192.168.1.100:9000

# 多个 UDP 目标（-t 可重复）
python serial_to_udp.py --serial COM3 -t 192.168.1.100:9000 -t 192.168.1.101:9001

# 使用配置文件
python serial_to_udp.py --config config_serial2udp.json
```

# udp_to_serial.py — UDP单播转串口

**单向**转发工具：监听本地 UDP 端口，将收到的数据写入串口。

```bash
# 监听 0.0.0.0:9010，转发到串口
python udp_to_serial.py --port 9010 --serial COM3

# 仅绑定特定网卡
python udp_to_serial.py --host 192.168.1.100 --port 9010 --serial /dev/ttyUSB0

# 使用配置文件
python udp_to_serial.py --config config_udp2serial.json
```

# Serial ↔ Network Bidirectional Forwarder

跨平台（Windows + Linux）串口与网络双向透明数据转发工具。

## 功能

- **TCP Server 模式**：监听端口，允许多个 TCP 客户端同时连接，串口数据广播到所有客户端
- **TCP Client 模式**：主动连接远端 TCP 服务器，支持自动重连
- **UDP 单播模式**：点对点 UDP 通信转发，支持本地/远端地址和端口分离
- **UDP 组播模式**：加入组播组，一对多数据分发，支持本地/远端端口分离
- **JSON 配置文件**：支持通过配置文件统一管理参数
- **透明转发**：不对数据做任何解析/分帧，原样传递

## 依赖

- Python 3.8+
- pyserial >= 3.5

```bash
pip install pyserial
pip install pyserial-asyncio
```

## 快速开始

### 1. UDP 单播模式

```bash
# 本地地址/端口和远端相同（--host/--port 同时用于绑定和发送）
python serial_tcp_forwarder.py --protocol udp_unicast --host 192.168.1.100 --port 9999 --serial /dev/ttyUSB0

# 本地绑定 0.0.0.0:20001 接收，发送到远端 192.168.1.100:20002
python serial_tcp_forwarder.py --protocol udp_unicast --host 192.168.1.100 --local-host 0.0.0.0 --local-port 20001 --remote-port 20002 --serial /dev/ttyUSB0
```

### 2. UDP 组播模式

```bash
# 本地端口和远端端口相同
python serial_tcp_forwarder.py --protocol udp_multicast --host 127.0.0.1 --multicast-group 226.0.1.80 --port 9000 --serial COM20 --multicast-ttl 2

# 本地端口和远端端口不同（例如：绑定 20001 监听，发送到组播组 :9000）
python serial_tcp_forwarder.py --protocol udp_multicast --host 127.0.0.1 --multicast-group 226.0.1.80 --local-port 20001 --remote-port 9000 --serial COM20 --multicast-ttl 2

# raspberryPi
python serial_tcp_forwarder.py --protocol udp_multicast --host 127.0.0.1 --multicast-group 226.0.1.80 --port 9000 --serial /dev/ttyAMA4 --multicast-ttl 2
```

### 3. TCP Server 模式（多客户端）

```bash
# Windows
python serial_tcp_forwarder.py --protocol tcp_server --host 0.0.0.0 --port 8888 --serial COM3 --baudrate 115200

# Linux
python serial_tcp_forwarder.py --protocol tcp_server --host 0.0.0.0 --port 8888 --serial /dev/ttyUSB0 --baudrate 115200
```

### 4. TCP Client 模式

```bash
python serial_tcp_forwarder.py --protocol tcp_client --host 192.168.1.100 --port 8888 --serial /dev/ttyUSB0
```

### 5. 串口 → UDP 单播模式（单向，多目标）

```bash
# 单个 UDP 目标
python serial_to_udp.py --serial COM3 --target 192.168.1.100:9000

# 多个 UDP 目标
python serial_to_udp.py --serial COM3 -t 192.168.1.100:9000 -t 192.168.1.101:9001

# 使用配置文件
python serial_to_udp.py --config config_serial2udp.json
```

### 6. UDP 单播 → 串口模式（单向，单源）

```bash
# 监听 0.0.0.0:9010，转发到串口
python udp_to_serial.py --port 9010 --serial COM3

# 绑定特定网卡
python udp_to_serial.py --host 192.168.1.100 --port 9010 --serial /dev/ttyUSB0

# 使用配置文件
python udp_to_serial.py --config config_udp2serial.json
```

### 7. 使用配置文件

```bash
python serial_tcp_forwarder.py --config config.json

# 配置文件 + 命令行覆盖（命令行优先级更高）
python serial_tcp_forwarder.py --config config.json --serial COM5 --log-level DEBUG
```

## 命令行参数

### 配置文件

| 参数 | 说明 |
|------|------|
| `--config`, `-c` | JSON 配置文件路径 |

### 串口设置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--serial`, `-s` | 串口号 (COM1, /dev/ttyUSB0) | (必填) |
| `--baudrate`, `-b` | 波特率 | 115200 |
| `--data-bits` | 数据位 (5/6/7/8) | 8 |
| `--parity` | 校验位 (N/E/O/M/S) | N |
| `--stop-bits` | 停止位 (1/1.5/2) | 1 |
| `--xonxoff` | 软件流控 | 关闭 |
| `--rtscts` | 硬件流控 (RTS/CTS) | 关闭 |

### 网络设置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--protocol`, `-p` | `tcp_server` / `tcp_client` / `udp_unicast` / `udp_multicast` | (必填) |
| `--host`, `-H` | 监听地址(server) 或 目标地址(client/udp) | (必填) |
| `--port`, `-P` | 端口号 | (必填) |
| `--local-host` | UDP 本地绑定地址 (未设则使用 --host) | (空) |
| `--remote-host` | UDP 远端发送地址 (未设则使用 --host) | (空) |
| `--multicast-group` | 组播组地址 (仅 udp_multicast) | 224.0.0.1 |
| `--multicast-ttl` | 组播 TTL (仅 udp_multicast) | 1 |
| `--local-port` | UDP 本地绑定端口 (未设则使用 --port) | 0 |
| `--remote-port` | UDP 远端发送端口 (未设则使用 --port) | 0 |

### 转发设置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--buffer-size` | 读取缓冲大小 (字节) | 4096 |
| `--reconnect` | 启用自动重连 | 启用 |
| `--no-reconnect` | 禁用自动重连 | — |
| `--reconnect-interval` | 重连间隔 (秒) | 5 |
| `--idle-timeout` | 空闲超时断开 (秒, 0=禁用) | 0 |

### 日志设置

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--log-file` | 日志文件路径 | 仅控制台 |
| `--log-level` | 日志级别 (DEBUG/INFO/WARNING/ERROR) | INFO |

## 配置文件 (config.json)

```json
{
    "serial": {
        "port": "COM3",
        "baudrate": 115200,
        "data_bits": 8,
        "parity": "N",
        "stop_bits": 1.0,
        "xonxoff": false,
        "rtscts": false
    },
    "network": {
        "protocol": "tcp_server",
        "host": "0.0.0.0",
        "port": 8888,
        "local_host": "",
        "remote_host": "",
        "local_port": 0,
        "remote_port": 0,
        "multicast_group": "224.0.0.1",
        "multicast_ttl": 1
    },
    "forward": {
        "buffer_size": 4096,
        "reconnect": true,
        "reconnect_interval": 5,
        "idle_timeout": 0
    },
    "logging": {
        "log_file": null,
        "log_level": "INFO"
    }
}
```

所有字段均可选，未指定的使用默认值。**配置优先级：命令行参数 > 配置文件 > 默认值**。

## 日志示例

```
2026-06-08 10:30:01 [INFO] Serial port COM3 opened (baudrate=115200)
2026-06-08 10:30:01 [INFO] TCP Server listening on 0.0.0.0:8888
2026-06-08 10:30:05 [INFO] New TCP client connected: 192.168.1.50:54321 (total: 1)
2026-06-08 10:30:10 [INFO] Serial→Network: forwarded 128 bytes to 1 client(s)
2026-06-08 10:30:12 [INFO] Network→Serial: forwarded 64 bytes
2026-06-08 10:30:15 [WARN] TCP client disconnected: 192.168.1.50:54321 (total: 0)
```

## 退出

按 `Ctrl+C` 优雅退出，脚本会自动关闭所有连接并释放资源。

## 典型应用场景

| 场景 | 工具/模式 | 说明 |
|------|----------|------|
| 串口数据上报（单向） | `serial_to_udp.py` | 串口数据主动推送到一个或多个 UDP 接收端 |
| 远程控制串口设备（单向） | `udp_to_serial.py` | 通过 UDP 发送指令到串口设备 |
| 远程访问串口设备 | `tcp_server` | 在设备端运行，远端通过 TCP 访问串口 |
| 串口数据上报 | `tcp_client` | 串口数据主动推送到中心服务器 |
| 点对点无线串口 | `udp_unicast` | 两台设备间通过 UDP 传递串口数据 |
| 一对多数据广播 | `udp_multicast` | 串口数据通过组播分发给多个接收端 |