# 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**: 0
- **Created**: 2025-06-16
- **Last Updated**: 2025-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 轻量级LED控制模块（增强注释版）

这是一个轻量级的LED控制软件框架，在原有项目基础上增加了全面的代码注释和文档，使其更加易于理解和使用。该模块可以方便地控制LED的各种状态，支持多个LED组合控制，如跑马灯、流水灯等效果。

## 增强版特点

* **全面的代码注释**：每个函数都有详细的功能说明、参数描述和返回值解释
* **统一的注释风格**：采用标准Doxygen格式的注释，便于生成API文档
* **代码结构优化**：重新组织了函数的顺序和分组，使逻辑更加清晰
* **命名规范统一**：将LED编号从1/2/3改为0/1/2，符合编程习惯

## 原有功能特点

* 移植方便，无需修改，只需实现LED控制回调函数
* 丰富的接口实现：
  * 单个LED控制：亮灭、翻转、闪烁、呼吸灯、自定义模式等
  * 多个LED组合控制：跑马灯、流水灯等效果
  * 支持设置控制次数和结束状态
* 代码量少，结构清晰
* 非阻塞设计，适用于裸机和RTOS环境
  * 注意：在操作系统环境下使用时，建议实现读写锁或互斥锁保护

## 软件架构

### 文件介绍

* **cot_led.h** - 头文件，定义了API接口和数据类型
* **cot_led.c** - 实现文件，包含所有功能的具体实现
* **led_manager.h/c** - 示例适配层，演示如何将模块适配到具体硬件

## 使用说明

### 1. 初始化

使用前需要调用`cotLed_Init`函数初始化LED控制模块：

```c
typedef enum
{
    LED_0 = 0,
    LED_1,
    LED_2,
  
    /* 勿删除,用来统计LED的数目 */
    LED_MAX_NUM
} LedType_e;

/* 控制LED0的回调函数 */
void CtrlLed0(cotLedState_e state)
{
    state == COT_LED_ON ? LED0(0) : LED0(1);  /* LED0是低电平点亮 */
}

/* 控制LED1的回调函数 */
void CtrlLed1(cotLedState_e state)
{
    state == COT_LED_ON ? LED1(0) : LED1(1);  /* LED1是低电平点亮 */
}

/* 控制LED2的回调函数 */
void CtrlLed2(cotLedState_e state)
{
    state == COT_LED_ON ? LED2(0) : LED2(1);  /* LED2是低电平点亮 */
}

/* LED模块初始化 */
void FML_LED_Init(void)
{
    static cotLedCfg_t s_ledTable[LED_MAX_NUM] = 
    {
        {.pfnLedCtrl = CtrlLed0},
        {.pfnLedCtrl = CtrlLed1},
        {.pfnLedCtrl = CtrlLed2},
    };

    InitLedIo();  /* 初始化LED相关IO口 */
    cotLed_Init(s_ledTable, LED_MAX_NUM);  /* 初始化LED控制模块 */
}
```

### 2. 周期调用控制函数

需要周期调用`cotLed_Ctrl`函数来更新LED状态：

```c
/* 在RTOS环境中 */
void LedTask(void)
{
    uint32_t time;
  
    while (1)
    {
        cotLed_Ctrl(GetTimerMs());  /* 传入系统当前时间(毫秒) */
        cotOs_WaitFor(1);  /* 等待1ms */
    }
}

/* 或在裸机环境中 */
int main(void)
{
    int time1ms_cnt = 0;

    while(1)
    {
        if (flag_1ms)  /* 1ms定时标志 */
        {
            flag_1ms = 0;
            cotLed_Ctrl(time1ms_cnt++);
        }
    }
}
```

### 3. 灯光控制示例

```c
/* 基本控制 */
cotLed_SetState(LED_0, COT_LED_ON);  /* 点亮LED0 */
cotLed_SetStateWithTime(LED_0, COT_LED_ON, 1000);  /* LED0点亮1秒后自动熄灭 */

/* 闪烁控制 */
cotLed_Twinkle(LED_0, 500);  /* LED0以500ms的间隔闪烁 */
cotLed_TwinkleWithCount(LED_0, 500, 3, COT_LED_OFF);  /* LED0闪烁3次后熄灭 */

/* 呼吸灯效果 */
cotLed_Breathe(LED_0, 2000);  /* LED0以2秒为周期呼吸 */
cotLed_BreatheWithCount(LED_0, 2000, 3, COT_LED_OFF);  /* LED0呼吸3次后熄灭 */

/* 自定义控制 */
/* 格式: 亮时间(ms), -灭时间(ms), ..., 0(结束) */
cotLed_Custom(LED_0, 100, -100, 100, -1700, 0);  /* 2秒内闪烁2次 */
cotLed_CustomWithCount(LED_0, 5, COT_LED_OFF, 100, -100, 100, -100, 100, -1600, 0);  /* 2秒内闪烁3次，重复5次，结束后熄灭 */

/* 多个LED组合控制 */
led_t leds[] = {LED_0, LED_1, LED_2};
cotLed_Marquee(leds, 3, 300);  /* 跑马灯效果，每个LED亮300ms */
cotLed_Waterfall(leds, 3, 300);  /* 流水灯效果，每隔300ms增加一个LED亮 */
```

## 注意事项

1. 呼吸灯模式需要保证`cotLed_Ctrl`的调用周期为1ms，以确保PWM效果平滑
2. 各控制函数不支持重复调用，重复调用会重置之前的设置
3. 状态位数组大小（`LED_STATE_BYTE_NUM`）限制了自定义模式下能设置的最大LED状态数量
4. 使用组合控制功能时（如跑马灯、流水灯），所有LED必须事先初始化并通过`cotLed_Init`注册
5. 多任务环境下需要注意对LED控制函数的并发访问保护（使用信号量或互斥锁）
6. LED控制回调函数应当尽量简短，避免执行耗时操作以减少对系统实时性的影响
7. 对于资源受限的系统，可以减小`LED_STATE_BYTE_NUM`的值以节省RAM
8. 使用自定义模式时，时间参数需要是控制任务调度周期的整数倍，否则会出现时间不准确问题
9. 当使用`WithCount`系列函数时，请确保设置合理的默认状态（`defState`），以避免效果结束后LED状态不符合预期

## 关于项目

本项目基于[原始项目](https://gitee.com/cot_package/cot_led)进行改进，主要增强了代码注释和文档，以便更好地理解和使用。

## 致谢

感谢原项目作者[大橙子疯](https://blog.csdn.net/qq_24130227)提供的优秀代码框架。