启元 T1 Pro 灯光 SDK 入门:颈灯状态与 LED 灯效预演
前言
机器人可以用灯光反馈状态,例如用颜色区分等待和处理中。T1 Pro 的 SDK 提供两类相关接口:颈灯状态用于读取开关和亮度,LED 灯带服务用于选择灯效。弄清二者区别,才能知道应该订阅什么、调用什么。
这篇从真实接口检查开始,再用四种装饰灯效做离线参数预演,最后展示有明确确认条件的调用入口。即使暂时没有机会操作机器人,也能先把程序跑通。

图 1|颈灯状态与灯带服务的两条开发通路,分别用于状态读取和效果控制。
1. 颈灯和灯带,分别调用什么接口?
ROS 2 的话题(Topic)像持续广播状态的频道;服务(Service)则是发送请求并等待回复。T1 Pro 的颈灯状态通过话题接收,灯带灯效通过服务请求,两者要分开处理。
| 能力 | 实际 ROS 2 接口 | 类型 |
|---|---|---|
| 颈灯状态话题 | /aima/hal/neck_light/state | NeckLightState |
| 查询颈灯状态 | /aimdk_5Fmsgs/srv/GetNeckLightState | GetNeckLightState |
| 设置颈灯 | /aimdk_5Fmsgs/srv/SetNeckLight | SetNeckLight |
| 灯带模式设置 | /aimdk_5Fmsgs/srv/LedStripCommand | LedStripCommand |
官方 NeckLightState.msg 包含 enable 和 brightness 两个字段,brightness 的范围是 0~100%。而 LedStripCommand.srv 使用 uint8 类型的 led_strip_mode,并在消息定义里给出了各个预设模式的整数编号。
注意,LedStripCommand 是服务类型;/aimdk_5Fmsgs/srv/LedStripCommand 才是这台机器人当前发现的服务名称。
2. 接口在线,为什么没有收到状态消息?
我们在已打通的 Windows ROS 2 Humble / Fast DDS 环境中,发现颈灯发布节点 hal_sensor_soc0,同时能看到 GetNeckLightState、SetNeckLight 和 LedStripCommand 三项服务。
11 月 4 日用户尝试相关功能期间,程序连续监听 600.08 秒:颈灯状态话题有 1 个发布者,但未收到状态消息;与此同时电池管理系统(BMS)收到 600 条数据,说明机器人与 PC 的 ROS 2 通信仍然正常。
| 现场检查 | 结果 |
|---|---|
| 颈灯话题发布者 | 1 个 |
| 灯光相关服务 | 3 项可发现 |
| 监听时长 | 600.08 秒 |
| 颈灯状态消息 | 0 条 |
| BMS 对照消息 | 600 条 |
| 灯光写入 | 0 次 |

图 2|真实监听结果:颈灯话题在线,600 秒内未收到亮度或开关变化消息。
日志证明 ROS 2 基础通信正常。由于灯带模式和颈灯开关/亮度属于不同接口,控制界面的灯效操作不一定会引发颈灯话题更新。本机已编译的 aimdk_msgs 也缺少 GetNeckLightState 的 Python 客户端类型,因此本次只检查话题和服务列表,没有调用该查询服务。
3. 用四种装饰效果练习灯效编号
官方 LedStripCommand.srv 列出了彩虹、流水、闪烁等模式及其编号。本例选用其中四种普通装饰灯效:
| 程序名称 | SDK 模式码 | 官方模式 |
|---|---|---|
| green_flow | 1 | 绿色流水 |
| rainbow | 2 | 彩虹 |
| twinkle | 4 | 星光闪烁 |
| white_breath | 20 | 白色呼吸 |
示例白名单只包含表中的四项。充电、低电量和故障提示等系统模式仍交给机器人原有控制逻辑。

图 3|四种供开发演示的官方灯带模式编号。颜色示意用于理解效果名称,并非实际拍摄的机器人灯带效果;具体视觉表现以对应固件和设备为准。

