diff --git a/docs/bundledplugins/cura.rst b/docs/bundledplugins/cura.rst new file mode 100644 index 00000000..a2f84de9 --- /dev/null +++ b/docs/bundledplugins/cura.rst @@ -0,0 +1,122 @@ +.. _sec-bundledplugins_cura: + +Cura +==== + +The Cura Plugin allows slicing of STL files uploaded to OctoPrint directly via +the `CuraEngine `_ **up to and +including version 15.04** and supersedes the slicing support integrated into +OctoPrint so far. + +.. note:: + + The current development version of CuraEngine has changed its calling + parameters in such a way that the current implementation of the Cura plugin + is not compatible to it. Until the plugin can be updated to be compatible + to these changes, please use only CuraEngine versions up to and including + 15.04 (or the ``legacy`` branch in the CuraEngine repository). + +The plugin offers a settings module that allows configuring the path to the +CuraEngine executable to use, as well as importing and managing slicing +profiles to be used. Please note that the Cura Plugin will use the printer +parameters you configured within OctoPrint (meaning bed size and extruder +count and offsets) for slicing. + +.. _sec-bundledplugins-cura-firststeps: + +First Steps +----------- + +Before you can slice from within OctoPrint, you'll need to + + #. :ref:`Install CuraEngine ` + #. :ref:`Configure the path to CuraEngine within OctoPrint ` + #. :ref:`Export a slicing profile from Cura and import it within OctoPrint ` + +.. note:: + + OctoPi 0.12.0 ships with steps 1 and 2 already done, you only need to + supply one or more slicing profiles to get going :) + +.. _sec-bundledplugins-cura-installing: + +Installing CuraEngine +--------------------- + +You'll need a current build of `CuraEngine `_ +in order to be able to use the Cura OctoPrint plugin. If you are running OctoPrint +on a desktop PC (Window, Mac, i386 Linux), you can take this from a full +install of `Cura `_ (you'll find it in the +installation directory). Otherwise you'll need to compile it yourself. + +If you previously used the `old variant of the Cura integration `_, +you probably still have a fully functional binary lying around in the +installation folder of the full install of Cura you used then -- just put the +path to that in the plugin settings. + +.. _sec-bundledplugins-cura-installing-raspbian: + +Compiling for Raspbian +++++++++++++++++++++++ + +.. note:: + + A binary of CuraEngine 14.12 precompiled on Raspbian 2015-01-31 is available + `here `_. Don't forget to make it + executable after copying it to your preferred destination on your Pi + (suggestion: ``/usr/local/bin``) with ``chmod +x cura_engine``. Use at your + own risk. + +You'll need to install a new version of gcc and g++ and patch CuraEngine's +Makefile (see `this post `_) +in order for the compilation to work on current Raspbian builds (e.g. OctoPi):: + + sudo apt-get -y install gcc-4.7 g++-4.7 + git clone -b legacy https://github.com/Ultimaker/CuraEngine.git + cd CuraEngine + wget http://bit.ly/curaengine_makefile_patch -O CuraEngine.patch + patch < CuraEngine.patch + make CXX=g++-4.7 + +After this has completed, you'll find your shiny new build of CuraEngine in +the `build` folder (full path for above example: +``~/CuraEngine/build/CuraEngine``). + +.. _sec-bundledplugins-cura-configuring: + +Configuring the plugin +---------------------- + +The Cura plugin needs to be configured with the full path to your copy of the +CuraEngine executable that it's supposed to use. You can do this either via +the Cura plugin settings dialog or by manually configuring the path to the +executable via ``config.yaml``, example: + +.. code-block:: yaml + + plugins: + cura: + cura_engine: /path/to/CuraEngine + +.. _sec-bundledplugins-cura-profiles: + +Using Cura Profiles +------------------- + +The Cura Plugin supports importing your existing profiles for Cura **up to and +including Cura 15.04**. Newer Cura releases (e.g. 15.06) do not allow to +export the slicing profile anymore and also use a different internal format +that will *not* work with the current version of the Cura Plugin. + +In order to export a slicing profile from the Cura desktop UI, open it, +set up your profile, then click on "File" and there on "Save Profile". You can +import the .ini-file this creates via the "Import Profile" button in the +Cura Settings within OctoPrint. + +.. _sec-bundledplugins-cura-sourcecode: + +Source code +----------- + +The source of the Cura plugin is bundled with OctoPrint and can be found in +its source repository under ``src/octoprint/plugins/cura``. diff --git a/docs/bundledplugins/discovery.rst b/docs/bundledplugins/discovery.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/bundledplugins/index.rst b/docs/bundledplugins/index.rst new file mode 100644 index 00000000..d5935a96 --- /dev/null +++ b/docs/bundledplugins/index.rst @@ -0,0 +1,13 @@ +.. _sec-bundledplugins: + +############### +Bundled Plugins +############### + +.. toctree:: + :maxdepth: 2 + + cura.rst + discovery.rst + pluginmanager.rst + softwareupdate.rst diff --git a/docs/bundledplugins/pluginmanager.rst b/docs/bundledplugins/pluginmanager.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/bundledplugins/softwareupdate.rst b/docs/bundledplugins/softwareupdate.rst new file mode 100644 index 00000000..fcbe49ac --- /dev/null +++ b/docs/bundledplugins/softwareupdate.rst @@ -0,0 +1,341 @@ +.. sec-bundledplugins-softwareupdate: + +Software Update Plugin +====================== + +The Software Update Plugin allows receiving notifications about new releases +of OctoPrint or installed plugins which registered with it and -- if properly +configured -- also applying the found updates. + +.. sec-bundledplugins-softwareupdate-firststeps: + +First Steps +----------- + +Out of the box the Software Update Plugin will be able to notify you of any +updates that might be available for your OctoPrint installation or any plugins +that registered themselves with it. In order to also be able to update +your OctoPrint installation, you'll need to :ref:`configure ` +at least OctoPrint's checkout folder, and you also should +configure the restart commands for OctoPrint and the whole server. + +.. sec-bundledplugins-softwareupdate-octoprintsetup: + +Making OctoPrint updateable on existing installations ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + OctoPi releases 0.12.0 and later ship with this already setup for you! + +.. note:: + + **OctoPi 0.11.0 users**: Please also take a look at + `the note at the very end of this FAQ entry `_. + Due to a little issue in that OctoPi release 0.11.0 you might have to fix + the URL your OctoPrint checkout is using for updating. This can easily be + done by SSHing into your OctoPi instance and doing this:: + + cd ~/OctoPrint + git remote set-url origin https://github.com/foosel/OctoPrint.git + +If you updated OctoPrint to 1.2.0 or later from a previous existing install, +you'll probably want to set up its software update configuration to allow it +to update itself from now on. For this you'll need to edit ``config.yaml`` and +make it look like this (``# ...`` indicates where your ``config.yaml`` might +contain additional lines that are not of interest here): + +.. code-block:: yaml + + # ... + plugins: + # ... + softwareupdate: + # ... + checks: + # ... + octoprint: + update_folder: /home/pi/OctoPrint + # ... + octoprint_restart_command: sudo service octoprint restart + environment_restart_command: sudo shutdown -r now + # ... + +.. note:: + + You can copy and paste this YAML snippet into the `Yamlpatcher `_ + to apply it to your ``config.yaml`` without having to edit it manually. Your + preview should look something like the screenshot below. + + .. image:: ../images/bundledplugins-softwareupdate-yaml_octoprintsetup.png + :align: center + :alt: Yamlpatcher preview + +If you are not running OctoPi or didn't setup OctoPrint following the +`Raspberry Pi setup guide `_ +you'll need to substitute ``/home/pi/OctoPrint`` with the folder you originally +cloned OctoPrint into during initial setup. + +Save the file, exit the editor, restart OctoPrint. Whenever new releases +become available, you should now be able to update right from the update +notification. + +.. sec-bundledplugins-softwareupdate-configuration: + +Configuring the Plugin +---------------------- + +.. code-block:: yaml + + plugins: + softwareupdate: + # the time-to-live of the version cache, in minutes + cache_ttl: 60 + + # command to restart OctoPrint (no automatic restart if unset) + octoprint_restart_command: sudo service octoprint restart + + # command to reboot OctoPrint's host (no automatic reboot if unset) + environment_restart_command: sudo shutdown -r now + + # configured version check and update methods + checks: + # "octoprint" is reserved for OctoPrint + octoprint: + # this defines an version check that will check against releases + # published on OctoPrint's Github repository and an update method + # utilizing an (included) update script that will be run on + # OctoPrint's checkout folder + type: github_release + user: foosel + repo: OctoPrint + update_script: '{python} "/path/to/octoprint-update.py" --python="{python}" "{folder}" "{target}"' + update_folder: /path/to/octoprint/checkout/folder + + # further checks may be define here + +.. sec-bundledplugins-softwareupdate-configuration-versionchecks: + +Version checks +++++++++++++++ + + * ``github_release``: Checks against releases published on Github. Additional + config parameters: + + * ``user``: (mandatory) Github user the repository to check belongs to + * ``repo``: (mandatory) Github repository to check + * ``prerelease``: ``True`` or ``False``, default ``False``, set to + ``True`` to also include releases on Github marked as prerelease. + * ``release_compare``: Method to use to compare between current version + information and release versions on Github. One of ``python`` (version + comparison using ``pkg_resources.parse_version``, newer version detected + if remote > current), ``semantic`` (version comparison using + ``semantic_version`` package, newer version detected if remote > current) + and ``unequal`` (string comparison, newer version detected if + remote != current). + + * ``github_commit``: Checks against commits pushed to Github. Additional + config parameters: + + * ``user``: (mandatory) Github user the repository to check belongs to + * ``repo``: (mandatory) Github repository to check + * ``branch``: Branch of the Github repository to check, defaults to + ``master`` if not set. + + * ``git_commit``: Checks a local git repository for new commits on its + configured remote. Additional config parameters: + + * ``checkout_folder``: (mandatory) The full path to the folder with a valid git + repository to check. + + * ``command_line``: Uses a provided script to determine whether an update + is available. Additional config parameters: + + * ``command``: (mandatory) The full path to the script to execute. The script is + expected to return a ``0`` return code if an update is available and to + return the display name of the available version as the final and + optionally the display name of the current version as the next to final + line on stdout. + + * ``python_checker``: Can only be specified by plugins through the + :ref:`hook `. Additional config + parameters: + + * ``python_checker``: (mandatory) A python callable which returns version + information and whether the current version is up-to-date or not, see + below for details. + +.. sec-bundledplugins-softwareupdate-configuration-updatemethods: + +Update methods +++++++++++++++ + + * ``pip``: An URL to provide to ``pip install`` in order to perform the + update. May contain a placeholder ``{target}`` which will be the most + recent version specifier as retrieved from the update check. + * ``update_script``: A script to execute in order to perform the update. May + contain placeholders ``{target}`` (for the most recent version specified + as retrieved from the update check), ``{folder}`` for the working directory + of the script and ``{python}`` for the python executable OctoPrint is + running under. The working directory must be specified either by an + ``update_folder`` setting or if the ``git_commit`` check is used its + ``checkout_folder`` setting. + * ``python_updater``: Can only be specified by plugins through the + :ref:`hook `. A python callable + which performs the update, see below for details. + +.. sec-bundledplugins-softwareupdate-configuration-patterns: + +Common configuration patterns ++++++++++++++++++++++++++++++ + +Example for a setup that allows "bleeding edge" updates of OctoPrint under +OctoPi (the ``update_script`` gets configured correctly automatically by the +plugin itself): + +.. code-block:: yaml + + plugins: + softwareupdate: + checks: + octoprint: + type: github_commit + user: foosel + repo: OctoPrint + branch: devel + update_folder: /home/pi/OctoPrint + +Plugin installed via pip and hosted on Github under +``https://github.com/someUser/OctoPrint-SomePlugin``, only releases should be +tracked: + +.. code-block:: yaml + + plugins: + softwareupdate: + checks: + some_plugin: + type: github_release + user: someUser + repo: OctoPrint-SomePlugin + pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip' + +The same, but tracking all commits pushed to branch ``devel`` (thus allowing +"bleeding edge" updates): + +.. code-block:: yaml + + plugins: + softwareupdate: + checks: + some_plugin: + type: github_commit + user: someUser + repo: OctoPrint-SomePlugin + branch: devel + pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip' + +.. sec-bundledplugins-softwareupdate-hooks: + +Hooks +----- + +.. sec-bundledplugins-softwareupdate-hooks-check_config: + +octoprint.plugin.softwareupdate.check_config +++++++++++++++++++++++++++++++++++++++++++++ + +.. py:function:: update_config_hook(*args, **kwargs) + + Returns additional check configurations for the Software Update plugin. + + Handlers should return a Python dict containing one entry per check. Usually + this will probably only be the check configuration for the plugin providing + the handler itself, using the plugin's identifier as key. + + The check configuration must match the format expected in the configuration + (see description above). Handlers may also utilize the ``python_checker`` + and ``python_updater`` properties to return Python callables that take care + of performing the version check or the update. + + ``python_checker`` is expected to be a callable matching signature and return + value of the ``get_latest`` methods found in the provided version checkers in + ``src/octoprint/plugins/softwareupdate/version_checks``. ``python_updater`` + is expected to be a callable matching signature and return value of the + ``perform_update`` methods found in the provided updaters in + ``src/octoprint/plugins/softwareupdate/updaters``. + + **Example** + + The example single-file-plugin updates itself from Github releases published + at the (fictional) repository ``https://github.com/someUser/OctoPrint-UpdatePluginDemo``. + + .. code-block:: python + + # coding=utf-8 + from __future__ import absolute_import + + def get_update_information(*args, **kwargs): + return dict( + updateplugindemo=dict( + displayName=self._plugin_name, + displayVersion=self._plugin_version, + + type="github_release", + current=self._plugin_version, + user="someUser", + repo="OctoPrint-UpdatePluginDemo", + + pip="https://github.com/someUser/OctoPrint-UpdatePluginDemo/archive/{target}.zip" + ) + ) + + __plugin_hooks__ = { + "octoprint.plugin.softwareupdate.check_config": get_update_information + } + + :return: A dictionary of check configurations as described above + :rtype: dict + +.. sec-bundledplugins-softwareupdate-helpers: + +Helpers +------- + +.. sec-bundledplugins-softwareupdate-helpers-version_checks: + +version_checks +++++++++++++++ + +``version_checks`` module of the Software Update plugin, allows reusing the +bundled version check variants from plugins (e.g. wrapped in a ``python_checker``). + +.. sec-bundledplugins-softwareupdate-helpers-updaters: + +updaters +++++++++ + +``updaters`` module of the Software Update plugin, allows reusing the bundled +updater variants from plugins (e.g. wrapped in a ``python_updater``). + +.. sec-bundledplugins-softwareupdate-helpers-exceptions: + +exceptions +++++++++++ + +``exceptions`` module of the Software Update plugin. + +.. sec-bundledplugins-softwareupdate-helpers-util: + +util +++++ + +``util`` module of the Software Update plugin. + +.. sec-bundledplugins-softwareupdate-source: + +Source Code +----------- + +The source of the Software Update plugin is bundled with OctoPrint and can be +found in its source repository under ``src/octoprint/plugins/softwareupdate``. diff --git a/docs/images/bundledplugins-softwareupdate-yaml_octoprintsetup.png b/docs/images/bundledplugins-softwareupdate-yaml_octoprintsetup.png new file mode 100644 index 00000000..d631dad8 Binary files /dev/null and b/docs/images/bundledplugins-softwareupdate-yaml_octoprintsetup.png differ diff --git a/docs/index.rst b/docs/index.rst index ba415bf4..4af93062 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,7 @@ Contents :maxdepth: 2 features/index.rst + bundledplugins/index.rst configuration/index.rst api/index.rst events/index.rst diff --git a/docs/plugins/hooks.rst b/docs/plugins/hooks.rst index b10227ce..525dc5e0 100644 --- a/docs/plugins/hooks.rst +++ b/docs/plugins/hooks.rst @@ -206,7 +206,7 @@ Available plugin hooks octoprint.accesscontrol.appkey ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(*args, **kwargs) +.. py:function:: acl_appkey_hook(*args, **kwargs) By handling this hook plugins may register additional :ref:`App session key providers ` within the system. @@ -354,7 +354,7 @@ octoprint.cli.commands octoprint.comm.protocol.action ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(comm_instance, line, action, *args, **kwargs) +.. py:function:: protocol_action_hook(comm_instance, line, action, *args, **kwargs) React to a :ref:`action command ` received from the printer. @@ -389,7 +389,7 @@ This describes actually four hooks: * ``octoprint.comm.protocol.gcode.sending`` * ``octoprint.comm.protocol.gcode.sent`` -.. py:function:: hook(comm_instance, phase, cmd, cmd_type, gcode, *args, **kwargs) +.. py:function:: protocol_gcodephase_hook(comm_instance, phase, cmd, cmd_type, gcode, *args, **kwargs) Pre- and postprocess commands as they progress through the various phases of being sent to the printer. The phases are the following: @@ -502,7 +502,7 @@ octoprint.comm.protocol.gcode.received octoprint.comm.protocol.scripts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(comm_instance, script_type, script_name, *args, **kwargs) +.. py:function:: protocol_scripts_hook(comm_instance, script_type, script_name, *args, **kwargs) Return a prefix to prepend and a postfix to append to the script ``script_name`` of type ``type``. Handlers should make sure to only proceed with returning additional scripts if the ``script_type`` and ``script_name`` match @@ -536,7 +536,7 @@ octoprint.comm.protocol.scripts octoprint.comm.transport.serial.factory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(comm_instance, port, baudrate, read_timeout, *args, **kwargs) +.. py:function:: serial_factory_hook(comm_instance, port, baudrate, read_timeout, *args, **kwargs) Return a serial object to use as serial connection to the printer. If a handler cannot create a serial object for the specified ``port`` (and ``baudrate``), it should just return ``None``. @@ -612,7 +612,7 @@ octoprint.comm.transport.serial.factory octoprint.filemanager.extension_tree ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(*args, **kwargs) +.. py:function:: file_extension_hook(*args, **kwargs) Return additional entries for the tree of accepted file extensions for uploading/handling by the file manager. @@ -648,7 +648,7 @@ octoprint.filemanager.extension_tree octoprint.filemanager.preprocessor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(path, file_object, links=None, printer_profile=None, allow_overwrite=False, *args, **kwargs) +.. py:function:: file_preprocessor_hook(path, file_object, links=None, printer_profile=None, allow_overwrite=False, *args, **kwargs) Replace the ``file_object`` used for saving added files to storage by calling :func:`~octoprint.filemanager.util.AbstractFileWrapper.save`. @@ -714,7 +714,7 @@ octoprint.printer.factory octoprint.server.http.bodysize ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(current_max_body_sizes, *args, **kwargs) +.. py:function:: server_bodysize_hook(current_max_body_sizes, *args, **kwargs) Allows extending the list of custom maximum body sizes on the web server per path and HTTP method with custom entries from plugins. @@ -752,7 +752,7 @@ octoprint.server.http.bodysize octoprint.server.http.routes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(server_routes, *args, **kwargs) +.. py:function:: server_route_hook(server_routes, *args, **kwargs) Allows extending the list of routes registered on the web server. @@ -807,7 +807,7 @@ octoprint.server.http.routes octoprint.ui.web.templatetypes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: hook(template_sorting, template_rules, *args, **kwargs) +.. py:function:: templatetype_hook(template_sorting, template_rules, *args, **kwargs) Allows extending the set of supported template types in the web interface. This is interesting for plugins which want to offer other plugins to hook into their own offered UIs. Handlers must return a list of additional template