From ee7d22870874f9c5e49d5458ba4d340e0dce1e2e Mon Sep 17 00:00:00 2001 From: David Crocker Date: Sat, 14 Dec 2019 17:00:55 +0000 Subject: Still 3.0RC1 provisional Bug fix: not all extrusion amounts were being cleared when preparing a move --- HTTP requests.md | 349 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 HTTP requests.md (limited to 'HTTP requests.md') diff --git a/HTTP requests.md b/HTTP requests.md new file mode 100644 index 00000000..2f12e1c4 --- /dev/null +++ b/HTTP requests.md @@ -0,0 +1,349 @@ +# 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. + +## 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 + +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" +} +``` + +- `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 || +| duet3mb6hc | Duet 3 v0.6 || + +## 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`. + +## GET /rr_status + +Retrieve a status response from RepRapFirmware in JSON format. + +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](JSON%20Responses.md) for further information. + +## Get /rr_config + +Retrieve the configuration response. This request provides a JSON object with values that are expected to change rarely. + +See [JSON responses](JSON%20Responses.md) 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. + +## 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). + +The G-code reply is returned as `text/plain`. + +## 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. + +## POST /rr_upload + +Upload a file. + +Supported URL parameters: + +- `name`: Path to the file to upload +- `time` (optional): ISO8601-like represenation 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). + +## 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. + +## GET /rr_delete + +Delete a file or directory. + +Supported parameters: + +- `name`: Filename to delete + +Returns + +``` +{ + "err": {code} +} +``` + +where code is either `0` on success or `1` on error. + +## GET /rr_filelist + +Retrieve a (partial) file list. + +Supported parameters: + +- `dir`: Directory to query +- `first` (optional): First item index to return. Defaults to `0` + +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 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_filelist` request. + +Retrieved files are returned as part of the `files` array. Note that `date` may not be present if it is invalid. Every item has the following properties: + +- `itemType`: Type of the file item. This is `d` for directories and `f` for files +- `itemName`: Name of the file or directory +- `itemSize`: Size of the file. This is always `0` for directories +- `itemDate`: Datetime of the last file modification + +## 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` +- `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. + +## 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. + +## 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. + +## 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, + "firstLayerHeight": firstLayerHeight, + "layerHeight": layerHeight, + "printTime": printTime, + "simulatedTime": simulatedTime, + "filament": filament, + "printDuration": printDuration, + "fileName": fileName, + "generatedBy": generatedBy +} +``` + +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 | +| firstLayerHeight | mm | Height of the first layer | 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 | no | +| fileName | file path | Absolute path to the file being printed | not applicable | no | +| generatedBy | text | Slicer or toolchain which generated this file | empty string | yes | -- cgit v1.2.3