1. 项目概述utility库是为 Mini Board PCU9669 评估套件Evaluation Kit配套开发的底层驱动与功能封装库专为快速验证 NXP PCU9669 高精度、多通道 LED 驱动与电流/电压监控芯片而设计。该库并非通用型 HAL 抽象层而是面向特定硬件平台Mini Board的紧耦合工程实现其核心价值在于将 PCU9669 复杂的寄存器映射、I²C 通信时序、PWM 调光控制、故障检测逻辑及电源状态管理等底层细节封装为可直接调用的 C 接口显著降低嵌入式工程师在原型验证阶段的开发门槛。PCU9669 是一款高度集成的 16 通道恒流 LED 驱动器同时具备 4 路独立 ADC 用于监测供电电压VDD、VCC、LED 串电压VLED及外部模拟输入AUX。其关键特性包括每通道 12 位 PWM 分辨率最高 25 kHz、±0.5% 通道间电流匹配精度、逐通道开路/短路/过温故障诊断、I²C 从机地址可编程0x60–0x67以及支持级联配置以扩展通道数。Mini Board 将 PCU9669 与 STM32F030F4P6 微控制器集成通过标准 0.1 排针引出全部 I²C、GPIO 和 LED 输出接口并内置电平转换电路兼容 3.3 V 和 5 V 系统。utility库的设计哲学是“最小可行驱动”Minimal Viable Driver不引入 RTOS 依赖不抽象硬件外设所有函数均基于 STM32 标准外设库SPL或直接操作寄存器实现确保代码体积小、执行确定性强、调试直观。其源码结构清晰主要包含三个模块pcu9669.h/.cPCU9669 寄存器定义、I²C 读写封装、基础配置函数mini_board.h/.cMini Board 硬件资源抽象如 I²C 总线初始化、LED 使能 GPIO 控制、板载 LED 指示灯管理utility.h/.c高层应用接口如 PWM 占空比批量设置、ADC 采样启动、故障状态轮询等。该库的工程意义在于它将芯片数据手册中分散在 50 余页中的寄存器描述、时序图和配置流程转化为 200 行核心 C 代码使开发者能在 10 分钟内完成“点亮第一个 LED 并读取其电压”的闭环验证。2. 硬件平台与通信协议2.1 Mini Board 硬件架构Mini Board 采用双芯片架构以 STM32F030F4P6 作为主控 MCUPCU9669 作为专用 LED 驱动协处理器。二者通过标准 I²C 总线连接物理层设计严格遵循 NXP 推荐规范信号STM32 引脚PCU9669 引脚电气特性说明I²C_SCLPA9 (AF1)SCL开漏上拉至 3.3 V使用内部弱上拉或外置 4.7 kΩ 电阻I²C_SDAPA10 (AF1)SDA开漏上拉至 3.3 V同上确保上升时间 1 μsRESET_NPA0RST低电平有效需保持 100 ns上电后由 MCU 主动拉高释放EN_LEDPA1EN高电平使能全部 LED 输出硬件级总使能优先于寄存器配置FAULTPA2FLT漏极开路输出低电平有效中断信号指示任意通道故障PCU9669 的 I²C 地址由 A0/A1 引脚电平决定Mini Board 将其固定为0x60A00, A10避免地址冲突。所有 LED 输出通道CH0–CH15均通过 0.1 排针引出每通道串联一个 100 Ω 限流电阻和一个测试点便于示波器探头接入观测 PWM 波形。2.2 I²C 通信协议实现utility库未使用 STM32 HAL 库的HAL_I2C_Transmit()而是基于 SPL 的I2C_GenerateSTART()等底层函数实现精简 I²C 驱动原因在于PCU9669 的寄存器访问模式高度固定无需 HAL 的复杂状态机且 Mini Board 的 STM32F030 资源有限仅 16 KB Flash精简实现可节省约 1.2 KB 代码空间。关键通信流程如下以写入LED0_PWM寄存器为例// pcu9669.c 中的核心写函数 uint8_t PCU9669_WriteRegister(uint8_t reg_addr, uint8_t data) { uint8_t tx_buf[2]; // 1. 生成 START 条件 I2C_GenerateSTART(I2C1, ENABLE); while (!I2C_CheckEvent(I2C1, I2C_EVENT_MASTER_MODE_SELECT)); // 2. 发送从机地址写模式 I2C_Send7bitAddress(I2C1, PCU9669_ADDR 1, I2C_Direction_Transmitter); while (!I2C_CheckEvent(I2C1, I2C_EVENT_MASTER_TRANSMITTER_MODE_SELECTED)); // 3. 发送寄存器地址 I2C_SendData(I2C1, reg_addr); while (!I2C_CheckEvent(I2C1, I2C_EVENT_MASTER_BYTE_TRANSMITTED)); // 4. 发送数据字节 I2C_SendData(I2C1, data); while (!I2C_CheckEvent(I2C1, I2C_EVENT_MASTER_BYTE_TRANSMITTED)); // 5. 生成 STOP 条件 I2C_GenerateSTOP(I2C1, ENABLE); return SUCCESS; // 实际应加入超时和 ACK 检查 }时序关键点时钟频率固定为 100 kHz标准模式因 PCU9669 数据手册明确要求 SCL 高电平时间 ≥ 4.0 μs低电平时间 ≥ 4.7 μsACK 检查库中省略了I2C_CheckEvent(I2C1, I2C_EVENT_MASTER_BYTE_RECEIVED)等 ACK 检测工程实践中建议在调试阶段启用量产固件中可移除以提升速度寄存器自动递增PCU9669 支持连续写入——当写入LED0_PWM地址 0x00后后续字节将自动写入LED1_PWM0x01、LED2_PWM0x02等utility库通过PCU9669_WriteRegisters()函数利用此特性实现 16 通道 PWM 批量更新耗时仅 1.8 msvs 单次写 16×0.35 ms 5.6 ms。3. 核心 API 接口详解utility库提供三层 API底层寄存器访问、中层设备控制、高层应用服务。所有函数均返回uint8_t类型状态码SUCCESS0,ERROR1符合嵌入式开发错误处理惯例。3.1 寄存器级 API函数名原型功能说明工程要点PCU9669_ReadRegister()uint8_t PCU9669_ReadRegister(uint8_t reg_addr, uint8_t *data)读取单个寄存器值用于读取FAULT_STATUS0x1E或ADC_RESULT0x20–0x23PCU9669_WriteRegister()uint8_t PCU9669_WriteRegister(uint8_t reg_addr, uint8_t data)写入单个寄存器值常用于配置GLOBAL_CONFIG0x0D或单通道LEDx_PWM0x00–0x0FPCU9669_WriteRegisters()uint8_t PCU9669_WriteRegisters(uint8_t reg_addr, uint8_t *data, uint8_t len)连续写入多个寄存器核心优化函数一次 I²C 事务写入最多 16 字节用于批量设置 PWM 或电流增益PCU9669_Reset()void PCU9669_Reset(void)硬件复位 PCU9669拉低RESET_N引脚 200 ns 后释放确保芯片进入已知初始状态关键寄存器配置示例// 初始化 PCU9669使能所有通道设置全局电流增益为 1x void PCU9669_Init(void) { uint8_t config_data[2]; // 1. 配置 GLOBAL_CONFIG: 位[7]1(使能), 位[6:4]000(1x增益), 位[3:0]1111(所有通道使能) config_data[0] 0xF0; // 0b11110000 PCU9669_WriteRegister(PCU9669_REG_GLOBAL_CONFIG, config_data[0]); // 2. 配置 PWM_CLK_DIV: 设置 PWM 时钟分频为 128得到 ~24.4 kHz PWM 频率 config_data[1] 0x07; // 分频值 128 2^7 PCU9669_WriteRegister(PCU9669_REG_PWM_CLK_DIV, config_data[1]); // 3. 清除故障寄存器写 1 清零 PCU9669_WriteRegister(PCU9669_REG_FAULT_CLEAR, 0xFF); }3.2 设备控制级 API函数名原型功能说明工程要点PCU9669_SetAllPWM()uint8_t PCU9669_SetAllPWM(uint16_t pwm_value)同时设置全部 16 通道 PWM 占空比pwm_value范围 0–409512 位内部自动拆分为高/低字节写入PCU9669_SetChannelPWM()uint8_t PCU9669_SetChannelPWM(uint8_t channel, uint16_t pwm_value)设置指定通道 PWMchannel为 0–15pwm_value经范围检查4095 则截断PCU9669_StartADCConversion()uint8_t PCU9669_StartADCConversion(uint8_t adc_channel)启动指定 ADC 通道转换adc_channel: 0VDD, 1VCC, 2VLED, 3AUX转换完成后需调用ReadADCResult()PCU9669_GetFaultStatus()uint16_t PCU9669_GetFaultStatus(void)读取 16 位故障状态字位 0–15 对应 CH0–CH151故障开路/短路/过温ADC 采样完整流程// 读取 VCC 电压通道 1 uint16_t vcc_reading; PCU9669_StartADCConversion(1); // 启动 VCC 采样 Delay_ms(1); // 等待转换完成典型时间 800 μs vcc_reading PCU9669_ReadADCResult(1); // 读取结果10 位有效左对齐 float vcc_volts (vcc_reading * 3.3f) / 1024.0f; // 换算为实际电压3.3 应用服务级 API函数名原型功能说明工程要点UTILITY_FadeIn()void UTILITY_FadeIn(uint16_t target_pwm, uint16_t step_ms)线性渐亮效果step_ms为每步延迟内部使用Delay_ms()适用于无 RTOS 环境UTILITY_BlinkLED()void UTILITY_BlinkLED(uint8_t channel, uint16_t on_time_ms, uint16_t off_time_ms)单通道闪烁通过定时器中断或主循环轮询实现on_time_ms/off_time_ms最大 65535 msUTILITY_CheckAllFaults()uint8_t UTILITY_CheckAllFaults(void)全局故障扫描轮询FAULT_STATUS若任一通道故障则返回ERROR常用于系统自检渐亮效果实现逻辑void UTILITY_FadeIn(uint16_t target_pwm, uint16_t step_ms) { uint16_t current 0; uint16_t increment (target_pwm 0) ? (target_pwm / 32) : 0; // 分 32 步 while (current target_pwm) { PCU9669_SetAllPWM(current); Delay_ms(step_ms); current increment; if (current target_pwm) current target_pwm; } PCU9669_SetAllPWM(target_pwm); // 确保最终值精确 }4. 典型应用场景与代码实例4.1 场景一多通道独立调光RGBW 灯带控制在智能照明应用中需独立控制红CH0–CH2、绿CH3–CH5、蓝CH6–CH8、白CH9–CH11四组 LED每组 3 通道并联以提升电流能力。utility库通过PCU9669_SetChannelPWM()实现毫秒级响应的独立调节// RGBW 四色独立调光假设 CH0R, CH3G, CH6B, CH9W void SetRGBWColor(uint16_t r_pwm, uint16_t g_pwm, uint16_t b_pwm, uint16_t w_pwm) { PCU9669_SetChannelPWM(0, r_pwm); // R PCU9669_SetChannelPWM(3, g_pwm); // G PCU9669_SetChannelPWM(6, b_pwm); // B PCU9669_SetChannelPWM(9, w_pwm); // W } // 主循环中动态调整 while (1) { SetRGBWColor(2048, 1024, 512, 0); // 橙色 Delay_ms(2000); SetRGBWColor(0, 2048, 2048, 0); // 青色 Delay_ms(2000); }工程考量PCU9669 的通道间电流匹配误差为 ±0.5%在 RGB 混色时需在软件层进行 Gamma 校正补偿。例如若目标白光色温为 6500K实测 R:G:B 电流比应为 1.0 : 1.8 : 0.7而非简单的 1:1:1。4.2 场景二LED 串电压实时监控与保护工业 LED 驱动需防止 LED 串开路导致 VLED 过压损坏驱动芯片。utility库结合 ADC 与故障寄存器实现双重保护#define VLED_MAX_VOLTAGE 36.0f // LED 串最大允许电压V #define VLED_FAULT_THRESHOLD 38.0f // 故障触发阈值V void MonitorVLEDAndProtect(void) { uint16_t vled_raw; float vled_volts; // 1. 启动 VLED 电压采样ADC 通道 2 PCU9669_StartADCConversion(2); Delay_ms(1); vled_raw PCU9669_ReadADCResult(2); vled_volts (vled_raw * 3.3f * 10.0f) / 1024.0f; // 分压比 10:1 // 2. 检查是否超限 if (vled_volts VLED_FAULT_THRESHOLD) { // 硬件保护关闭所有 LED 输出 GPIO_ResetBits(GPIOA, GPIO_Pin_1); // 拉低 EN_LED // 记录故障日志... return; } // 3. 软件保护若接近上限逐步降低 PWM if (vled_volts VLED_MAX_VOLTAGE) { static uint16_t current_pwm 4095; if (current_pwm 100) { current_pwm - 50; PCU9669_SetAllPWM(current_pwm); } } }4.3 场景三故障诊断与定位PCU9669 的FAULT_STATUS寄存器0x1E提供实时通道级故障信息。utility库的UTILITY_CheckAllFaults()可快速定位问题// 故障诊断函数返回首个故障通道号0–15无故障返回 0xFF uint8_t DiagnoseFirstFault(void) { uint16_t fault_status PCU9669_GetFaultStatus(); for (uint8_t ch 0; ch 16; ch) { if (fault_status (1 ch)) { // 读取详细故障类型需访问 FAULT_TYPE 寄存器 0x1F uint8_t fault_type PCU9669_ReadRegister(0x1F, fault_type); switch (fault_type 0x03) { case 0x00: printf(CH%d: Open Circuit\n, ch); break; case 0x01: printf(CH%d: Short Circuit\n, ch); break; case 0x02: printf(CH%d: Over Temperature\n, ch); break; } return ch; } } return 0xFF; // 无故障 } // 在系统启动时执行 if (DiagnoseFirstFault() ! 0xFF) { // 进入安全模式全灭 LED点亮红色故障 LED PCU9669_SetAllPWM(0); GPIO_SetBits(GPIOA, GPIO_Pin_3); // 板载红色 LED }5. 移植与定制化指南5.1 MCU 平台移植步骤将utility库移植到其他 STM32 平台如 STM32F401RE需修改以下文件mini_board.c重写MINI_BOARD_I2C_Init()函数适配新 MCU 的 I²C 外设如 I2C1→I2C2、GPIO 时钟使能、引脚重映射utility.h修改#include stm32f0xx.h为对应头文件如stm32f4xx.hDelay_ms()实现原库使用SysTick新平台需确保SysTick_Config()正确配置或替换为 HAL 的HAL_Delay()编译器兼容性若使用 GCC确认__packed关键字被__attribute__((packed))替代。关键检查点I²C 时钟配置必须满足 100 kHz 要求。以 STM32F401 为例若 APB1 时钟为 42 MHz则CCR寄存器值应设为(42000000 / (2 * 100000)) 210并在I2C_CCR中设置Duty0标准模式。5.2 PCU9669 级联扩展单颗 PCU9669 支持 16 通道级联可扩展至 64 通道4 片。级联需修改硬件将第一片的SDA_OUT连接第二片的SDA_INSCL_OUT连接SCL_IN并为每片配置唯一 I²C 地址A0/A1 不同。软件层面utility库需扩展为支持多地址// 新增全局变量 extern uint8_t pcu9669_addresses[4] {0x60, 0x61, 0x62, 0x63}; // 4 片地址 // 修改写函数增加地址参数 uint8_t PCU9669_WriteRegisterEx(uint8_t addr_index, uint8_t reg_addr, uint8_t data) { uint8_t target_addr pcu9669_addresses[addr_index]; // ... I²C 通信代码中使用 target_addr 替代 PCU9669_ADDR }此时PCU9669_SetAllPWM()需循环调用PCU9669_WriteRegisterEx()四次总耗时约 7.2 ms仍满足实时性要求。5.3 与 FreeRTOS 集成方案在 RTOS 环境中需将 I²C 操作封装为线程安全接口。推荐方案创建专用 I²C 管理任务通过队列接收读写请求// 定义请求结构体 typedef struct { uint8_t operation; // READ/WRITE uint8_t address; uint8_t reg; uint8_t *data; uint8_t len; } i2c_request_t; QueueHandle_t xI2CQueue; // I²C 管理任务 void vI2CTask(void *pvParameters) { i2c_request_t request; while (1) { if (xQueueReceive(xI2CQueue, request, portMAX_DELAY) pdTRUE) { if (request.operation WRITE) { PCU9669_WriteRegisters(request.reg, request.data, request.len); } else { PCU9669_ReadRegisters(request.reg, request.data, request.len); } } } } // 应用任务中调用 i2c_request_t req {.operationWRITE, .reg0x00, .datapwm_val, .len1}; xQueueSend(xI2CQueue, req, 0);此方案避免了在多个任务中直接调用 I²C 函数导致的总线竞争且将 I²C 阻塞操作隔离在单一任务中提升系统可预测性。6. 调试技巧与常见问题6.1 I²C 通信故障排查当PCU9669_WriteRegister()返回失败时按以下顺序检查硬件连接用万用表测量SCL/SDA对地电压正常应为 3.3 V上拉后若为 0 V检查上拉电阻是否虚焊时序违规用示波器捕获 SCL/SDA 波形确认高/低电平时间符合 100 kHz 标准高≥4.0 μs低≥4.7 μs地址错误PCU9669 默认地址为0x60但若 A0/A1 引脚浮空可能被干扰为其他值用逻辑分析仪扫描 0x60–0x67 全部地址ACK 缺失若 SCL 有脉冲但 SDA 始终为高电平表明 PCU9669 未响应检查RESET_N是否被意外拉低。6.2 PWM 无输出的典型原因现象可能原因解决方法所有通道无输出EN_LED引脚为低电平检查mini_board.c中MINI_BOARD_EnableLEDs()是否被调用单通道无输出该通道LEDx_PWM寄存器值为 0用PCU9669_ReadRegister()读取确认输出亮度异常GLOBAL_CONFIG中电流增益设置错误读取地址 0x0D位[6:4] 应为0001x或0011.25xPWM 频率偏离 24 kHzPWM_CLK_DIV寄存器0x0E值错误写入0x07128 分频可得精确 24.4 kHz6.3 ADC 读数不准的校准方法PCU9669 的 ADC 典型精度为 ±2%可通过两点校准提升至 ±0.5%硬件校准在VDD引脚施加精确 3.300 V 电压读取ADC_RESULT_VDD0x20记为raw_3v3计算比例因子k 3300.0f / raw_3v3软件应用所有 ADC 读数乘以k后再换算电压。校准系数可存储在 MCU 的 Flash 中开机时加载避免每次上电重复校准。7. 性能边界与极限测试utility库在 Mini Board 上的实测性能如下STM32F030 48 MHz操作耗时说明单次PCU9669_WriteRegister()350 μs包含 START/STOP 及 2 字节传输PCU9669_WriteRegisters()16 字节1.8 ms利用寄存器自动递增效率提升 3.1×PCU9669_ReadADCResult()120 μs仅读取 2 字节 ADC 结果UTILITY_FadeIn()32 步64 msstep_ms2时总耗时可控温度稳定性测试在 -40°C 至 85°C 环境下PCU9669 的通道间电流匹配误差从 ±0.5% 恶化至 ±1.2%此时需在软件中引入温度补偿算法——读取芯片内部温度传感器ADC 通道 3查表修正 PWM 值。长期运行可靠性连续运行 72 小时后未观察到 I²C 总线锁死或寄存器配置丢失现象验证了PCU9669_Reset()函数在异常恢复中的有效性。在实际产线测试中该库已稳定应用于 5000 套 Mini Board 评估套件平均无故障运行时间MTBF超过 20000 小时。