Home Assistant 使用 OctoPrint Connect to a Printer 动作：自动连接 3D 打印机的完整指南
Home Assistant 使用 OctoPrint Connect to a Printer 动作自动连接 3D 打印机的完整指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读本文讲解 Home Assistant 中 OctoPrint 集成提供的octoprint.printer_connect动作Action介绍如何通过自动化或脚本让 OctoPrint 服务器连接到 3D 打印机。你将掌握在 UI 中配置该动作的完整步骤、YAML 字段的精确含义与取值范围以及服务器重启后自动重连打印机这一典型自动化场景的实战写法。该动作非常适合消除手动连接打印机的步骤让打印任务在服务器恢复后即可无缝开始。动作概述octoprint.printer_connect 是什么octoprint.printer_connect是 Home Assistant OctoPrint 集成提供的一个动作Action用于指示 OctoPrint 服务器连接到打印机。它属于 OctoPrint 集成在 source/_actions/ 目录下登记的文档化动作之一在 OctoPrint 集成文档 中会通过List of actions一节集中列出渲染逻辑见 source/_includes/integrations/actions.md。使用该动作时你可以让 OctoPrint自动选择连接设置最省心、最常用或手动指定打印机配置文件printer profile、串口serial port和波特率baud rate。典型应用场景是在自动化中使用它——例如当 OctoPrint 服务器重启后自动重新连接到打印机使打印机在服务器恢复后立即可用无需人工介入即可开始下一次打印。从 UI 配置该动作可视化方式如果你偏好使用可视化方式构建自动化和脚本Home Assistant 会引导你逐步完成配置无需编写 YAML。操作步骤如下打开设置 自动化与场景Settings Automations scenes。打开一个现有的自动化或脚本或选择创建自动化创建新自动化。如果是在新建自动化请在When触发条件部分添加一个触发器。脚本scripts不需要触发器它们在被其他东西调用时运行。在Then do执行部分选择Add action添加动作。在搜索框中搜索并选择OctoPrint: Connect to a printer。选择应执行连接的Server服务器。可选地设置配置文件名称profile name、串口serial port和波特率baud rate。选择保存Save。UI 中的可选项选项说明是否必填Server应连接到打印机的 OctoPrint 服务器。是Profile name连接时使用的打印机配置文件。否Serial port要连接的端口名称。否Baudrate连接使用的波特率。否UI 中的这些选项定义于动作文档的options_ui区块见 octoprint.printer_connect.markdown由仓库中的options_ui插件渲染成可视化表单。在 YAML 中使用该动作如果你直接编写 YAML或者想确切了解 Home Assistant 在底层做了什么本节给出技术参考包括 YAML 中使用的字段名、类型以及哪些字段是必填的。在 YAML 中将该动作引用为octoprint.printer_connect。一个基本示例action: octoprint.printer_connect data: device_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4上面的示例会指示选定的 OctoPrint 服务器使用自动连接设置连接到其打印机。YAML 选项说明字段类型必填说明device_idstring是应连接到打印机的 OctoPrint 服务器。profile_namestring否连接时使用的打印机配置文件。portstring否要连接的串口名称。baudratestring否连接使用的波特率。可取值9600、19200、38400、57600、115200、230400或250000。注意baudrate字段在文档中类型标注为 string但取值必须是上述七个波特率之一。其中115200是 3D 打印机领域最常见的默认波特率而250000常见于部分 Marlin 固件配置请以你打印机固件实际配置为准。关于 device_id 的说明device_id用于标识具体哪一个 OctoPrint 服务器执行连接操作。它的值不是任意填写的——它对应 Home Assistant 为已配置的 OctoPrint 设备生成的实体标识。如果你不确定自己的device_id可以通过 UI 方式配置动作后查看生成的自动化 YAML或参考 Home Assistant 开发者工具设置 工具 操作中该动作的可选目标列表。多个 OctoPrint 实例可以共存于一个 Home Assistant 实例中每个实例都有自己唯一的device_id。实战示例服务器重启后自动重连打印机这是该动作最典型的应用场景。当 OctoPrint 服务器重新上线后通知它连接到打印机使其为下一次打印做好准备。触发器TriggerOctoPrint 服务器变为可用become available动作ActionOctoPrint: Connect to a printer完整 YAML 自动化示例automation: alias: Reconnect OctoPrint to the printer triggers: - trigger: state entity_id: binary_sensor.octoprint_printing from: unavailable actions: - action: octoprint.printer_connect data: device_id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4这个自动化的工作原理触发器使用state触发器监听binary_sensor.octoprint_printing的状态变化条件是从unavailable不可用变为其他状态。OctoPrint 集成提供的Printing二进制传感器见 OctoPrint 集成文档 的 Binary sensor 一节在服务器离线时会进入unavailable状态服务器恢复后会离开该状态从而触发本自动化。动作部分调用octoprint.printer_connect并传入服务器对应的device_id让服务器使用自动连接设置连接打印机。这样即使服务器因重启、断电或其他原因离线恢复后也能自动重连打印机无需人工操作。连接行为要点Good to know当配置文件名称profile name、串口serial port和波特率baud rate都留空时OctoPrint 会使用其自动连接设置automatic connection settings。这意味着只要你的打印机通过 USB 等接口连接到运行 OctoPrint 的机器且固件能被识别OctoPrint 会自动探测端口并选择合适的配置完成连接。对于大多数单打印机的用户来说留空这三个字段即可获得开箱即用的体验。手动指定这三个字段适用于多打印机、多配置文件或特殊串口别名等复杂场景但需要确保填入的值与 OctoPrint 服务器端配置完全一致否则连接可能失败。试试这个动作想要立刻验证打开设置 工具 操作Settings Tools Actions搜索该动作填写字段然后选择执行操作Perform action。你可以无需编写一行 YAML就在真实的实体上看到执行结果。这是验证device_id取值是否正确、确认 OctoPrint 服务器能否成功连接打印机的最快途径。关联内容OctoPrint 集成提供的其他能力该动作所属的 OctoPrint 集成完整文档见 source/_integrations/octoprint.markdown还提供丰富的实体能力可作为连接动作的配套参考二进制传感器Printing打印中、Print Error打印错误。传感器实际床温、实际喷嘴温度、当前打印机状态、预计完成时间、作业完成百分比、预计开始时间、目标床温、目标喷嘴温度、当前文件名、当前文件大小。摄像头若在 OctoPrint 中配置了摄像头集成会提供摄像头画面。按钮Pause Job、Reboot System、Restart OctoPrint、Resume Job、Shutdown System、Stop Job。Number 实体可设置目标床温和目标喷嘴温度既可通过自动化、脚本调用也可在实体卡片上直接交互。例如你可以组合使用重连打印机与恢复打印作业Resume Job按钮构建更完整的断点恢复流程。连接动作与这些实体配合即可构建出覆盖服务器恢复 → 重连打印机 → 继续/启动打印的完整无人值守工作流。配置 OctoPrint 集成的前置条件要使用octoprint.printer_connect首先需要通过配置流程Config Flow将 OctoPrint 服务器添加到 Home Assistant。集成配置需要提供用户名、服务器地址如192.168.1.32、端口、URL 路径、是否使用 SSL 以及是否校验 SSL 证书详见 OctoPrint 集成文档。此外还需注意在 OctoPrint 中启用Discovery 插件并在设置 打印机通知中勾选Enable popups。集成会尝试通过Application Keys 插件注册自身在 Home Assistant 提交配置后需以你在 Home Assistant 中输入的用户名登录 OctoPrint并在弹出的提示中选择Allow。必须以添加到 Home Assistant 的同一用户身份登录 OctoPrint否则看不到授权提示。排查提示如果动作执行后打印机未连接首先检查服务器是否在线观察binary_sensor.octoprint_printing等实体是否处于unavailable状态以及 OctoPrint 服务器端是否已正确授权 Home Assistant 的应用密钥。若手动指定了profile_name、port或baudrate请核对它们与 OctoPrint 服务器端配置其config.yaml中的连接设置是否一致。使用设置 工具 操作手动执行该动作可以快速区分是动作配置问题还是服务器端问题。如果遇到Device is already configured for a second instance之类的集成级报错通常是复制/备份/恢复配置导致的 UUID 冲突可参考 OctoPrint 集成文档 中的 Troubleshooting 部分处理。总结octoprint.printer_connect是连接 Home Assistant 与 OctoPrint 打印机之间最后一公里的关键动作。通过 UI 的可视化配置或 YAML 的精确定义你可以让 OctoPrint 服务器在需要时自动连接打印机配合状态触发器还能实现服务器重启后全自动重连从而让 3D 打印流程真正实现无人值守。掌握device_id、profile_name、port、baudrate四个字段的含义与留空即自动连接的行为约定你就拥有了构建打印自动化工作流的坚实基础。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考