chrisns/iot-zwave

Z-Wave AWS-IOT Bridge/Gateway

镜像概述和主要用途

该镜像作为Z-Wave设备与AWS IoT服务之间的桥接器/网关，实现Z-Wave网络与AWS云平台的连接。通过AWS IoT影子（Thing Shadow）机制，可远程管理Z-Wave设备，包括发送控制器命令、监控设备状态、配置设备参数等，适用于智能家居、远程监控等场景。

核心功能和特性

• 控制器命令支持：通过AWS IoT影子发送Z-Wave控制器命令，包括secureAddNode（安全添加节点）、healNetwork（网络修复）、addNode（添加节点）、cancelControllerCommand（取消命令）、removeNode（移除节点）、softReset（软重置）等
• 设备影子管理：为每个Z-Wave设备自动创建独立的Thing Shadow，命名格式为zwave_x_n（x为homeid，n为节点ID）
• 状态与配置读写：支持读取和写入Z-Wave设备的系统信息、配置参数、用户状态及基本状态
• 多网络支持：可管理多个Z-Wave网络，适用于不同频率范围、物理位置或安全隔离需求
• Docker化部署：提供Docker镜像，简化部署流程

使用场景和适用范围

• 智能家居设备的云连接与远程控制
• Z-Wave网络设备的集中监控与管理
• 跨区域或多物理位置的Z-Wave设备统一管理
• 需要通过AWS IoT生态实现自动化的场景

详细使用方法和配置说明

前置要求

• 在AWS IoT中创建名为zwave的Thing Type（事物类型），建议添加manufacturerid、productid、producttype属性以便过滤设备

Z-Wave网络密钥生成

使用random.org随机数生成器生成16个随机十六进制数，添加0x前缀和逗号分隔。示例格式：0x97,0x81,0x18,0x90,0xd3,0x57,0xac,0x93,0xa2,0x20,0x9c,0x91,0x6d,0x83,0x17,0xcb

部署方式

Docker部署

bash
docker run \ 
    --device=/dev/ttyACM0 \
    -e DEVICE=/dev/ttyACM0 \
    -e AWS_ACCESS_KEY_ID=XXX \
    -e AWS_SECRET_ACCESS_KEY=XX \
    -e AWS_IOT_ENDPOINT_HOST=XX \
    -e AWS_REGION=eu-west-2 \
    -e ZWAVE_NETWORK_KEY=XX \
    chrisns/iot-zwave

Node.js直接运行

bash
git clone git@github.com:chrisns/iot-zwave
cd iot-zwave
npm i
DEVICE=/dev/ttyACM0 \
AWS_ACCESS_KEY_ID=XXX \
AWS_SECRET_ACCESS_KEY=XX \
AWS_IOT_ENDPOINT_HOST=XX \
AWS_REGION=eu-west-2 \
ZWAVE_NETWORK_KEY=XX \
npm start

环境变量配置说明

控制器命令使用

通过发布消息到$aws/things/zwave/shadow/update或更新事物影子，发送控制器命令：

json
{
  "state": {
    "desired": {
      "X": "Y"
    }  
  }
}

• X为命令类型：secureAddNode、healNetwork、addNode、cancelControllerCommand、removeNode、softReset
• Y为任意标识（建议使用时间戳）

命令执行后，会在事物影子或$aws/things/zwave/shadow/update中收到报告：

json
{
  "state": {
    "reported": {
      "X": "Y"
    }  
  }
}

设备状态示例

Z-Wave设备状态会通过Thing Shadow报告，示例（门窗传感器）：

json
{
  "reported": {
    "system": {
      "Powerlevel": "Normal",
      "Application Version": "1.05",
      "ZWave+ Version": 1,
      "Protocol Version": "4.05"
    },
    "config": {
      "Interval time of battery report": 0,
      "Set the low battery value": 18
    },
    "user": {
      "Battery Level": 74,
      "Sensor": true
    },
    "basic": {
      "Basic": 255
    }
  }
}

已知限制

• 对AWS IoT的调用未优化，存在过多请求，需批量处理优化
• AWS IoT影子 payload 限制为8KB，无法包含OpenZWave提供的完整元数据（如有效值说明、帮助文本等）
• 不支持超过50个Z-Wave设备（需多连接支持）

已知安全漏洞

• 应用在8888端口开放telnet接口，允许执行zwave对象作用域内的任意代码，存在安全风险。严禁将此端口暴露给非信任网络

待实现功能（TODO）

• 二进制开关切换功能（用于警报）
• 支持ARM架构镜像（适配树莓派）
• 多控制器支持，实现配置共享与切换