灯光控制

灯光控制是 JieLi Home 示例应用中的设备功能模块，通过 Flutter 与 Android 原生蓝牙 SDK 的 MethodChannel 桥接，实现对 JL 蓝牙音箱/设备 LED 灯效的开关、颜色、闪烁与场景模式的完整控制。

Purpose and Scope

本文档介绍灯光控制功能的完整实现链路：从 LightPage 用户界面（灯光、闪烁、场景三个 Tab）、BleLightManager 的 Flutter API 封装，到经由 BleBaseManager.invokeMethod 下发至 Android 原生 LightManager.kt / LightProcessor.kt 的蓝牙指令流程。

本页覆盖范围：

• Flutter 侧灯光控制 API（BleLightManager）及其参数模型
• 灯光控制页面（LightPage）的 UI 状态机、三个控制 Tab 与事件流
• HSL ↔ RGB 颜色模型转换与灯效参数合成逻辑
• 灯光状态上报的监听与解析
• 与 Android 原生蓝牙 SDK 的交互边界

以下主题属于兄弟页面，不在本文档展开：蓝牙连接/断开管理（见连接状态管理相关页面）、通用事件流机制（BleEventStream）、设备信息管理（BleDeviceInfoManager）。

概述

灯光控制模块采用「Flutter UI → 方法通道（MethodChannel）→ Android 原生蓝牙 SDK → BLE 设备」的分层架构。用户通过 LightPage 的三个 Tab 分别调整基础灯效、闪烁模式和场景灯效；页面将 UI 状态（温度、亮度、饱和度、所选场景/闪烁索引）转换为 HSL 与 RGB 颜色参数，再调用 BleLightManager.setLightParams 一次性将全部灯效参数打包下发到设备。

该设计的核心意图是参数整包下发：无论用户只拨动了一个滑杆还是切换了整个场景，最终都会通过同一个 setLightParams 方法把所有参数（开关状态、模式、RGB、闪烁索引、频率索引、场景索引、HSL 分量）原子性地发送到原生层。这种设计简化了协议状态同步——设备端只需处理一种"完整灯效状态"消息，避免了逐参数增量更新带来的中间态不一致问题。

模块同时通过 BleEventStream.lightInfoStream 订阅设备上报的灯光信息，用于回显设备当前实际灯效状态（例如总开关状态），实现 UI 与设备的双向同步。

架构

flowchart TD
    subgraph sg_UI["UI 层 (example/lib/pages)"]
        LightPage["LightPage<br/>(StatefulWidget)"]
        LightTab["灯光 Tab"]
        BlinkTab["闪烁 Tab"]
        SceneTab["场景 Tab"]
    end

    subgraph sg_Flutter["Flutter API 层 (lib/manager)"]
        BleLightManager["BleLightManager<br/>setLightParams()"]
        BleBaseManager["BleBaseManager<br/>invokeMethod()"]
        BleMethodConstants["BleMethodConstants<br/>方法名/参数名常量"]
    end

    subgraph sg_Event["事件层"]
        BleEventStream["BleEventStream<br/>lightInfoStream"]
        LightTotalSwitchStatus["LightTotalSwitchStatus<br/>closed/open/unknown"]
    end

    subgraph sg_Native["Android 原生层 (kotlin)"]
        LightManager["LightManager.kt"]
        LightProcessor["LightProcessor.kt"]
        LightControlInfo["LightControlInfo.java<br/>(数据模型)"]
    end

    subgraph sg_Device["BLE 设备"]
        LED["设备 LED 灯效"]
    end

    LightPage --> LightTab
    LightPage --> BlinkTab
    LightPage --> SceneTab
    LightTab -->|"HSL→RGB + 参数合成"| BleLightManager
    BlinkTab --> BleLightManager
    SceneTab --> BleLightManager
    BleLightManager -->|"invokeMethod<br/>methodSetLightParams"| BleBaseManager
    BleBaseManager --> BleMethodConstants
    BleBaseManager -->|"MethodChannel 调用"| LightManager
    LightManager --> LightProcessor
    LightProcessor --> LightControlInfo
    LightManager -->|"BLE GATT 写"| LED
    LED -->|"通知上报"| LightProcessor
    LightProcessor -->|"lightInfoStream 分发"| BleEventStream
    BleEventStream -->|"监听"| LightPage
    LightPage --> LightTotalSwitchStatus

各组件职责：

分层设计的意图：BleLightManager 作为薄封装，把协议参数名（argLightState、argLightRed 等）集中定义在 BleMethodConstants 中，UI 层不直接接触方法通道细节；原生层负责 BLE 指令的协议打包与收发。这样 UI、API、协议三者的变更可以独立演进。

