theengs/gateway

Theengs Gateway

概述

Theengs Gateway 是一个多平台、多设备的蓝牙低功耗（BLE）转 MQTT 网关，基于 https://github.com/theengs/decoder 开发。它能够从多种 BLE 传感器（如 LYWSD03MMC、CGD1、RuuviTag、MiScale、MiFlora 等）获取数据，将其转换为可读的 JSON 格式，并推送至 MQTT 代理（broker），支持与多种物联网平台和家庭自动化控制器集成。

!https://github.com/theengs/home/raw/development/docs/img/Theengs-gateway-raspberry-pi.jpg

核心功能和特性

• 跨平台支持：兼容 Raspberry Pi、Windows、Apple 桌面/笔记本电脑及服务器，通过 Python 和多平台库利用设备蓝牙组件
• 多传感器兼容：支持 Govee、小米、Inkbird、QingPing、ThermoBeacon、ClearGrass、Blue Maestro 等品牌的多种 BLE 传感器，包括 LYWSD03MMC、CGD1、CGP1W、H5072、RuuviTag、WS02、MiScale、MiFlora 等型号
• 数据转换与推送：使用 Theengs Decoder 库解析 BLE 数据，转换为结构化 JSON 格式并推送至 MQTT broker
• 兼容性：与 OpenMQTTGateway 兼容，采用相同的 MQTT 主题结构和 payload 消息，可作为其补充解决方案
• 灵活配置：支持主动/被动扫描模式、Home Assistant 自动发现、自定义 MQTT 主题、日志级别调整等多种配置选项

使用场景

• 物联网平台集成：与 NodeRED、AWS IoT 等物联网平台对接，实现传感器数据的集中管理和分析
• 家庭自动化系统：支持 Home Assistant、OpenHAB、FHEM、IOBroker、DomoticZ 等家庭自动化控制器，实现环境监测与自动化控制
• 独立部署：作为独立的 BLE 数据采集网关，为各类 BLE 传感器提供数据接入能力
• 补充方案：扩展 OpenMQTTGateway 的功能，提升 BLE 传感器兼容性和数据处理能力

使用方法

Docker 基本运行示例

以下是使用最小化参数运行 Theengs Gateway 的示例，仅需指定 MQTT 代理地址：

shell
docker run --rm \
    --network host \
    -e MQTT_HOST=<host_ip> \
    -v /var/run/dbus:/var/run/dbus \
    --name TheengsGateway \
    theengs/gateway

Docker 完整参数运行示例

包含详细配置参数的运行示例：

shell
docker run --rm \
    --network host \
    -e MQTT_HOST=<host_ip> \
    -e MQTT_USERNAME=<username> \
    -e MQTT_PASSWORD=<password> \
    -e MQTT_PUB_TOPIC=home/TheengsGateway/BTtoMQTT \
    -e MQTT_SUB_TOPIC=home/TheengsGateway/commands \
    -e PUBLISH_ALL=true \
    -e TIME_BETWEEN=60 \
    -e SCAN_TIME=60 \
    -e LOG_LEVEL=DEBUG \
    -e HASS_DISCOVERY=true \
    -e DISCOVERY=true \
    -e DISCOVERY_TOPIC=homeassistant/sensor \
    -e DISCOVERY_DEVICE_NAME=TheengsGateway \
    -e DISCOVERY_FILTER="[IBEACON,GAEN,MS-CDP]" \
    -e SCANNING_MODE=active \
    -e ADAPTER=hci0 \
    -e TIME_SYNC="[]" \
    -e TIME_FORMAT=0 \
    -e BINDKEYS='{"00:11:22:33:44:55:66":"0dc540f3025b474b9ef1085e051b1add","AA:BB:CC:DD:EE:FF":"6385424e1b0341109942ad2a6bb42e58"}' \
    -e ENABLE_TLS=false \
    -e ENABLE_WEBSOCKET=false \
    -e IDENTITIES='{"00:11:22:33:44:55:66":"sensor_1","AA:BB:CC:DD:EE:FF":"sensor_2"}' \
    -v /var/run/dbus:/var/run/dbus \
    --name TheengsGateway \
    theengs/gateway

Docker Compose 示例

yaml
version: '3'
services:
  theengs-gateway:
    image: theengs/gateway
    network_mode: host
    environment:
      - MQTT_HOST=<host_ip>
      - MQTT_USERNAME=<username>
      - MQTT_PASSWORD=<password>
      - MQTT_PUB_TOPIC=home/TheengsGateway/BTtoMQTT
      - SCAN_TIME=60
      - LOG_LEVEL=INFO
      - HASS_DISCOVERY=true
      - ADAPTER=hci0
    volumes:
      - /var/run/dbus:/var/run/dbus
    restart: unless-stopped
    name: TheengsGateway

配置参数说明