物联网后端前端【免费下载链接】ValetudoCloud replacement for vacuum robots enabling local-only operation项目地址https://gitcode.com/gh_mirrors/va/Valetudo点击查看免费下载本文是一份以 Valetudo 官方 Home Assistant 集成文档docs/pages/integrations/home-assistant-integration.md为核心的实战指南。文章将带你走完「部署 Mosquitto 代理 → 配置 MQTT → 触发自动发现 → 搭建仪表盘 → 通过mqtt.publish实现指定区域/分段清扫」的完整链路并辅以 Valetudo 后端源码MQTT 控制器、Hass 控制器、MQTT Handle 映射与前端交互实现作为底层佐证。读完本文你将掌握如何让 Valetudo 机器人在 Home Assistant 中自动生成实体、如何在 Lovelace 中展示地图以及如何构造任意功能的 MQTT 命令负载。连接架构概览MQTT 自动发现对绝大多数用户而言Valetudo 最常用的主控平台就是 Home AssistantHA。两者之间不通过云端、不通过厂商 App而是通过局域网内的MQTT Broker完成全部通信Valetudo 作为 MQTT 客户端把机器人状态、能力句柄与事件发布到 BrokerHome Assistant 订阅这些主题并依靠MQTT AutodiscoveryMQTT 自动发现自动为每个能力注册对应的实体实体 Entity因此整个集成的先决条件只有一个你的局域网里有一个可用的 MQTT Broker。从源码看这一流程由 backend/lib/mqtt/MqttController.js 统一驱动控制器负责建立与 Broker 的连接含 TLS、认证、遗嘱消息在连接成功后依次完成 Homie 属性发布与 Home Assistant 自动发现配置this.client.on(connect, () { ... await this.robotHandle.configure(); if (this.currentConfig.interfaces.homeassistant.enabled) { await this.hassController.configure(); } ... });其中interfaces.homeassistant.enabled是自动发现的开关默认在 backend/lib/res/default_config.json 中即为开启状态homeassistant: { enabled: true }。为什么推荐 Mosquitto文档明确指出Mosquitto 是 MQTT Broker 的首选理由很实际几乎所有主流 Linux 发行版都自带它可以容器化部署Docker如果你运行的是 HAOSHome Assistant 的专用设备系统可以直接安装为 HAOS Add-On资源占用几乎可以忽略不计——即使你只是为 Valetudo 跑它也完全不用担心性能问题。当然正如文档调侃的那样智能家居是一条“非常滑的斜坡”Broker 很快就会承担起更多职责。无论用哪种方式部署 Mosquitto部署完成后的操作都非常简单让 Home Assistant 和 Valetudo 指向同一个 BrokerValetudo 的设备与实体就会“自动魔法般”出现在 Home Assistant 中。设备没有出现怎么办如果设备没有自动出现文档给出的排查顺序是查看Home Assistant 的日志查看Broker 的日志查看Valetudo 的日志。绝大多数情况下问题都出在网络连通性或Broker 的 ACL访问控制列表配置上。另外请特别留意MQTT Autodiscovery不会在 Home Assistant 中产生“发现新设备”的通知——新设备会“默默地”直接出现在实体列表中别因为没看到通知而误以为集成失败。在 Valetudo 中配置 MQTT 连接在 Home Assistant 与 Valetudo 指向同一 Broker 之前需要先在 Valetudo 侧完成 MQTT 配置。入口在 Valetudo Web 界面Connectivity → MQTT connectivity。这一页同时会展示 Valetudo 当前使用的 Base Topic 与 Identifier是后续构造命令主题的基础。结合 backend/lib/res/default_config.json 与 backend/lib/mqtt/MqttController.js 的loadConfig()/getMqttOptions()实现MQTT 配置的核心字段如下配置项默认值说明mqtt.enabledfalseMQTT 总开关集成前必须先打开mqtt.connection.hostfoobar.exampleBroker 地址需改为你 Mosquitto 的实际 IP/主机名mqtt.connection.port1883Broker 端口mqtt.connection.tls.enabledfalse是否启用mqtts://TLS 加密连接mqtt.connection.tls.caCA 证书内容mqtt.connection.tls.ignoreCertificateErrorsfalse为true时等价于客户端rejectUnauthorized falsemqtt.connection.authentication.credentials关闭用户名/密码认证username/passwordmqtt.connection.authentication.clientCertificate关闭客户端证书认证certificate/keymqtt.identity.identifier空自动生成设备标识构成主题的IDENTIFIER段默认取系统可读 IDmqtt.customizations.topicPrefixvaletudo主题前缀构成主题的TOPIC PREFIX段mqtt.interfaces.homie.enabledtrueHomie 约定属性发布供 Homie 兼容客户端发现mqtt.interfaces.homeassistant.enabledtrueHome Assistant 自动发现开关mqtt.interfaces.homeassistant.cleanAutoconfOnShutdownfalse关闭时是否清理 HA 自动发现配置主题mqtt.optionalExposedCapabilities[]可选暴露的能力句柄列表默认仅暴露基础能力源码层面值得注意的细节连接时客户端 ID 为valetudo_系统可读ID并设置 3 秒重连周期与clean: false保证 Wi-Fi 不稳定时 QoS 1/2 命令不丢失连接建立时会向状态主题发布遗嘱消息Will状态主题为TOPIC PREFIX/IDENTIFIER/$state断线时 Broker 会代发lostHome Assistant 据此将设备标记为不可用控制器内置 30 秒的自动刷新refreshInterval 30 * 1000周期性重发各 Handle 的最新值对收到的保留retained命令消息会直接丢弃并输出警告——因为命令本应是非保留的一次性消息详见MqttController.js中message事件处理逻辑。自动发现原理设备、实体与组件的生成开启自动发现后HA 端会出现一个厂商为 Valetudo、型号为「厂商 型号名」的设备。设备元数据由 backend/lib/mqtt/homeassistant/HassController.js 的getAutoconfDeviceBoilerplate()生成return { manufacturer: Valetudo, model: ${this.robot.getManufacturer()} ${this.robot.getModelName()}, name: this.friendlyName, identifiers: [this.identifier], sw_version: Tools.GET_VALETUDO_VERSION(), configuration_url: http://${Tools.GET_ZEROCONF_HOSTNAME()} };同时以valetudo_identifier作为 Object ID 注册各类组件。根据 MQTT 参考文档中的「Home Assistant components index」Valetudo 会按能力动态注册以下类型的组件vacuum.mqtt机器人本体启动、停止、暂停、回充、定位、风速、按段清扫sensor.mqtt电量、消耗品、统计、Wi-Fi、地图分段、事件、Dock 组件状态等switch.mqtt地毯模式、避障开关、儿童锁等select.mqtt吸力档位、水量档位、清扫模式、地毯传感器模式button.mqtt触发集尘、播放定位音、重置消耗品number.mqtt扬声器音量binary_sensor.mqtt尘盒/拖布/水箱附件安装状态camera.mqtt地图画面map-data-hass。以机器人本体组件为例backend/lib/mqtt/homeassistant/components/VacuumHassComponent.js 会依据机器人实际具备的能力动态填充supported_featuresstatus/start/stop/pause/return_home/locate/fan_speed并在具备地图分段能力时自动注册clean_segments_command_topic与对应的命令模板。值得注意的是HA 实体的状态变化几乎全部经由HassAnchor机制与 MQTT Handle 的主题解耦绑定所有组件不直接与MqttController通信而是统一经过HassController发布源码注释中明确要求只有以 Controller 结尾的类才能直接发布。这也解释了为什么“配置改变 → 实体自动更新”在 Valetudo 中是即时且自洽的。构建 Lovelace 仪表盘图标集与地图卡片设备与实体自动出现后就可以开始搭建仪表盘了。文档给出了两件配套工具Valetudo 图标集hass-valetudo如果你希望在仪表盘上使用 Valetudo 风格的图标可以安装对应的图标集资源仓库中即包含大量能力/预设图标可参考 assets/icons 目录下的 SVG 资源。Valetudo Map Cardlovelace-valetudo-map-card用于在 HA 仪表盘中显示机器人地图。安装与配置步骤请参考官方文档站hass.valetudo.cloud中的指引。地图卡片的数据来源是 MQTT 的MapData节点当启用 HA 自动发现时Valetudo 会自动添加map-data-hass属性把地图渲染为 PNG 图片并通过camera.mqtt组件呈现同时会提示建议安装 Valetudo Lovelace 卡片以获得更好的交互体验。如果你需要原始地图数据做深度二次开发可以订阅MapData/map-dataJSON 格式、deflate 压缩与MapData/segments分段 ID 到名称的 JSON 映射。与 Valetudo 交互实体操作与 mqtt.publish基础交互直接使用自动发现的实体日常大部分操作都可以直接通过自动发现的实体完成无需写任何自动化代码观察状态电量、清扫状态、消耗品剩余、错误等开关设置项地毯模式、避障、儿童锁触发集尘Auto Empty Dock启动全局清扫、回充、定位等。高级交互用mqtt.publish发送命令对于更复杂的场景例如只清扫指定的几个房间文档给出的标准姿势是使用 Home Assistant 的mqtt.publish服务动作。关键在于拿到两样东西负载Payload和主题Topic。第一步获取 Payload。在 Valetudo UI 中像平常一样配置好分段/区域/指定点然后长按将要启动该动作的按钮。此时会弹出一个小对话框直接给出可直接复制粘贴的负载仓库前端的SegmentActions.tsx、ZoneActions.tsx、GoToActions.tsx均基于use-long-press实现该长按交互并通过IntegrationHelpDialog展示 payload第二步获取主题。先到 Valetudo UI 的Connectivity → MQTT connectivity页面确认base topic然后到 MQTT 文档 中查阅目标能力Capability的完整主题后缀及其它注意事项。主题的通用格式为TOPIC PREFIX/IDENTIFIER/Capability/property/set以文档截图中的例子为例完整调用如下action: mqtt.publish data: topic: valetudo/InsecureYellowishGoldfish/MapSegmentationCapability/clean/set payload: {action:start_segment_action,segment_ids:[3,2,5],iterations:2,customOrder:true}MQTT 主题与负载参考速查以下内容摘自 docs/pages/integrations/mqtt.md该文档为 Valetudo 官方 MQTT API 参考由util/generate_mqtt_docs.js依据各 MQTT Handle 自动生成覆盖最常用的命令与状态主题。所有TOPIC PREFIX与IDENTIFIER均以 MQTT 设置页中配置的值为准。能力Capabilities命令主题能力属性命令主题.../set允许负载AutoEmptyDockManualTriggerCapabilitytrigger.../AutoEmptyDockManualTriggerCapability/trigger/setPERFORMBasicControlCapabilityoperation.../BasicControlCapability/operation/setSTARTSTOPPAUSEHOMEGoToLocationCapabilitygo.../GoToLocationCapability/go/set与 REST 相同的 JSONLocateCapabilitylocate.../LocateCapability/locate/setPERFORMMapSegmentationCapabilityclean.../MapSegmentationCapability/clean/set与 REST 相同的 JSONZoneCleaningCapabilitystart.../ZoneCleaningCapability/start/set与 REST 相同的 JSONConsumableMonitoringCapability消耗品/reset.../ConsumableMonitoringCapability/CONSUMABLE/reset/setPERFORMSpeakerVolumeControlCapabilityvalue.../SpeakerVolumeControlCapability/value/set0–100 的整数可读写retained属性则额外提供.../property读主题与.../property/set写主题例如CarpetModeControlCapability/enabledON/OFFCarpetSensorModeControlCapability/mode如lift、avoid、off以$format为准FanSpeedControlCapability/preset如offminlowmediumhighturbomax以$format为准OperationModeControlCapability/preset如mopvacuumvacuum_and_mopvacuum_then_mopWaterUsageControlCapability/preset如offminlowmediumhighmaxObstacleAvoidanceControlCapability/enabled、PetObstacleAvoidanceControlCapability/enabled、KeyLockCapability/enabledON/OFF。需要强调的是枚举负载因机型而异不同厂商/型号的机器人在吸力档位、水量档位、清扫模式、地毯传感器模式上的实现各不相同。文档与源码见PresetSelectionCapability相关 MQTT Handle都建议连接启动时务必检查$format或 HA 实体的json_attributes来确认当前机器实际支持的负载集合。常用命令负载示例指定分段清扫注意并非所有固件支持customOrder{ segment_ids: [20, 18, 16], iterations: 2, customOrder: true }对应的 MQTT 处理逻辑位于 backend/lib/mqtt/capabilities/MapSegmentationCapabilityMqttHandle.js它会先校验segment_ids非空、校验每个 ID 都真实存在于当前地图不存在则抛错Segment ID does not exist, or map was not loaded再把iterations/customOrder透传给executeSegmentAction()。因此发送负载前请确保地图已加载、分段 ID 正确ID 以字符串形式传递源码对数字型 ID 做了兼容处理。指定点清扫GoTo{ coordinates: { x: 50, y: 50 } }区域清扫Zone{ zones: [ { points: { pA: {x: 50, y: 50}, pB: {x: 100, y: 50}, pC: {x: 100, y: 100}, pD: {x: 50, y: 100} } } ], iterations: 1 }状态与地图主题状态类只读、retained节点属性读主题取值示例BatteryStateAttributelevel.../BatteryStateAttribute/level42%BatteryStateAttributestatus.../BatteryStateAttribute/statuschargingStatusStateAttributestatus.../StatusStateAttribute/statuscleaningStatusStateAttributeflag.../StatusStateAttribute/flagsegmentStatusStateAttributeerror.../StatusStateAttribute/errorJSON 错误对象StatusStateAttributeerror_description.../StatusStateAttribute/error_descriptionNo errorAttachmentStateAttributedustbin/mop/watertank.../AttachmentStateAttribute/nametrue/falseDockComponentStateAttributedetergent/dustbag/water_tank_clean/water_tank_dirty.../DockComponentStateAttribute/nameok/missing/empty/full/unknownDockStatusStateAttributestatus.../DockStatusStateAttribute/statusidle/emptying/drying…CurrentStatisticsCapabilityarea/time.../CurrentStatisticsCapability/name630000cm²/1440sTotalStatisticsCapabilityarea/count/time.../TotalStatisticsCapability/name面积 / 次数 / 秒ConsumableMonitoringCapabilityCONSUMABLE-MINUTES.../ConsumableMonitoringCapability/name29520剩余秒数ConsumableMonitoringCapabilityCONSUMABLE-PERCENT.../ConsumableMonitoringCapability/name59%WifiConfigurationCapabilityssid/signal/frequency/ips.../WifiConfigurationCapability/nameValetudo Wi-Fi/-23dBm…地图与事件类MapData/map-data原始地图 JSONdeflate 压缩MapData/map-data-hass嵌入 PNG 的地图数据自动发现开启时自动提供供camera.mqtt使用MapData/segments分段 ID → 名称的 JSON 映射例如{16: Hallway, 18: Bathroom, 20: Kitchen}ValetudoEvents/valetudo_events当前未处理事件列表JSON 对象键为事件 IDValetudoEvents/valetudo_events/interact/set事件交互命令例如对可忽略事件发送{id: 事件ID, interaction: ok}。文档同时提醒某些消耗品/统计属性是否可用取决于机器人型号——有的机器人以剩余时间秒上报消耗品有的以剩余百分比上报这与具体固件实现强相关需要以实际发布的主题为准。故障排查与注意事项汇总设备不出现依次检查 HA 日志、Broker 日志、Valetudo 日志重点排查网络连通与 Broker ACL确认 HA 的 MQTT 集成与 Valetudo 指向同一 Broker。不会收到“发现新设备”通知自动发现生成的设备是静默出现的属正常现象。命令不生效请确认发送的是**非保留retainfalse**消息——Valetudo 会直接丢弃带保留标志的命令消息并打印警告日志。枚举值不匹配不同厂商固件的档位负载不同务必以启动时$format/json_attributes为准不要硬编码负载。customOrder兼容性部分固件不支持自定义分段清扫顺序。地图数据开关MapData节点只有在 MQTT 配置开启地图数据提供时才可用map-data-hass则会在 HA 自动发现开启时自动加入。仓库中Configuration.js会移除旧版的mqtt.customizations.provideMapData配置键说明该键已被迁移/废弃配置时请以当前 MQTT 设置页为准。至此从 Broker 部署、Valetudo 配置、自动发现到仪表盘搭建与mqtt.publish命令调用你已经掌握了 Valetudo × Home Assistant 集成的完整闭环。更深入的能力清单每个 Capability 的 REST/MQTT 语义可继续阅读 能力总览 与 MQTT 集成参考。赞分享物联网后端前端【免费下载链接】ValetudoCloud replacement for vacuum robots enabling local-only operation项目地址https://gitcode.com/gh_mirrors/va/Valetudo点击查看免费下载相关推荐RuView v0.7.0 Home Assistant 集成解析MQTT 自动发现、Matter 桥接与语义自动化原语实战RuView v0.7.0 Home Assistant 集成解析MQTT 自动发现、Matter 桥接与语义自动化原语实战 v0.7.0feat 分支 f人工智能计算机视觉物联网智能家居后端嵌入式pipenv性能优化终极指南10个技巧减少虚拟环境启动时间pipenv性能优化终极指南10个技巧减少虚拟环境启动时间 Pipenv作为Python Development Workflow for Humans的工具后端前端WLED LD2410_v2 Usermod 实战用 24GHz 毫米波雷达实现移动检测与 MQTT/Home Assistant 集成WLED LD2410_v2 Usermod 实战用 24GHz 毫米波雷达实现移动检测与 MQTT/Home Assistant 集成 本文基于 WLED物联网嵌入式智能硬件上一篇TileLang 性能分析器实战用 Analyzer 从 TIR 静态估算 FLOPs、全局内存流量与 Roofline 执行时间下一篇HBM Predictor部署指南在生产环境中部署高带宽内存故障预测系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考