如何把Bambuddy接入Home Assistant：MQTT传感器与Prometheus指标集成完整指南-平芜编程栈

如何把Bambuddy接入Home Assistant：MQTT传感器与Prometheus指标集成完整指南

【免费下载链接】bambuddyYour Bambu Lab. No Cloud. Your Rules. Self-hosted command center for Bambu Lab — from one A1 to an entire print farm.项目地址: https://gitcode.com/gh_mirrors/ba/bambuddy

Bambuddy 是一个完全自托管的 Bambu Lab 打印机指挥中心（Self-hosted command center），从一台 A1 到整个打印农场都能管理。通过内置的Home Assistant 集成、MQTT 事件推送和Prometheus /metrics 指标端点，三套机制可以把它无缝接入你的智能家居和监控体系：HA 传感器双向联动、MQTT Broker 事件订阅、Prometheus 抓取温度与进度数据。本文带你完成 Bambuddy 接入 Home Assistant 的全部实战配置，全程 15 分钟。

一、为什么值得把 Bambuddy 接入 Home Assistant 🏠

集成方式	能力	典型场景
HA 实体读取	绑定`binary_sensor.`/`sensor.`，15 秒轮询	机箱门磁、环境温湿度显示与告警
HA 实体控制	绑定`switch`/`light`等实体	打印开始自动通电、完成自动断电
MQTT Relay	事件推送到外部 Broker	Node-RED / HA 自动化、打印农场看板
Prometheus`/metrics`	标准指标格式暴露	Grafana 面板、温度与队列告警

核心源码位置：

HA REST API 客户端：backend/app/services/homeassistant.py
HA 传感器轮询与告警引擎：backend/app/services/ha_sensor_manager.py
MQTT 事件推送服务：backend/app/services/mqtt_relay.py
Prometheus 指标端点：backend/app/api/routes/metrics.py

二、快速配置：为 Bambuddy 填入 Home Assistant 地址与令牌 ⚙️

在 Home Assistant 中：个人资料 → 安全 → 创建长期访问令牌（Long-Lived Access Token）。
打开 Bambuddy 的设置 → 网络 → Home Assistant，填入两项：
- ha_url：HA 地址，例如http://192.168.1.100:8123
- ha_token：刚才创建的令牌
点击测试连接，成功即返回 "Connected"。

💡 也支持通过环境变量HA_URL与HA_TOKEN注入配置，适合 Docker 部署。相关字段定义见 backend/app/schemas/settings.py。

HA 地址必须通过安全校验（homeassistant.py 的 _validate_url 会拦截内网元数据地址等危险目标），令牌校验失败会明确提示 "Invalid access token"，方便排查。

三、绑定 Home Assistant 传感器：门磁、温湿度上打印机卡片 🌡️

进入打印机卡片 → HA 传感器，从下拉框选择要绑定的 HA 实体（Bambuddy 会列出全部binary_sensor.*和带数值的sensor.*，实体来源接口为 ha_sensors.py）。每个传感器支持三类配置：

告警规则：数值型用alert_above/alert_below阈值，开关型用alert_state（如门磁的on）。
打印联锁（block_print）：传感器告警时自动暂停调度该打印机的队列任务，传感器恢复后立即自动放行——专为机箱门未关闭的场景设计。
告警通知（notify_on_alert）：仅在状态跳入告警时通知一次，持续告警不会刷屏。

轮询器每 15 秒读取一次所有绑定的实体（ha_sensor_manager.py），页面直接读缓存，不会给 HA 造成额外压力。更稳的设计是降级策略：HA 不可达时传感器视为"无意见"，不误报、不误挡队列，门磁断线不会卡死你的打印任务。

四、用 Home Assistant 控制智能插座与用电监测 💡

在设置 → 智能插座中，把插座的实体来源选为 Home Assistant，即可从实体列表直接选择switch.*/light.*/input_boolean.*/script.*（过滤逻辑见 homeassistant.py 的 list_entities）。

更进一步，插座还支持绑定能量传感器：Bambuddy 会列出 HA 中单位是 W/kWh 的sensor.*实体（list_sensor_entities），填入功率、今日能耗、总能耗三个实体后，打印机用电成本统计就有了实时数据来源。

五、接入自己的 MQTT Broker：事件推送与自动化 📡

打开设置 → MQTT，填入 Broker 地址（默认端口 1883，TLS 8883）、可选的用户名/密码与主题前缀（默认bambuddy）。字段说明见 settings.py 的 mqtt_* 字段。

连接成功后，Bambuddy 会把以下事件以 JSON 发布到 Broker（完整实现见 mqtt_relay.py）：

Topic 模式	含义
`{prefix}/status`	Bambuddy 在线/离线（保留消息）
`{prefix}/printers/{序列号}/status`	完整状态：进度、温度、层高（每秒最多 1 条节流）
`{prefix}/printers/{序列号}/print/startedcompletedfailed`	打印开始/完成/失败
`{prefix}/printers/{序列号}/plate_clear`	取件等待门（保留消息）
`{prefix}/printers/{序列号}/ams/changed`、`error`	AMS 换料、HMS 错误
`{prefix}/queue/job_addedjob_startedjob_completed`	队列任务流转
`{prefix}/maintenance/alert`、`{prefix}/filament/low`	保养提醒、耗材低量

在 Home Assistant 里用MQTT Discovery或手动建 MQTT 传感器订阅bambuddy/printers/+/status，即可把打印状态变成原生 HA 实体，实现"打印完成 → 开灯提醒 / 发手机通知"等自动化。

六、Prometheus /metrics：用 Grafana 监控温度与队列 📊

设置 → 监控中开启prometheus_enabled，建议同时设置prometheus_token（启用后需带Bearer令牌访问，端点未开启时返回 404）。
在 Prometheus 中增加抓取目标（示例仅 4 行）：
- job：bambuddy
- metrics_path：/metrics
- authorization credentials：你设置的令牌

Bambuddy 按 Prometheus 文本格式输出 20+ 项指标（构造逻辑见 metrics.py），常用的有：

实时状态：bambuddy_printer_connected、bambuddy_printer_state、bambuddy_print_progress、bambuddy_print_remaining_seconds、bambuddy_print_layer_current/total
温度与风扇：bambuddy_nozzle_temp_celsius、bambuddy_bed_temp_celsius、bambuddy_chamber_temp_celsius、bambuddy_fan_speed_percent
统计与队列：bambuddy_prints_total、bambuddy_filament_used_grams、bambuddy_print_time_seconds、bambuddy_queue_pending/printing、bambuddy_printers_connected

配合 Grafana 就能做出打印农场大屏：每台机器的温度曲线、队列堆积、故障率一目了然。

七、常见问题排查清单 ✅

现象	原因与处理
测试连接提示 Invalid access token	令牌过期或复制不完整，重新创建长期令牌
实体下拉框是空的	检查`ha_url`是否可达；控制类实体仅接受 switch/light/input_boolean/script 四类
传感器卡片长期空白	HA 不可达会显示为"不可读"，检查网络；恢复后 15 秒内自动回填
MQTT 已启用但没收到消息	确认 Broker 端口、主题前缀一致，查看 Bambuddy 日志中`MQTT relay connected`
`/metrics`返回 404	未在设置中开启`prometheus_enabled`

写在最后

至此，Bambuddy 的三条自动化通道已全部打通：HA 传感器负责本地联动与打印联锁，MQTT Relay负责事件级自动化，Prometheus负责历史数据与大盘监控。三者共用同一份设备状态源，互不冲突，可以按需组合——哪怕只开一项，你的 Bambu Lab 打印农场就已经纳入了统一的家庭智能体系。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考