引脚配置详解

本文档详细介绍芯片引脚配置的技术细节，是引脚封装教程的深入补充。

引脚对象结构

每个引脚在系统中表示为一个完整的对象：

{
  dir: 'left',             // 方向：left / right / top / bottom
  num: 4,                  // 引脚编号（在芯片封装图中的位置）
  name: 'PE5',             // 引脚名称
  port: 'GPIOE',           // 所属端口
  pin: 'GPIO_PIN_5',       // 引脚宏定义
  type: 'I/O',             // 电气类型
  color: '#00FF00',        // 显示颜色
  af: [                    // 复用功能列表
    {
      name: 'Reset_State',
      value: '-1'
    },
    {
      name: 'GPIO_Input',
      value: 'GPIO_Input'
    },
    {
      name: 'USART1_TX',
      value: 'GPIO_ALTERNATE_USART1_TX'
    },
    {
      name: 'TIM2_CH1',
      value: 'GPIO_REMAP_TIM2_CH1'
    }
  ]
}

复用功能 (af) 详解

字段说明

字段	类型	说明	示例
`name`	String	界面显示的功能名称，用户可以理解	`USART1_TX`
`value`	String	SDK 中对应的宏定义，用于代码生成	`GPIO_ALTERNATE_USART1_TX`

特殊复用功能

name	value	说明
`Reset_State`	`-1`	复位引脚，选择后从 GPIO 表中删除该引脚
`GPIO_Input`	`GPIO_Input`	通用数字输入
`GPIO_Output`	`GPIO_Output`	通用数字输出
`GPIO_Analog`	`GPIO_Analog`	模拟功能（ADC/DAC 等）
`GPIO_EXTIx`	`GPIO_EXTIx`	外部中断线

引脚颜色配置

默认颜色

不同类型的引脚可以设置不同的默认颜色：

// 引脚颜色配置
{
  pinTypes: {
    power: '#FF0000',      // 电源引脚 — 红色
    io: '#00FF00',         // I/O 引脚 — 绿色
    analog: '#0000FF',     // 模拟引脚 — 蓝色
    reset: '#FFA500',      // 复位引脚 — 橙色
    boot: '#808080',       // 启动引脚 — 灰色
    special: '#800080'     // 特殊功能 — 紫色
  }
}

选中颜色

当引脚被选中并配置了外设功能后，可以设置不同的高亮颜色：

{
  selectedColor: '#FFFF00'  // 选中状态 — 黄色高亮
}

系统引脚处理

以下系统引脚在 GPIO 配置表中默认不可见，且不应被普通外设占用：

引脚	功能	说明
NRST	复位	芯片硬件复位引脚
BOOT0	启动配置	启动模式选择
SWDIO	调试数据	SWD 调试接口数据线
SWCLK	调试时钟	SWD 调试接口时钟线
TK_IN	测试输入	测试模式引脚

引脚锁定机制

使用 _locked 属性标记引脚是否可被自动删除：

{
  name: 'PA9',
  af: { name: 'USART1_TX', value: 'GPIO_ALTERNATE_USART1_TX' },
  _locked: true           // 锁定后，auto_set_pins 不会删除此引脚
}

锁定场景

用户手动选择的引脚通常会被标记为锁定
关键功能引脚（如调试接口）默认锁定
自动分配的引脚默认不锁定，可被自动替换

updatePinTable 事件脚本

当用户选中/取消选中引脚时，系统触发 peri:updatePinTable 事件：

// 事件配置
{
  channel: 'peri:updatePinTable',
  script: function(event) {
    const { pin, selected, alternate } = event

    if (selected) {
      // 引脚被选中：添加到 GPIO 表
      this.addPinToTable(pin, alternate)
    } else {
      // 引脚被取消：从 GPIO 表移除
      this.removePinFromTable(pin)
    }
  }
}

引脚分组优化

生成初始化代码时，引脚按端口分组以优化代码结构：

// 引脚按端口分组
function groupByPort(pins) {
  const groups = {}
  pins.forEach(pin => {
    if (!groups[pin.port]) {
      groups[pin.port] = []
    }
    groups[pin.port].push(pin)
  })
  return groups
}

// 示例结果
{
  'GPIOA': [PA0, PA1, PA3],
  'GPIOB': [PB5, PB7],
  'GPIOC': [PC13]
}

引脚选择函数参考

查找引脚

// 根据引脚名称查找
getPinByName('PA0')

// 根据复用功能查找（支持模式匹配）
getPinByAlternate('USART1_TX')
getPinByAlternate('TIM${num}_CH1')  // 匹配 TIM1_CH1, TIM2_CH1 等

// 根据复用功能查找空闲引脚
isFreeByAlternate('USART1_TX')

添加/删除引脚

// 添加引脚
addPinByAlternate('USART1_TX')    // 自动查找空闲引脚
headPeripheralPinAf(pin, af)      // 手动指定引脚

// 删除引脚
deletePinByName('PA0')
deletePinByAlternate('USART1_TX')

引脚状态检查

// 检查芯片是否有该复用功能
hasPinByAlternate('USART1_TX')

// 检查该复用功能是否有空闲引脚
isFreeByAlternate('USART1_TX')

// 检查引脚是否已绑定该功能
bindByAlternate('USART1_TX')

最佳实践

复用功能命名：使用有意义的名称，如 USART1_TX 而非 AF1
value 映射：确保 value 与 SDK 头文件中的宏定义完全一致
引脚锁定：关键引脚使用 _locked: true 防止误删除
颜色编码：使用直观的颜色帮助用户快速识别引脚类型
事件脚本：利用 updatePinTable 事件实现自动化引脚管理