Domoticz dzVents脚本系统详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01139/article/details/148575448

Domoticz dzVents脚本系统详解

domoticz Open source Home Automation System 项目地址: https://gitcode.com/gh_mirrors/do/domoticz

概述

dzVents（Domoticz Easy Events）是Domoticz智能家居系统中的新一代Lua脚本引擎，它极大地简化了Domoticz自动化脚本的编写过程。通过提供简洁的API和强大的事件触发机制，dzVents让用户能够更轻松地控制智能家居设备，实现复杂的自动化场景。

dzVents核心优势

简化的API设计：封装了Domoticz底层复杂的数据结构，提供直观的设备控制接口
高效的事件处理：优化了设备信息获取机制，大幅提升脚本执行效率
灵活的定时规则：支持复杂的定时条件，满足各种场景需求
完整的状态访问：可以获取系统中所有设备、场景、变量的当前状态
100%兼容Lua：保留Lua语言的全部特性，便于已有脚本迁移

环境配置

要启用dzVents功能，需要进行以下配置：

在Domoticz设置中启用dzVents：
- 进入"设置 > 其他"
- 在"事件系统"部分确保"禁用dzVents"选项未勾选
安全设置调整：
- 进入"设置 > 系统 > 本地网络"
- 允许127.0.0.1（IPv4）和::1（IPv6）无需密码访问
位置信息设置：
- 进入"设置 > 系统 > 位置"
- 设置正确的地理位置，以确保昼夜状态判断准确

脚本创建方式

dzVents脚本可以通过两种方式创建：

文件系统方式：
- 在Domoticz服务器上的/path/to/domoticz/scripts/dzVents/scripts/目录下创建.lua文件
- 文件扩展名必须为.lua
- 遵循dzVents脚本结构规范
Web编辑器方式：
- 进入"设置 > 更多选项 > 事件"
- 点击"+"按钮，选择dzVents类型
- 从模板中选择合适的脚本模板
- 注意：脚本名称不需要加.lua扩展名

重要提示：文件系统脚本和Web编辑器脚本共享相同的命名空间。如果存在同名脚本，文件系统脚本将优先执行。

脚本结构详解

一个标准的dzVents脚本采用模块化结构，返回一个包含特定键的Lua表：

return {
    active = true,  -- 可选，控制脚本是否激活
    on = {         -- 事件触发器配置
        devices = {"开关名称"},
        timer = {"every hour"}
    },
    data = {},     -- 可选，脚本持久化数据
    logging = {},  -- 可选，日志配置
    execute = function(domoticz, device, triggerInfo)
        -- 脚本主逻辑
    end
}

主要组成部分

active字段（可选）：
- 布尔值或函数，控制脚本是否激活
- 默认值为true（激活）
- 可以是一个返回布尔值的函数，实现动态激活控制
on字段（必需）：
- 定义脚本的触发条件
- 支持多种触发器类型，可以组合使用
data字段（可选）：
- 用于脚本数据的持久化存储
- 数据在脚本执行间保持
logging字段（可选）：
- 控制脚本的日志行为
- 可以设置日志级别等参数
execute函数（必需）：
- 脚本的主逻辑实现
- 接收domoticz对象和触发信息作为参数

触发器类型详解

dzVents支持多种触发器类型，满足不同场景需求：

1. 设备触发器 (devices)

当指定设备状态变化时触发脚本：

on = {
    devices = {
        "客厅灯", 
        "卧室*",  -- 支持通配符
        123,      -- 设备IDX
        ["厨房传感器"] = {"at 18:*", "at 07:* on mon,tue"} -- 带时间条件
    }
}

2. 定时触发器 (timer)

基于时间的触发规则，支持复杂的时间表达式：

on = {
    timer = {
        "every hour",                      -- 每小时
        "every minute at nighttime",       -- 夜间每分钟
        "at 19:45 on mon,wed,fri",        -- 特定时间
        "between 30 minutes before sunset and sunrise" -- 日出日落相关
    }
}

3. 场景触发器 (scenes)

当指定场景被激活时触发：

on = {
    scenes = {"回家模式", "离家模式"}
}

4. 组触发器 (groups)

当组内设备状态变化时触发：

on = {
    groups = {"一楼灯光", "安防设备"}
}

5. 变量触发器 (variables)

当用户变量值变化时触发：

on = {
    variables = {"温度阈值", "模式设置"}
}

6. 安全系统触发器 (security)

当安全系统状态变化时触发：

on = {
    security = {domoticz.SECURITY_ARMEDAWAY, domoticz.SECURITY_DISARMED}
}

7. 系统事件触发器 (system)

响应Domoticz系统事件：

on = {
    system = {"start", "stop", "dailyBackupFinished"}
}

8. 自定义事件触发器 (customEvents)

通过API、MQTT或内部命令触发：

on = {
    customEvents = {"传感器警报", "远程指令"}
}

9. HTTP响应触发器 (httpResponses)

处理异步HTTP请求的响应：

on = {
    httpResponses = {"天气查询"}
}

10. Shell命令响应触发器 (shellCommandResponses)

处理异步Shell命令执行结果：

on = {
    shellCommandResponses = {"磁盘检查"}
}

快速入门示例

以下是一个简单的dzVents脚本示例，当指定开关状态变化时记录日志：

return {
    on = {
        devices = {"客厅主灯"}
    },
    execute = function(domoticz, device)
        if device.state == "On" then
            domoticz.log("客厅主灯已打开", domoticz.LOG_INFO)
        else
            domoticz.log("客厅主灯已关闭", domoticz.LOG_INFO)
        end
    end
}