Flutter API 层：BleLightManager

BleLightManager 是整个灯光控制模块在 Flutter 侧的唯一对外入口，定义于 lib/manager/ble_light_manager.dart。它是一个静态工具类，只暴露一个方法 setLightParams，负责将完整的灯效状态参数打包并通过方法通道发送到原生层。

/// Light Manager
class BleLightManager {
  /// Set lighting parameters
  static Future<void> setLightParams({
    required int lightState,
    required int lightMode,
    required int red,
    required int green,
    required int blue,
    required int flashIndex,
    required int frequencyIndex,
    required int sceneIndex,
    required double hue,
    required double saturation,
    required double lightness,
  }) async {
    await BleBaseManager.invokeMethod(
      BleMethodConstants.methodSetLightParams,
      arguments: {
        BleMethodConstants.argLightState: lightState,
        BleMethodConstants.argLightMode: lightMode,
        BleMethodConstants.argLightRed: red,
        BleMethodConstants.argLightGreen: green,
        BleMethodConstants.argLightBlue: blue,
        BleMethodConstants.argLightFlashIndex: flashIndex,
        BleMethodConstants.argLightFrequencyIndex: frequencyIndex,
        BleMethodConstants.argLightSceneIndex: sceneIndex,
        BleMethodConstants.argLightHue: hue.round(),
        BleMethodConstants.argLightSaturation: saturation.round(),
        BleMethodConstants.argLightness: lightness.round(),
      },
    );
  }
}

Source: ble_light_manager.dart

设计意图解读

• 静态方法、无状态设计：灯光参数完全由调用方（UI 层）持有，BleLightManager 不缓存任何状态。这让 API 层天然线程安全、易于测试，且原生层始终收到"完整快照"而非增量补丁。
• 参数名集中管理：方法名 methodSetLightParams 与参数名 argLightState、argLightRed 等全部来自 BleMethodConstants 常量类，避免魔法字符串在 Flutter 与 Android 两侧不一致。
• double 转 int：hue、saturation、lightness 在发送前调用 .round()，因为方法通道最终以整数参数下发；RGB 本身是 int，无需转换。这反映了协议层使用整数表示 0–360 的色相与 0–100 的饱和度/明度。

参数模型

UI 层：LightPage

LightPage 是灯光控制页面的入口，定义于 example/lib/pages/light_page.dart。它是一个带 TabController 的 StatefulWidget，将控制界面划分为三个 Tab，并通过 SingleTickerProviderStateMixin 支持 Tab 动画。

/// Light total switch status
enum LightTotalSwitchStatus {
  closed,   // Closed
  open,     // Open
  unknown,  // Unknown status
}

/// Light control page
class LightPage extends StatefulWidget {
  const LightPage({super.key});

  @override
  State<LightPage> createState() => _LightPageState();
}

Source: light_page.dart

页面状态与常量

_LightPageState 持有全部灯效 UI 状态：

页面上有三个常量控制 UI 规模：_blinkPatternCount = 8（闪烁图案数量）、_scenePatternCount = 12（场景数量）、_colorWheelSize = 236.0（色轮尺寸）。

初始化与事件订阅

页面在 initState 中创建 3 个 Tab、请求设备功能信息，并订阅灯光事件流：

@override
void initState() {
  super.initState();

  // Initialize TabController with 3 tabs
  _tabController = TabController(length: 3, vsync: this);

  // Get device function common info
  BleDeviceInfoManager.getFunctionCommon();

  // Listen to light info updates
  _lightInfoSubscription = BleEventStream.lightInfoStream.listen(_handleLightDataUpdate);
}

@override
void dispose() {
  _tabController.dispose();
  _lightInfoSubscription?.cancel();
  super.dispose();
}

Source: light_page.dart

设计意图：

• TabBarView 禁用横向滑动（NeverScrollableScrollPhysics），强制用户通过 Tab 栏切换，避免在滑杆操作时误触页面切换。
• 断开自动返回：build 中通过 context.watch<ConnectionStateManager>() 监听连接状态，一旦检测到 connectionDisconnect，在帧回调中 Navigator.maybePop 自动退出页面——这是设备类页面的通用安全模式，防止对已断连设备继续发送指令。
• 事件流订阅在 dispose 中取消，避免页面销毁后内存泄漏与回调泄漏。

三个控制 Tab

页面主体由 TabBarView 承载三个子页面：

