diff --git a/docs/bundledplugins/cura.rst b/docs/bundledplugins/cura.rst index a2f84de9..7f216ded 100644 --- a/docs/bundledplugins/cura.rst +++ b/docs/bundledplugins/cura.rst @@ -5,16 +5,16 @@ 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. +including version 15.04.x** and supersedes the slicing support integrated into +OctoPrint so far. It comes bundled with OctoPrint starting with version 1.2.0. .. 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). + Versions of CuraEngine later than 15.04.x have changed their calling + parameters in such a way that the current implementation of OctoPrint's Cura plugin + is not compatible to it. For this reason, please use only CuraEngine versions up to + and including 15.04 for now, as available in the ``legacy`` branch of the CuraEngine + repository on Github. The plugin offers a settings module that allows configuring the path to the CuraEngine executable to use, as well as importing and managing slicing @@ -35,7 +35,7 @@ Before you can slice from within OctoPrint, you'll need to .. note:: - OctoPi 0.12.0 ships with steps 1 and 2 already done, you only need to + OctoPi 0.12.0 and later 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: @@ -43,11 +43,9 @@ Before you can slice from within OctoPrint, you'll need to 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. +You'll need a build of ``legacy`` branch of `CuraEngine `_ +in order to be able to use the Cura OctoPrint plugin. You can find the ``legacy`` branch +`here `_. If you previously used the `old variant of the Cura integration `_, you probably still have a fully functional binary lying around in the @@ -59,6 +57,11 @@ path to that in the plugin settings. Compiling for Raspbian ++++++++++++++++++++++ +.. todo:: + + Provide updated binary, verify if makefile patch can finally be dumped on Raspbian + Jessie. + .. note:: A binary of CuraEngine 14.12 precompiled on Raspbian 2015-01-31 is available @@ -104,9 +107,10 @@ 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. +including Cura 15.04.x**. Newer Cura releases (e.g. 15.06 or 2.x) use a different +internal format that will *not* work with the current version of the Cura Plugin. + +You can find downloads of Cura 15.04.x for Windows, Mac and Linux `on Ultimaker's download page `_. 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 diff --git a/docs/bundledplugins/discovery.rst b/docs/bundledplugins/discovery.rst index e69de29b..f35be446 100644 --- a/docs/bundledplugins/discovery.rst +++ b/docs/bundledplugins/discovery.rst @@ -0,0 +1,184 @@ +.. _sec-bundledplugins-discovery: + +Discovery Plugin +================ + +The OctoPrint Discovery Plugin comes bundled with OctoPrint (starting with 1.2.0). + +It allows discovery of the OctoPrint instances via SSDP/UPNP. If +`pybonjour `_ is installed OctoPrint +will additionally support discovery via ZeroConf, also known as Bonjour or Avahi. + +The SSDP/UPNP support allows OctoPrint to announce itself to machines on the same +network running Microsoft Windows. You will be able to just double click on the +OctoPrint instance icon in "Networks > Other Devices" in your Windows Explorer, +which will take you directly to the web frontend. + +The ZeroConf support allows OctoPrint to announce itself to Safari on MacOS X +on the same network. + +Linux users should install `Avahi `_ and can then use one +of the various Avahi browsers (e.g. ``avahi-browse`` for the command +line) to scan for available instances. + +.. _fig-bundledplugins-discovery-windowsexplorer: +.. figure:: ../images/bundledplugins-discovery-windowsexplorer.png + :align: center + :alt: OctoPrint instances in Windows Explorer + + Various discovered OctoPrint instances in Windows Explorer + +.. _sec-bundledplugins-discovery-firststeps: + +First Steps +----------- + +.. _sec-bundledplugins-discovery-firststeps-pybonjour: + +Installing pybonjour +++++++++++++++++++++ + +.. note:: + + OctoPi versions 0.12.0 and later already come with pybonjour installed and ready to go, + you don't need to perform these steps there. + +In order for the Zeroconf discovery to work, the +`pybonjour package `_ needs to be available +to the Python installation running OctoPrint. + +It can be installed via ``pip``. Let's assume you installed OctoPrint manually +into some folder ``~/OctoPrint``. You executed ``python setup.py install`` within a +virtualenv in the same folder called ``venv``. In order to install ``pybonjour`` +so it will be available to OctoPrint you'll need to do the following:: + + venv/bin/pip install pybonjour + +**Linux users:** You'll need to install an additional dependency for this to work, the +libdnssd compatibility layer for libavahi. On Debian/Ubuntu that can be achieved with:: + + sudo apt-get install libavahi-compat-libdnssd-dev + + +.. _sec-bundledplugins-discovery-configuration: + +Configuring the plugin +---------------------- + +The plugin supports the following configuration keys: + + * ``publicPort``: Public port number OctoPrint is reachable under, + optional, if not set the port OctoPrint itself was started under will be used + * ``pathPrefix``: Path prefix OctoPrint is running under, optional, if not + set ``/`` will be used + * ``useSsl``: ``true``if OctoPrint should be called via HTTPS, ``false`` otherwise + * ``httpUsername``: HTTP Basic Auth username OctoPrint is reachable with, optional + * ``httpPassword``: HTTP Basic Auth password OctoPrint is reachable with, optional + * ``upnpUuid``: uPNP UUID used for SSDP service announcements, usually you will + not have to touch this, will be autogenerated if not set + * ``zeroConf``: A list of additional services to announce via ZeroConf, optional, + see below. + * ``model``: + + * ``name``: Name of the device model OctoPrint is running on, optional + * ``description``: Description of the device model OctoPrint is running on, + optional, used only for SSDP + * ``number``: Model number of the device OctoPrint is running on, optional, + used only for SSDP + * ``url``: URL with further details about the device OctoPrint is running on, + optional, used only for SSDP + * ``serial``: Serial number of the device OctoPrint is running on, optional, + used only for SSDP + * ``vendor``: Vendor of the device OctoPrint is running on, optional + * ``vendorUrl``: URL with further details about the vendor of the device + OctoPrint is running on, optional, used only for SSDP + +.. _sec-bundledplugins-discovery-configuration-furtherzeroconf: + +Further ZeroConf Services ++++++++++++++++++++++++++ + +The configuration also allows specifying additional ZeroConf service OctoPrint should +announce itself as. Each entry supports the following fields: + + * ``service``: The service to announce, this is the only obligatory field + * ``name``: The name to announce, defaults to the OctoPrint instance name if not + supplied + * ``port``: The port to announce, defaults to the OctoPrint was started under if + not supplied + * ``txt_record``: The TXT record to publish with the DNS-SD record, should be a + map of keys and associated values. + +.. _sec-bundledplugins-discovery-configuration-example: + +Example ++++++++ + +The following snippet is a valid configuration example for the discovery plugin in OctoPrint's +:ref:`config.yaml `: + +.. code-block:: yaml + + plugins: + discovery: + publicPort: 443 + useSsl: true + zeroConf: + - service: _someservice._tcp + port: 1234 + txt_record: + field1: value1 + field2: value2 + model: + name: Some Model + vendor: Some Vendor + +.. _sec-bundledplugins-discovery-announcedservices: + +Announced Services +------------------ + +.. _sec-bundledplugins-discovery-announcedservices-http: + +ZeroConf Service ``_http._tcp`` ++++++++++++++++++++++++++++++++ + +If :ref:`pybonjour ` is +correctly installed, OctoPrint will announce itself on the network via ZeroConf +as service ``_http._tcp``, with the TXT record containing the standard fields. + +See also `this documentation of _http._tcp TXT records `_ +for more information. + +.. _sec-bundledplugins-discovery-announcedservices-octoprint: + +ZeroConf Service ``_octoprint._tcp`` +++++++++++++++++++++++++++++++++++++ + +If :ref:`pybonjour ` is +correctly installed, OctoPrint will announce itself on the network via ZeroConf +as service ``_octoprint._tcp``. The TXT record may contain the following fields: + + * ``path``: path prefix to actual OctoPrint instance, inherited from ``_http._tcp`` + * ``u``: username if HTTP Basic Auth is used, optional, inherited from ``_http._tcp`` + * ``p``: password if HTTP Basic Auth is used, optional, inherited from ``_http._tcp`` + * ``version``: OctoPrint software version + * ``api``: OctoPrint API version + * ``model``: Model of the device that is running OctoPrint, optional + * ``vendor``: Vendor of the device that is running OctoPrint, optional + +Clients should construct the full path to the OctoPrint instance from this information +following this scheme:: + + http://[u[:p]@]host:port[path] + +See also `this documentation of _http._tcp TXT records `_ +for more information. + +.. _sec-bundledplugins-discovery-sourcecode: + +Source code +----------- + +The source of the Discovery plugin is bundled with OctoPrint and can be found in +its source repository under ``src/octoprint/plugins/discovery``. diff --git a/docs/bundledplugins/pluginmanager.rst b/docs/bundledplugins/pluginmanager.rst index e69de29b..e8c3675e 100644 --- a/docs/bundledplugins/pluginmanager.rst +++ b/docs/bundledplugins/pluginmanager.rst @@ -0,0 +1,84 @@ +.. _sec-bundledplugins-pluginmanager: + +Plugin Manager +============== + +The OctoPrint Plugin Manager comes bundled with OctoPrint starting with +version 1.2.0. + +It allows management of installed plugins (listing, enabling, disabling +and uninstalling) and installing new plugins from the official +`OctoPrint Plugin Repository `_, web addresses +or uploaded file archives. + +.. _fig-bundledplugins-pluginmanager-mainscreen: +.. figure:: ../images/bundledplugins-pluginmanager-mainscreen.png + :align: center + :alt: Plugin Manager + + The main dialog of the Plugin Manager + +.. _fig-bundledplugins-pluginmanager-installing: +.. figure:: ../images/bundledplugins-pluginmanager-installing.png + :align: center + :alt: Installation dialog + + Dialog for installing new plugins + +.. _fig-bundledplugins-pluginmanager-repofilters: +.. figure:: ../images/bundledplugins-pluginmanager-repofilters.png + :align: center + :alt: Filter options for the repository browser + + Filter options for the repository browser + +.. _sec-bundledplugins-pluginmanager-configuration: + +Configuring the Plugin +---------------------- + +The Plugin Manager plugin only has a handful of configuration settings +which normally won't have to be touched. + +You can modify them either through the plugin's configuration dialog that +you can open when clicking the little wrench icon in the upper right corner +under Settings > Plugin Manager, or by directly editing ``config.yaml``: + +.. code-block:: yaml + + plugins: + pluginmanager: + # The URL of the repository index to use + repository: http://plugins.octoprint.org/plugins.json + + # Time to live for the repository cache + repository_ttl: 1440 + + # Additional arguments to use with pip. Defaults to unset, + # you normally shouldn't need to modify this + pip_args: --some --additional --pip --arguments + + # Whether to force the --user flag with pip. Defaults to + # false, you normally shouldn't need to modify this + pip_force_user: false + + # Whether to have pip always follow dependency links. + # Defaults to false, you normally shouldn't need to + # modify this + dependency_links: false + + # List of plugin identifiers hidden from the plugin + # manager. Defaults to an empty list. Not available + # through the configuration dialog, only available + # to allow for vendor customization + hidden: + - some + - hidden + - plugins + +.. _sec-bundledplugins-pluginmanager-sourcecode: + +Source Code +----------- + +The source of the Plugin Manager is bundled with OctoPrint and can be found in its source repository under ``src/octoprint/plugins/pluginmanager``. diff --git a/docs/bundledplugins/softwareupdate.rst b/docs/bundledplugins/softwareupdate.rst index fcbe49ac..32281ff7 100644 --- a/docs/bundledplugins/softwareupdate.rst +++ b/docs/bundledplugins/softwareupdate.rst @@ -1,4 +1,4 @@ -.. sec-bundledplugins-softwareupdate: +.. _sec-bundledplugins-softwareupdate: Software Update Plugin ====================== @@ -7,7 +7,7 @@ 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: +.. _sec-bundledplugins-softwareupdate-firststeps: First Steps ----------- @@ -15,72 +15,57 @@ 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 ` +your OctoPrint installation, you'll need to 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: +For configuring the plugin you'll need to go into OctoPrint's Settings Dialog, navigate to the +Software Upda.. _section therein and once you are there click on the little wrench icon in the +upper right corner. -Making OctoPrint updateable on existing installations -+++++++++++++++++++++++++++++++++++++++++++++++++++++ +.. _fig-bundledplugins-softwareupdate-plugin-configuration: +.. figure:: ../images/bundledplugins-softwareupdate-plugin-configuration.png + :align: center + :alt: Software Update plugin configuration dialog -.. note:: + The Software Update plugin configuration dialog - OctoPi releases 0.12.0 and later ship with this already setup for you! +There you can adjust the following settings: -.. note:: + * **OctoPrint checkout folder**: This should be the path to OctoPrint's git checkout folder (``/home/pi/OctoPrint`` + for OctoPi or `manual installs following the Raspberry Pi setup guide `_). + This must be set to allow updating from within OctoPrint - **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:: + .. note:: - cd ~/OctoPrint - git remote set-url origin https://github.com/foosel/OctoPrint.git + OctoPi releases 0.12.0 and later ship with this already setup for you. -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): + .. note:: -.. code-block:: yaml + **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:: - # ... - plugins: - # ... - softwareupdate: - # ... - checks: - # ... - octoprint: - update_folder: /home/pi/OctoPrint - # ... - octoprint_restart_command: sudo service octoprint restart - environment_restart_command: sudo shutdown -r now - # ... + cd ~/OctoPrint + git remote set-url origin https://github.com/foosel/OctoPrint.git -.. note:: + * **OctoPrint version tracking**: Whether you want to track OctoPrint *releases* or every *commit*. Usually you want to + select "Release" here which is also the default, unless you are a developer. + * **OctoPrint Release Channel**: The release channel of OctoPrint to track for updates. If you only want stable versions, + select "Stable" here which is also the default. "Maintenance RCs" will also allow you to update to maintenance release + candidates, "Devel RCs" will also allow you to update to development release candidates. If in doubt, leave it at + "Stable". :ref:`Read more about Release Channels here `. + * **Version cache TTL**: The "time to live" of the cache OctoPrint will use to temporarily persist the version information + for the various components registered with the plugin, so that they don't have to be queried from the internet every time + you load the page. Defaults to 24h, you usually shouldn't need to change that value. - 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. +More settings are available by :ref:`editing the correspondi.. _section in config.yaml `. - .. image:: ../images/bundledplugins-softwareupdate-yaml_octoprintsetup.png - :align: center - :alt: Yamlpatcher preview +That restart commands for OctoPrint and the whole server can be configured under Settings > Server. -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: +.. _sec-bundledplugins-softwareupdate-configuration: Configuring the Plugin ---------------------- @@ -92,12 +77,6 @@ Configuring the Plugin # 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 @@ -114,7 +93,11 @@ Configuring the Plugin # further checks may be define here -.. sec-bundledplugins-softwareupdate-configuration-versionchecks: + # pip command, if another one than the automatically detected one should be + # used - should normally NOT be necessary and hence set + pip_command: /path/to/pip + +.. _sec-bundledplugins-softwareupdate-configuration-versionchecks: Version checks ++++++++++++++ @@ -126,6 +109,10 @@ Version checks * ``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_branch``: Branch name to check against ``target_comittish`` + field in Github release data - release will only be included if the + values match. Defaults to being unset, in which case no match will + be performed. * ``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 @@ -165,7 +152,7 @@ Version checks information and whether the current version is up-to-date or not, see below for details. -.. sec-bundledplugins-softwareupdate-configuration-updatemethods: +.. _sec-bundledplugins-softwareupdate-configuration-updatemethods: Update methods ++++++++++++++ @@ -175,7 +162,8 @@ Update methods 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 + as retrieved from the update check), ``{branch}`` for the branch to switch + to to access the release, ``{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 @@ -184,7 +172,7 @@ Update methods :ref:`hook `. A python callable which performs the update, see below for details. -.. sec-bundledplugins-softwareupdate-configuration-patterns: +.. _sec-bundledplugins-softwareupdate-configuration-patterns: Common configuration patterns +++++++++++++++++++++++++++++ @@ -235,12 +223,12 @@ The same, but tracking all commits pushed to branch ``devel`` (thus allowing branch: devel pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip' -.. sec-bundledplugins-softwareupdate-hooks: +.. _sec-bundledplugins-softwareupdate-hooks: Hooks ----- -.. sec-bundledplugins-softwareupdate-hooks-check_config: +.. _sec-bundledplugins-softwareupdate-hooks-check_config: octoprint.plugin.softwareupdate.check_config ++++++++++++++++++++++++++++++++++++++++++++ @@ -297,12 +285,12 @@ octoprint.plugin.softwareupdate.check_config :return: A dictionary of check configurations as described above :rtype: dict -.. sec-bundledplugins-softwareupdate-helpers: +.. _sec-bundledplugins-softwareupdate-helpers: Helpers ------- -.. sec-bundledplugins-softwareupdate-helpers-version_checks: +.. _sec-bundledplugins-softwareupdate-helpers-version_checks: version_checks ++++++++++++++ @@ -310,7 +298,7 @@ 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: +.. _sec-bundledplugins-softwareupdate-helpers-updaters: updaters ++++++++ @@ -318,21 +306,21 @@ 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: +.. _sec-bundledplugins-softwareupdate-helpers-exceptions: exceptions ++++++++++ ``exceptions`` module of the Software Update plugin. -.. sec-bundledplugins-softwareupdate-helpers-util: +.. _sec-bundledplugins-softwareupdate-helpers-util: util ++++ ``util`` module of the Software Update plugin. -.. sec-bundledplugins-softwareupdate-source: +.. _sec-bundledplugins-softwareupdate-source: Source Code ----------- diff --git a/docs/images/bundledplugins-discovery-windowsexplorer.png b/docs/images/bundledplugins-discovery-windowsexplorer.png new file mode 100644 index 00000000..fed976a2 Binary files /dev/null and b/docs/images/bundledplugins-discovery-windowsexplorer.png differ diff --git a/docs/images/bundledplugins-pluginmanager-installing.png b/docs/images/bundledplugins-pluginmanager-installing.png new file mode 100644 index 00000000..d97eaf39 Binary files /dev/null and b/docs/images/bundledplugins-pluginmanager-installing.png differ diff --git a/docs/images/bundledplugins-pluginmanager-mainscreen.png b/docs/images/bundledplugins-pluginmanager-mainscreen.png new file mode 100644 index 00000000..bf6e1c50 Binary files /dev/null and b/docs/images/bundledplugins-pluginmanager-mainscreen.png differ diff --git a/docs/images/bundledplugins-pluginmanager-repofilters.png b/docs/images/bundledplugins-pluginmanager-repofilters.png new file mode 100644 index 00000000..ab62e4a3 Binary files /dev/null and b/docs/images/bundledplugins-pluginmanager-repofilters.png differ diff --git a/docs/images/bundledplugins-softwareupdate-plugin-configuration.png b/docs/images/bundledplugins-softwareupdate-plugin-configuration.png new file mode 100644 index 00000000..7d5a672c Binary files /dev/null and b/docs/images/bundledplugins-softwareupdate-plugin-configuration.png differ diff --git a/docs/images/bundledplugins-softwareupdate-yaml_octoprintsetup.png b/docs/images/bundledplugins-softwareupdate-yaml_octoprintsetup.png deleted file mode 100644 index d631dad8..00000000 Binary files a/docs/images/bundledplugins-softwareupdate-yaml_octoprintsetup.png and /dev/null differ