# cotLed **Repository Path**: MagicBude/cot_led ## Basic Information - **Project Name**: cotLed - **Description**: 嵌入式设备常用的指示灯控制模块组件代码 - **Primary Language**: C - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-06-16 - **Last Updated**: 2026-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 轻量级 LED 控制模块 本模块提供亮灭、定时切换、闪烁、呼吸、自定义状态序列、跑马灯和流水灯效果,支持多个 LED 独立管理。 ## 功能特点 - 核心不依赖具体 MCU,通过输出回调适配实际硬件 - 支持固定亮灭、翻转及定时切换 - 支持闪烁、软件 PWM 呼吸、自定义亮灭序列和多灯组合效果 - 支持指定效果次数及结束状态 - 配置与周期控制分离,实际 GPIO 输出在控制任务中执行 ## 文件结构 - `cot_led.h` / `cot_led.c`:核心类型、效果配置及周期控制 - `led_manager.h` / `led_manager.c`:STM32F1 HAL 三灯管理层示例,提供 GPIO 定义及输出回调 ## 使用说明 ### 基本步骤 1. **初始化硬件**:配置 GPIO,并实现接收 `cotLedState_e` 的输出函数,完成逻辑状态与实际电平的转换。 2. **注册配置表**:为各项设置 `pfnLedCtrl`,调用 `cotLed_Init`。配置表和回调在组件使用期间须持续有效。 3. **配置效果**:通过亮灭、闪烁、呼吸或序列接口设置效果。 4. **周期控制**:在同一主循环或任务中周期调用 `cotLed_Ctrl`,传入累计毫秒时间,而非扫描间隔。 初始化清零运行字段并重置控制时间基准,不初始化 GPIO,也不立即输出电平。效果配置接口同样不直接写 GPIO,实际输出由周期控制完成。 ### 代码示例 以下为接入片段,GPIO 初始化及 `CtrlLed0`、`CtrlLed1`、`CtrlLed2` 由板级代码提供。 ```c #include "cot_led.h" void CtrlLed0(cotLedState_e state); void CtrlLed1(cotLedState_e state); void CtrlLed2(cotLedState_e state); void FML_LED_Init(void) { /* 配置表顺序对应 LED 索引,使用期间持续有效 */ static cotLedCfg_t s_ledTable[] = { { .pfnLedCtrl = CtrlLed0 }, { .pfnLedCtrl = CtrlLed1 }, { .pfnLedCtrl = CtrlLed2 }, }; cotLed_Init(s_ledTable, sizeof(s_ledTable) / sizeof(s_ledTable[0])); cotLed_Twinkle(0, 500); /* 每 500 ms 改变一次亮灭状态 */ } ``` 在 STM32 HAL 主循环或同一任务中周期执行: ```c cotLed_Ctrl(HAL_GetTick()); ``` 普通状态序列可按 20 ms 周期调用;呼吸灯使用软件 PWM,要求 1 ms 周期。时间参数应与调度周期匹配,调度抖动及漏调用会影响效果。回调在控制函数内同步执行,应尽快返回;配置和控制不得并发访问组件。定时中断可仅设置调度标志,由主循环执行控制。 #### 配置不同效果 以下是相互独立的示例;对同一 LED 再次配置会替换其原有效果。 ```c cotLed_ON(0); /* 固定点亮 */ cotLed_SetStateWithTime(0, COT_LED_ON, 1000); /* 点亮后切换为熄灭 */ cotLed_TwinkleWithCount(0, 500, 3, COT_LED_OFF); /* 闪烁三轮后保持熄灭 */ cotLed_Custom(0, (int32_t)100, (int32_t)-100, (int32_t)100, (int32_t)-300, (int32_t)0); ``` 自定义序列使用正数表示点亮时长、负数表示熄灭时长,零结束列表,单位:ms。每项及结束符须以 `int32_t` 类型传入。 ## 配置项 ### 效果接口 - 基础控制:`cotLed_SetState`、`cotLed_ON`、`cotLed_OFF`、`cotLed_Toggle` - 定时切换:`cotLed_SetStateWithTime`,时间结束后切换为指定状态的相反状态 - 闪烁:`cotLed_Twinkle`、`cotLed_TwinkleWithCount` - 呼吸:`cotLed_Breathe`、`cotLed_BreatheWithCount` - 自定义序列:`cotLed_Custom`、`cotLed_CustomWithCount` - 跑马灯:`cotLed_Marquee`、`cotLed_MarqueeWithCount` - 流水灯:`cotLed_Waterfall`、`cotLed_WaterfallWithCount` `cotLed_CustomWithCount` 的 `count = 0` 表示无限循环;其他带次数接口的零次数含义应查阅对应接口说明,不能直接类推。 ### 状态容量 `LED_STATE_BYTE_NUM` 默认值为 4,即 32 个状态位,每位表示一个最小控制间隔。编译期限制为 1~31 字节,以匹配 8 位偏移和有效位数字段。自定义序列和组合效果须保证有效位及访问位置不超出数组容量;流水灯额外使用一个状态位。 ## 适配指南 根据板卡修改 `led_manager` 的 GPIO 定义、初始化和输出回调。核心可脱离该管理层直接接入应用。 - 初始化检查配置项数量为 1~255、配置表非空及全部输出回调有效,失败时保留原实例。 - 自定义序列至少包含一个非零时长;绝对值不超过 65535,并能由最小非零时长整分,展开后不得超出状态容量。 - 避免对最小负数取绝对值;多灯效果的时间最终保存为 16 位间隔。 - 部分接口忽略越界 LED 索引并返回 0,返回成功不表示所有索引均被应用;以头文件说明为准。 - 管理层示例使用 STM32F1 HAL 接口,接入时须提供匹配的 HAL、启动文件和板级配置;主机语法检查不代表完整板级构建或运行验证。 本次未进行完整 STM32 工程构建或 GPIO、时基与呼吸效果实测。 ## 原项目信息 - 原作者:[大橙子疯](https://blog.csdn.net/qq_24130227?spm=1010.2135.3001.5343) - 联系邮箱:`const_zpc@163.com` - 原始代码:[轻量级 LED 控制模块](https://gitee.com/cot_package/cot_led) ## 许可证 [MIT](LICENSE) 主机时间基准回归见 [测试说明](tests/README.md)。 自定义序列会在写入前校验时长范围、整除关系及总容量;无效输入返回 -1,保留原配置。可变参数仍须使用 int32_t 并以零结束,调用者不得在使用期间清空输出回调。