1. 灯光 Tab（_buildLightTab）：色轮选色（ColorWheel 组件）+ 色温/亮度/色彩浓度三个滑杆（DualLabelSlider 组件）+ 开关。用户操作通过 _sendLightStateMessage 合成参数下发。
2. 闪烁 Tab（_buildBlinkTab）：从 _blinkPatternCount = 8 种闪烁图案中选择，并设置闪烁频率。
3. 场景 Tab（_buildSceneTab）：从 _scenePatternCount = 12 种预设场景中选择，例如彩虹、心跳、烛火、夜灯、舞台、漫彩呼吸、漫红呼吸、漫绿呼吸、漫蓝呼吸、绿色心情、夕阳美景、音乐律动。

场景通过图片资源（Assets.images.icons.lightIcon*）与本地化文案（localizations.rainbow 等）展示，映射函数以 switch 语句将场景索引转换为图标与标签：

case 1: return ( // 心跳
imagePath: Assets.images.icons.lightIconHeartbeat2x.path,
label: localizations.heartbeat
);
case 2: return ( // 烛火
imagePath: Assets.images.icons.lightIconCandle2x.path,
label: localizations.candlelight
);

Source: light_page.dart

参数合成与下发

_sendLightStateMessage 是 UI 状态到协议参数的核心转换函数：将三个滑杆值（0–1）映射为 HSL 分量，调用 hslToRgb 得到 RGB，然后一次性调用 BleLightManager.setLightParams：

/// Send light state message to BLE device
void _sendLightStateMessage(int lightState, int lightMode) {
  final hsl = ColorHSL(
    hue: 360 * _temperatureValue,
    saturation: 100 * _brightnessValue,
    luminance: 100 * _colorfulnessValue,
  );

  final rgb = hslToRgb(hsl);

  BleLightManager.setLightParams(
    lightState: lightState,
    lightMode: lightMode,
    red: rgb.red,
    green: rgb.green,
    blue: rgb.blue,
    flashIndex: _selectedBlinkIndex,
    frequencyIndex: _selectedBlinkFlashIndex,
    sceneIndex: _selectedSceneIndex,
    hue: 360 * _temperatureValue,
    saturation: 100 * _brightnessValue,
    lightness: 100 * _colorfulnessValue,
  );
}

Source: light_page.dart

设计意图：

• 滑杆值域映射：UI 滑杆输出 0–1 归一化值，分别乘以 360（色相）与 100（饱和度/明度）转换为 HSL 空间，符合人对"色温/亮度/浓度"的直觉操作；同时保留 HSL 与 RGB 双份参数下发，让设备端可以按需使用其中一种色彩模型。
• 参数整包发送：闪烁索引、频率索引、场景索引与颜色参数在同一次调用中打包，设备端收到一条完整灯效状态即可渲染，避免了多参数分帧下发导致灯效撕裂。

ColorRGB、ColorHSL 与 rgbToHsl / hslToRgb 辅助类/函数定义在同一文件中，其中 hslToRgb 负责把 HSL 三元组转换为 0–255 的 RGB 分量（示例工程中标注为占位实现，实际产品化时需实现标准 HSL→RGB 转换算法）。

设备状态回显

_intToLightStatus 将设备上报的整数状态转换为枚举：0 表示总开关关闭、1 表示开启、2 表示设置灯光中，其他值归为 unknown。该转换用于 _handleLightDataUpdate 更新 _totalSwitchStatus，使 UI 开关状态与设备实际状态保持一致。

核心流程

用户操作 → 灯效下发

sequenceDiagram
    participant U as 用户
    participant P as LightPage (UI)
    participant M as BleLightManager
    participant B as BleBaseManager (MethodChannel)
    participant N as Android 原生 (LightManager)
    participant D as BLE 设备 LED

    U->>P: 拖动滑杆 / 切换场景 / 打开开关
    P->>P: 更新 UI 状态 (温度/亮度/浓度/索引)
    P->>P: hslToRgb 转换 (HSL→RGB)
    P->>M: setLightParams(lightState, lightMode, rgb,<br/>flashIndex, frequencyIndex, sceneIndex, hsl)
    M->>B: invokeMethod(methodSetLightParams, args)
    B->>N: MethodChannel 调用 (参数序列化)
    N->>N: 组装 BLE 指令 (LightControlInfo)
    N->>D: GATT 写入灯效指令
    D-->>N: 灯效状态通知上报
    N-->>B: 调用结果回传
    B-->>M: Future 完成
    M-->>P: await 返回
    P-->>U: UI 呈现新灯效

流程要点：UI 的任何灯效操作都收敛到 _sendLightStateMessage 这一个函数，形成「状态合成 → 整包下发 → 设备渲染」的单一闭环。setLightParams 返回的 Future<void> 在原生层处理完成后 resolve，但 UI 并不阻塞等待设备确认——设备灯效属于"尽力而为"的实时控制，不需要事务性确认。

