diff --git a/docs/api/printer.rst b/docs/api/printer.rst index b6e69575..469af8dd 100644 --- a/docs/api/printer.rst +++ b/docs/api/printer.rst @@ -758,29 +758,57 @@ Retrieve the current SD state .. _sec-api-printer-arbcommand: Send an arbitrary command to the printer -============================= +======================================== .. http:post:: /api/printer/command - Sends any command to the printer via serial inerface. Should be used with some care as some commands can stop a running print job. + Sends any command to the printer via the serial interface. Should be used with some care as some commands can interfere with + or even stop a running print job. + + Expects a :ref:`Arbitrary Command Request ` as the request's body. If successful returns a :http:statuscode:`204` and an empty body. - **Example Request** + **Example for sending a single command** .. sourcecode:: http + POST /api/printer/command HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { - "command": "M27" + "command": "M106" } + .. sourcecode:: http + + HTTP/1.1 204 No Content + + **Example for sending multiple commands** + + .. sourcecode:: http + + POST /api/printer/command HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "commands": [ + "M18", + "M106 S0" + ] + } + + .. sourcecode:: http + + HTTP/1.1 204 No Content - :json string command: The command to issue. - :statuscode 204: No error + :json string command: Single command to send to the printer, mutually exclusive with ``commands``. + :json string commands: List of commands to send to the printer, mutually exclusive with ``command``. + :statuscode 204: No error .. _sec-api-printer-datamodel: @@ -857,3 +885,25 @@ SD State - 1 - Boolean - Whether the SD card has been initialized (``true``) or not (``false``). + +.. _sec-api-printer-datamodel-arbcommand: + +Arbitrary Command Request +------------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``command`` + - 0..1 + - String + - Single command to send to the printer, mutually exclusive with ``commands``. + * - ``commands`` + - 0..* + - Array of String + - Multiple commands to send to the printer (in the given order), mutually exclusive with ``command``. diff --git a/src/octoprint/server/api/printer.py b/src/octoprint/server/api/printer.py index 55ae6d3b..2f5662d5 100644 --- a/src/octoprint/server/api/printer.py +++ b/src/octoprint/server/api/printer.py @@ -300,7 +300,6 @@ def printerSdState(): @api.route("/printer/command", methods=["POST"]) @restricted_access def printerCommand(): - # TODO: document me if not printer.isOperational(): return make_response("Printer is not operational", 409) @@ -309,15 +308,17 @@ def printerCommand(): data = request.json - parameters = {} - if "parameters" in data.keys(): - parameters = data["parameters"] + parameters = dict() + if "parameters" in data.keys(): parameters = data["parameters"] - commands = [] - if "command" in data.keys(): + if "command" in data and "commands" in data: + return make_response("'command' and 'commands' are mutually exclusive", 400) + elif "command" in data: commands = [data["command"]] - elif "commands" in data.keys(): + elif "commands" in data and isinstance(data["commands"], (list, tuple)): commands = data["commands"] + else: + return make_response("Need either single 'command' or list of 'commands'", 400) commandsToSend = [] for command in commands: