From 45bf3984942b61f9eaeb93fb4185965a467122e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Wed, 25 Mar 2015 19:30:49 +0100 Subject: [PATCH] [Docs] Added an example for octoprint.comm.protocol.action handler Used same example to illustrate hook handlers within mixin implementations. --- docs/plugins/concepts.rst | 51 ++++---------------------------- docs/plugins/hooks.rst | 55 ++++++++++++++++++++++------------- src/octoprint/util/virtual.py | 2 ++ 3 files changed, 42 insertions(+), 66 deletions(-) diff --git a/docs/plugins/concepts.rst b/docs/plugins/concepts.rst index 9c733c1c..a5405e81 100644 --- a/docs/plugins/concepts.rst +++ b/docs/plugins/concepts.rst @@ -135,54 +135,13 @@ If you want your hook handler to be an instance method of a mixin implementation need access to instance variables handed to your implementation via mixin invocations), you can get this work by using a small trick. Instead of defining it directly via ``__plugin_hooks__`` utilize the ``__plugin_init__`` property instead, manually instantiate your implementation instance and then add its hook handler method to the -``__plugin_hooks__`` property and itself to the ``__plugin_implementations__`` property. Example: +``__plugin_hooks__`` property and itself to the ``__plugin_implementations__`` property. See the following example. -.. code-block:: python +.. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/custom_action_command.py :linenos: - - # ... - - class MyPluginImplementation(octoprint.plugin.StartupPlugin): - - def __init__(self): - self._host = None - self._port = None - - def on_startup(self, host, port): - self._host = host - self._port = port - - def my_script_hook_handler(self, comm, script_type, script_name): - if not script_type == "gcode" or not script_name == "afterPrinterConnected": - # we only extend the gcode script afterPrinterConnected, ignore this - return None - - if not self._host or not self._port: - # oops, we haven't started up yet, shouldn't even happen... - return None - - # we only append something to the existing script, we don't prepend - prefix = None - postfix = ["M117 Hello World from %s:%d" % (self._host, self._port)] - return prefix, postfix - - # ... - - __plugin_implementations__ = [] - __plugin_hooks__ = dict() - - def __plugin_init__(): - # this gets called when OctoPrint initializes the plugin, so let's create the - # instance of our main implementation ... - plugin = MyPluginImplementation() - - # ... register it as implementation ... - global __plugin_implementations__ - __plugin_implementations__ = [plugin] - - # ... and its hook handler method as hook handler. - global __plugin_hooks__ - __plugin_hooks__ = {"octoprint.comm.protocol.scripts": plugin.my_script_hook_handler} + :tab-width: 4 + :caption: `custom_action_command.py `_ + :name: sec-plugin-concepts-hooks-example .. seealso:: diff --git a/docs/plugins/hooks.rst b/docs/plugins/hooks.rst index f7f84cd5..2a72a0af 100644 --- a/docs/plugins/hooks.rst +++ b/docs/plugins/hooks.rst @@ -3,6 +3,34 @@ Available plugin hooks ====================== +.. _sec-plugins-hook-comm-protocol-action: + +octoprint.comm.protocol.action +------------------------------ + +.. py:function:: hook(comm_instance, line, action, *args, **kwargs) + + React to a :ref:`action command ` received from the printer. + + Hook handlers may use this to react to react to custom firmware messages. OctoPrint parses the received action + command ``line`` and provides the parsed ``action`` (so anything after ``// action:``) to the hook handler. + + No returned value is expected. + + **Example:** + + Logs if the ``custom`` action (``// action:custom``) is received from the printer's firmware. + + .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/custom_action_command.py + :linenos: + :tab-width: 4 + :caption: `custom_action_command.py `_ + + :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook. + :param str line: The complete line as received from the printer, format ``// action:`` + :param str action: The parsed out action command, so for a ``line`` like ``// action:some_command`` this will be + ``some_command`` + .. _sec-plugins-hook-comm-protocol-gcode: octoprint.comm.protocol.gcode @@ -39,6 +67,8 @@ octoprint.comm.protocol.gcode .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/rewrite_m107.py :linenos: + :tab-width: 4 + :caption: `rewrite_m107.py `_ :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook. :param str cmd: The GCODE command for which the hook was triggered. This is the full command as taken either @@ -49,25 +79,6 @@ octoprint.comm.protocol.gcode :return: A rewritten ``cmd``, a tuple of ``cmd`` and ``cmd_type`` or ``cmd``, ``cmd_type`` and ``with_checksum`` or None to suppress sending of the ``cmd`` to the printer. See above for details. -.. _sec-plugins-hook-comm-protocol-action: - -octoprint.comm.protocol.action ------------------------------- - -.. py:function:: hook(comm_instance, line, action, *args, **kwargs) - - React to a :ref:`action command ` received from the printer. - - Hook handlers may use this to react to react to custom firmware messages. OctoPrint parses the received action - command ``line`` and provides the parsed ``action`` (so anything after ``// action:``) to the hook handler. - - No returned value is expected. - - :param object comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook. - :param str line: The complete line as received from the printer, format ``// action:`` - :param str action: The parsed out action command, so for a ``line`` like ``// action:some_command`` this will be - ``some_command`` - .. _sec-plugins-hook-comm-protocol-scripts: octoprint.comm.protocol.scripts @@ -87,10 +98,14 @@ octoprint.comm.protocol.scripts The returned entries may be either iterables of script lines or a string including newlines of the script lines (which will be split by the caller if necessary). - Example: + **Example:** + + Appends an ``M117 OctoPrint connected`` to the configured ``afterPrinterConnected`` GCODE script. .. onlineinclude:: https://raw.githubusercontent.com/OctoPrint/Plugin-Examples/master/message_on_connect.py :linenos: + :tab-width: 4 + :caption: `message_on_connect.py `_ :param MachineCom comm_instance: The :class:`~octoprint.util.comm.MachineCom` instance which triggered the hook. :param str script_type: The type of the script for which the hook was called, currently only "gcode" is supported here. diff --git a/src/octoprint/util/virtual.py b/src/octoprint/util/virtual.py index e9f8cc91..32e32cdb 100644 --- a/src/octoprint/util/virtual.py +++ b/src/octoprint/util/virtual.py @@ -269,6 +269,8 @@ class VirtualPrinter(): self.outgoing.put("// action:resume") elif data == "action_disconnect": self.outgoing.put("// action:disconnect") + elif data == "action_custom": + self.outgoing.put("// action:custom") else: try: sleep_match = VirtualPrinter.sleep_regex.match(data)