# 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-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LED 控制模块

`cot_led.c/.h` 提供亮灭、定时切换、闪烁、呼吸、自定义状态序列、跑马灯和流水灯控制。
核心通过输出回调控制 LED，不依赖具体 MCU；`led_manager.c/.h` 是 STM32F1 HAL 的三灯适配示例。

## 文件与调用关系

- `cot_led.h`：状态类型、配置表和公共接口说明。
- `cot_led.c`：效果配置、状态序列和软件 PWM 处理。
- `led_manager.h`：示例 GPIO、输出宏和 LED 索引。
- `led_manager.c`：示例 GPIO 初始化及输出回调注册。

每个 LED 对应一项可写的 `cotLedCfg_t`。初始化前设置 `pfnLedCtrl`，调用 `cotLed_Init` 注册表，
再选择控制效果。周期调用 `cotLed_Ctrl`，模块读取状态、更新计时并调用各项输出回调。
配置效果不会立即写 GPIO，实际输出发生在控制任务中。

## 最小接入

由板级代码实现三个输出回调，并在调用模块初始化之前完成 GPIO 初始化。
回调参数是逻辑状态，板级代码自行将 `COT_LED_ON` 和 `COT_LED_OFF` 转换为实际电平。

```c
#include "cot_led.h"

/* 由板级代码提供，参数是逻辑亮灭状态。 */
void CtrlLed0(cotLedState_e state);
void CtrlLed1(cotLedState_e state);
void CtrlLed2(cotLedState_e state);

static cotLedCfg_t sg_ledTable[] =
{
    {.pfnLedCtrl = CtrlLed0},
    {.pfnLedCtrl = CtrlLed1},
    {.pfnLedCtrl = CtrlLed2},
};

void FML_LED_Init(void)
{
    /* GPIO 应在此函数调用前完成初始化。 */
    cotLed_Init(sg_ledTable, sizeof(sg_ledTable) / sizeof(sg_ledTable[0]));
    cotLed_Twinkle(0, 500);
}

void LedTask(uint32_t nowMs)
{
    cotLed_Ctrl(nowMs);
}
```

配置表和回调必须在模块使用期间始终有效。`cotLed_Init` 清零运行字段，不初始化 GPIO，
也不立即输出电平。普通效果可按固定毫秒周期调度；呼吸灯使用软件 PWM，要求 1 ms 周期。
时间参数应与调度周期匹配，调度抖动及漏调用会影响实际效果。

## 接口分类

- 初始化与调度：`cotLed_Init`、`cotLed_Ctrl`。
- 基础控制：`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`。

完整参数、返回值和调用约定见头文件对应接口。自定义序列以正数表示点亮时长、负数表示
熄灭时长、0 结束，单位为 ms；可变参数按 `int32_t` 读取，传参类型应与之匹配。
`cotLed_CustomWithCount` 的 `count = 0` 表示不限次数；其他带次数的接口不能据此推定相同含义。

## 调用约束与已知限制

- 核心未提供并发保护，应将配置和控制任务串行调用，或由调用者同步。
- 当前初始化使用 8 位循环计数，配置项数量应限制在 1 至 255；配置表和输出回调须有效。
- 状态数组默认有 32 位。组合效果和自定义序列必须保证有效位及访问位置不超出数组容量；
  流水灯额外使用一个状态位。当前实现未完整校验这些边界。
- 自定义时长必须能用最小非零时长整分，展开后不超过状态容量；避免无有效时长、过大时长
  及负数绝对值超出表示范围的输入。组合效果的时间最终保存为 16 位间隔。
- 部分接口会忽略越界 LED 索引并返回 0，例如呼吸灯和组合效果；返回 0 不代表每项配置均成功。
- `led_manager` 示例将 `LED0/1/2` 的 `do/while` 语句宏用于条件表达式的操作数，普通 C 编译
  会报告语法错误。该示例存在原有编译问题，不能据核心编译结果推定它可直接构建使用。