HTTP requests

List of supported HTTP requests

RepRapFirmware provides an HTTP interface for dealing with client requests. These requests are tailored for Duet Web Control in the first place but they may be used by third-party applications, too.

Every request except for rr_connect returns HTTP status code 401 if the client does not have a valid session. If no machine password is set, a user session is created whenever an arbitrary HTTP request is made. Besides, RepRapFirmware may run short on memory and may not be able to respond properly. In this case, HTTP status code 503 is returned.

In the following requests datetime strings may be used. These datetime strings are very similar to ISO8601-encoded strings but they do not contain timezone details. An example for such a string is 2019-12-13T21:27:00. Make sure to follow this format where applicable.

Note: Starting from v3.4.1 there are OpenAPI definition files for SBC and standalone mode. If you are using .NET, check out the DuetHttpClient package. If you want to explore the api using swagger, paste the .yaml file into : https://editor.swagger.io/

GET /rr_connect

Attempt to create a new connection and log in using the (optional) password.

Supported parameters:

password (optional): Machine password to log in with. If omitted, this defaults to reprap
time (optional): Current datetime that will be used to update RepRapFirmware's internal clock
sessionKey (optional): Either yes or no, if set to yes, RRF will generate a unique HTTP session (supported in RRF 3.5-b4 and later)

Returns

{
    "err": code
}

where code may be one of the following:

0: Password is valid and the client's IP address is added to the list of HTTP sessions
1: Password is invalid
2: No more user sessions available. This may occur when too many client devices are connected at the same time

If the password is valid, extra fields are returned:

{
    "err": 0,
    "sessionTimeout": 8000,
    "boardType": "duetwifi102",
    "sessionKey": 123456
}

sessionTimeout is the idle timeout in milliseconds before a client is removed again from the list of client sessions
boardType represents the board's type

Officially supported board types are:

boardType	Board	Remarks
duet06	Duet 0.6	deprecated
duet07	Duet 0.7	deprecated
duet085	Duet 0.8.5	deprecated
duetwifi10	Duet WiFi v1.0
duetwifi102	Duet WiFi v1.02
duetethernet10	Duet Ethernet v1.0
duetethernet102	Duet Ethernet v1.02
duetmaestro100	Duet Maestro v1.0
duet3mb6hc100	Duet 3 MB6HC v0.6 and v1.0
duet3mb6hc101	Duet 3 MB6HC v1.01
duet3mb6xd	Duet 3 MB6XD v1.0
duet5lcwifi	Duet 3 Mini 5+ WiFi
duet5lcethernet	Duet 3 Mini 5+ Ethernet

HTTP Client:

A HTTP Client is defined as a source IP address connecting to the HTTP Interface. If you have multiple applications that need to connect to the HTTP interface then they should be bound to a different IP address or use some other mechanism to manage replies.

HTTP Sessions:

Up to v3.5-b3 only one session per IP / HTTP Client is supported, further calls to rr_connect when an active session exists will be result in a "err" code of "0" returned but no additional session will be created. The same limitation applies if a client connects in 3.5-b4 and later if no sessionKey parameter with value yes is present. If a session key is used, the client must set the X-Session-Key header to the returned sessionKey value in all following HTTP requests in order to authenticate itself.

Since IP-based sessions cannot keep the G-code reply for more than a single session per IP address, the usage of session keys is encouraged in v3.5-b4 and later.

example /rr_connect

curl http://<address>/rr_connect?password=

GET /rr_disconnect

Disconnect again from the RepRapFirmware controller.

Returns

{
    "err": code
}

where code may be 0 if the session could be removed, else it is 1.

example /rr_disconnect

curl http://<address>/rr_disconnect

GET /rr_status (deprecated, scheduled for removal in RRF 3.6)

Retrieve a status response from RepRapFirmware in JSON format. Deprecated in RRF 3.0 and later, use rr_model instead.

Supported parameters:

type: Type of the status response

The value of type can be one of:

1: Standard status response
2: Advanced status response. This also contains fields from the standard status response
3: Print status response. This contains fields from the standard status response as well as information about the current (print) job

See JSON responses for further information.

Get /rr_config (deprecated, scheduled for removal in RRF 3.6)

Retrieve the configuration response. This request provides a JSON object with values that are expected to change rarely. Deprecated in RRF 3.0 and later, use rr_model instead.

See JSON responses for further information.

GET /rr_gcode

Execute arbitrary G/M/T-code(s).

Supported parameters:

gcode: G/M/T-code to execute. This parameter must be present although it can be empty

Returns

{
    "buff": bufferSpace
}

where bufferSpace indicates how much buffer space for new G/M/T-codes is still available.

If a file is supposed to be streamed over the HTTP interface, call this repeatedly and transfer only as many bytes as allowed.

example /rr_gcode

