4.3 LED API 简介

本节导读

总览页我们已经动手点过一次灯（HalLedSet / HalLedBlink）。这一节把 LED 的"家当"全部摆出来：一共有哪些 API、每个参数什么含义、返回值是什么。

看完你就能像点菜一样熟练地操作 LED 了。

原站本节内容已失效，本站按 Z-Stack 3.0 的 hal_led.h 源码与教学实践重写。

一、API 在哪个文件？

LED 驱动 API 定义在 hal_led.h（接口说明书）中，实现在 target\CC2530EB\hal_led.c（施工队）中——对应 4.1 讲的"include 定接口、target 做实现"。

打开 hal_led.h，能找到 6 个 API + 2 组宏。

二、先认识两组宏：LED 编号 和 工作模式

① LED 编号宏（告诉 API 操作哪个灯）

#define HAL_LED_1  0x01   // LED1
#define HAL_LED_2  0x02   // LED2
#define HAL_LED_3  0x04   // LED3
#define HAL_LED_4  0x08   // LED4

注意编号是按位编码的（1、2、4、8）——所以可以组合使用：HAL_LED_1 | HAL_LED_2 表示同时操作 LED1 和 LED2。

对照 GEC2530 底板原理图（Sheet 8）：LED1~LED4 分别接 P1_0 / P1_1 / P1_4 / P0_1，低电平点亮。

② 工作模式宏（告诉 API 让灯干什么）

#define HAL_LED_MODE_OFF    0x00   // 熄灭
#define HAL_LED_MODE_ON     0x01   // 点亮
#define HAL_LED_MODE_TOGGLE 0x02   // 翻转（亮变灭、灭变亮）
#define HAL_LED_MODE_BLINK  0x03   // 闪烁

三、六个 API 逐个看

① HalLedInit() —— 初始化

void HalLedInit(void);

把所有用到的 LED 引脚配置为输出模式。由 HalDriverInit() 在定义了 HAL_LED=TRUE 时自动调用，一般不用手动调。

② HalLedSet() —— 设置状态（最常用）

uint8 HalLedSet(uint8 led, uint8 mode);

参数	含义	例子
led	操作哪个灯（可组合）	HAL_LED_1 或 `HAL_LED_1
mode	什么状态	HAL_LED_MODE_ON / OFF / TOGGLE

点亮 LED1 并翻转 LED2：

HalLedSet(HAL_LED_1, HAL_LED_MODE_ON);       // LED1 亮
HalLedSet(HAL_LED_2, HAL_LED_MODE_TOGGLE);   // LED2 翻转

③ HalLedBlink() —— 闪烁

uint8 HalLedBlink(uint8 led, uint8 numBlinks, uint8 percent, uint16 period);

参数	含义	大白话
led	哪个灯	谁闪
numBlinks	闪烁次数	闪几下
percent	亮的时间占比（0~100）	亮多久（占一个周期的百分比）
period	一个周期的毫秒数	闪多快

让 LED1 闪 10 次，每次亮 50% 时间、周期 1000ms（亮 500ms 灭 500ms）：

HalLedBlink(HAL_LED_1, 10, 50, 1000);

⚠️ HalLedBlink 底层依赖 HAL 任务的 HAL_LED_BLINK_EVENT 事件（4.2 讲过）——LED 闪烁不是"卡住 CPU 等待"，而是事件驱动的定时更新，不耽误其他任务干活。

④ HalLedGetState() —— 查询状态

uint8 HalLedGetState(void);

返回当前所有 LED 的状态（哪个灯亮着）。比如返回值 HAL_LED_1 表示 LED1 亮着。

⑤ HalLedEnterSleep() / HalLedExitSleep() —— 睡眠/唤醒

void HalLedEnterSleep(void);
void HalLedExitSleep(void);

低功耗模式下保存/恢复 LED 状态。一般不需要管，知道有这两个就行。

四、返回值

多数 LED API 返回一个状态码：

#define HAL_LED_STATUS_OK   0x00   // 操作成功
#define HAL_LED_STATUS_ERROR 0xFF  // 操作失败

写代码时可以用 if (HalLedSet(...) == HAL_LED_STATUS_OK) 判断是否成功，但大多数例程直接忽略返回值。

五、小结

API	作用	常用参数/例子
HalLedInit()	初始化引脚为输出	自动调用
HalLedSet(led, mode)	点亮/熄灭/翻转	HalLedSet(HAL_LED_1, HAL_LED_MODE_ON)
HalLedBlink(led, n, pct, period)	闪烁	HalLedBlink(HAL_LED_1, 10, 50, 1000)
HalLedGetState()	查询亮灭状态	if (HalLedGetState() & HAL_LED_1)
HalLedEnterSleep/ExitSleep()	低功耗保存/恢复	一般不管

一句话总结：LED 操作 = 编号宏（哪个灯）+ 模式宏（干什么），核心就三个 API——Init（布置）、Set（点/灭/翻）、Blink（闪）。记住编号按位编码可以组合，这一节就毕业了。

---

内容来源：紫甲 IoT《ZigBee 3.0 开发指南》第三部分·4.3 节（原站已失效），本站按 Z-Stack 3.0 的 hal_led.h 源码与教学实践重写；原站链接