From ad68b05f7d3df4da0227ee788340a00f734a6c42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Mon, 9 Mar 2015 09:28:33 +0100 Subject: [PATCH] Fix: docs for printer resource now match implementation --- CHANGELOG.md | 1 + docs/api/printer.rst | 711 ++++++++++++++++++++++++---- src/octoprint/server/api/printer.py | 21 +- 3 files changed, 647 insertions(+), 86 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 307e7ca2..8b48dc78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ * [#719](https://github.com/foosel/OctoPrint/issues/719) - Properly center print bed in GCODE viewer * [#780](https://github.com/foosel/OctoPrint/issues/780) - Always (re)set file position in SD files to 0 so that reprints work correctly (backported from ``devel``) +* [#801](https://github.com/foosel/OctoPrint/issues/801) - Fixed setting of bed temperature offset * [IRC] - Don't hiccup on slic3r ``filament_diameter`` comments generated for multi extruder setups * [ML] - Fixed relative URL to SockJS endpoint, wasn't yet using the proper base url * [unreported] & [#698](https://github.com/foosel/OctoPrint/issues/698) - Generated URLs now take X-Forwarded-Host header diff --git a/docs/api/printer.rst b/docs/api/printer.rst index a39c5121..31d9f1ca 100644 --- a/docs/api/printer.rst +++ b/docs/api/printer.rst @@ -16,15 +16,167 @@ Printer control is mostly achieved through the use of commands, issued to resour printer. OctoPrint currently knows the following components: Print head - Print head commands allow jogging and homing the print head in all three axes. See :ref:`sec-api-printer-printheadcommand`. -Heater - Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Currently - OctoPrint only supports one hotend heater (this will change in the future). See :ref:`sec-api-printer-heatercommand`. -Feeder - Feeder commands allow extrusion/extraction of filament. Currently OctoPrint only supports one feeder (this will - change in a future version). See :ref:`sec-api-printer-feedercommand`. + Print head commands allow jogging and homing the print head in all three axes. Querying the resource is currently + not supported. + See :ref:`sec-api-printer-printheadcommand`. +Tool + Tool commands allow setting the temperature and temperature offsets for the printer's hotends/tools. Querying the + corresponding resource returns temperature information including an optional history. + See :ref:`sec-api-printer-toolcommand`. +Bed + Bed commands allow setting the temperature and temperature offset for the printer's heated bed. Querying the + corresponding resource returns temperature information including an optional history. + See :ref:`sec-api-printer-bedcommand`. SD card - SD commands allow initialization, refresh and release of the printer's SD card (if available). See :ref:`sec-api-printer-sdcommand`. + SD commands allow initialization, refresh and release of the printer's SD card (if available). Querying the + corresponding resource returns the current SD card state. + See :ref:`sec-api-printer-sdcommand`. + +Besides that, OctoPrint also provides a :ref:`full state report of the printer `. + +.. _sec-api-printer-state: + +Retrieve the current printer state +================================== + +.. http:get:: /api/printer + + Retrieves the current state of the printer. Returned information includes: + + * temperature information (see also :ref:`Retrieve the current tool state ` and + :ref:`Retrieve the current bed state `) + * sd state (if available, see also :ref:`Retrieve the current SD state `) + * general printer state + + Temperature information can also be made to include the printer's temperature history by supplying the ``history`` + query parameter. The amount of data points to return here can be limited using the ``limit`` query parameter. + + Clients can specific a list of attributes to not return in the response (e.g. if they don't need it) via the + ``exclude`` query parameter. + + Returns a :http:statuscode:`200` with a :ref:`Full State Response ` in the + body upon success. + + **Example 1** + + Include temperature history data, but limit it to two entries. + + .. sourcecode:: http + + GET /api/printer?history=true&limit=2 HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "temperature": { + "tool0": { + "actual": 214.8821, + "target": 220.0, + "offset": 0 + }, + "tool1": { + "actual": 25.3, + "target": null, + "offset": 0 + }, + "bed": { + "actual": 50.221, + "target": 70.0, + "offset": 5 + }, + "history": [ + { + "time": 1395651928, + "tool0": { + "actual": 214.8821, + "target": 220.0 + }, + "tool1": { + "actual": 25.3, + "target": null + }, + "bed": { + "actual": 50.221, + "target": 70.0 + } + }, + { + "time": 1395651926, + "tool0": { + "actual": 212.32, + "target": 220.0 + }, + "tool1": { + "actual": 25.1, + "target": null + }, + "bed": { + "actual": 49.1123, + "target": 70.0 + } + } + ] + }, + "sd": { + "ready": true + }, + "state": { + "text": "Operational", + "flags": { + "operational": true, + "paused": false, + "printing": false, + "sdReady": true, + "error": false, + "ready": true, + "closedOrError": false + } + } + } + + **Example 2** + + Exclude temperature and sd data. + + .. sourcecode:: http + + GET /api/printer?exclude=temperature,sd HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "state": { + "text": "Operational", + "flags": { + "operational": true, + "paused": false, + "printing": false, + "sdReady": true, + "error": false, + "ready": true, + "closedOrError": false + } + } + } + + :query exclude: An optional comma-separated list of fields to exclude from the response (e.g. if not needed by + the client). Valid values to supply here are ``temperature``, ``sd`` and ``state``. + :query history: If set to ``true`` (or: ``yes``, ``y``, ``1``), history information will be included in the response + too. If no ``limit`` parameter is given, all available temperature history data will be returned. + :query limit: If set to an integer (``n``), only the last ``n`` data points from the printer's temperature history + will be returned. Will be ignored if ``history`` is not enabled. + :statuscode 200: No error + :statuscode 409: If the printer is not operational. .. _sec-api-printer-printheadcommand: @@ -70,6 +222,10 @@ Issue a print head command "z": 0.02 } + .. sourcecode:: http + + HTTP/1.1 204 No Content + **Example Home Request** Home the X and Y axes. @@ -86,6 +242,10 @@ Issue a print head command "axes": ["x", "y"] } + .. sourcecode:: http + + HTTP/1.1 204 No Content + :json string command: The command to issue, either ``jog`` or ``home``. :json number x: ``jog`` command: The amount to travel on the X axis in mm. :json number y: ``jog`` command: The amount to travel on the Y axis in mm. @@ -96,67 +256,70 @@ Issue a print head command request. :statuscode 409: If the printer is not operational or currently printing. -.. _sec-api-printer-heatercommand: +.. _sec-api-printer-toolcommand: -Issue a heater command -====================== +Issue a tool command +==================== -.. todo:: +.. http:post:: /api/printer/tool - Update to current implementation! + Tool commands allow setting the temperature and temperature offsets for the printer's tools (hotends), selecting + the current tool and extruding/retracting from the currently selected tool. Available commands are: -.. http:post:: /api/printer/heater + target + Sets the given target temperature on the printer's tools. Additional parameters: - Heater commands allow setting the temperature and temperature offsets for the printer's hotend and bed. Available - commands are: - - temp - Sets the given target temperature on the printer's hotend and/or bed. Additional parameters: - - * ``targets``: Target temperature(s) to set, allowed properties are: - - * ``hotend``: New target temperature of the printer's hotend in centigrade. - * ``bed``: New target temperature of the printer's bed in centigrade. + * ``targets``: Target temperature(s) to set, properties must match the format ``tool{n}`` with ``n`` being the + tool's index starting with 0. offset - Sets the given temperature offset on the printer's hotend and/or bed. Additional parameters: + Sets the given temperature offset on the printer's tools. Additional parameters: - * ``offsets``: Offset(s) to set, allowed properties are: + * ``offsets``: Offset(s) to set, properties must match the format ``tool{n}`` with ``n`` being the tool's index + starting with 0. - * ``hotend``: New offset of the printer's hotend temperature in centigrade, max/min of +/-50°C. - * ``bed``: New offset of the printer's bed temperature in centigrade, max/min of +/-50°C. + select + Selects the printer's current tool. Additional parameters: - All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a - :http:statuscode:`409` is returned. + * ``tool``: Tool to select, format ``tool{n}`` with ``n`` being the tool's index starting with 0. + + extrude + Extrudes the given amount of filament from the currently selected tool. Additional parameters: + + * ``amount``: The amount of filament to extrude in mm. May be negative to retract. Upon success, a status code of :http:statuscode:`204` and an empty body is returned. **Example Target Temperature Request** - Set the printer's hotend target temperature to 220°C and the bed target temperature to 75°C. + Set the target temperature for the printer's first hotend to 220°C and the printer's second extruder to 205°C. .. sourcecode:: http - POST /api/printer/heater HTTP/1.1 + POST /api/printer/tool HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { - "command": "temp", - "temps": { - "hotend": 220, - "bed": 75 + "command": "target", + "targets": { + "tool0": 220, + "tool1": 205 } } + .. sourcecode:: http + + HTTP/1.1 204 No Content + **Example Offset Temperature Request** - Set the offset for hotend temperatures to +10°C and for bed temperatures to -5°C. + Set the offset for temperatures on ``tool0`` to +10°C and on ``tool1`` to -5°C. .. sourcecode:: http - POST /api/printer/heater HTTP/1.1 + POST /api/printer/tool HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... @@ -164,62 +327,62 @@ Issue a heater command { "command": "offset", "offsets": { - "hotend": 10, - "bed": -5 + "tool0": 10, + "tool1": -5 } } - :json string command: The command to issue, either ``temp`` or ``offset`` - :json object temps: ``temp`` command: The target temperatures to set. Valid properties are ``hotend`` and ``bed`` - :json object offsets: ``offset`` command: The offset temperature to set. Valid properties are ``hotend`` and ``bed`` - :statuscode 204: No error - :statuscode 400: If ``temps`` or ``offsets`` contains a property other than ``hotend`` or ``bed``, the - target or offset temperature is not a valid number or outside of the supported range, or if the - request is otherwise invalid. - :statuscode 409: If the printer is not operational. + .. sourcecode:: http -.. _sec-api-printer-feedercommand: + HTTP/1.1 204 No Content -Issue a feeder command -====================== + **Example Tool Select Request** -.. http:post:: /api/printer/feeder - - Feeder commands allow extrusion/extraction of filament. Available commands are: - - extrude - Extrudes the given amount of filament. Additional parameters: - - * ``amount``: The amount of filament to extrude in mm. May be negative to retract. - - All of these commands may only be sent if the printer is currently operational and not printing. Otherwise a - :http:statuscode:`409` is returned. - - Upon success, a status code of :http:statuscode:`204` and an empty body is returned. - - **Example Extrude Request** - - Extrudes 1mm of filament + Select the second hotend of the printer for any following ``extrude`` commands. .. sourcecode:: http - POST /api/printer/feeder HTTP/1.1 + POST /api/printer/tool HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "select", + "tool": "tool1" + } + + .. sourcecode:: http + + HTTP/1.1 204 No Content + + **Example Extrude Request** + + Extrude 5mm on the currently selected tool. + + .. sourcecode:: http + + POST /api/printer/tool HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... { "command": "extrude", - "amount": 1 + "amount": 5 } - **Example Retract Request** - - Retracts 3mm of filament - .. sourcecode:: http - POST /api/printer/feeder HTTP/1.1 + HTTP/1.1 204 No Content + + **Example Retract Request** + + Retract 3mm of filament on the currently selected tool. + + .. sourcecode:: http + + POST /api/printer/tool HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: abcdef... @@ -229,16 +392,239 @@ Issue a feeder command "amount": -3 } - :json string command: The command to issue, only ``extrude`` is supported right now. - :json number amount: ``extrude`` command: The amount of filament to extrude/retract in mm. + .. sourcecode:: http + + HTTP/1.1 204 No Content + + :json string command: The command to issue, either ``target``, ``offset``, ``select`` or ``extrude``. + :json object targets: ``target`` command: The target temperatures to set. Valid properties have to match the format ``tool{n}``. + :json object offsets: ``offset`` command: The offset temperature to set. Valid properties have to match the format ``tool{n}``. + :json object tool: ``select`` command: The tool to select, value has to match the format ``tool{n}``. + :json object amount: ``extrude`` command: The amount of filament to extrude from the currently selected tool. + :json number factor: ``flowrate`` command: The factor to apply to the flow rate, percentage between 75 and 125% as integer or float. :statuscode 204: No error :statuscode 400: If the value given for `amount` is not a valid number or the request is otherwise invalid. :statuscode 409: If the printer is not operational or currently printing. +.. _sec-api-printer-toolstate: + +Retrieve the current tool state +=============================== + +.. http:get:: /api/printer/tool + + Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, + timestamp) for all of the printer's available tools. + + It's also possible to retrieve the temperature history by supplying the ``history`` query parameter set to ``true``. The + amount of returned history data points can be limited using the ``limit`` query parameter. + + Returns a :http:statuscode:`200` with a Temperature Response in the body upon success. + + .. note:: + If you want both tool and bed temperature information at the same time, take a look at + :ref:`Retrieve the current printer state `. + + **Example** + + Query the tool temperature data and also include the temperature history but limit it to two entries. + + .. sourcecode:: http + + GET /api/printer/tool?history=true&limit=2 HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "tool0": { + "actual": 214.8821, + "target": 220.0, + "offset": 0 + }, + "tool1": { + "actual": 25.3, + "target": null, + "offset": 0 + }, + "history": [ + { + "time": 1395651928, + "tool0": { + "actual": 214.8821, + "target": 220.0 + }, + "tool1": { + "actual": 25.3, + "target": null + } + }, + { + "time": 1395651926, + "tool0": { + "actual": 212.32, + "target": 220.0 + }, + "tool1": { + "actual": 25.1 + } + } + ] + } + + :query history: If set to ``true`` (or: ``yes``, ``y``, ``1``), history information will be included in the response + too. If no ``limit`` parameter is given, all available temperature history data will be returned. + :query limit: If set to an integer (``n``), only the last ``n`` data points from the printer's temperature history + will be returned. Will be ignored if ``history`` is not enabled. + :statuscode 200: No error + :statuscode 409: If the printer is not operational. + +.. _sec-api-printer-bedcommand: + +Issue a bed command +=================== + +.. http:post:: /api/printer/bed + + Bed commands allow setting the temperature and temperature offsets for the printer's heated bed. Available commands + are: + + target + Sets the given target temperature on the printer's tools. Additional parameters: + + * ``target``: Target temperature to set. + + offset + Sets the given temperature offset on the printer's tools. Additional parameters: + + * ``offset``: Offset to set. + + All of these commands may only be sent if the printer is currently operational. Otherwise a :http:statuscode:`409` + is returned. + + Upon success, a status code of :http:statuscode:`204` and an empty body is returned. + + **Example Target Temperature Request** + + Set the target temperature for the printer's heated bed to 75°C. + + .. sourcecode:: http + + POST /api/printer/bed HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "target", + "target": 75 + } + + .. sourcecode:: http + + HTTP/1.1 204 No Content + + **Example Offset Temperature Request** + + Set the temperature offset for the heated bed to -5°C. + + .. sourcecode:: http + + POST /api/printer/bed HTTP/1.1 + Host: example.com + Content-Type: application/json + X-Api-Key: abcdef... + + { + "command": "offset", + "offset": -5 + } + + .. sourcecode:: http + + HTTP/1.1 204 No Content + + :json string command: The command to issue, either ``target`` or ``offset``. + :json object target: ``target`` command: The target temperature to set. + :json object offset: ``offset`` command: The offset temperature to set. + :statuscode 204: No error + :statuscode 400: If ``target`` or ``offset`` is not a valid number or outside of the supported range, or if the + request is otherwise invalid. + :statuscode 409: If the printer is not operational. + +.. _sec-api-printer-bedstate: + +Retrieve the current bed state +============================== + +.. http:get:: /api/printer/bed + + Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, + timestamp) for the printer's heated bed. + + It's also possible to retrieve the temperature history by supplying the ``history`` query parameter set to ``true``. The + amount of returned history data points can be limited using the ``limit`` query parameter. + + Returns a :http:statuscode:`200` with a Temperature Response in the body upon success. + + .. note:: + If you want both tool and bed temperature information at the same time, take a look at + :ref:`Retrieve the current printer state `. + + **Example** + + Query the bed temperature data and also include the temperature history but limit it to two entries. + + .. sourcecode:: http + + GET /api/printer/bed?history=true&limit=2 HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "bed": { + "actual": 50.221, + "target": 70.0, + "offset": 5 + }, + "history": [ + { + "time": 1395651928, + "bed": { + "actual": 50.221, + "target": 70.0 + } + }, + { + "time": 1395651926, + "bed": { + "actual": 49.1123, + "target": 70.0 + } + } + ] + } + + :query history: If set to ``true`` (or: ``yes``, ``y``, ``1``), history information will be included in the response + too. If no ``limit`` parameter is given, all available temperature history data will be returned. + :query limit: If set to an integer (``n``), only the last ``n`` data points from the printer's temperature history + will be returned. Will be ignored if ``history`` is not enabled. + :statuscode 200: No error + :statuscode 409: If the printer is not operational. + .. _sec-api-printer-sdcommand: -Issue a SD command -================== +Issue an SD command +=================== .. http:post:: /api/printer/sd @@ -279,6 +665,10 @@ Issue a SD command "command": "init" } + .. sourcecode:: http + + HTTP/1.1 204 No Content + **Example Refresh Request** .. sourcecode:: http @@ -292,6 +682,10 @@ Issue a SD command "command": "refresh" } + .. sourcecode:: http + + HTTP/1.1 204 No Content + **Example Release Request** .. sourcecode:: http @@ -305,6 +699,10 @@ Issue a SD command "command": "release" } + .. sourcecode:: http + + HTTP/1.1 204 No Content + :json string command: The command to issue, either ``init``, ``refresh`` or ``release``. :statuscode 204: No error :statuscode 409: If a ``refresh`` or ``release`` command is issued but the SD card has not been initialized (e.g. @@ -324,14 +722,15 @@ Retrieve the current SD state Returns a :http:statuscode:`200` with an :ref:`SD State Response ` in the body upon success. - **Example Request** + **Example** + + Read the current state of the SD card. .. sourcecode:: http GET /api/printer/sd HTTP/1.1 Host: example.com - - **Example Response** + X-Api-Key: abcdef... .. sourcecode:: http @@ -345,15 +744,123 @@ Retrieve the current SD state :statuscode 200: No error :statuscode 404: If SD support has been disabled in OctoPrint's config. +.. _sec-api-printer-arbcommand: + +Send an arbitrary command to the printer +======================================== + +.. http:post:: /api/printer/command + + 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 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": "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: 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: Datamodel ========= +.. _sec-api-printer-datamodel-fullstate: + +Full State Response +------------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``temperature`` + - 0..1 + - :ref:`Temperature State ` + - The printer's temperature state data + * - ``sd`` + - 0..1 + - :ref:`SD State ` + - The printer's sd state data + * - ``state`` + - 0..1 + - :ref:`Printer State ` + - The printer's general state + +.. _sec-api-printer-datamodel-temps: + +Temperature State +----------------- + +.. list-table:: + :widths: 15 5 10 30 + :header-rows: 1 + + * - Name + - Multiplicity + - Type + - Description + * - ``tool{n}`` + - 0..* + - :ref:`Temperature Data ` + - Current temperature stats for tool *n*. Enumeration starts at 0 for the first tool. Not included if querying + only bed state. + * - ``bed`` + - 0..1 + - :ref:`Temperature Data ` + - Current temperature stats for the printer's heated bed. Not included if querying only tool state. + * - ``history`` + - 0..1 + - List of :ref:`Historic Temperature Datapoint ` + - Temperature history + .. _sec-api-printer-datamodel-sdstate: -SD State Response ------------------ +SD State +-------- .. list-table:: :widths: 15 5 10 30 @@ -366,4 +873,38 @@ SD State Response * - ``ready`` - 1 - Boolean - - Whether the SD card has been initialized (``true``) or not (``false``). \ No newline at end of file + - 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`` and ``script``. + * - ``commands`` + - 0..* + - Array of String + - Multiple commands to send to the printer (in the given order), mutually exclusive with ``command`` and ``script``. + * - ``script`` + - 0..* + - String + - Name of the GCODE script template to send to the printer, mutually exclusive with ``command`` and ``commands``. + * - ``parameters`` + - 0..1 + - Map of key value pairs + - Key value pairs of parameters to replace in sent commands/provide to the script renderer + * - ``context`` + - 0..1 + - Map of key value pairs + - (only if ``script`` is set) additional template variables to provide to the script renderer diff --git a/src/octoprint/server/api/printer.py b/src/octoprint/server/api/printer.py index 674953f4..66eef692 100644 --- a/src/octoprint/server/api/printer.py +++ b/src/octoprint/server/api/printer.py @@ -17,8 +17,27 @@ def printerState(): if not printer.isOperational(): return make_response("Printer is not operational", 409) + # process excludes + excludes = [] + if "exclude" in request.values: + excludeStr = request.values["exclude"] + if len(excludeStr.strip()) > 0: + excludes = filter(lambda x: x in ["temperature", "sd", "state"], map(lambda x: x.strip(), excludeStr.split(","))) + result = {} - result.update(_getTemperatureData(lambda x: x)) + + # add temperature information + if not "temperature" in excludes: + result.update({"temperature": _getTemperatureData(lambda x: x)}) + + # add sd information + if not "sd" in excludes and settings().getBoolean(["feature", "sdSupport"]): + result.update({"sd": {"ready": printer.isSdReady()}}) + + # add state information + if not "state" in excludes: + state = printer.getCurrentData()["state"] + result.update({"state": state}) return jsonify(result)