alxgmpr/lutron-tools
GitHub: alxgmpr/lutron-protocols
逆向工程 Lutron 智能照明系统多种通信协议的固件分析与硬件工具集，实现跨产品线设备互联与自定义控制。
Stars: 6 | Forks: 1
# 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 有关联。标签：StruQ, 协议逆向分析, 射频通信, 嵌入式系统, 智能家居, 物联网, 硬件黑客, 自动化攻击