{"id":18756496,"url":"https://github.com/octoprint/octoprint-mqtt","last_synced_at":"2025-04-09T09:06:15.028Z","repository":{"id":29514082,"uuid":"33052422","full_name":"OctoPrint/OctoPrint-MQTT","owner":"OctoPrint","description":"An OctoPrint Plugin that adds support for MQTT.","archived":false,"fork":false,"pushed_at":"2024-06-19T14:25:03.000Z","size":183,"stargazers_count":161,"open_issues_count":35,"forks_count":52,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-02T05:09:39.144Z","etag":null,"topics":["octoprint","octoprint-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OctoPrint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-28T22:19:12.000Z","updated_at":"2025-03-17T10:09:19.000Z","dependencies_parsed_at":"2024-01-07T08:23:27.508Z","dependency_job_id":"46dc06e6-3041-48f5-8689-7395312f613e","html_url":"https://github.com/OctoPrint/OctoPrint-MQTT","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctoPrint%2FOctoPrint-MQTT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctoPrint%2FOctoPrint-MQTT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctoPrint%2FOctoPrint-MQTT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OctoPrint%2FOctoPrint-MQTT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OctoPrint","download_url":"https://codeload.github.com/OctoPrint/OctoPrint-MQTT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008629,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["octoprint","octoprint-plugin"],"created_at":"2024-11-07T17:36:52.385Z","updated_at":"2025-04-09T09:06:15.004Z","avatar_url":"https://github.com/OctoPrint.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OctoPrint MQTT Plugin\n\nThis is an OctoPrint Plugin that adds support for [MQTT](http://mqtt.org/) to OctoPrint.\n\n### Events\n\nOut of the box OctoPrint will send all [events](http://docs.octoprint.org/en/devel/events/index.html#available-events)\nincluding their payloads to the topic `octoPrint/event/\u003cevent\u003e`, where `\u003cevent\u003e` will be the name of the event. The message\npayload will be a JSON representation of the event's payload, with an additional property `_event` containing the name\nof the event and a property `_timestamp` containing the unix timestamp of when the message was created.\n\nExamples:\n\n| Topic                        | Message                                                          |\n|------------------------------|------------------------------------------------------------------|\n| octoPrint/event/ClientOpened | `{\"_timestamp\": 1517190629, \"_event\": \"ClientOpened\", \"remoteAddress\": \"127.0.0.1\"}`       |\n| octoPrint/event/Connected    | `{\"_timestamp\": 1517190629, \"_event\": \"Connected\", \"baudrate\": 250000, \"port\": \"VIRTUAL\"}` |\n| octoPrint/event/PrintStarted | `{\"_timestamp\": 1517190629, \"_event\": \"PrintStarted\", \"origin\": \"local\", \"file\":\"/home/pi/.octoprint/uploads/case_bp_3.6.v1.0.gco\", \"filename\": \"case_bp_3.6.v1.0.gco\"}` |\n\n### Print and slicing progress\n\nThe print progress and the slicing progress will also be send to the topic `octoPrint/progress/printing` and\n`octoPrint/progress/slicing` respectively. The payload will contain the `progress` as an integer between 0 and 100.\nPrint progress will also contain information about the currently printed file (storage `location` and `path` on storage),\nslicing progress will contain information about the currently sliced file (storage `source_location` and `destination_location`,\n`source_path` and `destination_path` on storage, used `slicer`). The payload will also contain a property `_timestamp`\ncontaining the unix timestamp of when the message was created. The published progress messages will be marked as\nretained.\n\nExamples:\n\n| Topic                        | Message                                                          |\n|------------------------------|------------------------------------------------------------------|\n| octoPrint/progress/printing  | `{\"_timestamp\": 1517190629, \"progress\": 23, \"location\": \"local\", \"path\": \"test.gco\"}`      |\n| octoPrint/progress/slicing   | `{\"_timestamp\": 1517190629, \"progress\": 42, \"source_location\": \"local\", \"source_path\": \"test.stl\", \"destination_location\": \"local\", \"destination_path\": \"test.gcode\", \"slicer\": \"cura\"}` |\n\n### Temperatures\n\nThe plugin also publishes the temperatures of the tools and the bed to `octoPrint/temperature/\u003ctool\u003e` where `\u003ctool\u003e` will either\nbe 'bed' or 'toolX' (X is the number of the tool). The payload will contain the `actual` and the `target` temperature as floating point value plus the current `time` as unix timestamp in seconds.\nNew messages will not be published constantly, but only when a value changes. The payload will also contain a property `_timestamp`\ncontaining the unix timestamp of when the message was created. The published messages will be marked as retained.\n\nExamples:\n\n| Topic                        | Message                                                          |\n|------------------------------|------------------------------------------------------------------|\n| octoPrint/temperature/tool0  | `{\"_timestamp\": 1517190629, \"actual\": 65.3, \"target\": 210.0}`                              |\n| octoPrint/temperature/bed    | `{\"_timestamp\": 1517190629, \"actual\": 42.1, \"target\": 65.0}`                               |\n\n### Additional Metadata\n\nYou can also define keys from the print file's additional metadata to publish on print start. This is especially useful together with plugins like [OctoPrint-SlicerSettingsParser](https://plugins.octoprint.org/plugins/SlicerSettingsParser/).\nYou can enter a comma separted list of keys in the plugin settings. The plugin will then publish the values of these keys to the topic `octoprint/metadata/\u003ckey\u003e`.\nCollections (dictionaries, lists) will be json encoded. To get specific values from a dictionary, you can use a dot notation (e.g. `dict.key.subkey`).\n\nExamples:\n\n| Topic                                            | Message                                                                              |\n|--------------------------------------------------|--------------------------------------------------------------------------------------|\n| octoprint/metadata/layer_height                  | `0.2`                                                                                |\n| octoprint/metadata/slicer_settings               | `{\"material_type\": \"PLA\", \"layer_height\": \"0.2\", \"filament_amount\": \"[48.92]\", ...}` |\n| octoprint/metadata/slicer_settings.material_type | `PLA`                                                                                |\n\n\n### Connection status / Last will\n\nAdditionally the plugin will publish `connected` to `octoPrint/mqtt` on connection and instruct the MQTT broker to publish\n`disconnected` there if the connection gets closed. The published messages will be marked as retained.\n\nExamples:\n\n| Topic                        | Message              |\n|------------------------------|----------------------|\n| octoPrint/mqtt               | `connected`          |\n\nYou are able to deactivate topics and the status/last will in the settings. This allows you to e.g. only send temperature messages when you don't\nneed event or progress messages.\n\n### Printer data\n\nIf the Printer Data option is set, then extended printer information as outlined in the\n[Common data model](http://docs.octoprint.org/en/master/api/datamodel.html) will be included in a `printer_data` attribute.\nUseful to get information such as print time remaining.\n\nExample:\n\n| Topic                        | Message              |\n|------------------------------|----------------------|\n| octoPrint/progress/printing  | `{\"progress\": 0, \"_timestamp\": 1525654824, \"location\": \"local\", \"path\": \"Stringing_Test.gco\", \"printer_data\": {\"progress\": {\"completion\": 0.008520926537352922, \"printTimeLeftOrigin\": \"average\", \"printTime\": 0, \"printTimeLeft\": 273, \"filepos\": 139}, \"state\": {\"text\": \"Printing\", \"flags\": {\"cancelling\": false, \"paused\": false, \"operational\": true, \"pausing\": false, \"printing\": true, \"sdReady\": true, \"error\": false, \"ready\": false, \"closedOrError\": false}}, \"currentZ\": null, \"job\": {\"file\": {\"origin\": \"local\", \"name\": \"Stringing_Test.gco\", \"date\": 1525586467, \"path\": \"Stringing_Test.gco\", \"display\": \"Stringing_Test.gco\", \"size\": 1631278}, \"estimatedPrintTime\": 1242.9603101308749, \"averagePrintTime\": 273.6990565955639, \"filament\": {\"tool0\": {\"volume\": 0.0, \"length\": 363.0717599999999}}, \"lastPrintTime\": 269.25606203079224}, \"offsets\": {}}}` |\n\nThe plugin also offers several helpers that allow other plugins to both publish as well as subscribe to\nMQTT topics, see below for details and a usage example.\n\n## Installation\n\nInstall via the bundled [Plugin Manager](https://github.com/foosel/OctoPrint/wiki/Plugin:-Plugin-Manager) using this URL:\n\n    https://github.com/OctoPrint/OctoPrint-MQTT/archive/master.zip\n\n## Configuration\n\nThe plugin offers a settings dialog that allows you to configure all relevant settings. If you want to configure things\nmanually by editing `config.yaml`, this is the structure you'd find therein:\n\n``` yaml\nplugins:\n    mqtt:\n        broker:\n            # the broker's url, mandatory, if not configured the plugin will do nothing\n            url: 127.0.0.1\n\n            # the broker's port\n            #port: 1883\n\n            # the username to use to connect with the broker, if not set no user\n            # credentials will be sent\n            #username: unset\n\n            # the password to use to connect with the broker, only used if a\n            # username is supplied too\n            #password: unset\n\n            # the keepalive value for the broker connection\n            #keepalive: 60\n\n            # tls settings\n            #tls:\n                # path to the server's certificate file\n                #ca_certs: unset\n\n                # paths to the PEM encoded client certificate and private keys\n                # respectively, must not be password protected, only necessary\n                # if broker requires client certificate authentication\n                #certfile: unset\n                #keyfile: unset\n\n                # a string specifying which encryption ciphers are allowable for this connection\n                #ciphers: unset\n\n            # configure verification of the server hostname in the server certificate.\n            #tls_insecure: false\n\n            # configure protocol version to use, valid values: MQTTv31 and MQTTv311\n            #protocol: MQTTv31\n\n            # should mqtt connection status / last will be retained?\n            #lwRetain: true\n\n        publish:\n            # base topic under which to publish OctoPrint's messages\n            #baseTopic: octoPrint/\n\n            # include extended printer data in a printer_data attribute, this will\n            # greatly increase the size of each message\n            # printerData: false\n\n            # topic for events, appended to the base topic, '{event}' will\n            # be substituted with the event name\n            #eventTopic: event/{event}\n\n            # should events be published?\n            #eventActive: true\n\n            # topic for print and slicer progress, appended to the base topic,\n            # '{progress}' will be substituted with either 'printing' or 'slicing'\n            #progressTopic: progress/{progress}\n\n            # should progress be published?\n            #progressActive: true\n\n            # topic for temperatures, appended to the base topic,\n            # '{temp}' will be substituted with either 'toolX' (X is the number of the tool) or 'bed'\n            #temperatureTopic: temperature/{temp}\n\n            # should temperatures be published?\n            #temperatureActive: true\n\n            # topic for additional metadata, appended to the base topic,\n            # '{key}' will be substituted with the key from the additional metadata\n            #metadataTopic: metadata/{key}\n\n            # should additional metadata be published?\n            #metadataActive: false\n\n            # keys from the additional metadata to publish, comma separated string\n            #metadataKeys: \"slicer_settings.material_type\"\n\n            # should mqtt connection status / last will be published?\n            #lwActive: true\n\n            # topic for connection status / last will\n            #lwTopic: mqtt\n```\n\n## Helpers\n\n### mqtt_publish(topic, payload, retained=False, qos=0, allow_queueing=False, raw_data=False)\n\nPublishes `payload` to `topic`. If `retained` is set to `True`, message will be flagged to be retained by the\nbroker. The QOS setting can be overridden with the `qos` parameter.\n\n`payload` may be a string in which case it will be sent as is. Otherwise a value conversion to JSON will be performed, unless you set `raw_data` to `True`.\n\nIf the MQTT plugin is currently not connected to the broker but `allow_queueing` is `True`, the message will be\nstored internally and published upon connection to the broker.\n\nReturns `True` if the message was accepted to be published by the MQTT plugin, `False` if the message could not\nbe accepted (e.g. due to the plugin being not connected to the broker and queueing not being allowed).\n\n### mqtt_publish_with_timestamp(topic, payload, retained=False, qos=0, allow_queueing=False, timestamp=None)\n\nPublishes `payload` to `topic` including a timestamp. `payload` *must* be a Python `dict` and will be extended by a\nproperty `_timestamp` set to the provided `timestamp` or - if unset - the current timestamp.\n\nIf the `publish.printerData` option is set, then all of the data from `self._printer.get_current_data()` will be\nincluded as a `printer_data` attribute in the payload. Useful to get things such as time remaining.\n\nEverything else behaves as `mqtt_publish` (which is also used internally).\n\n### mqtt_subscribe(topic, callback, args=None, kwargs=None)\n\nSubscribes `callback` for messages published on `topic`. The MQTT plugin will call the `callback` for received\nmessages like this:\n\n    callback(topic, payload, args..., retained=..., qos=..., kwargs...)\n\n`topic` will be the exact topic the message was received for, payload the message's payload, `retained` whether the\nmessage was retained by the broker and `qos` the message's QOS setting.\n\nThe callback should therefore at least accept `topic` and `payload` of the message as positional arguments and\n`retain` and `qos` as keyword arguments. If additional positional arguments or keyword arguments where provided\nduring subscription, they will be provided as outlined above.\n\n### mqtt_unsubscribe(callback, topic=None)\n\nUnsubscribes the `callback`. If not `topic` is provided all subscriptions for the `callback` will be removed, otherwise\nonly those matching the `topic` exactly.\n\n### Example\n\nThe following single file plugin demonstrates how to use the provided helpers. Place it as `mqtt_test.py` into your\n`~/.octoprint/plugins` (or equivalent) folder.\n\n```python\nimport octoprint.plugin\n\nclass MqttTestPlugin(octoprint.plugin.StartupPlugin):\n\n\tdef __init__(self):\n\t\tself.mqtt_publish = lambda *args, **kwargs: None\n\t\tself.mqtt_subscribe = lambda *args, **kwargs: None\n\t\tself.mqtt_unsubscribe = lambda *args, **kwargs: None\n\n\tdef on_after_startup(self):\n\t\thelpers = self._plugin_manager.get_helpers(\"mqtt\", \"mqtt_publish\", \"mqtt_subscribe\", \"mqtt_unsubscribe\")\n\t\tif helpers:\n\t\t\tif \"mqtt_publish\" in helpers:\n\t\t\t\tself.mqtt_publish = helpers[\"mqtt_publish\"]\n\t\t\tif \"mqtt_subscribe\" in helpers:\n\t\t\t\tself.mqtt_subscribe = helpers[\"mqtt_subscribe\"]\n\t\t\tif \"mqtt_unsubscribe\" in helpers:\n\t\t\t\tself.mqtt_unsubscribe = helpers[\"mqtt_unsubscribe\"]\n\n\t\tself.mqtt_publish(\"octoPrint/plugin/mqtt_test/pub\", \"test plugin startup\")\n\t\tself.mqtt_subscribe(\"octoPrint/plugin/mqtt_test/sub\", self._on_mqtt_subscription)\n\n\tdef _on_mqtt_subscription(self, topic, message, retained=None, qos=None, *args, **kwargs):\n\t\tself._logger.info(\"Yay, received a message for {topic}: {message}\".format(**locals()))\n\t\tself.mqtt_publish(\"octoPrint/plugin/mqtt_test/pub\", \"echo: \" + message)\n\n\n__plugin_implementations__ = [MqttTestPlugin()]\n```\n\n## Acknowledgements \u0026 Licensing\n\nOctoPrint-MQTT is licensed under the terms of the [APGLv3](https://gnu.org/licenses/agpl.html) (also included).\n\nOctoPrint-MQTT uses the [Eclipse Paho Python Client](https://www.eclipse.org/paho/clients/python/) under the hood,\nwhich is dual-licensed and used here under the terms of the [EDL v1.0 (BSD)](https://www.eclipse.org/org/documents/edl-v10.php).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctoprint%2Foctoprint-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctoprint%2Foctoprint-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctoprint%2Foctoprint-mqtt/lists"}