Lunar 4.6.1 版本解读:DIY 无线环境光传感器接入与稳定性修复
Lunar 4.6.1 版本解读:DIY 无线环境光传感器接入与稳定性修复
本文围绕 Lunar 4.6.1 版本的官方发布说明(ReleaseNotes/4.6.1.md),逐项拆解新特性、改进与修复内容,并结合本仓库源码说明其实现方式:读者将理解 Lunar 如何通过 ESPHome 固件支持 DIY 无线环境光传感器(Ambient Light Sensor),了解 Paddle 框架升级带来的 default.profraw 问题修复,以及 4.6.1 针对热键缓存、睡眠唤醒亮度等稳定性问题所做的修复及其背后的代码逻辑。
4.6.1 更新总览
4.6.1 是一个典型的"小步快跑"稳定性版本,更新被划分为三个板块:
- Features(新特性):支持 DIY 无线环境光传感器,官方教程已接近完成;
- Improvements(改进):更新 Paddle 框架,修复 CLI 每次运行时产生
default.profraw文件的问题;在主窗口的 Lunar Logo 下方显示当前版本号; - Fixes(修复):修复热键缓存线程不安全导致的崩溃、nil 变量访问崩溃、睡眠唤醒后亮度被置为最大值的问题,以及使用
x按钮清除热键时热键未被注销的问题。
其中"DIY 无线环境光传感器"是本次更新中体量最大、最具技术含量的一项功能,对应的工程产物全部落在仓库的 Lunar/ALS 目录下,下文将以其为主线展开。
新特性:DIY 无线环境光传感器
环境光传感器是 Lunar 的 Sensor Mode(传感器模式)依赖的硬件基础:它实时采集环境照度(lux),Lunar 据此在白天、夜晚等不同光照条件下自动调节外接显示器亮度。4.6.1 起,用户不再需要购买成品传感器,而是可以按照官方教程,自己选购开发板与照度传感器芯片,烧录仓库内置的固件模板,搭建一套"无线"(通过 WiFi 上报数据)环境光传感器。
说明:发布说明中提到官方教程已接近完成,并提示周期性关注官方发布页获取更新。本仓库中与传感器直接相关的配置模板、安装脚本与安装界面源码均已就绪,可作为 DIY 实践的第一手参考。
支持的传感器芯片
仓库的 Lunar/ALS 目录为 6 种主流 I²C 环境光传感器分别提供了 ESPHome 配置片段,并在 ALSInstallViewController.swift 中通过 AmbientLightSensor 枚举与之一一对应:
| 传感器芯片 | 配置片段 | 特点 |
|---|---|---|
| TSL2591 | tsl2591.yaml | 高动态范围,支持红外与全光谱通道,gain: auto 自动增益 |
| TSL2561 | tsl2561.yaml | 经典照度计芯片,可在固件内动态切换增益与积分时间 |
| BH1750 | bh1750.yaml | 数字照度计,接入最简单 |
| MAX44009 | max44009.yaml | 超低功耗,mode: auto 自动量程 |
| LTR390 | ltr390.yaml | 同时提供 UV 与可见光通道 |
| TCS34725 | tcs34725.yaml | 带 RGB 颜色传感器,可输出色温与照度 |
配套的驱动库(Adafruit 系列)以 MicroPython 或 Python 形式存放在 Lunar/ALS/lib 目录中,例如 adafruit_tsl2591.mpy、adafruit_tcs34725.mpy 等。
传感器配置片段解析(以 TSL2591 为例)
每个 *.yaml 文件都是 ESPHome 配置中 sensor: 段落的一个片段,最终会被拼接进主模板。以 tsl2591.yaml 为例:
- platform: tsl2591
name: "Ambient Light TSL2591"
gain: auto
integration_time: 200ms
update_interval: 1s
infrared:
name: "TSL2591 Infrared Light"
full_spectrum:
name: "TSL2591 Full Spectrum Light"
calculated_lux:
id: ambient_light
name: "Ambient Light"
filters:
- filter_out: 65535
- filter_out: nan
- sliding_window_moving_average:
window_size: 15
send_every: 2
send_first_at: 2
其中几个关键配置点值得注意:
id: ambient_light:这是 Lunar 主程序识别照度值的统一标识,所有传感器配置片段都保持该 id 一致,保证上层逻辑无需区分具体芯片;filter_out: 65535与filter_out: nan:剔除传感器原始读数溢出(65535 为 AD 饱和值)与非法值,避免把脏数据上报给 Lunar;sliding_window_moving_average:滑动窗口均值滤波,window_size: 15表示取最近 15 次采样求平均,send_every: 2、send_first_at: 2控制上报节奏,让亮度曲线更平滑。
而 tsl2561.yaml 则展示了另一类做法:通过 on_raw_value 触发器在固件内根据原始读数动态调整增益(TSL2561_GAIN_1X / TSL2561_GAIN_16X)和积分时间(14ms / 101ms / 402ms),实现宽动态范围的自动量程切换。
固件主模板 lunar.yaml
仓库的 lunar.yaml 是完整的 ESPHome 固件主模板,DIY 传感器的基础能力都由它定义:
substitutions:
ssid: Wifi
password: password
board: board
platform: platform
platform_version: platform_version
sda: sda
scl: scl
esphome:
name: lunarsensor
platform: $platform
board: $board
libraries:
- "SPI"
- "Adafruit Unified Sensor@^1.1.6"
- "Adafruit BusIO@^1.13.2"
- "Adafruit TSL2591 Library@^1.4.3"
platformio_options:
platform: $platform_version
lib_ldf_mode: "chain+"
wifi:
ssid: $ssid
password: $password
ap:
ssid: "Lunar Sensor Hotspot"
password: "lunarals23"
captive_portal:
logger:
level: INFO
api:
reboot_timeout: 0s
ota:
sensor:
SENSOR_DEFINITION
i2c:
sda: $sda
scl: $scl
scan: False
id: bus_a
web_server:
port: 80
模板的要点包括:
substitutions占位机制:ssid、password、board、platform、platform_version、sda、scl全部由安装时通过esphome -s参数注入,用户无需手工编辑 YAML;name: lunarsensor:设备固定命名为lunarsensor,因此主机名默认就是lunarsensor.local(见下文 Lunar 对接部分);- WiFi 兜底:
ap段配置了名为Lunar Sensor Hotspot的回退热点(密码lunarals23),配合captive_portal,在 WiFi 连接失败时可临时配置网络; sensor: SENSOR_DEFINITION:这一行是拼接点,安装脚本会把所选传感器芯片的配置片段替换进来;web_server: port 80:传感器板同时提供 Web 服务端口,Lunar 主程序可通过 HTTP 读取传感器数据;ota:开放 OTA 升级能力,固件后续可无线更新。
一键烧录:install.sh 与图形化安装
仓库的 install.sh 是实际的固件编译与烧录脚本,其核心流程为:
- 将
lunar.yaml中的SENSOR_DEFINITION占位符替换为所选传感器的配置片段(通过 Python 字符串替换实现); - 根据板卡类型(
BOARD变量)确定默认的 I²C 引脚SDA/SCL——例如esp32dev默认SDA=19、SCL=23,ESP8266 系列(nodemcuv2、d1_mini等)则切换平台到platformio/espressif8266@4.2.1并使用D2/D1; - 通过
pip安装 Lunar 定制的 ESPHome 分支(alin23/esphome.git@lunar); - 以
esphome run lunar.yaml --device <串口>完成编译、上传,全程日志写入/tmp/lunar-sensor-install.log。
macOS 应用侧则由 ALSInstallViewController.swift 提供图形化安装界面:它负责枚举可用串口设备(通过 Glob 匹配 /dev/cu.usb*,并额外用 ping 探测 lunarsensor.local)、让用户选择开发板与传感器型号,然后以环境变量的形式把 WIFI_SSID、WIFI_PASSWORD、BOARD、SENSOR、SDA、SCL、ESP_DEVICE 传给 install.sh 执行,并在安装过程中实时回读日志的最后几行展示给用户。安装成功后,界面会提示:只要 WiFi 凭据正确,Lunar 检测到局域网内的传感器后会自动切换到 Sensor Mode。
与 Lunar 主程序的对接
传感器板通过 WiFi 接入局域网后,Lunar 通过以下设置项与其通信(定义于 DataStore.swift):
| 设置项 | 说明 |
|---|---|
sensorHostname |
传感器主机名,默认 lunarsensor.local(见 AdvancedSettingsView.swift) |
sensorPort |
传感器服务端口 |
sensorPathPrefix |
读取数据的 URL 路径前缀 |
sensorPollingSeconds |
轮询间隔(秒) |
也就是说,传感器侧通过 web_server 暴露读数,Mac 侧的 Lunar 按 sensorPollingSeconds 周期轮询 sensorHostname 获取环境照度,再交由 Sensor Mode 计算目标亮度。整套链路是"ESP32/ESP8266 开发板 + I²C 照度芯片 + ESPHome 固件 → WiFi → HTTP → Lunar",端到端均可由用户 DIY。
改进项
Paddle 框架升级:不再每次运行 CLI 都生成 default.profraw
default.profraw 是 LLVM 编译器插桩(coverage/sanitizer)产生的原始覆盖率数据文件。在旧版 Paddle(Lunar 使用的更新/许可框架)下,每次运行 CLI 都会在工作目录留下一个 default.profraw,既污染目录又干扰版本控制。4.6.1 更新 Paddle 框架后,该问题被修复——这一条目同时记录在 CHANGELOG.md 与 Releases/appcast.xml 的 4.6.1 发布条目中。
主窗口显示当前版本号
作为配套改进,4.6.1 在主窗口的 Lunar Logo 下方直接显示当前应用版本号,方便用户确认自己所处的版本、判断是否需要升级,也便于在反馈问题时快速定位版本信息。
稳定性修复解析
热键缓存线程不安全导致的崩溃
4.6.1 修复了"因为热键缓存线程不安全导致的崩溃"。热键系统是 Lunar 的核心交互之一,其数据结构集中在 Hotkeys.swift,包括 PersistentHotkey(持久化热键)、HotkeyIdentifier(热键枚举)、以及 Magnet.HotKey 底层注册。从源码结构看,热键的注册/注销、启停与持久化读写分布在多个入口,若缓存层未加同步保护,在多线程回调中并发访问就可能触发崩溃。4.6.1 对该缓存做了线程安全化处理,从根上消除了这一类崩溃。
访问 nil 变量的崩溃
修复了因访问 nil 变量导致的崩溃。这类问题在 Swift/Objective-C 混编的 App 中常见于可选值强解包或异步回调中对象已释放的场景;该修复降低了用户在使用过程中的偶发闪退概率。
睡眠唤醒后亮度被置为最大值
这是影响体验最直观的一个修复:此前某些场景下 Mac 从睡眠唤醒后,外接显示器亮度会被置为最大值。仓库 AppDelegate.swift 中的 reapplyAfterWake() 逻辑展示了这类问题的防御性处理:Lunar 监听 NSWorkspace.screensDidWakeNotification 等唤醒通知(见 AppDelegate.swift),唤醒后读取显示器当前亮度并与 lastNativeBrightness 比对,若发现亮度与睡眠前不一致(尤其是被系统重置为 1.0 满亮度),则重新写回睡眠前的亮度值。4.6.1 正是围绕这一环节修复了亮度在唤醒后失控被拉满的问题。
使用 x 按钮清除热键后未注销
修复了在热键配置界面点击 x 按钮清除某个热键后,该热键仍保持注册、按键仍会触发动作的问题。正确的清除流程应当同时更新持久化配置并调用底层注销,4.6.1 补上了这一环节,避免"看似删除了热键、实际仍然生效"的困惑。
升级方式
Lunar 使用 Sparkle 框架进行自动更新,发布清单见 Releases/appcast.xml(其中 4.6.1 条目完整包含了本节解析的三段更新内容)。普通用户通常无需手动操作,应用会自动检测并安装新版本;升级后即可使用 DIY 无线环境光传感器相关的安装入口(应用内的传感器安装界面),并享受到热键、唤醒亮度等稳定性修复。对于希望自行编译或深入研究的开发者,本仓库中的 Lunar/ALS 目录提供了完整的固件模板、传感器配置与安装脚本,是理解这套传感器方案的最佳起点。
前提说明:本文所述功能与源码均以当前仓库 4.6.1 版本为准;DIY 传感器教程由官方发布页维护,仓库内的配置与脚本即为其工程实现。