diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md new file mode 100644 index 00000000..c3b095a7 --- /dev/null +++ b/RELEASE-NOTES.md @@ -0,0 +1,73 @@ +# OctoPrint Release Notes + +## 1.1.0 + +### New Features + +* New REST API, including User API Keys additionally to the global API key. Please note that **this will break existing + API clients** as it replaces the old API (same endpoint). You can find the documentation of the new API at + [docs.octoprint.org](http://docs.octoprint.org/en/1.1.0/api/index.html). +* New Event structure allows more flexibility regarding payload data, configuration files will be migrated automatically. + You can find the documentation of the new event format and its usage at [docs.octoprint.org](http://docs.octoprint.org/en/1.1.0/events/index.html). +* Support for multi extruder setups. With this OctoPrint now in theory supports an unlimited amount of extruders, however + for now it's artificially limited to 9. +* Log files can be accessed from within the browser via the Settings dialog ([#361](https://github.com/foosel/OctoPrint/pull/361)) +* Timelapses can now have a post-roll duration configured which will be rendered into the video too to not let it + end so abruptly ([#384](https://github.com/foosel/OctoPrint/issues/384)) +* The terminal tab now has a command history ([#388](https://github.com/foosel/OctoPrint/pull/388)) + +### Improvements + +* Stopping the application via Ctrl-C produces a less scary message ([#277](https://github.com/foosel/OctoPrint/pull/277)) +* Webcam stream is disabled when control tab is not in focus, reduces bandwidth ([#316](https://github.com/foosel/OctoPrint/issues/316)) +* M and G commands entered in Terminal tab are automatically converted to uppercase +* GCODE viewer now only loads automatically if GCODE file size is beneath certain threshold (different ones for desktop + and mobile devices), only actually loads file if user acknowledges that this might be too much for his browser +* Added time needed for printing file to PrintDone event's payload ([#333](https://github.com/foosel/OctoPrint/issues/333)) +* Also provide the filename (basename without the path) in print events +* Support for circular beds in the GCODE viewer ([#407](https://github.com/foosel/OctoPrint/pull/407)) +* The dimensions of the print bed can now be configured via the Settings ([#396](https://github.com/foosel/OctoPrint/pull/396)) +* Target temperature reporting format of Repetier Firmware is now supported as well ([360](https://github.com/foosel/OctoPrint/issues/360)) +* Version tracking now based on git tagging and [versioneer](https://github.com/warner/python-versioneer/). +* Made "Center viewport on model" and "Zoom in on model" in the GCODE viewer automatically deselect and de-apply if + viewport gets manipulated by the user ([#398](https://github.com/foosel/OctoPrint/issues/398)) +* GCODE viewer now interprets inverted axes for printer control and mirrors print bed accordingly ([#431](https://github.com/foosel/OctoPrint/issues/431)) +* Added `clean` command to `setup.py`, removes old build artifacts (mostly interesting for developers) +* Added version resource on API which reports application and API version +* Made the navbar static instead of fixed to improve usability on mobile devices ([#257](https://github.com/foosel/OctoPrint/issues/257)) +* Switch to password field upon enter in username field, submit login form upon enter in password field +* Changed default path to OctoPrint executable in included init-script to `/usr/local/bin/octoprint` (the default when + installing via `python setup.py install`) + +### Bug Fixes + +* Properly calculate time deltas (forgot to factor in days) +* [#35](https://github.com/foosel/OctoPrint/issues/35) - GCODE viewer has been modularized, options are now functional +* [#337](https://github.com/foosel/OctoPrint/issues/337) - Also recognize `--iknowwhatimdoing` when running as daemon +* [#357](https://github.com/foosel/OctoPrint/issues/357) - Do not run GCODE analyzer when a print is ongoing +* [#381](https://github.com/foosel/OctoPrint/issues/381) - Only list those SD files that have an ASCII filename +* Fixed a race condition that could occur when pressing "Print" (File not opened yet, but attempt to read from it) +* [#398](https://github.com/foosel/OctoPrint/issues/398) - Fixed interfering options in GCODE viewer +* [#399](https://github.com/foosel/OctoPrint/issues/399) & [360](https://github.com/foosel/OctoPrint/issues/360) - Leave + bed temperature unset when not detected (instead of dying a horrible death) +* [#492](https://github.com/foosel/OctoPrint/issues/492) - Fixed a race condition which could lead to an attempt to read + from an already closed serial port, causing an error to be displayed to the user +* [#257](https://github.com/foosel/OctoPrint/issues/257) - Logging in on mobile devices should now work +* [#476](https://github.com/foosel/OctoPrint/issues/476) - Also update the metadata correctly when an analysis finishes +* Various fixes of bugs in newly introduced features and improvements: + - [#314](https://github.com/foosel/OctoPrint/issues/314) - Use G28 for homing (G1 was copy and paste error) + - [#317](https://github.com/foosel/OctoPrint/issues/317) - Fixed "load and print" function + - [#326](https://github.com/foosel/OctoPrint/issues/326) - Fixed refresh of SD file list + - [#338](https://github.com/foosel/OctoPrint/issues/338) - Refetch file list when deleting a file + - [#339](https://github.com/foosel/OctoPrint/issues/339) - More error resilience when handling temperature offset data from the backend + - [#345](https://github.com/foosel/OctoPrint/issues/345) - Also recognize such temperature reports that do not contain a `T:` but a `T0:` + - [#377](https://github.com/foosel/OctoPrint/pull/377) - URLs in API examples fixed + - [#378](https://github.com/foosel/OctoPrint/pull/378) - Fixed crash of API call when `getStartTime()` returns None + - [#379](https://github.com/foosel/OctoPrint/pull/379) - Corrected response code for connection success + - [#414](https://github.com/foosel/OctoPrint/pull/414) - Fix style attribute for Actual column header + +([Commits](https://github.com/foosel/OctoPrint/compare/1.0.0...1.1.0)) + +## 1.0.0 + +First release with new versioning scheme. \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst index 7d296a1b..92a81195 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -8,6 +8,7 @@ API Documentation :maxdepth: 2 general.rst + version.rst fileops.rst connection.rst printer.rst diff --git a/docs/api/version.rst b/docs/api/version.rst new file mode 100644 index 00000000..47b0c56e --- /dev/null +++ b/docs/api/version.rst @@ -0,0 +1,32 @@ +.. _sec-api-version: + +******************* +Version information +******************* + +.. http:get:: /api/version + + Retrieve information regarding server and API version. Returns a JSON object with two keys, ``api`` containing + the API version, ``server`` containing the server version. + + **Example Request** + + .. sourcecode:: http + + GET /api/version HTTP/1.1 + Host: example.com + X-Api-Key: abcdef... + + **Example Response** + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "api": "0.1", + "server": "1.1.0" + } + + :statuscode 200: No error diff --git a/docs/events/index.rst b/docs/events/index.rst new file mode 100644 index 00000000..f264cd9d --- /dev/null +++ b/docs/events/index.rst @@ -0,0 +1,341 @@ +.. _sec-events: + +#################### +Events Documentation +#################### + +.. contents:: + +With release of OctoPrint 1.1.0, the payload data has been harmonized, it is now a key-value-map for all events. +Additionally, the format of the placeholders in both system command and gcode command triggers has been changed to +accommodate for this new format. Last but not least, the way of specifying event hooks has changed, OctoPrint no longer +separates hooks into two sections (gcodeCommandTrigger and systemCommandTrigger) but instead event hooks are now typed +to indicate what to do with the command contained. + +.. _sec-events-configuration: + +Configuration +============= + +Event hooks are configured via OctoPrint's configuration file ``config.yaml``. There they are contained in a +``subscriptions`` list located directly under the ``events`` node. The ``command`` node accepts either a single string +or a list of strings so that multiple commands can be executed in one go. Each hook carries an additional node type that +must be either ``gcode`` (for GCODE commands to be sent to the printer based on the event) or ``system`` (for commands to be +executed on the system OctoPrint is running on). + +All event hooks can be disabled completely by setting ``event > enabled`` to ``false``. You can also disable individual +hooks by setting the (optional) node ``enabled`` to false, see the example below. + +Example +------- + +.. sourcecode:: yaml + + events: + enabled: True + subscriptions: + - event: Disconnected + command: python ~/growl.py -t mygrowlserver -d "Lost connection to printer" -a OctoPrint -i http://raspi/Octoprint_logo.png + type: system + enabled: false + - event: PrintStarted + command: python ~/growl.py -t mygrowlserver -d "Starting {file}" -a OctoPrint -i http://raspi/Octoprint_logo.png + type: system + - event: PrintDone + command: python ~/growl.py -t mygrowlserver -d "Completed {file}" -a OctoPrint -i http://raspi/Octoprint_logo.png + type: system + - event: Connected + command: + - M115 + - M117 printer connected! + - G28 + type: gcode + +.. _sec-events-placeholders: + +Placeholders +============ + +You can use the following generic placeholders in your events: + + * ``{__currentZ}``: the current Z position of the head if known, -1 if not available + * ``{__filename}``: filename of the currently selected file, "NO FILE" if not available + * ``{__progress}``: the progress of the print in percent, 0 if not available + * ``{__data}``: a string representation of the payload + * ``{__now}``: the date and time of the event in ISO 8601 + +Additionally, all data from the payload can be accessed by its key. Example: If the payload happens to be defined +something like this: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +then you'll be able to access the filename via the placeholder ``{file}`` and the origin via the placeholder ``{origin}``. + + +.. _sec-events-available_events: + +Available Events +================ + +Server +------ + +Startup + The server has started + +ClientOpened + A client has connected to the web server. + + Payload: + + * ``remoteAddress``: the remote address (IP) of the client that connected + + **Note:** Name changed in version 1.1.0 + +ClientClosed + A client has disconnected from the webserver + +Printer communication +--------------------- + +Connected + The server has connected to the printer. + + Payload: + + * ``port``: the connected serial port + * ``baudrate``: the baud rate + +Disconnected + The server has disconnected from the printer + +Error + An error has occurred in the printer communication. + + Payload: + + * ``error``: the error string + +File handling +------------- + +Upload + A file has been uploaded. + + Payload: + * ``file``: the file's name + * ``target``: the target to which the file was uploaded, either ``local`` or ``sdcard`` + +UpdatedFiles + A file list was modified. + + Payload: + + * ``type``: the type of file list that was modified, currently only ``gcode`` is supported here + +MetadataAnalysisStarted + The metadata analysis of a GCODE file has started. + + Payload: + + * ``file``: the file's name + +MetadataAnalaysisFinished + The metadata analysis of a GCODE file has finished. + + Payload: + + * ``file``: the file's name + * ``result``: the analysis result -- this is a python object currently only available for internal use + +FileSelected + A GCODE file has been selected for printing. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +FileDeselected + No file is selected any more for printing. + +TransferStarted + A GCODE file transfer to SD has started. + + Payload: + + * ``local``: the file's name as stored locally + * ``remote``: the file's name as stored on SD + + **Note:** Name changed in version 1.1.0 + +TransferDone + A GCODE file transfer to SD has finished. + + Payload: + + * ``time``: the time it took for the transfer to complete in seconds + * ``local``: the file's name as stored locally + * ``remote``: the file's name as stored on SD + +Printing +-------- + +PrintStarted + A print has started. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +PrintFailed + A print failed. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +PrintDone + A print completed successfully. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + * ``time``: the time needed for the print, in seconds (float) + +PrintCancelled + The print has been cancelled via the cancel button. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +PrintPaused + The print has been paused. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +PrintResumed + The print has been resumed. + + Payload: + + * ``file``: the file's name + * ``origin``: the origin of the file, either ``local`` or ``sdcard`` + +GCODE processing +---------------- + +PowerOn + The GCode has turned on the printer power via M80 + +PowerOff + The GCODE has turned on the printer power via M81 + +Home + The head has gone home via G28 + +ZChange + The printer's Z-Height has changed (new layer) + +Paused + The print has been paused + +Waiting + The print is paused due to a gcode wait command + +Cooling + The GCODE has enabled the platform cooler via M245 + +Alert + The GCODE has issued a user alert (beep) via M300 + +Conveyor + The GCODE has enabled the conveyor belt via M240 + +Eject + The GCODE has enabled the part ejector via M40 + +EStop + The GCODE has issued a panic stop via M112 + +Timelapses +---------- + +CaptureStart + A timelapse image has started to be captured. + + Payload: + + * ``file``: the name of the image file to be saved + +CaptureDone + A timelapse image has completed being captured. + + Payload: + * ``file``: the name of the image file that was saved + +MovieRendering + The timelapse movie has started rendering. + + Payload: + + * ``gcode``: the GCODE file for which the timelapse would have been created (only the filename without the path) + * ``movie``: the movie file that is being created (full path) + * ``movie_basename``: the movie file that is being created (only the file name without the path) + +MovieDone + The timelapse movie is completed. + + Payload: + + * ``gcode``: the GCODE file for which the timelapse would have been created (only the filename without the path) + * ``movie``: the movie file that has been created (full path) + * ``movie_basename``: the movie file that has been created (only the file name without the path) + +MovieFailed + There was an error while rendering the timelapse movie. + + Payload: + + * ``gcode``: the GCODE file for which the timelapse would have been created (only the filename without the path) + * ``movie``: the movie file that would have been created (full path) + * ``movie_basename``: the movie file that would have been created (only the file name without the path) + * ``returncode``: the return code of ``ffmpeg`` that indicates the error that occurred + +Slicing +------- + +SlicingStarted + The slicing of a file has started. + + Payload: + + * ``stl``: the STL's filename + * ``gcode``: the sliced GCODE's filename + +SlicingDone + The slicing of a file has completed. + + Payload: + + * ``stl``: the STL's filename + * ``gcode``: the sliced GCODE's filename + * ``time``: the time needed for slicing, in seconds (float) + +SlicingFailed + The slicing of a file has failed. + + Payload: + + * ``stl``: the STL's filename + * ``gcode``: the sliced GCODE's filename + * ``reason``: the reason for the slicing having failed diff --git a/docs/index.rst b/docs/index.rst index 87f940b4..8fb692dd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,4 +22,5 @@ Contents :maxdepth: 2 api/index.rst + events/index.rst