33 极物科技 | Control4 对接 - A8 按键面板驱动

极物科技 | Control4 对接 - A8 按键面板驱动

前言

在智能控制领域，"协议壁垒"与"系统稳定性"始终是绕不开的难题。极物科技（Zeewo）以 "重构空间交互体验" 为使命，通过自研的 极物 OS，实现了 KNX、DALI、CAN、RS485 等多种总线协议在单一主机上的深度融合。

我们认为，一个真正优秀的智能系统，不仅要实现灯光、遮阳、温控、音乐、安防等全生态设备的无界融合 ，更要确保本地运行、断网可用 ，并具备WEB 远程调试 和 OTA 固件升级的能力。基于此底层架构，我们推出了诸如带双路 DALI 的 KNX 主机、HomeKit 网桥等核心硬件，并将极物 OS 成功接入了 Apple HomeKit、小度、纯血鸿蒙及 HomeAssistant 等主流生态系统。

一句话概述：本文详细解析极物网关 A8 按键面板驱动的 Control4 DriverWorks 实现，涵盖 8 路按键事件处理、RS485 通讯协议、Proxy 代理机制及场景联动。

本文聚焦于 极物 A8 按键面板驱动的完整实现，从 8 路按键结构体、RS485 通讯协议、Proxy 代理机制到场景联动，逐一深入剖析，并提供完整代码供 C4 集成商参考。

开源代码：本系列文档对应的 Control4 对接驱动代码已完全开源，访问 Gitee 仓库获取完整源码：https://gitee.com/fujianxinxi/aolebahe.git

1. 驱动概述

1.1 驱动定位

A8 按键面板驱动是 Control4 系统中直接面向终端用户的输入设备驱动，负责：

接收 C4 Composer 或场景的控制指令
处理 8 路按键事件（按下、释放、长按）
通过 RS485 总线与极物网关通讯
支持场景联动和自定义动作

1.2 驱动文件结构

复制代码

Aolebach-A8-Keypad/
├── driver.xml              # 驱动元数据与配置定义
├── driver.lua              # 驱动主逻辑（入口、命令路由、Proxy 分发）
├── rs485.lua               # RS485 协议封装
├── proxy.lua               # Proxy 代理逻辑
├── action.lua              # 动作处理
├── const.lua               # 常量定义（Proxy ID、设备结构体）
├── documentation.rtf       # 驱动文档说明
└── Aolebach-A8-Keypad.c4zproj  # C4 Composer 工程文件

1.3 通讯参数

参数	规格
通讯方式	RS485 总线
网关 Proxy ID	1（RS485_GATE_WAY_PROXY_ID）
按键 Proxy ID	5001（A8_KEYPAD_PROXY_ID）
按键编号	101 ~ 108（A8_BUTTON_1 ~ A8_BUTTON_8）
设备地址	RS485 总线地址
按键数量	8 路

2. 驱动配置（driver.xml）

xml 复制代码

<devicedata>
  <manufacturer>Aolebach</manufacturer>
  <name>奥乐巴赫 A8 按键面板</name>
  <model>A8 Keypad Module</model>
  <version>2025011309</version>
  <control>lua_gen</control>
  <driver>DriverWorks</driver>

  <proxies>
    <proxy>Aolebach-A8-Keypad-Module</proxy>
  </proxies>

  <config>
    <properties>
      <property>
        <name>设备地址</name>
        <type>RANGED_INTEGER</type>
        <readonly>false</readonly>
        <default>0</default>
      </property>
      <property>
        <name>Debug Mode</name>
        <type>LIST</type>
        <items>
          <item>Off</item>
          <item>Print</item>
          <item>Log</item>
          <item>Print and Log</item>
        </items>
        <default>Off</default>
      </property>
    </properties>
  </config>
</devicedata>

3. 常量定义（const.lua）

lua 复制代码

-- 代理
RS485_GATE_WAY_PROXY_ID = 1
A8_KEYPAD_PROXY_ID = 5001

A8_BUTTON_BASE = 100
A8_BUTTON_1 = 101
A8_BUTTON_2 = 102
A8_BUTTON_3 = 103
A8_BUTTON_4 = 104
A8_BUTTON_5 = 105
A8_BUTTON_6 = 106
A8_BUTTON_7 = 107
A8_BUTTON_8 = 108

-- 按键事件
RELEASE_BUTTON = 0
PRESS_BUTTON = 1
LONG_PRESS_BUTTON = 2

4. 驱动核心实现

4.1 设备结构体

lua 复制代码

require "utils"
require "ao_timer"
require "rs485"
require "proxy"
require "const"
require "action"

local g_rs485_proxy_bound_status = false

-- A8 按键面板设备结构体
local g_a8_keypad_device = {
    address = 0,
    button = {
        {sub_id = 1, status = "release"},
        {sub_id = 2, status = "release"},
        {sub_id = 3, status = "release"},
        {sub_id = 4, status = "release"},
        {sub_id = 5, status = "release"},
        {sub_id = 6, status = "release"},
        {sub_id = 7, status = "release"},
        {sub_id = 8, status = "release"}
    }
}

4.2 属性变更回调

lua 复制代码

