is a neat software used as a web-operated printserver
for 3D printers
.
OctoPrint is a neat software used as a web-operated printserver
for 3D printers.
Sometimes, however, a commandline control is desired.
There is a utility called octocmd, that provides
a way to upload and select files, run printing and slicer, and watch status. It however misses
a lot of functionality.
An easy way with a richer set of commandline utilities was desired. Many functions (move, extrude,
retract, pause...) may need to be run from e.g. a control panel sending USB HID events. A simple
script then can handle the events and send the associated OctoPrint API calls.
The OctoPrint server comes with a powerful REST API accessible
over the HTTP protocol and extensively using JSON format for the data.
The production version API documentation is here.
The HTTP REST API can be accessed via cURL commandline utility.
The OctoControl, aka 8control, is a simple bash shell script housing multiple utilities and calling the API via cURL.
The host and API key are fetched from the octocmd configuration file, housed in ~/.octocmd.conf - the file is in JSON
format and is parsed via grep and cut to extract the variables.
Bash was chosen instead of e.g. Python. Octocmd is written in Python and
on less powerful computers, e.g. the Raspberry Pi, Python tends have a fairly slow start. Bash scripts,
at least the simple ones, are much snappier.
The core command is a bash shell script, _8command.sh. All the commands it hosts are linked by a
symbolic link.
Options:
8control octoprint command suite, complementary to octocmd
Global commands:
-h this help
-v verbose (show requests)
-vv more verbose (show requests and headers)
Config file location: /etc/octocmd.conf (or /root/.octocmd.conf) (current=/etc/octocmd.conf)
8checkcfg check 8control's configuration
8apiver show API and server version
8statusraw show controller connection status, raw JSON
8status show controller connection status, status only
8connect connect controller to server
8disconnect disconnect controller from server
8reconnect disconnect, reset, connect
8g "<code>" send gcode to controller
8gcode "<code>" send gcode to controller
8g0 "<coords>" send G0 command to controller
8g1 "<coords>" send G1 command to controller
8speed <factor> override speed, in percents
8feed <factor> override filament feed, in percents
8start start loaded print job
8print start loaded print job
8restart restart print job
8pause_raw pause/unpause running job, raw call
8pause pause running job
8resume resume running job
8cancel cancel running job
8xcancel cancel running job, keep temperature setting of the tools
8home home printer head
8jog <x> <y> <z> jog printer head by x,y,z mm
8jog <z> jog printer head by z mm
8settemp <temp> set tool0 to <temp> 'C, M104 S<temp>
8setbed <temp> set bed to <temp> 'C, M140 S<temp>
8settempr <temp> adjust tool0 by <temp> 'C, M104 R S<temp>; firmware MUST support Shad's R extension
8setbedr <temp> set bed to <temp> 'C, M140 R S<temp>; firmware MUST support Shad's R extension
8ex <mm> extrude <mm> millimeters of filament (negative to retract)
8extrude <mm> extrude <mm> millimeters of filament (negative to retract)
8fex <mm> [mm/min] fast extrude <mm> millimeters of filament (negative to retract) with optional speed
8eject [-t temp] eject filament, optionally heat head before
8gmulti <cmd> [<cmd>]... send several commands in one transaction
8upload <file> upload gcode file
8runfile <file> upload gcode file as tmp.g and execute it
8fan <on|off|0..255> control the head fan
8fan2 <on|off> control the bed fan (M42 P57)
8gettemp_raw show tool temperature
8gettemp show tool temperature
8getbed show bed temperature, raw JSON
8getbed show bed temperature
8servo <num> <angle> set servo angle
8run <cmd> run system-menu custom command (see .octoprint/config.yaml or 8ListCmds for commands)
8reset run system-menu command "reset"
8on power up the printer
8off power down the printer
8ListCmds list system commands (raw JSON)
8ls_raw list available files (raw JSON)
8ls list available files
8ll <filename> show info for <filename> (raw JSON)
8fselect <filename> select <filename>
8getjob information about current job, raw JSON
8msg "<msg>" show message on display via M117 gcode
8beep [n [f]] beep via M300 gcode [optionally for n milliseconds [at f Hz]]
8alarm [d] <t|b> <T> wait until <t>ip or <b>ed reaches temperature T ("d" for decreasing), then beep and exit
8alarmq [d] <t|b> <T> wait until <t>ip or <b>ed reaches temperature T ("d" for decreasing), then quietly exit
Some commands retrieve data. They are usually in JSON format. The most commonly needed data are extracted via grep. Such commands have the corresponding _raw version that shows the JSON itself.
All the commands start with 8. The host file starts with _8, to avoid collisions.
Most commands do not have parameters. Most commands do not have any response.
Some commands use G-code. There is also a command to directly send G-code commands to the printer.
The G-code is converted to uppercase before being sent to the printer.
The pause API call toggles the printing and paused status; calling it twice would pause and resume the print. To achieve stateless operation, the corresponding commands are checking the printer status before acting; 8pause will fire only when Printing, 8resume only when Paused. This will be important for pausing prints when some supervisory electronics (filament jam or runout sensor, computer vision...) detects an operator-requiring anomaly.
Beware, the API documentation shows /api/job correctly but the examples show /api/control/job - this was confusing a bit.
The jog directions are sign-flipped, to match the directions of the G-code based movements, so e.g. positive Z would move up and negative would move down.
The fast extrude is handy for replacing the filament.
The commands are set up in the ~/.octoprint/config.yaml file. Typical functions are switching the video streaming on and off.
This was not described in the documentation, or it was not possible to find there, so it had to be reverse-engineered using tcpdump or tshark.
monitor of the port for the interactive ones.
The archive with the host file and the symlink can be unzipped right to the target directory (usually /usr/bin/ or /usr/local/bin/. Simply cd to the directory and then run tar -xzvf <archive_name.tar.gz>.
- archive with host script and all the symlinks
- the host script itself
Do not forget to run the install.sh script to make the symlinks, eg. to /usr/bin: