# ModemFileTransferTool

**Repository Path**: lewque/modem-file-transfer-tool

## Basic Information

- **Project Name**: ModemFileTransferTool
- **Description**: 多协议文件传输工具 - 支持Ymodem和Zmodem协议，可通过TCP和串口 进行可靠文件传输
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-14
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ModemFileTransferTool - 多协议文件传输工具 (Ymodem & Zmodem)

![License](https://img.shields.io/badge/license-Mulan_PSL_v2-blue)
![Version](https://img.shields.io/badge/version-2.0.0-green)
![Platform](https://img.shields.io/badge/platform-Windows-blue)

## 项目简介

ModemFileTransferTool是一个支持多种协议的可靠文件传输工具，同时支持Ymodem和Zmodem协议，具备网络传输(TCP)和串口传输两种通信方式。该工具具备自动串口检测、进度监控、错误恢复机制以及协议自适应等高级特性。

## 主要特性

- **多协议支持**: 支持Ymodem和Zmodem两种传输协议
- **双重通信支持**: 支持TCP网络传输和串口传输
- **完整协议实现**: 实现完整的Ymodem和Zmodem协议，包含CRC16/CRC32错误校验
- **自适应传输**: Zmodem协议支持自适应块大小和流式传输
- **自动串口检测**: 自动检测新连接的串口设备
- **进度监控**: 实时显示传输进度
- **错误恢复**: 通信错误时自动重传
- **附加参数支持**: 支持在文件传输前发送自定义参数
- **向下兼容**: 保持与原有Ymodem模式的完全兼容
- **Windows原生支持**: 集成WMI的Windows原生实现

## 项目架构

### 核心组件

```
ModemFileTransferTool/
├── Inc/                          # 头文件
│   ├── CommunicationInterface.h  # 抽象通信接口
│   ├── TcpConnection.h          # TCP连接实现
│   ├── SerialPortConnection.h   # 串口连接实现
│   ├── FileTransferProtocol.h   # 文件传输协议抽象接口
│   ├── YmodemProtocol.h         # Ymodem协议实现
│   └── ZmodemProtocol.h         # Zmodem协议实现
├── Scr/                         # 源文件
│   ├── main.cpp                 # 主程序入口
│   ├── FileTransferProtocol.cpp # 协议工厂实现
│   ├── YmodemProtocol.cpp       # Ymodem协议实现
│   ├── ZmodemProtocol.cpp       # Zmodem协议实现
│   ├── TcpConnection.cpp       # TCP连接实现
│   ├── SerialPortConnection.cpp # 串口实现
│   └── CommunicationInterface.cpp # 基础接口
├── CMakeLists.txt              # CMake构建文件
├── LICENSE                      # 木兰宽松许可证v2
└── README.md                   # 本文件
```

### 设计模式

- **策略模式**: `CommunicationInterface`允许在TCP和串口通信之间切换，`FileTransferProtocol`允许在不同传输协议间切换
- **RAII**: COM对象和文件句柄的自动资源管理
- **工厂模式**: `ProtocolFactory`根据用户输入动态创建协议对象，支持通信接口和协议对象的创建
- **多态性**: 通过基类指针调用不同协议的具体实现

## 安装说明

### 系统要求

- Windows操作系统
- Visual Studio 2017或更高版本（编译用）
- Windows SDK

### 源码编译

1. **克隆仓库**:
   ```bash
   git clone <repository-url>
   cd ModemFileTransferTool
   ```

2. **使用Visual Studio编译或命令行编译**:
   ```bash
   cl /EHsc /I"Inc" Scr/*.cpp /Fe:ModemFileTransferTool.exe /link Ws2_32.lib ole32.lib wbemuuid.lib oleaut32.lib
   ```
   
   **或使用CMake构建**:
   ```bash
   mkdir build
   cd build
   cmake ..
   cmake --build . --config Release
   ```

3. **生成的可执行文件**: 项目目录下的`ModemFileTransferTool.exe`

### 安装部署

1. 将`ModemFileTransferTool.exe`复制到所需位置
2. 将目录添加到系统PATH环境变量中
3. 重启命令提示符以全局使用该工具

## 使用方法

### 基本语法

```
ModemFileTransferTool [文件名] [协议类型] [tcp|serial] [地址|端口] [端口|波特率] [附加参数]
```

**向下兼容模式**（默认使用Ymodem）:
```
ModemFileTransferTool [文件名] [tcp|serial] [地址|端口] [端口|波特率] [附加参数]
```

### 参数说明

- **文件名**: 要发送的文件路径（路径包含空格时需使用引号）
- **协议类型**: 传输协议选择
  - `ymodem`: 使用Ymodem协议（传统、稳定、广兼容）
  - `zmodem`: 使用Zmodem协议（高效、自适应、流式传输）
- **tcp|serial**: 通信方式
  - `tcp`: 通过TCP网络传输
  - `serial`: 通过串口传输
- **地址|端口**: 
  - TCP模式: IP地址（如：`192.168.1.1`）
  - 串口模式: 端口名称（如：`COM1`）或`NULL`（自动检测）
- **端口|波特率**:
  - TCP模式: 端口号（如：`8080`）
  - 串口模式: 波特率（如：`115200`）
- **附加参数**: 文件传输前发送的自定义参数

### 串口配置参数

- 数据位: 8位
- 停止位: 1位
- 校验位: 无
- 流控制: 无

### 使用示例

#### 使用Ymodem协议
```bash
# TCP传输 - 指定Ymodem协议
ModemFileTransferTool "firmware.bin" ymodem tcp 192.168.1.100 8080

# 串口传输 - 指定Ymodem协议
ModemFileTransferTool "firmware.bin" ymodem serial COM1 115200

# 向下兼容模式（默认Ymodem）
ModemFileTransferTool "firmware.bin" tcp 192.168.1.100 8080
```

#### 使用Zmodem协议
```bash
# TCP传输 - 使用Zmodem协议（更高效）
ModemFileTransferTool "large_file.bin" zmodem tcp 192.168.1.100 8080

# 串口传输 - 使用Zmodem协议（自适应传输）
ModemFileTransferTool "firmware.bin" zmodem serial COM1 115200

# 自动检测串口 - 使用Zmodem协议
ModemFileTransferTool "update.bin" zmodem serial NULL 115200
```

#### 带附加参数的传输
```bash
# Ymodem协议带参数
ModemFileTransferTool "update.bin" ymodem tcp 192.168.1.50 2000 BOOT1 BOOT2 RESET

# Zmodem协议带十六进制参数
ModemFileTransferTool "data.bin" zmodem serial COM3 9600 0x01 0x02 0x03
```

#### 获取帮助
```bash
# 显示版本信息
ModemFileTransferTool -v

# 显示帮助信息
ModemFileTransferTool -h
```

### 交互模式

不带参数运行ModemFileTransferTool时，将进入交互模式:

```bash
ModemFileTransferTool
Input [filename]
> firmware.bin
Input [protocol] [tcp|serial] [address|port] [port|baudrate]
Protocol (ymodem/zmodem, default ymodem): zmodem
> zmodem serial COM1 115200
```

## 协议详情

### 协议对比

| 特性 | Ymodem | Zmodem |
|------|--------|--------|
| 数据块大小 | 128/1024字节固定 | 可变，自适应调整 |
| 错误校验 | CRC16 | CRC16/CRC32 |
| 传输效率 | 标准 | 高效，流式传输 |
| 错误恢复 | 重传整个块 | 智能恢复，续传支持 |
| 兼容性 | 广泛支持 | 现代系统优先 |
| 适用场景 | 稳定可靠的传输 | 大文件、不稳定线路 |

### Ymodem协议实现

实现标准Ymodem协议，具有以下特性:

- **128字节和1024字节数据块**: 根据数据大小自动选择
- **CRC16错误校验**: 使用CCITT-16多项式(0x1021)
- **起始帧**: 包含文件名和文件大小
- **数据帧**: 顺序传输，支持自动重传
- **结束帧**: 确认传输完成

**Ymodem帧结构:**
```
起始帧: SOH + 序列号 + 反序列号 + 文件名 + 文件大小 + 填充 + CRC16
数据帧: SOH/STX + 序列号 + 反序列号 + 数据(128/1024) + CRC16  
结束帧: SOH + 0x00 + 0xFF + 填充 + CRC16
传输结束: 0x04 (EOT)
```

### Zmodem协议实现

实现现代Zmodem协议，具有以下高级特性:

- **自适应块大小**: 根据线路质量动态调整(256-8192字节)
- **流式传输**: 连续发送数据，减少等待时间
- **CRC32错误校验**: 更强的错误检测能力
- **断点续传**: 支持传输中断后恢复
- **自动流控**: 根据接收方能力调整传输速度

**Zmodem帧结构:**
```
头部: ZPAD + ZDLE + 帧类型 + 位置信息 + CRC
数据: ZDLE编码数据 + ZDLE + 结束类型 + CRC
控制: 各种控制帧(ZRQINIT, ZFILE, ZDATA, ZEOF, ZFIN等)
```

### 错误处理

**通用错误处理:**
- **超时处理**: 针对不同操作的可配置超时
- **重传机制**: 自动检测并重传错误数据
- **最大重试**: 防止无限重试循环

**Ymodem错误处理:**
- **NAK响应**: 触发帧重传
- **'C'请求**: 等待CRC16模式确认

**Zmodem错误处理:**
- **ZNAK响应**: 智能错误恢复
- **ZRPOS请求**: 精确定位错误位置并恢复
- **自适应调整**: 根据错误率调整传输参数

## 技术规格

### 系统要求
- Windows Vista或更高版本
- 最低1MB内存
- 网络适配器（TCP模式）
- 串口或USB转串口适配器（串口模式）

### 性能指标
- **TCP传输**: 受网络带宽限制
- **串口传输**: 受波特率限制（典型范围: 9600-921600 bps）
- **文件大小**: 无实际限制（已测试100MB）
- **进度更新**: 实时进度条显示
- **Ymodem性能**: 稳定传输，适中速度
- **Zmodem性能**: 高效传输，自适应优化，大文件传输速度提升20-40%

### 协议选择建议

**选择Ymodem的场景:**
- 与老旧设备通信，需要最大兼容性
- 网络环境稳定，对传输速度要求不高
- 小文件传输（<1MB）
- 需要与标准Ymodem接收器兼容

**选择Zmodem的场景:**
- 大文件传输（>10MB）
- 不稳定的网络或串口环境
- 需要最高传输效率
- 支持断点续传的场景
- 现代系统间的文件传输

### 支持的文件类型
- 所有二进制和文本文件
- 固件镜像文件（.bin, .hex, .elf）
- 压缩归档文件
- 任何格式的文件（协议无关）

## 故障排除

### 常见问题

#### 连接失败
```
Failed to establish connection
```
**解决方案:**
- 验证IP地址和端口（TCP模式）
- 检查串口是否存在且未被占用（串口模式）
- 确保防火墙允许连接（TCP模式）
- 尝试不同的波特率（串口模式）

#### 文件未找到
```
Failed to open file: filename.bin
```
**解决方案:**
- 验证文件路径正确
- 使用绝对路径或确保文件在当前目录
- 检查文件权限
- 文件名包含空格时使用引号

#### 传输中断
```
Transmit abord
```
**解决方案:**
- 检查物理连接
- 验证接收端准备就绪且兼容
- 降低传输速度（较低波特率）
- 检查电磁干扰

#### 自动检测问题
```
Starting serial port monitoring...
```
**解决方案:**
- 确保设备正确连接
- 安装USB转串口适配器的正确驱动
- 尝试手动指定端口名称而非NULL
- 在Windows设备管理器中检查端口冲突

### 高级调试

通过检查源代码注释启用调试模式。该工具提供详细的错误消息，可显示帧级传输详情。

## 开发说明

### 自定义版本构建

代码库采用模块化设计，便于定制:

1. **添加新协议**: 实现继承自`CommunicationInterface`的新类
2. **修改Ymodem行为**: 编辑`ymodem.cpp`中的函数
3. **扩展串口检测**: 修改`SerialPortConnection.cpp`中的WMI查询

### 代码组织

- **抽象接口**: `CommunicationInterface`提供通用API
- **协议实现**: `ymodem.cpp`处理Ymodem特定逻辑
- **平台代码**: 连接类中的Windows特定实现
- **错误处理**: 全面的错误检查和报告

### 贡献代码

1. Fork本仓库
2. 创建功能分支
3. 进行更改并充分测试
4. 提交包含详细描述的pull request

## 许可证

本项目采用木兰宽松许可证，第2版（Mulan PSL v2）。

您可以根据木兰宽松许可证第2版的条款和条件使用此软件。您可以在以下网址获得木兰宽松许可证第2版的副本: http://license.coscl.org.cn/MulanPSL2

本软件按"原样"提供，不提供任何明示或暗示的担保，包括但不限于对适销性、适用于特定用途和非侵权性的暗示担保。

详情请参见木兰宽松许可证第2版。

## 主要特性

### v2.0.0 核心功能
- ✨ **双协议支持**: 完整实现Ymodem和Zmodem协议
- 🏗️ **现代架构**: 采用策略模式和工厂模式，支持协议扩展
- 🔧 **协议选择**: 用户可以选择使用Ymodem或Zmodem协议
- 📈 **高性能**: Zmodem协议在大文件传输中性能提升显著
- 🔄 **完全兼容**: 支持向下兼容的使用方式
- 🛠️ **现代构建**: 支持静态链接，便于跨机器部署

## 技术支持

如有问题、错误报告或功能请求，请参考项目仓库或联系维护人员。

---

**注意**: 此工具设计用于合法的文件传输目的。用户有责任确保在使用此软件时遵守适用的法律法规。