图 4|真实 light_lab.py 源码节选:灯效模式白名单、参数检查和离线预演函数。图片按实际源码文件行号排版。
4. 先预演参数,再查看真机接口
灯带服务的请求结构包括 CommonRequest、led_strip_mode 和 r、g、b、period。对这四种预置模式,本例不使用自定义 RGB 与周期参数,统一预演为 0。
运行:
python light_lab.py --preview --mode rainbow
实际离线输出核心字段是:
{
"mode": "OFFLINE_PREVIEW",
"payload": {
"name": "rainbow",
"led_strip_mode": 2,
"r": 0,
"g": 0,
"b": 0,
"period": 0
},
"robot_service_calls": 0
}
OFFLINE_PREVIEW 表示程序只在电脑上生成灯效请求参数,机器人不会收到灯光设置命令;输出里的 robot_service_calls=0 就是对应记录。
再运行一次真实设备只读检查:
python light_lab.py --live-readonly --seconds 12
第二条命令用于确认 ROS 2 端点是否存在,并在状态发生变化时读取 enable 和 brightness。本机真实监听结果见第 2 节。

图 5|真实执行离线彩虹预演与 7.11 秒真机颈灯只读检查后的标准输出节选。彩虹模式编号为 2;真机颈灯发布者 1 个、状态消息 0 条,且没有灯光写入。
5. 真机写入之前,为什么要加确认开关?
light_lab.py 单独实现了可选的灯带写入分支,但默认不开放。开发者需要同时输入 --apply 和 --confirm-led-change,才能走到真实服务请求;没有双重确认时,程序会在 ROS 2 导入之前直接拒绝。
此外,mode 只能是前面四个装饰模式,故障灯、充电灯和关机相关编号不能直接用于本示例。
plan = preview_mode(mode)
if not confirmed:
raise PermissionError(
"Live light command requires explicit confirmation"
)
调试灯效编号时,我会先用预演模式查看请求参数,再通过只读模式确认接口是否在线。这里实际执行的也是这两种模式,没有发送 --apply 写入请求。代码中的双重确认和白名单用于避免调试时误覆盖机器人原本的状态提示;原灯效的回读与恢复并未在这次测试中使用。

图 6|预演、只读检查与实际写入的三条路径。前两条只观察和生成参数;只有明确确认后,代码才会走到写入分支。
6. 灯光接口看起来简单,真正容易踩坑的是这三件事
写完这个小示例,我觉得最值得记住的是:读颈灯状态、生成灯效参数、改变灯带效果,是三个不同的步骤。它们虽然都和“灯”有关,却走不同的 ROS 2 接口。调试时把三者混在一起,就很难分清问题出在状态订阅、模式编号还是服务调用。
这段代码把四种装饰灯效放进白名单,默认用 preview 查看参数,需要实际写入时再经过单独的确认开关。配套的单元测试也覆盖了模式映射、亮度范围和误操作拦截;ROS 2 的服务列表与只读监听则有真实设备日志可以对照。
对我来说,灯光开发的第一步并不是追求多炫的动画,而是让每一次状态读取和模式选择都有清楚的入口。把这层逻辑写明白,后面的交互程序也会更容易维护。
参考资料
[2] 官方接口说明:硬件抽象与 LED
本文代码
- 灯效预演与颈灯只读检查:light_lab.py —— 包括四种灯效白名单、–preview 和 --live-readonly。
- 配套单元测试:tests/test_light_lab.py —— 检查模式编号、亮度范围和写入确认逻辑。
nly。 - 配套单元测试:tests/test_light_lab.py —— 检查模式编号、亮度范围和写入确认逻辑。
更多资料获取
启元机器人开发者社区 https://dev.primebot.com/
PrimeHub 技能市场skillhub.primebot.com
DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。
更多推荐



所有评论(0)