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.
cfgloc:/root/.octocmd.conf 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=/root/.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 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 8setbed <temp> set bed to <temp> 'C 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 8gmulti <cmd> [<cmd>]... send several commands in one transaction 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 8run <cmd> run system-menu command (see .octoprint/config.yaml for commands) 8reset run system-menu command "reset" 8on power up the printer 8off power down the printer 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 beep via M300 gcode 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.
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>.
Do not forget to run the install.sh script to make the symlinks, eg. to /usr/bin: