# hal_led

**Repository Path**: peculiarly/hal_led

## Basic Information

- **Project Name**: hal_led
- **Description**: 简易led指示灯控制模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# hal_led

English | [中文说明见下方](#hal_led-中文说明)

A small, portable LED control module for embedded systems.

- Periodic state-machine update (non-blocking, no delays inside)
- Configurable blinking: by cycles + frequency or custom on/off durations
- Timed on then auto-off (e.g. light 3s then off)
- Pluggable GPIO writer callback per slot to adapt any MCU

## API Overview

- Initialization
  - `void HalLedInit(void);` (default 10ms update interval)
  - `void HalLedInitEx(uint16_t update_interval_ms);`
- Registration
  - `void HalLedRegister(uint8_t led_index, void (*led_write)(uint8_t onoff));`
- Control
  - `void HalLedOnOff(uint8_t led_index, uint8_t onoff);`
  - `void HalLedBlink(uint8_t led_index, uint16_t cycles, uint16_t freq_hz); // cycles=0 -> infinite`
  - `void HalLedBlinkEx(uint8_t led_index, uint16_t cycles, uint16_t on_time_ms, uint16_t off_time_ms); // cycles=0 -> infinite`
  - `void HalLedLightFor(uint8_t led_index, uint32_t duration_ms);`
  - `void HalLedCancel(uint8_t led_index);`
- Periodic update
  - `void HalLedUpdate(void);` // call every `update_interval_ms`

Note: You must register each LED slot with a writer callback (GPIO abstraction) before using it.

## Quick Start

```c
#include "hal_led.h"

static void led0_write(uint8_t onoff) {
    // TODO: call your platform GPIO driver here
}

void app_init(void) {
    HalLedInitEx(10);              // 10ms tick
    HalLedRegister(0, led0_write); // register slot 0
}

void app_timer_tick_10ms(void) {
    HalLedUpdate();
}

void demo(void) {
    HalLedBlink(0, 0, 2);          // infinite blink at 2Hz
    // or
    // HalLedBlinkEx(0, 5, 200, 300); // blink 5 cycles, on 200ms/off 300ms
    // HalLedLightFor(0, 3000);       // light for 3 seconds then off
}
```

## Portability Notes
- The module does not depend on specific GPIO types; users provide a `led_write(onoff)` per slot.
- Keep `led_write` fast and non-blocking.
- Call `HalLedUpdate()` periodically at the configured interval.

## License
Choose a license (e.g., MIT/Apache-2.0/BSD-3-Clause). Add a LICENSE file before publishing.

---

# hal_led 中文说明

一个适用于嵌入式系统的轻量级、可移植LED控制模块。

- 状态机驱动，周期性调用，无阻塞、无延时
- 支持可配置次数/频率的闪烁，或自定义亮灭时长
- 支持定时点亮后自动熄灭（如点亮3秒后自动灭）
- 每个LED槽位可注册独立GPIO控制回调，适配任意MCU

## 主要API

- 初始化
  - `void HalLedInit(void);`（默认10ms更新周期）
  - `void HalLedInitEx(uint16_t update_interval_ms);`
- 注册
  - `void HalLedRegister(uint8_t led_index, void (*led_write)(uint8_t onoff));`
- 控制
  - `void HalLedOnOff(uint8_t led_index, uint8_t onoff);`
  - `void HalLedBlink(uint8_t led_index, uint16_t cycles, uint16_t freq_hz); // cycles=0表示无限闪烁`
  - `void HalLedBlinkEx(uint8_t led_index, uint16_t cycles, uint16_t on_time_ms, uint16_t off_time_ms); // cycles=0表示无限闪烁`
  - `void HalLedLightFor(uint8_t led_index, uint32_t duration_ms);`
  - `void HalLedCancel(uint8_t led_index);`
- 周期推进
  - `void HalLedUpdate(void);` // 每`update_interval_ms`调用一次

注意：每个LED槽位使用前必须注册写回调（GPIO抽象）。

## 快速上手

```c
#include "hal_led.h"

static void led0_write(uint8_t onoff) {
    // TODO: 调用你的平台GPIO驱动
}

void app_init(void) {
    HalLedInitEx(10);              // 10ms周期
    HalLedRegister(0, led0_write); // 注册槽位0
}

void app_timer_tick_10ms(void) {
    HalLedUpdate();
}

void demo(void) {
    HalLedBlink(0, 0, 2);          // 2Hz无限闪烁
    // 或
    // HalLedBlinkEx(0, 5, 200, 300); // 闪烁5次，亮200ms/灭300ms
    // HalLedLightFor(0, 3000);       // 亮3秒后自动熄灭
}
```

## 可移植性说明
- 本模块不依赖具体GPIO类型，用户需为每个槽位提供写回调
- 回调应尽量快且无阻塞
- `HalLedUpdate()`需按设定周期定时调用

## 许可证
推荐选择MIT/Apache-2.0/BSD-3-Clause等开源协议，发布前请添加LICENSE文件。