ebusd MQTT 集成实战：将加热系统数据发布到物联网平台的完整指南

【免费下载链接】ebusd daemon for communication with eBUS heating systems 项目地址: https://gitcode.com/gh_mirrors/eb/ebusd

你是否想让家中的加热系统数据无缝接入智能家居平台？想要通过MQTT协议将eBUS加热系统的实时数据发布到Home Assistant或其他物联网平台？本文将为你提供一份完整的ebusd MQTT集成实战指南，帮助你轻松实现加热系统数据的物联网连接！🚀

ebusd是一个专门用于与eBUS加热系统通信的守护进程，它能够将加热系统的数据通过MQTT协议发布到物联网平台，让你可以轻松监控和控制家中的加热系统。通过MQTT集成，你可以实现温度、湿度、能耗等数据的实时监控和智能控制。

🔧 ebusd MQTT集成核心功能

ebusd的MQTT集成功能非常强大，主要包括：

• 数据发布：自动将eBUS设备的数据发布到MQTT主题
• Home Assistant自动发现：支持MQTT Discovery协议，自动在Home Assistant中创建实体
• 双向通信：支持通过MQTT向eBUS设备发送控制命令
• 灵活配置：通过配置文件自定义主题结构和数据格式
• 状态监控：实时监控ebusd运行状态和连接状态

📋 安装与配置准备

安装ebusd

首先，你需要安装ebusd。如果你的系统支持Docker，这是最简单的方式：

docker pull john30/ebusd

或者从源码编译安装：

./autogen.sh
make install-strip

注意：编译时需要安装libmosquitto-dev包来支持MQTT功能。

基本MQTT配置

启动ebusd时，需要配置MQTT连接参数：

ebusd --device=/dev/ttyUSB0 \
      --mqttport=1883 \
      --mqtthost=mqtt.local \
      --mqtttopic=ebusd/ \
      --mqttjson

关键参数说明：

• --mqtthost：MQTT代理服务器地址
• --mqttport：MQTT代理端口（默认1883）
• --mqtttopic：MQTT主题前缀
• --mqttjson：使用JSON格式发布数据

🎯 MQTT集成配置文件详解

ebusd提供了强大的配置文件系统，让你可以完全自定义MQTT集成行为。主要的配置文件位于：

• contrib/etc/ebusd/mqtt-integration.cfg - 基础MQTT集成配置
• contrib/etc/ebusd/mqtt-hassio.cfg - Home Assistant专用配置

配置文件结构

配置文件使用变量替换系统，支持丰富的占位符：

# 预定义常量
%version    # ebusd版本号
%prefix     # MQTT主题前缀
%circuit    # 电路名称
%name       # 消息名称
%field      # 字段名称
%type       # 字段类型（number、list、string等）
%unit       # 字段单位

过滤配置

你可以通过过滤器控制哪些数据被发布到MQTT：

# 只包含至少收到过一次数据的消息
filter-seen = 1

# 只包含特定方向的消息（r=读取，w=写入，u=更新）
filter-direction = r|u

# 排除特定字段
filter-non-field = ^sensor$

🏠 Home Assistant自动发现配置

ebusd的Home Assistant集成非常智能，可以自动创建传感器、开关等实体。使用mqtt-hassio.cfg配置文件：

ebusd --device=/dev/ttyUSB0 \
      --mqttport=1883 \
      --mqtthost=mqtt.local \
      --mqttjson \
      --mqttint=/etc/ebusd/mqtt-hassio.cfg

Home Assistant配置示例

Home Assistant配置文件的关键特性：

1. 自动设备发现：自动为每个eBUS电路创建设备实体
2. 智能实体分类：根据数据类型自动创建传感器、开关、选择器等
3. 单位转换：自动处理温度、湿度、功率等单位
4. 状态类支持：支持测量、总计等状态类型

# Home Assistant设备配置
circuit_part = {
   "identifiers":"%{PREFIX}_%CIRCUIT",
   "manufacturer":"ebusd.eu",
   "name":"%prefixn %circuit",
   "via_device":"%PREFIXN",
   "sw_version":"%version",
   "suggested_area":"%area"
  }

🔌 MQTT主题结构

ebusd的MQTT主题结构非常灵活，默认格式为：

ebusd/<circuit>/<message>/<field>

例如：

• ebusd/heating/temperature/actual - 实际温度
• ebusd/heating/mode/current - 当前模式
• ebusd/global/status/running - ebusd运行状态

