Metadata-Version: 2.4
Name: TBurn
Version: 2.0.3
Summary: Cross-platform serial firmware burn tool with modern TUI interface
Author-email: Thierry Cao <thierrycao@example.com>
License: MIT
Project-URL: Homepage, https://github.com/thierrycao/TBurn
Project-URL: Documentation, https://github.com/thierrycao/TBurn#readme
Project-URL: Repository, https://github.com/thierrycao/TBurn
Project-URL: Issues, https://github.com/thierrycao/TBurn/issues
Project-URL: Releases, https://github.com/thierrycao/TBurn/releases
Keywords: serial,firmware,burn,flash,tui,csk,arcs
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Terminals
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.40.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual-fspicker>=0.1.0
Requires-Dist: pyserial>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == "build"
Requires-Dist: build>=1.0.0; extra == "build"
Requires-Dist: twine>=5.0.0; extra == "build"
Dynamic: license-file

# TBurn

![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Version](https://img.shields.io/badge/version-2.0.3-orange.svg)
![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)

**TBurn** 是一个跨平台串口固件烧录工具，提供现代化的终端用户界面（TUI），支持多种芯片类型的固件烧录。

## 功能特性

- 🔥 **多芯片支持** - CSK6、ARCS、ARCS_DUAL、VENUSA
- 📦 **多烧录目标** - SPI Flash、eMMC
- ⚡ **高速烧录** - 支持波特率切换，最高 3Mbps
- ✅ **MD5 校验** - 烧录后自动验证固件完整性
- 🔁 **自动烧录** - Wait 模式（等待设备）+ Repeat 模式（循环烧录）
- 💾 **配置持久化** - 自动保存用户配置和固件列表
- 🎨 **现代化 TUI** - 基于 Textual 框架，全键盘操作

## 快速开始

### 安装

```bash
# pip 安装（推荐）
pip install TBurn

# 或从源码安装
git clone https://github.com/thierrycao/TBurn.git
cd TBurn
pip install -r requirements.txt
```

### 运行

```bash
# pip 安装后直接运行
tburn

# 或从源码运行
python run_tui.py

# 指定串口
python run_tui.py -p /dev/ttyUSB0

# 调试模式
python run_tui.py --debug
```

## 界面预览

![TBurn TUI Interface](docs/images/tburn_ui.jpg)

TBurn 提供现代化的终端用户界面，主要包含以下面板：

| 面板 | 功能 |
|------|------|
| **状态面板** | 显示芯片类型、串口端口、波特率、连接状态 |
| **固件面板** | 管理固件列表，显示名称、地址、烧录状态 |
| **烧录面板** | 自动进入烧录模式开关、开始烧录按钮 |
| **日志面板** | 实时显示烧录过程日志 |
| **进度面板** | 烧录进度条显示 |
| **命令面板** | 快捷键提示 |

## 快捷键

| 键 | 功能 | 说明 |
|----|------|------|
| `C` | 芯片选择 | 选择芯片类型（CSK6/ARCS/ARCS_DUAL/VENUSA） |
| `T` | 目标选择 | 选择烧录目标（SPI Flash/eMMC） |
| `P` | 端口选择 | 选择串口设备 |
| `B` | 波特率选择 | 选择通信波特率 |
| `F` | 固件管理 | 添加/编辑/删除固件 |
| `Space` | 开始烧录 | 执行烧录流程 |
| `D` | 调试模式 | 开启/关闭调试日志 |
| `Q` / `Esc` | 退出 | 退出应用程序 |

## 平台支持

### Linux

```bash
# 安装依赖
pip install TBurn

# 串口权限（需要添加用户到 dialout 组）
sudo usermod -a -G dialout $USER
# 重新登录后生效
```

### macOS

```bash
# 安装依赖
pip install TBurn

# 串口设备通常为 /dev/tty.usbserial-* 或 /dev/cu.usbserial-*
```

### Windows

```bash
# 安装依赖
pip install TBurn

# 串口设备通常为 COM3、COM4 等
```

## 芯片支持详情

| 芯片 | 烧录地址 | RTS/DTR | Flash擦除 | 特殊配置 |
|------|----------|---------|-----------|----------|
| CSK6 | 0x0 | 标准 | 自动 | 无 |
| ARCS | 0x20040000 | 反向 | **需要** | 无 |
| ARCS_DUAL | 0x20040000 | 反向 | **需要** | 双Flash选择 |
| VENUSA | 0x20050000 | 反向 | **需要** | 时钟配置 |

## 配置文件

配置保存在用户目录：`~/.tburn_config.json`

```json
{
  "chip_type": "arcs",
  "burn_target": "spi_flash",
  "port": "/dev/ttyUSB0",
  "baudrate": 1500000,
  "firmwares": [
    {"name": "master.bin", "path": "/path/to/master.bin", "addr": "0x0"}
  ]
}
```

## 烧录流程

1. **初始化串口** - 打开指定端口（115200）
2. **进入烧录模式** - RTS/DTR 序列控制
3. **同步设备** - 多次 SYNC 命令确认连接
4. **加载 Burner** - 上传烧录器固件到 RAM
5. **配置 Burner** - 波特率切换、时钟配置
6. **烧录固件** - 分段写入 Flash
7. **MD5 校验** - 验证烧录数据完整性
8. **复位设备** - 重启设备运行新固件

## 开发与构建

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/thierrycao/TBurn.git
cd TBurn

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest src/tests/mock/ -v
```

### 构建二进制

```bash
# 安装构建工具
pip install pyinstaller

# 构建单文件可执行程序
pyinstaller TBurn.spec

# 输出位于 dist/TBurn
```

### 发布到 PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

## 文档

- [架构设计](docs/01-architecture/ARCHITECTURE.md)
- [协议说明](docs/02-protocol/PROTOCOL.md)
- [功能说明](docs/03-features/FEATURES.md)
- [项目状态](docs/04-progress/PROJECT_STATUS.md)
- [会话恢复](docs/05-session/SESSION_RESUME.md)
- [CI/CD指南](docs/06-devops/CICD_GUIDE.md)
- [PyPI发布指南](docs/06-devops/PYPI_PUBLISH_GUIDE.md)

## 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## License

MIT License - 详见 [LICENSE](LICENSE) 文件

## 作者

Thierry Cao - [GitHub](https://github.com/thierrycao)
