RGB 灯效架构

概述

本键盘 RGB 系统基于 WS2812 驱动，支持多种灯效模式、独立指示灯亮度，以及通过 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	状态指示开关
indicator_brightness	uint8_t	指示灯亮度 (0-255，最低 13)

灯效模式 (kbd_rgb_mode_t)

值	模式	使用颜色	说明
0	OFF	-	已取消，UI 不再提供
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
• UI 应提供调色盘或 hex 输入

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

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

---

双亮度机制

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

仅指示灯模式（WS2812_LED_NUM==1）时，两者同步；多 LED 时可分别调节。

---

HID 协议

• RGB_GET：返回 9 字节 enabled,mode,brightness,speed,color_r,color_g,color_b,indicator_enabled,indicator_brightness
• RGB_SET：接收相同 9 字节，写入配置（需 CFG_SAVE 持久化）

详见 hid.md。