JSON数据格式

当使用--mqttjson参数时，数据以JSON格式发布：

{
  "value": 21.5,
  "unit": "°C",
  "timestamp": 1692172800
}

⚙️ 高级配置技巧

自定义主题结构

你可以完全自定义MQTT主题结构：

# 自定义主题模板
topic = home/heating/%circuit/%name/%field

数据类型映射

ebusd支持智能数据类型映射：

# 数据类型到Home Assistant实体类型的映射
type_map-number = sensor
type_map-list = binary_sensor
type_switch-by = %name%field,%unit

条件配置

使用条件变量实现更复杂的逻辑：

# 仅当字段有单位时才包含单位信息
unit_of_measurement ?= ,
  "unit_of_measurement":"%unit"

🔄 双向通信配置

ebusd不仅支持数据发布，还支持通过MQTT接收控制命令：

# 为可写字段添加命令主题
type_part-number = ,
  "command_topic":"%topic/set"
  "min":%min
  "max":%max
  "step":%step

通过订阅<topic>/set主题，你可以向eBUS设备发送控制命令。

🚀 实战部署示例

Docker部署完整示例

# docker-compose.yaml
version: '3'
services:
  ebusd:
    image: john30/ebusd
    container_name: ebusd
    restart: unless-stopped
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    environment:
      - EBUSD_DEVICE=/dev/ttyUSB0
      - EBUSD_MQTTHOST=mqtt.local
      - EBUSD_MQTTPORT=1883
      - EBUSD_MQTTTOPIC=ebusd/
      - EBUSD_MQTTJSON=1
      - EBUSD_MQTTINT=/etc/ebusd/mqtt-hassio.cfg
    volumes:
      - ./mqtt-hassio.cfg:/etc/ebusd/mqtt-hassio.cfg

系统服务配置

创建systemd服务文件：

# /etc/systemd/system/ebusd.service
[Unit]
Description=ebusd MQTT Integration
After=network.target mosquitto.service

[Service]
Type=simple
ExecStart=/usr/local/bin/ebusd \
  --device=/dev/ttyUSB0 \
  --mqttport=1883 \
  --mqtthost=localhost \
  --mqtttopic=home/heating/ \
  --mqttjson \
  --mqttint=/etc/ebusd/mqtt-hassio.cfg

[Install]
WantedBy=multi-user.target

🔍 故障排除与调试

常见问题

1. MQTT连接失败

   • 检查MQTT代理地址和端口
   • 验证网络连接
   • 检查防火墙设置

2. 数据不显示

   • 确认eBUS设备连接正常
   • 检查过滤器配置
   • 查看ebusd日志输出

3. Home Assistant不发现设备

   • 确认MQTT Discovery已启用
   • 检查主题前缀配置
   • 验证配置文件路径

调试命令

# 查看MQTT连接状态
mosquitto_sub -t "ebusd/#" -v

# 测试ebusd连接
ebusctl info

# 查看详细日志
journalctl -u ebusd -f

📊 监控与维护

ebusd提供了丰富的状态监控功能：

• 运行状态：ebusd/global/status/running
• 版本信息：ebusd/global/status/version
• 信号强度：ebusd/global/status/signal
• 运行时间：ebusd/global/status/uptime

这些状态信息可以帮助你监控ebusd的运行状况，及时发现并解决问题。

🎉 总结

通过ebusd的MQTT集成，你可以轻松将传统的eBUS加热系统接入现代智能家居平台。无论是简单的温度监控，还是复杂的自动化控制，ebusd都提供了强大而灵活的解决方案。

关键优势：

• ✅ 开箱即用：预配置的Home Assistant集成
• ✅ 高度可定制：灵活的配置文件系统
• ✅ 双向通信：支持读取和控制
• ✅ 自动发现：减少手动配置工作
• ✅ 状态监控：完整的系统健康监控

现在就开始你的智能加热系统之旅吧！通过ebusd MQTT集成，让你的加热系统变得更加智能和高效。🔥

提示：更多详细配置选项和高级用法，请参考项目文档中的contrib/etc/ebusd/mqtt-hassio.cfg和contrib/etc/ebusd/mqtt-integration.cfg配置文件。

【免费下载链接】ebusd daemon for communication with eBUS heating systems 项目地址: https://gitcode.com/gh_mirrors/eb/ebusd