curl http://<address>/rr_connect?password=
curl http://<address>/rr_gcode?gcode=G28

GET /rr_reply

Retrieve the last G-code reply. The G-code reply is buffered per connected HTTP client and it is discarded when every HTTP client has fetched it or when the firmware is short on memory and the client has not requested it within reasonable time (1 second).

Client should keep querying rr_model?key=seqs and monitor seqs.reply. When its value is incremented, that means there is new reply data available to fetch.

The G-code reply is always returned as text/plain.

example /rr_reply

in this example we send the M115 gcode in order to generate a reply to fetch

curl http://<address>/rr_connect?password=
curl http://<address>/rr_gcode?gcode=M115
curl http://<address>/rr_reply

GET /rr_upload

Get the last file upload result.

Returns

{
    "err": code
}

where code can be either 0 if the last upload successfully finished or 1 if an error occurred.

example GET /rr_upload

assuming sent immediately after a file upload

curl http://<address>/rr_upload

POST /rr_upload

Upload a file.

Supported URL parameters:

name: Path to the file to upload
time (optional): ISO8601-like representation of the time the file was last modified
crc32 (optional): CRC32 checksum of the file content as hex string without leading 0x. Usage of this parameter is encouraged

The raw HTTP body contains the file content. Binary file uploads are supported as well. Make sure to set Content-Length to the length of the HTTP body if your HTTP client does not already do that.

Returns

{
    "err": code
}

where code can be either 0 if the last upload successfully finished or 1 if an error occurred (e.g. CRC mismatch).

example POST /rr_upload

curl http://<address>/rr_connect?password=
curl --data-binary @"<path_and_filename.gcode>" "http://<address>/rr_upload?name=/gcodes/<filename.gcode>"

GET /rr_download

Download a file.

Supported parameters:

name: Filename to download

If the file could not be found, HTTP status code 404 is returned, else the file content is sent to the client.

example /rr_download

curl http://<address>/rr_connect?password=
curl "http://<address>/rr_download?name=/sys/config.g" > <path_to_config_backup>/config.g

GET /rr_delete

Delete a file or directory.

Supported parameters:

name: Filename to delete
recursive (optional): Set this to yes to delete the directory recursively if applicable. Defaults to no (requires 3.5b3 and newer)

Returns

{
    "err": {code}
}

where code is either 0 on success or 1 on error.

example /rr_delete

curl http://<address>/rr_connect?password=
curl "http://<address>/rr_delete?name=/macros/<file to delete>"

GET /rr_filelist

Retrieve a (partial) file list.

Supported parameters:

dir: Directory to query
first (optional): First item index to return. Defaults to 0
max (optional): Maximum number of items to return (RRF 3.6.0-beta.2 and newer). Defaults to -1

Returns

{
    "dir": dir,
    "first": first,
    "files": [
        {
            "type": itemType,
            "name": itemName,
            "size": itemSize,
            "date": itemDate
        },
        ...
    ],
    "next": next,
    "err": code
}

where dir and first equal the query parameters. err can be one of:

0: List query successful
1: Drive is not mounted
2: Directory does not exist

The next field may be missing if the query was not successful. It is 0 if there are no further items. If there are more items than could be returned, this value should be used for the first parameter of a following rr_filelist request to retrieve the next block of items.

Retrieved files are returned as part of the files array. Every item has the following properties, except that date may not be present if it is invalid:

type: Type of the file item. This is d for directories and f for files
name: Name of the file or directory
size: Size of the file. This is always 0 for directories
date: Datetime of the last file modification

example /rr_filelist

curl http://<address>/rr_connect?password=
curl http://<address>/rr_filelist?dir=/macros/

GET /rr_files

Retrieve a list of files without any attributes.

Supported parameters:

dir: Directory to query
first (optional): First item index to return. Defaults to 0
max (optional): Maximum number of items to return (RRF 3.6.0-beta.2 and newer). Defaults to -1
flagDirs (optional): Set this to 1 to prefix directory items with *. Defaults to 0

Returns

{
    "dir": dir,
    "first": first,
    "files": [
        "file1",
        "file2",
        ...
    ],
    "next": next,
    "err": err
}

where dir and first equal the query parameters. err can be one of:

0: List query successful
1: Drive is not mounted
2: Directory does not exist

The next field may be omitted if the query was not successful and it is 0 if the query has finished. If there are more items to query, this value can be used for the first parameter of a successive rr_files request.

example /rr_files

curl http://<address>/rr_connect?password=
curl http://<address>/rr_files?dir=/macros/

GET /rr_model

Retrieve object model information like M409. Supported in RRF 3. and later.

Supported parameters:

key: Key to query
flags: Query flags

Returns

{
    "key": <key>,
    "flags": <flags>,
    "result": <object model JSON>
}

or HTTP code 503 if the response could not be written due to a lack of memory.

