RGB 灯效架构

概述

RGB 由 WS2812 驱动。Studio 通过 HID 修改灯效、亮度、颜色、按键反馈和休眠参数。

---

架构分层

┌─────────────────────────────────────────────────────────────────────┐
│  应用层 (Studio UI / HID 协议)                                        │
│  - 模式选择、亮度、颜色、速度                                          │
│  - RgbConfig: mode, brightness, colorR/G/B, indicatorBrightness       │
└────────────────────────────┬────────────────────────────────────────┘
                             │ HID RGB_GET / RGB_SET
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│  命令层 (kbd_command.c)                                               │
│  - 解析 RGB_SET 帧 → 写入 kbd_rgb_config_t                            │
│  - 组装 RGB_GET 响应                                                  │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│  灯效引擎 (kbd_rgb.c)                                                 │
│  - KBD_RGB_Process() 主循环 (约 20ms 间隔)                             │
│  - 模式分发：静态/呼吸/闪烁/彩虹/仅指示灯                               │
│  - 亮度/颜色/速度应用                                                 │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│  硬件抽象层 (ws2812.c)                                                │
│  - WS2812_Fill(r,g,b) / WS2812_Set_Indicator(r,g,b)                  │
│  - 亮度独立：s_rgb_brightness（按键灯） / s_indicator_brightness（指示灯）│
│  - TMR1 + DMA 生成 GRB 时序                                           │
└─────────────────────────────────────────────────────────────────────┘

---

数据结构

固件 kbd_rgb_config_t (kbd_types.h)

字段	类型	说明
enabled	uint8_t	RGB 总开关
mode	uint8_t	灯效模式 (0-5)
brightness	uint8_t	RGB/按键灯亮度 (0-255)
speed	uint8_t	动画速度 (0=最慢, 255=最快)
color_r	uint8_t	静态/呼吸/闪烁 颜色 R
color_g	uint8_t	静态/呼吸/闪烁 颜色 G
color_b	uint8_t	静态/呼吸/闪烁 颜色 B
indicator_enabled	uint8_t	状态指示字段；当前 RGB_SET 固定写为启用
indicator_brightness	uint8_t	指示灯亮度 (0-255，最低 13)
press_effect	uint8_t	0=无，1=按下亮起渐灭，2=按下熄灭渐亮

灯效模式 (kbd_rgb_mode_t)

值	模式	使用颜色	说明
0	OFF	-	按键灯关闭，状态指示仍可运行
1	STATIC	color_r/g/b	固定颜色常亮
2	BREATHING	color_r/g/b	亮度渐变循环
3	BLINK	color_r/g/b	周期性开关
4	RAINBOW	-	色相渐变，无用户色
5	INDICATOR	预设色	根据连接状态自动变换

---

颜色流向

需要用户配置颜色的模式

• 静态 / 呼吸 / 闪烁：共用 color_r, color_g, color_b
• Studio 提供调色盘和十六进制输入

预设颜色（无需用户配置）

• 仅指示灯：根据 kbd_state_t 选择颜色
  • USB 已连接: 白色短亮
  • BLE 未连接: 红（呼吸）
  • BLE 广播中: 蓝（呼吸）
  • BLE 已连接: 绿色短亮
  • 低电量: 橙红色快闪
• 层切换闪烁：固件内 s_layer_colors[5][3] 固定为蓝、绿、黄、紫、红

---

双亮度机制

参数	作用对象	最低值
brightness	按键灯、灯效主亮度	0
indicator_brightness	指示灯（第一个 LED）	13 (~5%)

仅有一颗 WS2812 时，只驱动指示灯；多颗时，按键灯和指示灯分别计算亮度。

---

HID 协议

• RGB_GET：返回状态码加 12 字节配置：enabled, mode, brightness, speed, color_r/g/b, indicator_enabled, indicator_brightness, press_effect, auto_sleep_min, deep_sleep_min。
• RGB_SET：接收 12 字节配置。固件校验长度后立即调用 KBD_Config_Save()；Studio 不需要再单独提交 RGB 配置。

详见 hid.md。