ICD 文件格式转换器

概述

本技能用于将各厂商、各项目不同格式的航空电子系统接口控制文件（ICD, Interface Control Document）Excel， 统一转换为标准的 Template 格式，以便系统集成、数据库管理和后续工具链处理。

转换前必须执行的分析步骤

第1步：读取并理解源文件结构

1. 使用 openpyxl 加载 Excel，检查所有 Sheet 名称
2. 定位协议/帧结构所在的 Sheet（通常命名为"协议"、"协议(2)"、"帧定义"等）
3. 定位字段元数据所在的 Sheet（通常命名为"数据格式"、"信号定义"等）
4. 定位帧说明所在的 Sheet（通常命名为"帧说明"、"物理层"等，包含帧头格式、CRC算法、字节序等）

第2步：颜色编码识别（关键！）

许多 ICD 文件使用单元格背景色区分不同位宽的字段类型。必须使用 openpyxl 读取 cell.fill.fgColor.rgb 来识别：

若文件未使用颜色编码，则从"数据格式"Sheet 的位宽列推断。

第3步：构建字段元数据索引

从"数据格式"Sheet 提取每个信号字段的元数据，建立查找字典：

field_meta[signal_name] = {
    'desc': 变量描述,
    'fmt':  数据类型(uint16/int16/bool),
    'width': 位宽(16/1),
    'freq': 信号频率,
    'note': 备注(含枚举信息)
}

第4步：逐行解析帧结构

遍历帧数据 Sheet 的每一行，根据颜色将每个单元格归类为：

• 蓝色 → 帧头字段（16bit，标识帧类型）
• 橙色 → 16bit 数据字段
• 绿色 → 1bit bool 字段（含 Spare 预留位）

跳过元数据行（"CRC校验"、"长度"、"备注"、"16bit"、"1bit"等文本标签）。

第5步：帧长度校验（必须执行！）

这是保证转换正确性的关键步骤：

1. 累加所有字段的位宽：total_bits = sum(field.bit_width)
2. 与声明的数据字数对比：expected_bits = stated_word_count × 16
3. 差值必须为 0；若不足，使用 Spare 字段补齐到目标位数

if current_bit_offset < target_bits:
    padding = target_bits - current_bit_offset
    for i in range(padding):
        fields.append({'name': 'Spare', 'bit_width': 1, ...})

Template 输出规范

表头字段（18列，从左到右）

默认值规则

合并单元格规则

同一帧中，"序号"、"帧名称"、"帧长度(Bytes)"、"帧类型"、"校验方式"、"校验区间" 这几列纵向合并单元格。

物理帧结构处理

航空电子 ICD 通常使用三层帧结构：

┌──────────┬──────────┬──────────────────┬──────────┐
│ 物理帧头  │  帧标识   │    数据字段       │ CRC校验  │
│ 0xA0 0x01│ (16bit)  │  (混合16bit+1bit) │ (16bit)  │
│  2 Bytes  │  2 Bytes │    N Bytes        │  2 Bytes │
└──────────┴──────────┴──────────────────┴──────────┘

• 物理帧头（2字节）：如 0xA0 0x01，不计入数据字数
• 帧标识（2字节）：逻辑帧类型，已包含在数据字中
• 数据字段：115 words = 230 bytes（含帧标识）
• CRC校验（2字节）：帧尾

校验区间计算

check_start = 物理帧头字节数 (通常为2)
check_end   = 物理帧头字节数 + 数据字节数 - 1

格式："2,231" 表示校验从字节2到字节231（字节0-1是帧头，字节232-233是CRC）。

帧头数据处理

帧标识如 0xA001，按小端序输出时需字节交换：

• 高字节 A0，低字节 01
• 小端序输出：01 A0（低字节在前）

def process_frame_header(hex_str):
    val = int(hex_str, 16)
    high = (val >> 8) & 0xFF
    low = val & 0xFF
    return f"{low:02X} {high:02X}"  # 小端序

重名字段去重

同一帧内出现多次的同名字段，第1次保持原名，第2次起追加 _2、_3：

def deduplicate(fields):
    counts = {}
    for f in fields:
        name = f['name']
        if name in counts:
            counts[name] += 1
            f['name'] = f"{name}_{counts[name]}"
        else:
            counts[name] = 1

枚举信息提取

从"数据格式"Sheet 的备注列提取 bool 字段的枚举含义。常见格式：

• 1（True）：故障\n0（False）：正常 → 1:故障;0:正常
• 1（True）：地面\n0（False）：空中 → 1:地面;0:空中
• 1（True）：激活\n0（False）：未激活 → 1:激活;0:未激活

转换后操作

生成 Template.xlsx 后，按用户需求依次执行：

1. 转换为 .icd 文件：调用 icd_converter 工具
2. 加入数据库：调用 add_icd_file_to_data_bases 工具

脚本使用

本技能捆绑了一个 Python 转换脚本 scripts/convert_icd.py，可作为转换模板使用。

python scripts/convert_icd.py <source.xlsx> <output_template.xlsx>

脚本需要根据具体 ICD 文件的 Sheet 结构和颜色编码进行调整。