嵌入式调光控制库：轻量级软启/渐变/记忆逻辑实现

1. 项目概述DimmerControl 是一个面向嵌入式平台的轻量级调光控制库专为可控硅TRIAC或 MOSFET/IGBT 驱动的交流/直流调光系统设计。其核心目标并非实现完整驱动硬件而是提供一套可复用、可配置、具备工程鲁棒性的调光行为逻辑层——即在已具备基础过零检测、触发脉冲生成能力的前提下封装软启/软关、渐变调光、亮度保持、防抖动等关键人机交互与电气安全逻辑。该库不依赖特定 MCU 架构或 HAL 层采用纯 C 编写无动态内存分配所有状态均通过显式传入的DimmerHandle_t结构体维护符合 IEC 61508 SIL-2 级别对确定性执行的要求。典型部署场景包括基于 STM32G0/G4 的智能墙壁调光开关配合 MOC3021/MOC3041 过零光耦 BTA16 TRIACESP32-WROVER 驱动的 DALI-2 调光网关将 DALI 指令映射为内部亮度曲线RTOS 环境下的多路独立调光通道管理FreeRTOS 任务中周期调用Dimmer_Update()其设计哲学是“分离关注点”底层硬件时序如过零中断响应、触发延迟计数由 BSP 层保障中间层如 PWM 占空比计算、相位角查表由驱动层实现而 DimmerControl 仅负责定义“用户按一下按键后灯应如何变化”并将这一意图转化为精确的目标亮度值0–100%交由下层执行。2. 核心功能与工程原理2.1 软启/软关Soft On/Off传统机械开关导致白炽灯冷态电阻极小合闸瞬间浪涌电流可达额定值 10–15 倍加速灯丝老化。DimmerControl 通过指数衰减型亮度过渡曲线实现软启// 内部实现亮度目标值按指数趋近设定值 // target current (target_desired - current) * (1 - exp(-k * dt)) // 其中 k 由 SOFT_STEP_MS 配置决定dt 为两次 Update 调用间隔软启过程非线性前 30% 亮度变化缓慢保护冷态灯丝后 70% 加速上升符合人眼感知特性。软关则反向执行确保关断前亮度平滑归零消除闪烁感。工程依据IEC 62386-102:2014 规定 DALI 调光设备软启时间应 ≥ 0.5 s软关时间 ≥ 0.3 s。DimmerControl 默认SOFT_STEP_MS 50单次调用耗时 5 μs10 步完成 0→100% 过渡500 ms满足标准且留有裕量。2.2 渐变调光Ramp Dimming支持两种模式绝对模式Absolute Mode直接设置目标亮度百分比如Dimmer_SetBrightness(h, 75)相对模式Relative Mode以当前亮度为基准增减如Dimmer_RampUp(h, 10)表示“10%”Dimmer_RampDown(h, 5)表示“−5%”相对模式内置长按识别与加速机制按键持续 ≥ 300 ms 后步进值自动倍增如从 1% → 5%每 100 ms 检测一次按键状态避免机械抖动误触发该逻辑在Dimmer_ProcessKey()中实现开发者仅需在 GPIO 中断中调用此函数无需自行管理去抖定时器。2.3 亮度记忆与恢复Brightness Memory掉电后亮度值需保持以便上电复亮至上次状态。DimmerControl 不直接操作 EEPROM/Flash而是提供Dimmer_GetStoredBrightness()和Dimmer_StoreBrightness()两个钩子函数// 用户需在 hal_dimmer.c 中实现 uint8_t Dimmer_GetStoredBrightness(void) { uint8_t val; // 从指定 Flash 页读取 last_brightness 字段 if (FLASH_ReadByte(FLASH_ADDR_BRIGHTNESS, val) FLASH_OK) { return val; } return 100; // 默认全亮 } void Dimmer_StoreBrightness(uint8_t brightness) { // 擦除页、写入新值、校验 FLASH_ErasePage(FLASH_ADDR_BRIGHTNESS); FLASH_ProgramByte(FLASH_ADDR_BRIGHTNESS, brightness); }此设计解耦了存储介质差异EEPROM vs. Flash适配不同 MCU 的数据持久化方案。2.4 安全限幅与状态同步最小导通角限制防止 TRIAC 因触发角过小 15°导致开通失败或误关断内部强制brightness_min 5%对应约 18° 相位角最大导通角限制避免全导通时失去调光能力brightness_max 95%对应约 162°状态同步机制当外部强制修改亮度如通过串口指令调用Dimmer_SyncToTarget(h, 80)可立即跳转至目标值跳过渐变过程适用于紧急场景3. API 接口详解3.1 初始化与配置结构体typedef struct { uint8_t brightness; // 当前实际亮度0–100 uint8_t target; // 当前目标亮度0–100 uint16_t ramp_step_ms; // 渐变单步时间ms默认 50 uint8_t min_brightness; // 最小允许亮度%默认 5 uint8_t max_brightness; // 最大允许亮度%默认 95 uint8_t long_press_ms; // 长按阈值ms默认 300 uint8_t accel_step; // 长按时步进值默认 5 uint8_t normal_step; // 短按时步进值默认 1 uint8_t stored_brightness; // 上电读取的存储值供内部使用 } DimmerHandle_t; void Dimmer_Init(DimmerHandle_t* h);Dimmer_Init()执行以下操作将h-brightness和h-target置为h-stored_brightness若已实现存储钩子初始化内部计时器用于长按检测设置默认限幅参数关键配置说明ramp_step_ms直接影响渐变速度。设为 20 ms 可实现 200 ms 内完成 0→100%但过小易受中断延迟影响建议 30–100 ms 区间。min_brightness对 LED 驱动需设为 1–2%对白炽灯可设为 5–10%避免低温闪烁。accel_step与normal_step需满足accel_step normal_step否则长按无加速效果。3.2 主要控制函数函数签名功能说明典型调用上下文void Dimmer_Update(DimmerHandle_t* h)执行一次控制周期更新亮度、检测长按、推进渐变FreeRTOS 周期任务10–50 Hz或 SysTick 中断void Dimmer_SetBrightness(DimmerHandle_t* h, uint8_t b)设定绝对目标亮度0–100串口指令解析、触摸屏事件处理void Dimmer_RampUp(DimmerHandle_t* h, uint8_t step)相对增加亮度step 为增量值按键中断服务程序ISRvoid Dimmer_RampDown(DimmerHandle_t* h, uint8_t step)相对减少亮度同上void Dimmer_Toggle(DimmerHandle_t* h)若当前亮度 5%则关至 0%否则开至上次非零值双击/长按组合逻辑void Dimmer_SyncToTarget(DimmerHandle_t* h, uint8_t target)立即跳转至目标亮度禁用渐变故障恢复、远程强制控制3.3 状态查询与辅助函数uint8_t Dimmer_GetBrightness(const DimmerHandle_t* h); // 返回当前实际亮度非目标值 uint8_t Dimmer_IsRamping(const DimmerHandle_t* h); // 是否处于渐变过程中brightness ! target void Dimmer_ResetRamp(DimmerHandle_t* h); // 强制停止渐变brightness targetDimmer_IsRamping()对资源受限系统尤为关键当返回true时可关闭 LCD 背光刷新、暂停传感器采样降低功耗。4. 典型集成示例4.1 STM32 HAL FreeRTOS 集成// dimmer_task.c #include dimmer_control.h #include main.h static DimmerHandle_t g_dimmer; QueueHandle_t xDimmerCmdQueue; // FreeRTOS 任务每 20 ms 执行一次 void DimmerControlTask(void *pvParameters) { TickType_t xLastWakeTime xTaskGetTickCount(); Dimmer_Init(g_dimmer); for(;;) { Dimmer_Update(g_dimmer); // 将当前亮度同步至硬件驱动假设使用 TIM1 CH1 输出触发脉冲 uint16_t phase_angle map_brightness_to_angle(g_dimmer.brightness); __HAL_TIM_SET_COMPARE(htim1, TIM_CHANNEL_1, phase_angle); vTaskDelayUntil(xLastWakeTime, pdMS_TO_TICKS(20)); } } // 按键 ISRHAL_GPIO_EXTI_Callback void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) { if (GPIO_Pin KEY_UP_Pin) { BaseType_t xHigherPriorityTaskWoken pdFALSE; xQueueSendFromISR(xDimmerCmdQueue, (uint8_t){CMD_RAMP_UP}, xHigherPriorityTaskWoken); portYIELD_FROM_ISR(xHigherPriorityTaskWoken); } } // 命令处理在任务中 void process_dimmer_cmd(uint8_t cmd) { switch(cmd) { case CMD_RAMP_UP: Dimmer_RampUp(g_dimmer, g_dimmer.normal_step); break; case CMD_RAMP_DOWN: Dimmer_RampDown(g_dimmer, g_dimmer.normal_step); break; case CMD_TOGGLE: Dimmer_Toggle(g_dimmer); break; } }4.2 与硬件驱动层的衔接要点DimmerControl 输出的是0–100% 亮度值需转换为具体硬件参数调光类型映射关系注意事项交流相控TRIACphase_angle 180° × (1 − brightness/100)需过零检测信号作为计时起点最小相位角 ≥ 15°对应 brightness ≤ 92%直流 PWMLEDduty_cycle brightness频率需 200 Hz 避免频闪考虑 Gamma 校正duty pow(brightness/100, 2.2) × 100DALI 指令DALI_SetLevel(addr, brightness)DALI Level 范围 0–254需线性缩放level (brightness × 254) / 100关键验证点在Dimmer_Update()后立即读取Dimmer_GetBrightness()确认其值在min_brightness与max_brightness之间。若超出说明外部驱动未正确约束输出需检查硬件层限幅逻辑。5. 关键参数配置与调试技巧5.1 配置宏定义dimmer_config.h#ifndef DIMMER_CONFIG_H #define DIMMER_CONFIG_H // 渐变精度11%55%影响存储空间与计算开销 #define DIMMER_RESOLUTION 1U // 长按检测窗口单位Dimmer_Update 调用次数 #define DIMMER_LONG_PRESS_CYCLES (300U / 20U) // 300ms / 20ms 15 cycles // 硬件层反馈延迟补偿ms #define DIMMER_HARDWARE_LATENCY_MS 3U // 启用/禁用亮度记忆0禁用1启用 #define DIMMER_ENABLE_MEMORY 1U #endif /* DIMMER_CONFIG_H */5.2 调试信号注入法当实测亮度变化不符合预期时优先使用 GPIO 打点法验证逻辑流// 在 Dimmer_Update() 开头添加 HAL_GPIO_WritePin(DEBUG_GPIO_Port, DEBUG_Pin, GPIO_PIN_SET); // 在 Dimmer_Update() 结尾添加 HAL_GPIO_WritePin(DEBUG_GPIO_Port, DEBUG_Pin, GPIO_PIN_RESET);用示波器测量该引脚高电平宽度即可确认Dimmer_Update()执行耗时应 10 μs。若超时需检查是否在其中调用了阻塞函数如HAL_Delay()。5.3 常见问题与解决方案现象根本原因解决方案亮度跳变而非渐变Dimmer_Update()调用频率过低 10 Hz或ramp_step_ms设置过大将任务周期设为 10–20 msramp_step_ms设为 30–50长按无加速long_press_ms与实际调用间隔不匹配或未在每次Dimmer_Update()中调用确认Dimmer_Update()周期稳定long_press_ms应 ≥ 2× 周期关灯后重启仍为关Dimmer_GetStoredBrightness()返回 0 或未实现在Dimmer_Init()后添加printf(Stored: %d\n, h-stored_brightness)日志亮度上限卡在 90%硬件驱动层未正确处理 95% 以上值或max_brightness被误设为 90检查h-max_brightness初始化值及驱动层map_brightness_to_angle()实现6. 与主流嵌入式生态的协同策略6.1 与 STM32CubeMX 的协同在 CubeMX 中配置TIM2设置为 1 MHz 计数频率Prescaler79Counter Period999用于Dimmer_Update()内部微秒级延时如长按计时EXTI Line0连接按键触发HAL_GPIO_EXTI_CallbackTIM1 CH1配置为 PWM 模式Period1000Pulse值由map_brightness_to_angle()动态更新生成代码后在main.c中添加extern DimmerHandle_t g_dimmer; // 在 MX_GPIO_Init() 后添加 g_dimmer.ramp_step_ms 40; g_dimmer.min_brightness 3; Dimmer_Init(g_dimmer);6.2 与 Zephyr RTOS 的适配Zephyr 中需替换 FreeRTOS 相关调用xTaskGetTickCount()→k_uptime_get_32()vTaskDelayUntil()→k_sleep(K_MSEC(20))队列操作 →k_msgq_put()/k_msgq_get()关键修改在dimmer_update.c// 替换原有延时逻辑 static uint32_t last_update_ms 0; void Dimmer_Update(DimmerHandle_t* h) { uint32_t now k_uptime_get_32(); if (now - last_update_ms h-ramp_step_ms) { // 执行渐变计算 last_update_ms now; } }6.3 与 Matter 协议栈的桥接在 Matter SDK 的lighting-app中将 DimmerControl 作为LightingManager的后端// lighting_manager.cpp void LightingManager::Init() { Dimmer_Init(mDimmer); // 注册 Matter 属性变更回调 emberAfPluginLightingSetOnOffCallback on_off_changed; emberAfPluginLightingSetLevelCallback level_changed; } void level_changed(uint8_t new_level) { // Matter Level: 0–254 → Dimmer Brightness: 0–100 uint8_t brightness (new_level * 100) / 254; Dimmer_SetBrightness(mDimmer, brightness); }此桥接使传统调光模块可直连 Matter 生态无需额外网关。7. 性能边界与极限测试方法DimmerControl 在 Cortex-M048 MHz上实测性能Dimmer_Update()平均耗时3.2 μs编译选项-O2单核可支撑最多 12 路独立调光通道每通道 20 ms 周期总开销 384 μs/20 msRAM 占用每个实例 16 字节DimmerHandle_t大小极限压力测试用例高频按键注入用信号发生器向 EXTI 引脚注入 10 Hz 方波模拟疯狂按键观察Dimmer_IsRamping()是否始终返回true亮度是否线性上升至 100%电源扰动测试在调光至 50% 时用电子负载施加 500 ms 电压跌落12 V → 9 V验证Dimmer_GetStoredBrightness()是否仍返回正确值温度漂移验证将 PCB 置于 85°C 烤箱中 2 小时测量同一亮度指令下LED 光通量变化是否 3%需配合光度计通过上述测试可确认该库在工业级温宽−40°C 至 85°C与电磁干扰环境下的可靠性。DimmerControl 的价值不在于它做了什么而在于它明确拒绝做什么它不碰寄存器不占 IRQ不连外设只做一件事——把“用户意图”翻译成“确定性亮度值”。在 STM32H7 上跑满 12 路调光时其 CPU 占用率仍低于 0.8%这正是嵌入式底层库应有的样子沉默、精准、可预测。