316 lines
6.5 KiB
Markdown
316 lines
6.5 KiB
Markdown
# 快速入门指南
|
||
|
||
本文档帮助你快速上手 PinMAP → PinList 转换器。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
### 系统要求
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| 操作系统 | Windows 7+ / Linux / macOS |
|
||
| Python | 3.6+（推荐 3.8+） |
|
||
| 内存 | ≥ 64MB（实际使用 < 20MB） |
|
||
| 磁盘 | ≥ 1MB |
|
||
|
||
### 依赖项
|
||
|
||
**零第三方依赖** — 仅需 Python 标准库。
|
||
|
||
```bash
|
||
# 检查 Python 版本
|
||
python --version
|
||
# 输出示例: Python 3.12.3
|
||
```
|
||
|
||
### GUI 支持（可选）
|
||
|
||
- **Windows**: tkinter 内置，开箱即用
|
||
- **Linux**: 需要 `python3-tk` 包（`sudo apt install python3-tk`）
|
||
- **macOS**: tkinter 内置
|
||
|
||
> 无 GUI 环境时自动回退到命令行模式，不影响核心功能。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 第一步：获取项目
|
||
|
||
```bash
|
||
# 进入项目目录
|
||
cd pinmap-to-pinlist/Code/src/
|
||
```
|
||
|
||
### 第二步：运行转换
|
||
|
||
#### 方式一：GUI 模式（推荐）
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
弹出文件选择对话框，选择 `.xls` 或 `.xlsx` 文件即可。
|
||
|
||
#### 方式二：命令行模式
|
||
|
||
```bash
|
||
python main.py /path/to/your/input.xlsx
|
||
```
|
||
|
||
### 第三步：查看输出
|
||
|
||
转换完成后，在当前目录生成 `{原文件名}_PinList.xlsx`：
|
||
|
||
```
|
||
输入: QFP44_PinMAP.xlsx
|
||
输出: QFP44_PinMAP_PinList.xlsx
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 示例 1：标准方形 PinMAP
|
||
|
||
**输入文件** `QFP44.xlsx`：
|
||
|
||
```
|
||
A B C D E F
|
||
1 QFP-44
|
||
2 Pin6 6
|
||
3 Pin5 5
|
||
4 1 Pin1
|
||
5 2 Pin2
|
||
6 Pin3 Pin4
|
||
7 3 4
|
||
```
|
||
|
||
**运行命令**：
|
||
|
||
```bash
|
||
python main.py QFP44.xlsx
|
||
```
|
||
|
||
**输出**：
|
||
|
||
```
|
||
[INFO] 解析完成: 6x6 方形，共 8 个Pin
|
||
[INFO] 封装信息: QFP-44
|
||
|
||
[SUCCESS] 转换完成！输出文件: QFP44_PinList.xlsx
|
||
- 封装信息: QFP-44
|
||
- Pin数量: 8
|
||
```
|
||
|
||
**输出文件内容**：
|
||
|
||
```
|
||
A B
|
||
1 QFP-44
|
||
2 Pin1 1
|
||
3 Pin2 2
|
||
4 Pin3 3
|
||
5 Pin4 4
|
||
6 Pin5 5
|
||
7 Pin6 6
|
||
```
|
||
|
||
### 示例 2：长方形 PinMAP
|
||
|
||
**输入文件** `LQFP100.xlsx`（13 个引脚的长方形封装）
|
||
|
||
```bash
|
||
python main.py LQFP100.xlsx
|
||
```
|
||
|
||
**输出**：
|
||
|
||
```
|
||
[INFO] 解析完成: 长方形结构，共 13 个Pin
|
||
[INFO] 封装信息: LQFP-100
|
||
|
||
[SUCCESS] 转换完成！输出文件: LQFP100_PinList.xlsx
|
||
- 封装信息: LQFP-100
|
||
- Pin数量: 13
|
||
```
|
||
|
||
### 示例 3：处理警告
|
||
|
||
当 PinMAP 中部分引脚缺少 PinName 时：
|
||
|
||
```
|
||
[INFO] 解析完成: 6x6 方形，共 8 个Pin
|
||
[INFO] 封装信息: QFP-44
|
||
|
||
[WARN] 发现 3 个警告:
|
||
- 检测到 3 个引脚缺少 PinName: 缺失引脚序号: [2, 3, 4]，将默认为 NC
|
||
|
||
[SUCCESS] 转换完成！输出文件: QFP44_PinList.xlsx
|
||
- 封装信息: QFP-44
|
||
- Pin数量: 8
|
||
```
|
||
|
||
缺失 PinName 的引脚在输出中自动标记为 "NC"。
|
||
|
||
### 示例 4：处理错误
|
||
|
||
当 PinMAP 存在数据错误时：
|
||
|
||
```
|
||
[INFO] 解析完成: 6x6 方形，共 8 个Pin
|
||
[INFO] 封装信息: QFP-44
|
||
|
||
[ERROR] 发现 1 个错误:
|
||
- Pin序号不连续: 缺失的序号: [3]
|
||
|
||
转换终止，请修正PinMAP文件后重试。
|
||
```
|
||
|
||
---
|
||
|
||
## PinMAP 文件规范
|
||
|
||
### 格式要求
|
||
|
||
| 要求 | 说明 |
|
||
|------|------|
|
||
| A1 单元格 | 必须包含封装信息（如 "QFP-44"） |
|
||
| 方形区域 | 至少 2×2，引脚沿四条边分布 |
|
||
| 引脚序号 | 1-based 整数，从 1 到 N 连续 |
|
||
| 排序方向 | 左上角为 1 脚，逆时针排列 |
|
||
| PinName 位置 | 在序号单元格的"内侧相邻"位置 |
|
||
|
||
### 四边 PinName 位置
|
||
|
||
```
|
||
左边：序号在 (r, min_col)，PinName 在 (r, min_col+1)
|
||
下边：序号在 (max_row, c)，PinName 在 (max_row-1, c)
|
||
右边：序号在 (r, max_col)，PinName 在 (r, max_col-1)
|
||
上边：序号在 (min_row, c)，PinName 在 (min_row+1, c)
|
||
```
|
||
|
||
### 支持的输入格式
|
||
|
||
| 格式 | 扩展名 | 支持情况 |
|
||
|------|--------|----------|
|
||
| Excel 97-2003 | `.xls` | ✅ 支持（BIFF8 引擎） |
|
||
| Excel 2007+ | `.xlsx` | ✅ 支持（OOXML 引擎） |
|
||
|
||
### 输出格式
|
||
|
||
| 格式 | 扩展名 | 说明 |
|
||
|------|--------|------|
|
||
| Excel 2007+ | `.xlsx` | 唯一输出格式 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 运行时提示 "未选择文件，退出"
|
||
|
||
**原因**：在 GUI 模式下点击了"取消"，或在无 GUI 环境下未提供命令行参数。
|
||
|
||
**解决**：
|
||
```bash
|
||
# 提供命令行参数
|
||
python main.py input.xlsx
|
||
```
|
||
|
||
### Q2: 提示 "文件读取失败"
|
||
|
||
**可能原因**：
|
||
- 文件路径不存在
|
||
- 文件格式不是有效的 Excel 文件
|
||
- 文件已损坏
|
||
|
||
**解决**：
|
||
- 检查文件路径是否正确
|
||
- 确认文件可以用 Excel 正常打开
|
||
- 尝试用 Excel 重新保存文件
|
||
|
||
### Q3: 提示 "A1 单元格为空，缺少封装信息"
|
||
|
||
**原因**：PinMAP 文件的 A1 单元格为空。
|
||
|
||
**解决**：在 Excel 中打开文件，在 A1 单元格填入封装信息（如 "QFP-44"），保存后重新转换。
|
||
|
||
### Q4: 提示 "Pin序号不连续"
|
||
|
||
**原因**：Pin 序号存在间隔（如 1, 2, 4, 5，缺少 3）。
|
||
|
||
**解决**：检查 PinMAP 文件，补全缺失的引脚序号。
|
||
|
||
### Q5: 提示 "Pin序号重复"
|
||
|
||
**原因**：同一个 Pin 序号出现了多次。
|
||
|
||
**解决**：检查 PinMAP 文件，修正重复的序号。
|
||
|
||
### Q6: 警告 "检测到 N 个引脚缺少 PinName"
|
||
|
||
**说明**：这是警告而非错误，转换会继续进行。缺失的 PinName 会自动设为 "NC"。
|
||
|
||
**解决**（可选）：在 Excel 中补全缺失的 PinName，重新转换。
|
||
|
||
### Q7: Linux 下没有弹出文件选择对话框
|
||
|
||
**说明**：Linux 无头环境（无显示器）不支持 tkinter GUI。
|
||
|
||
**解决**：使用命令行模式：
|
||
```bash
|
||
python main.py /path/to/input.xlsx
|
||
```
|
||
|
||
如需 GUI，安装 tkinter：
|
||
```bash
|
||
sudo apt install python3-tk
|
||
```
|
||
|
||
### Q8: 输出文件打不开
|
||
|
||
**可能原因**：Excel 版本过旧（2003 及以下不支持 .xlsx）。
|
||
|
||
**解决**：使用 Excel 2007+ 或 WPS Office 打开输出文件。
|
||
|
||
### Q9: 支持多大的 PinMAP？
|
||
|
||
**回答**：当前实现适合 < 1000 引脚的场景。典型 IC 封装引脚数在 8~200 之间，完全满足需求。
|
||
|
||
### Q10: 能否批量转换多个文件？
|
||
|
||
**回答**：当前版本一次处理一个文件。如需批量转换，可使用 shell 脚本：
|
||
|
||
```bash
|
||
for f in *.xlsx; do
|
||
python main.py "$f"
|
||
done
|
||
```
|
||
|
||
---
|
||
|
||
## 测试验证
|
||
|
||
运行内置单元测试：
|
||
|
||
```bash
|
||
cd Code/src/
|
||
python test_pinmap.py
|
||
```
|
||
|
||
预期输出：
|
||
```
|
||
✓ test_4x4_parse passed
|
||
✓ test_4x4_validate passed
|
||
✓ test_missing_names_warning passed
|
||
✓ test_duplicate_numbers passed
|
||
✓ test_gap_in_numbers passed
|
||
✓ test_empty_cells passed
|
||
✓ test_no_pins passed
|
||
✓ test_12pin_square passed
|
||
|
||
✅ All tests passed!
|
||
```
|