API¶
OpenGB functionality is exposed via a JSON-RPC 2.0 API over HTTP using WebSockets.
Connecting¶
The OpenGB web server exposes a WebSocket at http://<hostname>:<port>/ws.
To connect using Javascript:
var socket = new WebSocket("ws://" + window.location.host + "/ws");
socket.onmessage = function (message) {
parseMessage(message)
};
Message Types¶
In accordance with the JSON-RPC 2.0 spec there are two distinct message types used by the API. The payloads of both are encoded as JSON objects.
Method¶
The client sends a JSON-RPC 2.0 request to the server defining a method call and the server replies with a JSON-RPC 2.0 response.
Example request (setting target temperatures):
{
"jsonrpc": "2.0",
"id": 1,
"method": "set_temp",
"params": {
"bed": 105,
"nozzle1": 206,
"nozzle2": 203
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
Event¶
The server sends an unsolicited JSON-RPC 2.0 message to the client defining an event which has occured.
Example event (temperature update):
{
"jsonrpc": "2.0",
"event": "temp",
"params": {
"bed_current": 203,
"bed_target": 105,
"nozzle2_target": 203,
"nozzle1_current": 104,
"nozzle2_current": 108,
"nozzle1_target": 206
}
}
Methods¶
The opengb.server.MessageHandler
class contains the methods exposed to JSON-RPC 2.0 clients.
set_temp¶
-
MessageHandler.
set_temp
(bed=None, nozzle1=None, nozzle2=None)¶ Set printer target temperatures.
Unspecified target temperatures will remain unchanged.
Parameters: - bed (
float
) – Bed target temperature. - nozzle1 (
float
) – Nozzle1 target temperature. - nozzle2 (
float
) – Nozzle2 target temperature.
- bed (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "set_temp",
"params":{
"bed": 105,
"nozzle1": 206,
"nozzle2": 203
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
move_head_relative¶
-
MessageHandler.
move_head_relative
(x=0, y=0, z=0, rate=300)¶ Move the print head along one or more axes relative to the current position.
Parameters: - x (
float
) – Millimeters to move along the X axis. - y (
float
) – Millimeters to move along the Y axis. - z (
float
) – Millimeters to move along the Z axis. - rate (
float
) – Rate at which to move in mm/s.
- x (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "move_head_relative",
"params": {
"x": 13.2,
"y": -2,
"z": 0.03,
"rate": 60
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
move_head_absolute¶
-
MessageHandler.
move_head_absolute
(x=0, y=0, z=0, rate=300)¶ Move the print head along one or more axes to an absolute position.
Parameters: - x (
float
) – Position to move to along the X axis. - y (
float
) – Position to move to along the Y axis. - z (
float
) – Position to move to along the Z axis. - rate (
float
) – Rate at which to move in mm/s.
- x (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "move_head_absolute",
"params": {
"x": 105,
"y": 80,
"z": 20,
"rate": 60
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
home_head¶
-
MessageHandler.
home_head
(x=True, y=True, z=True)¶ Home the print head along one or more axes.
Parameters: - x (
bool
) – Whether or not to home the X axis. - y (
bool
) – Whether or not to home the Y axis. - z (
bool
) – Whether or not to home the Z axis.
- x (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "home_head",
"params":{
"x": true,
"y": true,
"z": false
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
retract_filament¶
-
MessageHandler.
retract_filament
(head, length, rate=300)¶ Retract filament into the print head.
Parameters: - head (
int
) – Print head to retract (0 or 1). - length (
float
) – Amount of filament to retract in mm. - rate (
float
) – Rate at which to retract in mm/s.
- head (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "retract_filament",
"params": {
"head": 0,
"length": 5,
"rate": 300
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
unretract_filament¶
-
MessageHandler.
unretract_filament
(head, length, rate=300)¶ Unretract filament from the print head.
Parameters: - head (
int
) – Print head to unretract (0 or 1). - length (
float
) – Amount of filament to unretract in mm. - rate (
float
) – Rate at which to unretract in mm/s.
- head (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "unretract_filament",
"params": {
"head": 0,
"length": 5,
"rate": 300
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
set_extrude_override¶
-
MessageHandler.
set_extrude_override
(percent)¶ Set percentage override applied to extrusion commands.
Parameters: percent ( float
) – Percentage by which extrusion should be overridden.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "set_extrude_override",
"params": {
"percent":120
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
set_speed_override¶
-
MessageHandler.
set_speed_override
(percent)¶ Set speed percentage override applied to movement commands.
Parameters: percent ( float
) – Percentage by which movement speed should be overridden.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "set_speed_override",
"params": {
"percent":120
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
set_fan_speed¶
-
MessageHandler.
set_fan_speed
(fan, percent)¶ Set fan speed.
Parameters: - fan (class:int (0-2)) – Number of fan for which to set speed.
- percent (
float
) – Percentage of maximum speed to set.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "set_fan_speed",
"params": {
"fan": 1,
"percent": 75
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
filament_swap_begin¶
-
MessageHandler.
filament_swap_begin
()¶ Begin filament swap procedure.
Normally this will pause an ongoing print, move the print head/bed and retract filament ready to be swapped.
Once filament swap is complete
filament_swap_complete()
should be called to return print head to previous position and continue printing.Note
This is an experimental method and may be implemented differently for various printer + firmware combinations.
This method may be called internally as the result of a filament detection script being triggered.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "filament_swap_begin",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
filament_swap_complete¶
-
MessageHandler.
filament_swap_complete
()¶ Complete filament swap procedure.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "filament_swap_complete",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
enable_steppers¶
-
MessageHandler.
enable_steppers
()¶ Enable stepper motors.
Prevents motors and axes from moving freely.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "enable_steppers",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
disable_steppers¶
-
MessageHandler.
disable_steppers
()¶ Disable stepper motors.
Allows motors and axes to moving freely.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "disable_steppers",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
print_gcode_file¶
-
MessageHandler.
print_gcode_file
(id)¶ Print gcode file with given id.
Parameters: id ( int
) – ID of the gcode file to get.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "print_gcode_file",
"params": {
"id": 1
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
pause_print¶
-
MessageHandler.
pause_print
()¶ Pause the current print job.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "pause_print",
"params":{}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
resume_print¶
-
MessageHandler.
resume_print
()¶ Resume a paused print job.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "resume_print",
"params":{}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
cancel_print¶
-
MessageHandler.
cancel_print
()¶ Cancel the current print job.
The current print job status and position will be discarded.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method":"cancel_print",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
emergency_stop¶
-
MessageHandler.
emergency_stop
()¶ Halt the printer immediately.
Note
Use only in emergencies as this will most likely lock the printer and require a reboot.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "emergency_stop",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
put_gcode_file¶
-
MessageHandler.
put_gcode_file
(payload, name, print_material='', print_quality='', print_extruders='', print_time_sec=0, print_filament_mm=0, print_material_gm=0, thumbnail_png_base64='')¶ Upload a gcode file.
Parameters: - payload (
str
) – Gcode file as ASCII text. - name (
str
) – Gcode file name. - print_material (
str
) – Intended print material (e.g. “PLA”). - print_quality (
str
) – Intended print quality (e.g. “High”). - print_extruders (
str
) – Extruders utilised (e.g. “Both”). - print_time_sec (
int
) – Estimated print time in seconds. - print_filament_mm (
int
) – Estimated print filament length in millimeters. - print_material_gm (
int
) – Estimated print material weight in grams. - thumbnail_png_base64 (
str
representing a base64-encoded png file) – Thumbnail image.
- payload (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "put_gcode_file",
"params": {
"name": "test_cube.gco",
"payload": "<gcode>"
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"id": 3,
"name":"test_cube.gco"
}
}
get_gcode_file¶
-
MessageHandler.
get_gcode_file
(id, content=False)¶ Get details of a single gcode file with the given id.
Optionally include the gcode file content.
Parameters: - id (
int
) – ID of the gcode file to get. - content (
bool
(default False)) – Include the gcode file content in the results.
- id (
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "get_gcode_file",
"params": {
"id": 1
}
}
Example response:
{
"jsonrpc": "2.0",
"result": {
"size": 2914599,
"id": 1,
"name": "FE_Drakkar_Bow.gcode",
"uploaded": "2016-04-11 19:54:31.929633"
}
}
get_gcode_files¶
-
MessageHandler.
get_gcode_files
()¶ Get details of all gcode files.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "get_gcode_files",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"gcode_files": [
{
"size": 2914599,
"id": 1,
"name": "FE_Drakkar_Bow.gcode",
"uploaded": "2016-04-11 19:54:31.929633"
},
{
"size": 24356,
"id": 2,
"name": "10mm_Test_Cube.gcode",
"uploaded": "2016-04-12 13:24:15.345623"
}
]
}
}
delete_gcode_file¶
-
MessageHandler.
delete_gcode_file
(id)¶ Delete a single gcode file with the given id.
Parameters: id ( int
) – ID of the gcode file to delete.
Example request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "delete_gcode_file",
"params": {
"id": 3
}
}
Example response:
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
get_counters¶
-
MessageHandler.
get_counters
()¶ Get printer counter values.
Counters are listed in
opengb.database.COUNTERS
.
Example request:
{
"jsonrpc": "2.0",
"id": 2,
"method": "get_counters",
"params":{}
}
Example response:
{
"jsonrpc": "2.0",
"id": 2,
"result":{
"counters": {
"nozzle_2_up_mins":128,
"motor_x1_up_mins":128,
"motor_x2_up_mins":128,
"motor_y2_up_mins":128,
"nozzle_1_up_mins":128,
"motor_z2_up_mins":128,
"motor_z1_up_mins":128,
"printer_up_mins":128,
"printer_print_mins":46,
"bed_up_mins":128,
"motor_y1_up_mins":128,
"printer_up_mins_session":32
}
}
}
get_filesystem_utilization¶
-
MessageHandler.
get_filesystem_utilization
()¶ Get current filesystem utilization.
Example request:
{
"jsonrpc": "2.0",
"id": 3,
"method": "get_filesystem_utilization",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
'/': {
'free_bytes': 183485939712,
'total_bytes': 243515678720,
'utilized_bytes': 47636201472,
'utilized_percent': 19.6
},
'/boot': {
'free_bytes': 110014464,
'total_bytes': 246755328,
'utilized_bytes': 124001280,
'utilized_percent': 50.3
}
}
}
get_status¶
-
MessageHandler.
get_status
()¶ Get current printer status.
Note
This method should only be used to determine baseline printer status. To maintain a view of current printer status listen for the various jsonrpc events.
Example request:
{
"jsonrpc": "2.0",
"id": 4,
"method": "get_status",
"params": {}
}
Example response:
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"status": {
"progress": {
"current": 0,
"total": 0
},
"state": 20,
"position": {
"z": 0,
"y": 0,
"x": 0
},
"temp": {
"bed_current": 100,
"nozzle2_target": 0,
"bed_target": 0,
"nozzle1_target": 0,
"nozzle2_current": 209,
"nozzle1_current": 205
},
"steppers": {
"enabled": true
},
"extrude_override": {
"percent": 100
},
"speed_override": {
"percent": 120
},
"fan_speed": {
0: 100,
1: 75,
2: 0
}
}
}
}
Events¶
state_change¶
Sent when the printer status changes. Valid states are:
DISCONNECTED
READY
EXECUTING
PAUSED
FILAMENT_SWAP
ERROR
Example event:
{
"jsonrpc": "2.0",
"event": "state_change",
"params": {
"old": "READY",
"new": "EXECUTING"
}
}
extrude_override_change¶
Sent when the extrude override percentage changes.
Example event:
{
"jsonrpc": "2.0",
"event": "extrude_override_change",
"params": {
"percent": 120
}
}
speed_override_change¶
Sent when the movement speed override percentage changes.
Example event:
{
"jsonrpc": "2.0",
"event": "speed_override_change",
"params": {
"percent": 120
}
}
fan_speed_change¶
Sent when the speed of a fan changes.
Example event:
{
"jsonrpc": "2.0",
"event": "fan_speed_change",
"params": {
"fan": 1,
"percent": 75
}
}
temp_update¶
Sent periodically to provide current and target temperatures of printer components.
Note
Not all parameters of every temp_update will necessarily contain values. If a parameter’s value is null then the update does not contain any new data for that parameter and its value should be considered unchanged.
Example event:
{
"jsonrpc": "2.0",
"event": "temp_update",
"params": {
"bed_current": 205,
"bed_target": 0,
"nozzle1_current": 106,
"nozzle1_target": 0,
"nozzle2_current": 101,
"nozzle2_target": 0
}
}
position_update¶
Sent on print head movement to provide current print head position.
Example event:
{
"jsonrpc": "2.0",
"event": "position_update",
"params": {
"x": 100,
"y": 80,
"z": 20
}
}
progress_update¶
Sent periodically while printer is executing a gcode sequence.
Example event:
{
"jsonrpc": "2.0",
"event": "progress_update",
"params": {
"current_line": 327,
"total_lines": 4393
}
}
steppers_update¶
Sent when stepper motors are enabled/disabled.
Example event:
{
"jsonrpc": "2.0",
"event": "steppers_update",
"params": {
"enabled": true
}
}