alxgmpr/lutron-tools
GitHub: alxgmpr/lutron-tools
Stars: 2 | Forks: 0
# Lutron Tools
Lutron 照明控制系统反向工程的工具和固件，涵盖 CCA（433 MHz RF）、CCX（Thread/802.15.4）和 LEAP（处理器 API）。基于 STM32H723 + CC1101 + nRF52840 平台并使用 TypeScript 主机工具。
支持 Phoenix、Caseta 和 Vive 产品系列。
## 背景
本项目始于 Caseta CCA 无线电，随后扩展至反向工程 Lutron Designer 二进制文件和固件镜像（来自公开可访问的文件以及从 eBay 购买的硬件）。随着时间推移，这项工作对 Lutron 的控制系统有了深入理解，并实现了以下能力：
- 作为发射器配对设备，即模仿 Pico（直接控制，无需桥接器）
- 模仿桥接器，将设备配对到我们自己的无线电和伪造的 CCA 子网
- 添加虚拟设备到项目，允许与其他设备进行低延迟桥接（我曾用此将 RGB+CCT WiZ WiFi 灯泡变成假的 Ketra 灯泡）
- 混合设备家族（RA3 <-> HomeWorks QSX），并“教导”设备与其他家族配对
- 在配对期间欺骗设备以允许更多 x-家族配对
- 实时配置设备和扩展参数，如淡入淡出速率、延迟、校准配置和状态 LED 配置
- 解码 Vive、Caseta、RA2 Select 和 Phoenix（RA3/QSX/Athena/XC）固件
- 这包括从 FCC 内部照片备案中定位测试焊盘引脚图。焊接后加载用原始汇编编写的自定义 SPL，以从 eMMC 提取数据。随后更新 SPL 以 surgically 将 `#` 替换为 `\n`，从而通过 UART 串口控制台获得 root 访问权限
- Phoenix 和 Caseta/RA2 Select 桥接固件中的 root 漏洞利用
- 解锁设备限制，更改设备类型
## 关键概念
- CCA = QS Link over radio = 8N1 数据包 + TDMA 槽位。Seq + 6 = 75ms 时间差。Seq + 1 = 12.5ms。
- CCX = 2.4 GHz Thread + CBOR 编码 + CoAP 端口。代号 Pegasus。凭证可从 LEAP 或 Designer 数据库中提取
- Phoenix = RadioRA3、HomeWorks QSX、Athena、myRoomXc。Designer 项目决定功能。固件在此家族中完全一致
- Sunnata 变体是相同硬件：RRST = HRST = ARST。RA3 调光器无需修改即可配对到 HWQS。唯一区别是产品标签
- Lutron Designer = .NET 应用 + LocalDB。项目文件是数据库的唯一可信源
## 硬件
```
CC1101 (433 MHz CCA) ──┐ ┌── UART shell (ST-LINK VCP)
├── STM32H723 Nucleo (FreeRTOS) ─┤
nRF52840 (Thread CCX) ──┘ Ethernet, UDP :9433 └── Stream → CLI (cli/nucleo.ts)
```
该开发板搭载两个无线电：用于 CCA（433 MHz FSK）的 CC1101 和用于 CCX（Thread/802.15.4 在 2.4 GHz）的 nRF52840 NCP。主机 CLI 通过 UDP 连接以显示数据包、协议解码和命令调度。
这在架构上与 Lutron 的生产桥接器类似。Caseta/Vive/RA2 Select 使用带一个或两个 CC110L 无线电的 STM32L100，以及用于 CCX 的 EFR32。
## 协议覆盖
| 层级 | 传输 | 描述 |
| ---- | ---- | ---- |
| **CCA** | 433 MHz 2-FSK，CC1101 | 调光控制、Pico 遥控器、配对、状态报告 |
| **CCX** | 802.15.4 Thread，nRF52840 | Sunnata/Darter 多播级别/场景、单播 CoAP 编程 |
| **LEAP** | TLS 双向认证 JSON | 用于区域/设备/层级、状态和配置的处理器 API |
## 快速开始
```
git clone https://github.com/alxgmpr/lutron-tools.git && cd lutron-tools
npm install
cp config.example.json config.json # configure processor IPs and cert paths
# 连接到 Nucleo
npx tsx cli/nucleo.ts
# 一次性命令
npx tsx tools/nucleo-cmd.ts "ccx coap get rloc:4800 fw/it/md"
npx tsx tools/nucleo-cmd.ts "cca button 001D94EF on"
# LEAP
npx tsx tools/leap-dump.ts --save
```
## 固件
```
cd firmware
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake
make -C build -j8
make flash # OpenOCD + ST-LINK
make test # C++ unit tests
```
需要 `arm-none-eabi-gcc`、CMake 和 OpenOCD。
## CLI
交互式 TUI（`cli/nucleo.ts`）显示解码的数据包、分发 CCA/CCX 命令并支持录制。
```
ccx coap get rloc:4800 fw/it/md # CoAP GET with CBOR decode
ccx coap scan 4800 cg/db/ct/c/AA # Scan bucket names A-Z
ccx coap trim rloc:4800 95.0 1.0 # Set dimmer trim
ccx level 3663 50 # Multicast level to zone
cca button 001D94EF on # CCA button press
status # Radio/network status
```
## 工具
| 工具 | 用途 |
| ---- | ---- |
| `cli/nucleo.ts` | 交互式 TUI — 数据包显示、命令、CoAP 探索器 |
| `tools/nucleo-cmd.ts` | 可脚本化的一次性 Nucleo 命令 |
| `tools/coap-probe.ts` | 扫描所有 CCX 设备的 CoAP 端点 |
| `tools/coap-fuzz.ts` | 快速 CoAP 路径模糊测试器 |
| `tools/leap-dump.ts` | 转储 LEAP 设备/区域层级 |
| `tools/leap-cmd.ts` | LEAP 区域控制（亮度、开/关、升高、降低） |
| `tools/ccx-sniffer.ts` | Thread 流量嗅探器 |
| `tools/ccx-send.ts` | 发送 CCX 多播命令 |
| `tools/codegen.ts` | 从 TypeScript 协议定义生成 C 头文件 |
| `tools/thread-decrypt.ts` | 解密 802.15.4 帧 |
| `tools/rtlsdr-cca-decode.ts` | 从 RTL-SDR 捕获中解码 CCA |
| `tools/dll-patcher/` | .NET DLL 补丁器 — Designer 的通用解锁 |
| `tools/designer-project.ts` | 解析 Lutron Designer `.hw`/`.ra3` 项目文件 |
| `bridge/` | CCX→WiZ 桥接（HA 插件）— Thread 嗅探到 WiZ UDP |
## 文档
协议研究和反向工程发现位于 `docs/`。请参阅 [docs/index.md](docs/index.md) 获取完整目录。
## 配置
主机地址、证书路径和 Designer 虚拟机凭证保存在 `config.json`（已忽略在 git 中）：
```
{
"processors": {
"10.x.x.x": {
"cert": "lutron-ra3-cert.pem",
"key": "lutron-ra3-key.pem",
"ca": "lutron-ra3-ca.pem"
}
},
"openBridge": "10.x.x.x",
"designer": { "host": "10.x.x.x", "user": "user", "pass": "pass" }
}
```
处理器类型（RA3 / HomeWorks QSX / Caseta）会从 LEAP 的 `/server` ProtocolVersion 自动检测。LEAP 工具需要双向 TLS 证书（`lutron-{name}-{cert,key,ca}.pem` 在项目根目录）。
线程凭证来自 LEAP 转储数据（`data/leap-*.json`），而非静态配置 — 使用 `npx tsx tools/leap-dump.ts --save` 从处理器中提取。
## 前期工作
- Entropy512 的 Lutron RF 参数与数据包结构研究：[github.com/Entropy512/lutron_hacks](https://github.com/Entropy512/lutron_hacks)
- Ceady 的无线接口文档：[hackaday.io/project/2291](https://hackaday.io/project/2291-integrated-room-sunrise-simulator/log/7223-the-wireless-interface)
## 后续工作
- 原生 Vive 跨兼容性。自定义桥接器已在应用层处理此问题，但原生配对需要对 Caseta NCP 刷入 Vive（链路类型 30）CCA 而非 Caseta/HWQS（类型 9/11）。目前仅有 MRF2/MRF2S 设备原生配对成功。
- 强化 `LeapConnection`（`tools/leap-client.ts`）以支持长时间运行：周期性 `/server/1/status/ping` 心跳 + 断开后自动重连、批量 `/zone/status` 和 `/area/status` 订阅（而非每个区域单独订阅）、类型化的错误类（`BridgeResponseError`、`BridgeDisconnectedError`）、UUID ClientTags。可借鉴 [gurumitts/pylutron-caseta](https://github.com/gurumitts/pylutron-caseta) 的模式。这对 CCX→WiZ 桥接器尤为重要，因为该桥接器目前缺乏 LEAP 端的心跳监控。
- 移植一个 LEAP 配对助手（从 `pylutron-caseta/pairing.py` 移植 8083 端口 CSR 流程），以便工具可以注册自己的客户端证书，而无需从 Designer VM 复制出来。
- Fork `pylutron-caseta` 以添加 RA3/HWQS 场景支持（`/areascene` + `/preset/{id}/presetassignment` 用于目标亮度）、时间钟/事件暴露，以及可选的 CCX 线程凭证提取 — 这能让 Home Assistant 显示场景并为 RA3 处理器提供桥接配对。
## 许可证
研究与教育用途。不与 Lutron Electronics 有关联。
## 背景
本项目始于 Caseta CCA 无线电，随后扩展至反向工程 Lutron Designer 二进制文件和固件镜像（来自公开可访问的文件以及从 eBay 购买的硬件）。随着时间推移，这项工作对 Lutron 的控制系统有了深入理解，并实现了以下能力：
- 作为发射器配对设备，即模仿 Pico（直接控制，无需桥接器）
- 模仿桥接器，将设备配对到我们自己的无线电和伪造的 CCA 子网
- 添加虚拟设备到项目，允许与其他设备进行低延迟桥接（我曾用此将 RGB+CCT WiZ WiFi 灯泡变成假的 Ketra 灯泡）
- 混合设备家族（RA3 <-> HomeWorks QSX），并“教导”设备与其他家族配对
- 在配对期间欺骗设备以允许更多 x-家族配对
- 实时配置设备和扩展参数，如淡入淡出速率、延迟、校准配置和状态 LED 配置
- 解码 Vive、Caseta、RA2 Select 和 Phoenix（RA3/QSX/Athena/XC）固件
- 这包括从 FCC 内部照片备案中定位测试焊盘引脚图。焊接后加载用原始汇编编写的自定义 SPL，以从 eMMC 提取数据。随后更新 SPL 以 surgically 将 `#` 替换为 `\n`，从而通过 UART 串口控制台获得 root 访问权限
- Phoenix 和 Caseta/RA2 Select 桥接固件中的 root 漏洞利用
- 解锁设备限制，更改设备类型
## 关键概念
- CCA = QS Link over radio = 8N1 数据包 + TDMA 槽位。Seq + 6 = 75ms 时间差。Seq + 1 = 12.5ms。
- CCX = 2.4 GHz Thread + CBOR 编码 + CoAP 端口。代号 Pegasus。凭证可从 LEAP 或 Designer 数据库中提取
- Phoenix = RadioRA3、HomeWorks QSX、Athena、myRoomXc。Designer 项目决定功能。固件在此家族中完全一致
- Sunnata 变体是相同硬件：RRST = HRST = ARST。RA3 调光器无需修改即可配对到 HWQS。唯一区别是产品标签
- Lutron Designer = .NET 应用 + LocalDB。项目文件是数据库的唯一可信源
## 硬件
```
CC1101 (433 MHz CCA) ──┐ ┌── UART shell (ST-LINK VCP)
├── STM32H723 Nucleo (FreeRTOS) ─┤
nRF52840 (Thread CCX) ──┘ Ethernet, UDP :9433 └── Stream → CLI (cli/nucleo.ts)
```
该开发板搭载两个无线电：用于 CCA（433 MHz FSK）的 CC1101 和用于 CCX（Thread/802.15.4 在 2.4 GHz）的 nRF52840 NCP。主机 CLI 通过 UDP 连接以显示数据包、协议解码和命令调度。
这在架构上与 Lutron 的生产桥接器类似。Caseta/Vive/RA2 Select 使用带一个或两个 CC110L 无线电的 STM32L100，以及用于 CCX 的 EFR32。
## 协议覆盖
| 层级 | 传输 | 描述 |
| ---- | ---- | ---- |
| **CCA** | 433 MHz 2-FSK，CC1101 | 调光控制、Pico 遥控器、配对、状态报告 |
| **CCX** | 802.15.4 Thread，nRF52840 | Sunnata/Darter 多播级别/场景、单播 CoAP 编程 |
| **LEAP** | TLS 双向认证 JSON | 用于区域/设备/层级、状态和配置的处理器 API |
## 快速开始
```
git clone https://github.com/alxgmpr/lutron-tools.git && cd lutron-tools
npm install
cp config.example.json config.json # configure processor IPs and cert paths
# 连接到 Nucleo
npx tsx cli/nucleo.ts
# 一次性命令
npx tsx tools/nucleo-cmd.ts "ccx coap get rloc:4800 fw/it/md"
npx tsx tools/nucleo-cmd.ts "cca button 001D94EF on"
# LEAP
npx tsx tools/leap-dump.ts --save
```
## 固件
```
cd firmware
cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi.cmake
make -C build -j8
make flash # OpenOCD + ST-LINK
make test # C++ unit tests
```
需要 `arm-none-eabi-gcc`、CMake 和 OpenOCD。
## CLI
交互式 TUI（`cli/nucleo.ts`）显示解码的数据包、分发 CCA/CCX 命令并支持录制。
```
ccx coap get rloc:4800 fw/it/md # CoAP GET with CBOR decode
ccx coap scan 4800 cg/db/ct/c/AA # Scan bucket names A-Z
ccx coap trim rloc:4800 95.0 1.0 # Set dimmer trim
ccx level 3663 50 # Multicast level to zone
cca button 001D94EF on # CCA button press
status # Radio/network status
```
## 工具
| 工具 | 用途 |
| ---- | ---- |
| `cli/nucleo.ts` | 交互式 TUI — 数据包显示、命令、CoAP 探索器 |
| `tools/nucleo-cmd.ts` | 可脚本化的一次性 Nucleo 命令 |
| `tools/coap-probe.ts` | 扫描所有 CCX 设备的 CoAP 端点 |
| `tools/coap-fuzz.ts` | 快速 CoAP 路径模糊测试器 |
| `tools/leap-dump.ts` | 转储 LEAP 设备/区域层级 |
| `tools/leap-cmd.ts` | LEAP 区域控制（亮度、开/关、升高、降低） |
| `tools/ccx-sniffer.ts` | Thread 流量嗅探器 |
| `tools/ccx-send.ts` | 发送 CCX 多播命令 |
| `tools/codegen.ts` | 从 TypeScript 协议定义生成 C 头文件 |
| `tools/thread-decrypt.ts` | 解密 802.15.4 帧 |
| `tools/rtlsdr-cca-decode.ts` | 从 RTL-SDR 捕获中解码 CCA |
| `tools/dll-patcher/` | .NET DLL 补丁器 — Designer 的通用解锁 |
| `tools/designer-project.ts` | 解析 Lutron Designer `.hw`/`.ra3` 项目文件 |
| `bridge/` | CCX→WiZ 桥接（HA 插件）— Thread 嗅探到 WiZ UDP |
## 文档
协议研究和反向工程发现位于 `docs/`。请参阅 [docs/index.md](docs/index.md) 获取完整目录。
## 配置
主机地址、证书路径和 Designer 虚拟机凭证保存在 `config.json`（已忽略在 git 中）：
```
{
"processors": {
"10.x.x.x": {
"cert": "lutron-ra3-cert.pem",
"key": "lutron-ra3-key.pem",
"ca": "lutron-ra3-ca.pem"
}
},
"openBridge": "10.x.x.x",
"designer": { "host": "10.x.x.x", "user": "user", "pass": "pass" }
}
```
处理器类型（RA3 / HomeWorks QSX / Caseta）会从 LEAP 的 `/server` ProtocolVersion 自动检测。LEAP 工具需要双向 TLS 证书（`lutron-{name}-{cert,key,ca}.pem` 在项目根目录）。
线程凭证来自 LEAP 转储数据（`data/leap-*.json`），而非静态配置 — 使用 `npx tsx tools/leap-dump.ts --save` 从处理器中提取。
## 前期工作
- Entropy512 的 Lutron RF 参数与数据包结构研究：[github.com/Entropy512/lutron_hacks](https://github.com/Entropy512/lutron_hacks)
- Ceady 的无线接口文档：[hackaday.io/project/2291](https://hackaday.io/project/2291-integrated-room-sunrise-simulator/log/7223-the-wireless-interface)
## 后续工作
- 原生 Vive 跨兼容性。自定义桥接器已在应用层处理此问题，但原生配对需要对 Caseta NCP 刷入 Vive（链路类型 30）CCA 而非 Caseta/HWQS（类型 9/11）。目前仅有 MRF2/MRF2S 设备原生配对成功。
- 强化 `LeapConnection`（`tools/leap-client.ts`）以支持长时间运行：周期性 `/server/1/status/ping` 心跳 + 断开后自动重连、批量 `/zone/status` 和 `/area/status` 订阅（而非每个区域单独订阅）、类型化的错误类（`BridgeResponseError`、`BridgeDisconnectedError`）、UUID ClientTags。可借鉴 [gurumitts/pylutron-caseta](https://github.com/gurumitts/pylutron-caseta) 的模式。这对 CCX→WiZ 桥接器尤为重要，因为该桥接器目前缺乏 LEAP 端的心跳监控。
- 移植一个 LEAP 配对助手（从 `pylutron-caseta/pairing.py` 移植 8083 端口 CSR 流程），以便工具可以注册自己的客户端证书，而无需从 Designer VM 复制出来。
- Fork `pylutron-caseta` 以添加 RA3/HWQS 场景支持（`/areascene` + `/preset/{id}/presetassignment` 用于目标亮度）、时间钟/事件暴露，以及可选的 CCX 线程凭证提取 — 这能让 Home Assistant 显示场景并为 RA3 处理器提供桥接配对。
## 许可证
研究与教育用途。不与 Lutron Electronics 有关联。标签：433 MHz, 802.15.4, Caseta, CC1101, CCA, CCX, eMMC, FCC, LEAP, Lutron, nRF52840, Phoenix, Root 权限, SPL, STM32H723, Thread, TypeScript, UART, Vive, 中继桥接, 主机工具, 参数配置, 固件分析, 固件解码, 固件逆向, 安全插件, 射频通信, 引导加载程序, 无线电协议, 根访问, 测试点, 照明控制, 硬件黑客, 自动化攻击, 虚拟设备, 设备伪造, 设备配对, 跨家族配对