Printer control is mostly achieved through the use of commands, issued to resources reflecting components of the printer. OctoPrint currently knows the following components:
- Print head
Print head commands allow jogging and homing the print head in all three axes. Querying the resource is currently not supported. See
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
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. Note that Bed commands are only available if the currently selected printer profile has a heated bed. See
sec-api-printer-bedcommand.- SD card
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
sec-api-printer-sdcommand.
Besides that, OctoPrint also provides a full state report of the printer <sec-api-printer-state>.
Note
You might be wondering why all command responses below only return a 204 with an empty body instead of the output of the just sent commands. There are two reasons for this.
OctoPrint's internal webserver is single threaded and can only handle one request at a time. This is not a problem generally since asynchronous programming allows to just have one request which is waiting for data from a long running backend operation to sleep while handling other requests. The internal framework used for providing the REST API though, Flask, is based on WSGI, which is synchrounous in nature. This means that it is impossible to wait in a non blocking wait while handling a request on the REST API. So in order to return the response of a command sent to the printer, the single thread of the webserver would have to be blocked by the API while the response wasn't available yet. Which in turn would mean that the whole web server would stop responding while waiting for the printer to reply, which, depending on the command in question (e.g. homing) can take a long while. That would be a bad idea.
The second reason is that thanks to a large number of firmwares out there having a particular bug that makes it impossible to track the output of sent commands, identifying the correct response to a given sent command is pretty much hit-and-miss. That situation gets even worse considering that it's next to impossible to distinguish firmware versions which have that bug from firmware versions which don't have it.
Hence OctoPrint currently doesn't offer any synchronous way of retrieving the output of responses from the printer. If you need the printer's serial communication, you'll need to subscribe to push updates <sec-api-push>.
| Name | Multiplicity | Type | Description |
|---|---|---|---|
temperature |
0..1 | Temperature State <sec-api-printer-datamodel-temps> |
The printer's temperature state data |
sd |
0..1 | SD State <sec-api-printer-datamodel-sdstate> |
The printer's sd state data |
state |
0..1 | Printer State <sec-api-datamodel-printer-state> |
The printer's general state |
| Name | Multiplicity | Type | Description |
|---|---|---|---|
tool{n} |
0..* | Temperature Data <sec-api-datamodel-printer-tempdata> |
Current temperature stats for tool n. Enumeration starts at 0 for the first tool. Not included if querying only bed state. |
bed |
0..1 | Temperature Data <sec-api-datamodel-printer-tempdata> |
Current temperature stats for the printer's heated bed. Not included if querying only tool state or if the currently selected printer profile does not have a heated bed. |
history |
0..1 | List of Historic Temperature Datapoint <sec-api-datamodel-printer-temphistory> |
Temperature history |
| Name | Multiplicity | Type | Description |
|---|---|---|---|
ready |
1 | Boolean | Whether the SD card has been initialized (true) or not (false). |
| 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 |