function OnPropertyChanged(strProperty)
    local value = Properties[strProperty]
    if (value == nil) then
        value = ''
    end

    if (strProperty == '设备地址') then
        g_a8_keypad_device.address = tonumber(value)
    end

    Print_table("g_a8_keypad_device", g_a8_keypad_device)
end

4.3 延迟初始化

lua 复制代码

function OnDriverLateInit(dit)
    for property, _ in pairs(Properties) do
        OnPropertyChanged(property)
    end

    gTestTimer = AddTimer(gTestTimer, 3)

    LUMI_CMD.GET_CONNECTED_STATE(RS485_GATE_WAY_PROXY_ID, nil, nil)
end

4.4 Proxy 绑定变更

lua 复制代码

function OnBindingChanged(idBinding, class, bIsBound)
    dbg("OnBindingChanged(), idBinding = " .. tostring(idBinding) .. ", class = " .. class .. ", bIsBound = " ..
            tostring(bIsBound))
    if (idBinding == RS485_GATE_WAY_PROXY_ID) then
        g_rs485_proxy_bound_status = bIsBound
    end
end

4.5 命令路由

lua 复制代码

function ExecuteCommand(strCommand, tParams)
    Print_table("strCommand", strCommand)
    Print_table("tParams", tParams)
    if (strCommand == "LUA_ACTION") then
        lua_normal_action(tParams, g_a8_keypad_device)
    else
        lua_special_action(strCommand, tParams, g_a8_keypad_device)
    end
end

4.6 Proxy 分发

lua 复制代码

function ReceivedFromProxy(idBinding, strCommand, tParams)
    if (idBinding == RS485_GATE_WAY_PROXY_ID) then
        -- 网关下发的状态更新
        proxy_info_update_by_gateway(g_a8_keypad_device, strCommand, tParams)
    elseif (idBinding == A8_KEYPAD_PROXY_ID) then
        -- 按键控制
        proxy_keypad_control(g_a8_keypad_device, strCommand, tParams)
    end
end

5. 按键事件处理

5.1 按键事件类型

lua 复制代码

-- 按键动作
RELEASE_BUTTON = 0      -- 释放
PRESS_BUTTON = 1        -- 按下
LONG_PRESS_BUTTON = 2   -- 长按

5.2 按键事件处理流程

复制代码

用户操作按键
       ↓
A8 面板通过 RS485 发送按键事件
       ↓
极物网关接收并转发
       ↓
C4 驱动 ReceivedFromProxy(RS485_GATE_WAY_PROXY_ID)
       ↓
proxy_info_update_by_gateway() 解析按键事件
       ↓
触发对应 Proxy 事件（A8_BUTTON_1 ~ A8_BUTTON_8）

6. 场景联动

6.1 场景配置

A8 按键面板支持通过 C4 Composer 配置场景联动：

短按触发指定场景
长按触发另一场景
支持多键组合触发复杂场景

6.2 动作处理（action.lua）

lua 复制代码

function lua_normal_action(tParams, device)
    for cmd, cmdv in pairs(tParams) do
        if cmd == "ACTION" then
            if cmdv == "BUTTON_1_PRESS" then
                -- 按键 1 按下动作
            elseif cmdv == "BUTTON_1_RELEASE" then
                -- 按键 1 释放动作
            elseif cmdv == "BUTTON_1_LONG_PRESS" then
                -- 按键 1 长按动作
            -- ... 其他按键类似
            end
        end
    end
end

7. 注意事项

⚠️ 设备地址配置

设备地址需与网关中配置的 RS485 地址一致

每个 RS485 设备有唯一的地址
⚠️ 按键事件

支持 8 路按键输入

每路按键支持按下、释放、长按三种事件

按键事件通过 Proxy 转发到 C4 Composer
⚠️ RS485 总线

RS485 总线需正确接线（A+、B-）

总线终端需加 120Ω 匹配电阻

8. 相关文档

《极物科技 | Control4 对接 - 系统架构与驱动开发概述》
《极物科技 | Control4 对接 - RS485 网关驱动》
《极物科技 | Control4 对接 - 窗帘驱动》

关于极物科技（ZEEWO）

极物科技（Zeewo）致力于为用户提供智能控制系统及硬件产品。我们以总线系统为技术底座，以**"稳定、可靠、快速响应"**为产品底线，是国内少有的拥有 KNX、DALI 全套软硬件自主研发能力的厂商之一。

我们的核心能力：

系统架构：自研极物 OS，支持多协议无界融合（KNX/DALI/CAN/RS485/IP）。
核心硬件：带双路 DALI 的 KNX 主机、超薄全金属定制面板、各类智选传感器及网关。
生态互联：深度融入 Apple HomeKit、Matter、小度、HomeAssistant 及纯血鸿蒙生态。
调试交付：独家支持 ETS 导出 XML 直接导入进行 APP 免编程调试，支持远程 WEB 运维。

我们的市场覆盖：

服务网点已覆盖全国核心城市（含长三角、珠三角、成渝等），并以高品质的方案深耕家居生活、酒店民宿、企业办公、疗愈康养、餐馆会所等多个细分领域。

(如果您在开发或落地中遇到技术问题，欢迎通过官网或后台私信与我交流探讨)