The flags string may include one or more of the following letters (see the M409 documentation linked above for more information):

f: return only those values in the object model that typically change frequently during a job v: Verbose: include values that are rarely needed and not normally returned n: include fields with null values o: include obsolete fields (v3.3 and newer) d: limit the depth of the reported tree to the specified number following the letter d. Objects at the maximum depth will be returned as {}.

example /rr_model

curl http://<address>/rr_connect?password=
curl http://<address>/rr_model?key=boards[0]

GET /rr_move

Move a file or directory.

Supported parameters:

old: Current path to the file or directory
new: New path of the file or directory
deleteexisting (optional): Set this to yes to delete the new file if it already exists. Defaults to no

Returns

{
    "err": code
}

where code is either 0 on success or 1 on error.

example /rr_move

curl http://<address>/rr_connect?password=
curl -G http://<address>/rr_move -d old="/macros/<file name>" -d new="/sys/<file name>"

GET /rr_mkdir

Create a new directory.

Supported parameters:

dir: Path to the new directory

Returns

{
    "err": code
|

where code is either 0 on success or 1 on error.

example /rr_mkdir

curl http://<address>/rr_connect?password=
curl http://<address>/rr_mkdir?dir=/macros/sub_directory

GET /rr_fileinfo

Parse a G-code job file and return retrieved information. If no file is specified, information about the file being printed is returned.

Supported parameters:

name (optional): Path to the file to parse

Returns

{
    "err": code,
    "size": size,
    "lastModified": lastModified,
    "height": height,
    "layerHeight": layerHeight,
    "printTime": printTime,
    "simulatedTime": simulatedTime,
    "filament": filament,
    "printDuration": printDuration,
    "fileName": fileName,
    "generatedBy": generatedBy,
    "thumbnails": [{width: 0, height: 0, format: "png", offset: 0, size: 0}, ...]
}

where code is either 0 on success or 1 on error. If the file could not be parsed, all other fields are omitted.

Other fields are:

Field	Unit	Description	Default value if invalid	Present if `name` is omitted
size	bytes	Size of the file in bytes	not applicable	yes
lastModified	datetime	Datetime of the last file modification	omitted	maybe
height	mm	Final print height of the object	0.00	yes
layerHeight	mm	Layer height	0.00	yes
printTime	seconds	Estimated print time	omitted	maybe
simulatedTime	seconds	Estimated print time according to the last simulation	omitted	maybe
filament	array of mm	Total filament consumption per extruder	empty array	yes
printDuration	seconds	Total print time so far	not applicable	yes
fileName	file path	Absolute path to the file being printed	not applicable	yes
generatedBy	text	Slicer or toolchain which generated this file	empty string	yes
thumbnails	array	Info about embedded thumbnails	empty array	yes

example /rr_fileinfo

curl http://<address>/rr_connect?password=
curl http://<address>/rr_fileinfo?name=/gcodes/<print_file_name>

GET /rr_thumbnail

Query a thumbnail from a G-code file.

Supported parameters:

name: Path to the file to query
offset: Start offset of the thumbnail to query (from rr_fileinfo response)

the offset parameter should be retreved from the rr_fileinfo response, e.g.

"thumbnails":[{"width":30,"height":30,"format":"qoi","offset":106,"size":3348},{"width":300,"height":300,"format":"qoi","offset":3644,"size":37148}]

two thumbnails are present in the above example, one starting at 106 and the other at 3644

Returns:

{
  "fileName": name,
  "offset": offset,
  "data": "base64-encoded thumbnail data",
  "next": 0,
  "err": 0
}

where next is the offset of the following data or 0 if the thumbnail is complete and err indicates an error if present (non-zero on error).

example /rr_thumbnail

curl http://<address>/rr_connect?password=
curl -G http://<address>/rr_rr_thumbnail -d name=/gcodes/<print_file_name> -d offset=106

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HTTP requests

List of supported HTTP requests

GET /rr_connect

HTTP Client:

HTTP Sessions:

example /rr_connect

GET /rr_disconnect

example /rr_disconnect

GET /rr_status (deprecated, scheduled for removal in RRF 3.6)

Get /rr_config (deprecated, scheduled for removal in RRF 3.6)

GET /rr_gcode

example /rr_gcode

GET /rr_reply

example /rr_reply

GET /rr_upload

example GET /rr_upload

POST /rr_upload

example POST /rr_upload

GET /rr_download

example /rr_download

GET /rr_delete

example /rr_delete

GET /rr_filelist

example /rr_filelist

GET /rr_files

example /rr_files

GET /rr_model

example /rr_model

GET /rr_move

example /rr_move

GET /rr_mkdir

example /rr_mkdir

GET /rr_fileinfo

example /rr_fileinfo

GET /rr_thumbnail

example /rr_thumbnail

Clone this wiki locally