设备状态回显流程

sequenceDiagram
    participant D as BLE 设备
    participant N as 原生 LightProcessor
    participant S as BleEventStream (lightInfoStream)
    participant P as LightPage
    participant S1 as LightTotalSwitchStatus

    D->>N: 灯光信息通知
    N->>S: 解析并分发 lightInfo 事件
    S->>P: _handleLightDataUpdate(data)
    P->>P: _intToLightStatus(value) 转换
    P->>S1: closed / open / unknown
    S1-->>P: 更新 _totalSwitchStatus
    P-->>P: setState 刷新开关 UI

使用示例

基本用法：打开灯光并设置纯色

在页面初始化或用户打开开关时，发送基础灯效（模式 0，红色）：

BleLightManager.setLightParams(
  lightState: 1,          // 1 = 开启
  lightMode: 0,           // 基础灯光模式
  red: 255,
  green: 0,
  blue: 0,
  flashIndex: 0,
  frequencyIndex: 0,
  sceneIndex: 0,
  hue: 0,                 // 红色对应色相 0
  saturation: 100,
  lightness: 50,
);

Source: ble_light_manager.dart

进阶用法：跟随滑杆实时调色

与 LightPage 相同的模式——监听滑杆变化，将 0–1 归一化值映射为 HSL 后整包下发：

void _sendLightStateMessage(int lightState, int lightMode) {
  final hsl = ColorHSL(
    hue: 360 * _temperatureValue,
    saturation: 100 * _brightnessValue,
    luminance: 100 * _colorfulnessValue,
  );

  final rgb = hslToRgb(hsl);

  BleLightManager.setLightParams(
    lightState: lightState,
    lightMode: lightMode,
    red: rgb.red,
    green: rgb.green,
    blue: rgb.blue,
    flashIndex: _selectedBlinkIndex,
    frequencyIndex: _selectedBlinkFlashIndex,
    sceneIndex: _selectedSceneIndex,
    hue: 360 * _temperatureValue,
    saturation: 100 * _brightnessValue,
    lightness: 100 * _colorfulnessValue,
  );
}

Source: light_page.dart

监听设备上报的灯光状态

页面初始化时订阅事件流，并在销毁时取消：

_lightInfoSubscription = BleEventStream.lightInfoStream.listen(_handleLightDataUpdate);
// ...
@override
void dispose() {
  _tabController.dispose();
  _lightInfoSubscription?.cancel();
  super.dispose();
}

Source: light_page.dart

API 参考

BleLightManager.setLightParams(...)

静态方法，向设备发送完整的灯效状态参数。这是 Flutter 侧灯光控制的唯一对外 API。

参数：

返回： Future<void> — 方法通道调用完成后 resolve；原生层失败时抛出平台异常。

抛出： PlatformException（由 BleBaseManager.invokeMethod 透传原生层错误）。

LightPage 关键内部方法

Android 原生层

Flutter 侧的方法通道最终由 Android 原生蓝牙 SDK 处理。本仓库中灯光相关的原生实现位于：

说明：本页写作时原生文件未被完整阅读（受本次源材料探索预算限制），上述角色划分依据文件命名与 Flutter 侧调用链推断。具体协议字节格式、GATT 特征值与错误码请直接阅读 LightManager.kt、LightProcessor.kt 与 LightControlInfo.java。

预期调用链为：BleBaseManager.invokeMethod → MethodChannel methodSetLightParams → LightManager 解析参数并构造 LightControlInfo → LightProcessor 将数据模型编码为 BLE 指令 → GATT 写入设备；设备灯效变化通过通知回调反向传入 LightProcessor，再由事件通道分发给 Flutter 的 BleEventStream.lightInfoStream。

失败模式、边界情况与并发

设备断连

• LightPage.build 通过 context.watch<ConnectionStateManager>() 监听连接状态，检测到 connectionDisconnect 时在帧回调中 Navigator.maybePop(context) 自动退出页面。
• 设计意图：防止在蓝牙已断开时继续向 setLightParams 发送指令，避免无谓的通道调用与异常弹窗。
• 边界情况：断连发生在用户拖动滑杆的过程中时，setLightParams 的 Future 可能因原生层错误而抛出 PlatformException；页面代码中 _sendLightStateMessage 未显式捕获该异常，调用方（滑杆 onChanged）需自行处理或依赖全局错误兜底。

未知设备状态

