Light 灯光模块 · 知识库
本知识库由 4 个 Explore Agent 并行调研 + 源码对抗验证产出（2026-07-12），4 个 Agent 全部成功。 Light 是 5 个车控模块中最复杂的（氛围灯系统极其精巧），故氛围灯单独成篇（03）。
模块定位
Light 模块（settingsPage/micarLightSettings，包名 com.android.micar.settings.light）是「灯光」设置页，入口 LightsSettingsFragment（继承 AudioControlSettingsFragment）。
两大功能域：
- 外部灯（
miauto.lights包）：大灯模式/雾灯/位置灯/远光自适应/转向灯自动取消/迎宾灯/阅读灯/按键背光 - 氛围灯（跨
miauto.lights+miauto.display+micar.settings.display三包，历史命名混乱）：总开关/模式/颜色/主题/双拼色/亮度/呼吸/律动/迎宾联动/夜间减弱/照脚灯
核心特色：右栏车模灯光可视化（LightsRightFragment 继承 BaseScrollModelRightFragment）——左滚联动右栏换图 + 氛围灯颜色遮罩 + 呼吸/Lottie 律动动画。
关键认知（对抗验证纠正）
| 常见误解 | 源码真相 |
|---|---|
| 车型差异靠 sourceSet 分目录 | ✅ 本模块无 dcddif/xcddif/global 目录，差异完全靠运行时配置字（同 VehicleBody） |
| 「迎宾灯」是一个功能 | ✅ 三态歧义：WELCOME_LIGHT(外灯 Tab/昆仑 Switch) + WELCOME_LIGHT_SWITCH(氛围灯迎宾联动)，分属两组 |
| 音乐律动 app 监听音频 | ✅ app 端无 AudioManager/MediaController，车端硬件做音频分析，上报 MUSIC_RHYTHM_STATE + ATMOSPHERE_COLOR_IN_RHYTHM(专辑封面色)，app 仅消费做车模预览 |
| 26A 是随机代号 | ✅ 26A = Modena-26A 双层氛围灯车型（isDualLayerAtmosphereLightEnable，DEVICE_KEPLER） |
| 灯光状态用实际灯泡信号 | ✅ 右栏车模用仪表 Warning 信号（POSITION/LOW/HIGH/FOG_BEAM_STATUS），注释明示「单泡故障不应影响设置项展示」 |
READING_LEAM 正确 | ❌ 拼写错误（应为 LAMP）；BEAM_AUTOADJUST 命名误导（值=氛围灯模式） |
车型代号映射（破译，来自 DeviceUtil）
| DeviceUtil 常量 | 平台 | 灯光相关 |
|---|---|---|
DEVICE_KUNLUN | KunLun（昆仑） | 迎宾灯用 Switch（OFF/BRIEF），非 Tab |
DEVICE_WATT | Modena | 不显示照脚灯 |
DEVICE_HERTZ | Modena-U | 不显示照脚灯 |
DEVICE_KEPLER | Modena-26A / Modena-27A 出海 | 双层氛围灯（26A 组） |
DEVICE_FARADAY | Modena-27B 出海 | — |
DEVICE_SUIREN | Lemans Base | — |
文档导航
| 文档 | 内容 |
|---|---|
| 01-代码结构与子系统 | 入口 Fragment、XML 25 项全表、16 Controller 逐解、右栏车模机制 |
| 02-信号梳理 | 45 个 LightCtrl 信号穷举、7 子域分组、Controller→信号映射、枚举值 |
| 03-氛围灯系统专题 | 三层架构、双拼色同步精巧设计、256 色色盘、音乐律动真相 |
| 04-功能差异与对抗验证 | 25 功能、12 车型差异规则、配置字、3 套不可用原因、对抗记录 |
关键文件索引
| 类型 | 路径 |
|---|---|
| 入口 Fragment | micarLightSettings/.../lights/LightsSettingsFragment.java |
| 主 XML | .../res/xml/miauto_lights_settings_fragment.xml |
| 右栏 Fragment | .../lights/LightsRightFragment.kt（车模可视化） |
| 右栏 Controller | .../vehicle/LightsRightFragmentController.kt |
| 氛围灯 ViewModel | .../display/livedata/AtmosphereData.java（6 个 LiveData 总线） |
| 双拼色中枢 | .../display/ColorPickManager.kt（object 单例） |
| 跨进程同步 | .../display/AtmosphereLightSyncReceiver.kt |
| 可见性 Helper | .../common/LightPreferenceVisibleStatusHelper.java |
| 信号映射 | .../common/LightsVehiclePropertysMap.java |
| 信号域定义 | base/settingsBaseLib/.../vehicle/MiCarPropertyIds.java（LightCtrl 21-122 行） |