• 设备上报的总开关值不在 0/1/2 范围内时，_intToLightStatus 落入 default 分支返回 LightTotalSwitchStatus.unknown。UI 对 unknown 状态应保持上次显示或显示不确定样式，避免错误回显。
• 首次进入页面时 _totalSwitchStatus 初始为 closed，在收到设备上报前 UI 显示关闭状态——这是"乐观默认值"策略，换取启动速度。

参数边界与数值精度

• hue（0–360）、saturation/lightness（0–100）在发送前 .round() 取整。浮点精度在 0–360 区间内取整损失可忽略，但若调用方传入超出协议范围的数值（如负数或 >100），原生层校验行为以 LightManager.kt 实现为准。
• flashIndex 与 sceneIndex 的合法范围由 UI 常量约束（8 种闪烁、12 种场景），页面内不会越界；但 BleLightManager 本身不做范围校验，直接透传。

并发与节流

• BleLightManager.setLightParams 为异步方法，滑杆连续拖动会触发高频连续调用。由于每次调用都是整包状态下发，后发消息覆盖先发消息，设备端只需渲染最新状态——这避免了逐参数增量更新的竞态，但高频调用仍可能让 BLE 写入队列拥塞（BLE 写操作本身较慢）。
• 示例代码未内置防抖/节流；产品化场景建议在滑杆 onChangeEnd 时下发，或在 _sendLightStateMessage 前做节流（如 30–50ms 合并）。
• 事件流监听与 UI 更新发生在主 isolate；_handleLightDataUpdate 直接操作 setState，需保证回调在主线程执行。

性能与运维注意事项

• BLE 写吞吐限制：灯光控制本质是"尽力而为"的实时指令，单次 setLightParams 约 11 个参数，序列化后体积很小，但 GATT 写间隔受设备与链路限制。建议避免在动画循环中逐帧下发。
• 事件流生命周期：lightInfoStream 订阅必须在 dispose 中取消（页面已实现），否则页面反复进出会造成监听器累积，导致内存增长与重复 setState。
• 资源开销：场景图标使用 Assets.images.icons.lightIcon*（含 1x/2x/3x 多分辨率），首次进入场景 Tab 时会一次性加载多张图片，可考虑懒加载或缓存策略。

扩展点

• 新增场景：在 _scenePatternCount 对应的场景映射 switch 中增加 case（如 case 12），同时添加对应的 light_icon_* 资源与本地化文案即可扩展预设场景；sceneIndex 值随协议定义扩展。
• 新增闪烁图案：调整 _blinkPatternCount 并扩展闪烁图案构建逻辑（_buildBlinkTab 区域），索引与设备端协议对应。
• 自定义灯效协议：若需要新增灯效参数（如色温开尔文值、呼吸速度），在 BleMethodConstants 增加参数常量、BleLightManager.setLightParams 增加命名参数，并在 Android 原生 LightManager.kt 中同步解析。
• 复用入口：任何页面只需 import 'package:jl_home/manager/ble_light_manager.dart' 并调用 BleLightManager.setLightParams，即可在不依赖 LightPage UI 的情况下发送灯效指令（例如语音助手、自动化场景）。

测试与验证

本次探索未在仓库中发现灯光控制模块的独立单元测试文件（未匹配到 light 相关 *_test.dart）。该模块的验证主要依赖：

• 示例应用手工验证：example/lib/pages/light_page.dart 作为演示页面，通过真机连接 JL 蓝牙设备验证灯效下发与回显。
• 编译期验证：BleLightManager.setLightParams 全部参数使用 required 关键字，编译器强制调用方提供完整参数集，从类型层面保证协议参数不会遗漏。
• 事件流集成验证：_handleLightDataUpdate 的解析逻辑可通过构造模拟 lightInfoStream 事件数据在 Widget 测试中覆盖（仓库当前未提供）。

若需为模块补充测试，建议优先覆盖：_intToLightStatus 的边界值映射（0/1/2/其他）、_sendLightStateMessage 的 HSL→RGB 参数合成正确性、以及 BleLightManager 在方法通道 mock 下的参数序列化格式。

相关链接

• ble_light_manager.dart — Flutter 灯光 API
• light_page.dart — 灯光控制页面
• LightManager.kt — Android 原生灯光管理器
• LightProcessor.kt — Android 原生灯光处理器
• LightControlInfo.java — 灯光数据模型

相关文档导航：

• 蓝牙连接与断开管理、设备信息获取（BleDeviceInfoManager）属于设备连接相关页面，本文档不展开。
• 通用事件流机制（BleEventStream）与设备事件常量（BleEventConstants）请参见对应事件/通知页面。
• 其他设备功能（如音频控制、按键控制等）请参见设备功能目录下的对应兄弟页面。