Adding documentation for the virtual printer plugin.
This commit is contained in:
Peter Backx
Gina Häußge
parent
807b44a35e
commit
452ee8e156
3 changed files with 297 additions and 179 deletions
177
docs/development/environment.rst
Normal file
177
docs/development/environment.rst
Normal file
|
|
@ -0,0 +1,177 @@
|
|||
.. _sec-development-environment:
|
||||
|
||||
Setting up a Development environment
|
||||
====================================
|
||||
|
||||
.. _sec-development-environment-source:
|
||||
|
||||
Obtaining, building and running the source
|
||||
------------------------------------------
|
||||
|
||||
This describes the general steps in obtaining, building and running. OS specific instructions can be found
|
||||
below.
|
||||
|
||||
* Prerequisites:
|
||||
|
||||
* `Python 2.7 <https://python.org>`_ including ``pip``, ``setuptools`` and ``virtualenv``
|
||||
* `Git <https://git-scm.com>`_
|
||||
|
||||
* Checkout the OctoPrint sources from their Git repository: ``git clone https://github.com/foosel/OctoPrint.git``
|
||||
* Create a virtual environment in the checkout folder to use for installing and running OctoPrint and its
|
||||
dependencies (this avoids potential versioning issues for the dependencies with system wide installed
|
||||
instances): ``virtualenv venv``
|
||||
* Activate the virtual environment: ``source venv/bin/activate`` (might differ per your platform/OS)
|
||||
* Update ``pip`` in the virtual environment: ``pip install --upgrade pip``
|
||||
* Install OctoPrint in `"editable" mode <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_,
|
||||
including its regular *and* development dependencies: ``pip install -e .[develop]``
|
||||
|
||||
.. _sec-development-environment-source-linux:
|
||||
|
||||
Linux
|
||||
.....
|
||||
|
||||
This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different
|
||||
location, please substitute accordingly.
|
||||
|
||||
First make sure you have python including its header files, pip, setuptools, virtualenv, git and some build requirements
|
||||
installed:
|
||||
|
||||
* On apt based distributions (e.g. Debian, Ubuntu, ...):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
sudo apt-get install python python-pip python-dev python-setuptools python-virtualenv git libyaml-dev build-essential
|
||||
|
||||
.. todo::
|
||||
|
||||
Using a Linux distribution that doesn't use ``apt``? Please send a
|
||||
`Pull Request <https://github.com/foosel/OctoPrint/blob/master/CONTRIBUTING.md#pull-requests>`_ to get the necessary
|
||||
steps into this guide!
|
||||
|
||||
Then:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd ~/devel
|
||||
git clone https://github.com/foosel/OctoPrint.git
|
||||
cd OctoPrint
|
||||
virtualenv venv
|
||||
source ./venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -e .[develop]
|
||||
|
||||
You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual
|
||||
environment.
|
||||
|
||||
.. _sec-development-environment-windows:
|
||||
|
||||
Windows
|
||||
.......
|
||||
|
||||
This assumes you'll host your OctoPrint development checkout at ``C:\Devel\OctoPrint``. If you want to use a different
|
||||
location, please substitute accordingly.
|
||||
|
||||
First download & install:
|
||||
|
||||
* `Python 2.7.12 Windows x86 MSI installer <https://www.python.org/downloads/release/python-2712/>`_
|
||||
|
||||
* make sure to have the installer add Python to the ``PATH`` and have it install ``pip`` too
|
||||
|
||||
* `Microsoft Visual C++ Compiler for Python 2.7 <http://www.microsoft.com/en-us/download/details.aspx?id=44266>`_
|
||||
* `Git for Windows <https://git-for-windows.github.io/>`_
|
||||
|
||||
Open the Git Bash you just installed and in that:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
pip install virtualenv
|
||||
cd /c/Devel
|
||||
git clone https://github.com/foosel/OctoPrint.git
|
||||
cd OctoPrint
|
||||
virtualenv venv
|
||||
source ./venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -e .[develop]
|
||||
|
||||
You can then start OctoPrint via ``/c/Devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual
|
||||
environment.
|
||||
|
||||
.. _sec-development-environment-mac:
|
||||
|
||||
Mac OS X
|
||||
........
|
||||
|
||||
.. note::
|
||||
|
||||
This guide is based on the `Setup Guide for Mac OS X on OctoPrint's wiki <https://github.com/foosel/OctoPrint/wiki/Setup-on-Mac/>`_.
|
||||
Please report back if it works for you, due to lack of access to a Mac I cannot test it myself. Thanks.
|
||||
|
||||
This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different
|
||||
location, please substitute accordingly.
|
||||
|
||||
You'll need a user account with administrator privileges.
|
||||
|
||||
* Install the latest version of Xcode suitable for your OS. For example, OS X 10.11 (El Capitan) requires Xcode 7.
|
||||
* Install Xcode's command line tools:
|
||||
|
||||
* ``xcode-select --install``
|
||||
* ``sudo xcodebuild`` (ensure the license was accepted)
|
||||
* If you have more than one Xcode installed: ``sudo xcode-select -s /Applications/Xcode.app/Contents/Developer``
|
||||
|
||||
* Install Homebrew and use that to install Python:
|
||||
|
||||
* ``ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"``
|
||||
* ``brew install python``
|
||||
|
||||
* Install `virtualenv <https://virtualenv.pypa.io/>`_
|
||||
|
||||
* ``pip install virtualenv``
|
||||
|
||||
* Install OctoPrint
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd ~/devel
|
||||
git clone https://github.com/foosel/OctoPrint.git
|
||||
cd OctoPrint
|
||||
virtualenv venv
|
||||
source venv/bin/activate
|
||||
pip install -e .[develop]
|
||||
|
||||
You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual
|
||||
environment.
|
||||
|
||||
.. _sec-development-environment-ides:
|
||||
|
||||
IDE Setup
|
||||
---------
|
||||
|
||||
.. todo::
|
||||
|
||||
Using another IDE than the ones below? Please send a
|
||||
`Pull Request <https://github.com/foosel/OctoPrint/blob/master/CONTRIBUTING.md#pull-requests>`_ to get the necessary
|
||||
steps into this guide!
|
||||
|
||||
.. _sec-development-environment-ides-pycharm:
|
||||
|
||||
PyCharm
|
||||
.......
|
||||
|
||||
- "File" > "Open ...", select OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``)
|
||||
- "File" > "Settings ..." > "Project: OctoPrint" > "Project Interpreter" > "Add local ...", select OctoPrint venv
|
||||
folder (e.g. ``~/devel/OctoPrint/venv`` or ``C:\Devel\OctoPrint\venv``)
|
||||
- Right click "src" in project tree, mark as source folder
|
||||
- Add Run/Debug Configuration, select "Python":
|
||||
|
||||
* Name: OctoPrint server
|
||||
* Script: path to ``run`` in the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint/run`` or ``C:\Devel\OctoPrint\run``)
|
||||
* Script parameters: ``--debug``
|
||||
* Project: ``OctoPrint``
|
||||
* Python interpreter: the ``venv`` local virtual environment
|
||||
* Working directory: the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``)
|
||||
|
||||
.. note::
|
||||
|
||||
Make sure you are running a PyCharm version of 2016.1 or later, or manually fix
|
||||
`a debugger bug contained in earlier versions <https://youtrack.jetbrains.com/issue/PY-18365>`_ or plugin management
|
||||
will not work in your developer install when running OctoPrint from PyCharm in debug mode.
|
||||
|
|
@ -4,183 +4,8 @@
|
|||
Development
|
||||
###########
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
.. _sec-development-environment:
|
||||
|
||||
Setting up a Development environment
|
||||
====================================
|
||||
|
||||
.. _sec-development-environment-source:
|
||||
|
||||
Obtaining, building and running the source
|
||||
------------------------------------------
|
||||
|
||||
This describes the general steps in obtaining, building and running. OS specific instructions can be found
|
||||
below.
|
||||
|
||||
* Prerequisites:
|
||||
|
||||
* `Python 2.7 <https://python.org>`_ including ``pip``, ``setuptools`` and ``virtualenv``
|
||||
* `Git <https://git-scm.com>`_
|
||||
|
||||
* Checkout the OctoPrint sources from their Git repository: ``git clone https://github.com/foosel/OctoPrint.git``
|
||||
* Create a virtual environment in the checkout folder to use for installing and running OctoPrint and its
|
||||
dependencies (this avoids potential versioning issues for the dependencies with system wide installed
|
||||
instances): ``virtualenv venv``
|
||||
* Activate the virtual environment: ``source venv/bin/activate`` (might differ per your platform/OS)
|
||||
* Update ``pip`` in the virtual environment: ``pip install --upgrade pip``
|
||||
* Install OctoPrint in `"editable" mode <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_,
|
||||
including its regular *and* development dependencies: ``pip install -e .[develop]``
|
||||
|
||||
.. _sec-development-environment-source-linux:
|
||||
|
||||
Linux
|
||||
.....
|
||||
|
||||
This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different
|
||||
location, please substitute accordingly.
|
||||
|
||||
First make sure you have python including its header files, pip, setuptools, virtualenv, git and some build requirements
|
||||
installed:
|
||||
|
||||
* On apt based distributions (e.g. Debian, Ubuntu, ...):
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
sudo apt-get install python python-pip python-dev python-setuptools python-virtualenv git libyaml-dev build-essential
|
||||
|
||||
.. todo::
|
||||
|
||||
Using a Linux distribution that doesn't use ``apt``? Please send a
|
||||
`Pull Request <https://github.com/foosel/OctoPrint/blob/master/CONTRIBUTING.md#pull-requests>`_ to get the necessary
|
||||
steps into this guide!
|
||||
|
||||
Then:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd ~/devel
|
||||
git clone https://github.com/foosel/OctoPrint.git
|
||||
cd OctoPrint
|
||||
virtualenv venv
|
||||
source ./venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -e .[develop]
|
||||
|
||||
You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual
|
||||
environment.
|
||||
|
||||
.. _sec-development-environment-windows:
|
||||
|
||||
Windows
|
||||
.......
|
||||
|
||||
This assumes you'll host your OctoPrint development checkout at ``C:\Devel\OctoPrint``. If you want to use a different
|
||||
location, please substitute accordingly.
|
||||
|
||||
First download & install:
|
||||
|
||||
* `Python 2.7.12 Windows x86 MSI installer <https://www.python.org/downloads/release/python-2712/>`_
|
||||
|
||||
* make sure to have the installer add Python to the ``PATH`` and have it install ``pip`` too
|
||||
|
||||
* `Microsoft Visual C++ Compiler for Python 2.7 <http://www.microsoft.com/en-us/download/details.aspx?id=44266>`_
|
||||
* `Git for Windows <https://git-for-windows.github.io/>`_
|
||||
|
||||
Open the Git Bash you just installed and in that:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
pip install virtualenv
|
||||
cd /c/Devel
|
||||
git clone https://github.com/foosel/OctoPrint.git
|
||||
cd OctoPrint
|
||||
virtualenv venv
|
||||
source ./venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -e .[develop]
|
||||
|
||||
You can then start OctoPrint via ``/c/Devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual
|
||||
environment.
|
||||
|
||||
.. _sec-development-environment-mac:
|
||||
|
||||
Mac OS X
|
||||
........
|
||||
|
||||
.. note::
|
||||
|
||||
This guide is based on the `Setup Guide for Mac OS X on OctoPrint's wiki <https://github.com/foosel/OctoPrint/wiki/Setup-on-Mac/>`_.
|
||||
Please report back if it works for you, due to lack of access to a Mac I cannot test it myself. Thanks.
|
||||
|
||||
This assumes you'll host your OctoPrint development checkout at ``~/devel/OctoPrint``. If you want to use a different
|
||||
location, please substitute accordingly.
|
||||
|
||||
You'll need a user account with administrator privileges.
|
||||
|
||||
* Install the latest version of Xcode suitable for your OS. For example, OS X 10.11 (El Capitan) requires Xcode 7.
|
||||
* Install Xcode's command line tools:
|
||||
|
||||
* ``xcode-select --install``
|
||||
* ``sudo xcodebuild`` (ensure the license was accepted)
|
||||
* If you have more than one Xcode installed: ``sudo xcode-select -s /Applications/Xcode.app/Contents/Developer``
|
||||
|
||||
* Install Homebrew and use that to install Python:
|
||||
|
||||
* ``ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"``
|
||||
* ``brew install python``
|
||||
|
||||
* Install `virtualenv <https://virtualenv.pypa.io/>`_
|
||||
|
||||
* ``pip install virtualenv``
|
||||
|
||||
* Install OctoPrint
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd ~/devel
|
||||
git clone https://github.com/foosel/OctoPrint.git
|
||||
cd OctoPrint
|
||||
virtualenv venv
|
||||
source venv/bin/activate
|
||||
pip install -e .[develop]
|
||||
|
||||
You can then start OctoPrint via ``~/devel/OctoPrint/venv/bin/octoprint`` or just ``octoprint`` if you activated the virtual
|
||||
environment.
|
||||
|
||||
.. _sec-development-environment-ides:
|
||||
|
||||
IDE Setup
|
||||
---------
|
||||
|
||||
.. todo::
|
||||
|
||||
Using another IDE than the ones below? Please send a
|
||||
`Pull Request <https://github.com/foosel/OctoPrint/blob/master/CONTRIBUTING.md#pull-requests>`_ to get the necessary
|
||||
steps into this guide!
|
||||
|
||||
.. _sec-development-environment-ides-pycharm:
|
||||
|
||||
PyCharm
|
||||
.......
|
||||
|
||||
- "File" > "Open ...", select OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``)
|
||||
- "File" > "Settings ..." > "Project: OctoPrint" > "Project Interpreter" > "Add local ...", select OctoPrint venv
|
||||
folder (e.g. ``~/devel/OctoPrint/venv`` or ``C:\Devel\OctoPrint\venv``)
|
||||
- Right click "src" in project tree, mark as source folder
|
||||
- Add Run/Debug Configuration, select "Python":
|
||||
|
||||
* Name: OctoPrint server
|
||||
* Script: path to ``run`` in the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint/run`` or ``C:\Devel\OctoPrint\run``)
|
||||
* Script parameters: ``--debug``
|
||||
* Project: ``OctoPrint``
|
||||
* Python interpreter: the ``venv`` local virtual environment
|
||||
* Working directory: the OctoPrint checkout folder (e.g. ``~/devel/OctoPrint`` or ``C:\Devel\OctoPrint``)
|
||||
|
||||
.. note::
|
||||
|
||||
Make sure you are running a PyCharm version of 2016.1 or later, or manually fix
|
||||
`a debugger bug contained in earlier versions <https://youtrack.jetbrains.com/issue/PY-18365>`_ or plugin management
|
||||
will not work in your developer install when running OctoPrint from PyCharm in debug mode.
|
||||
environment.rst
|
||||
virtual_printer.rst
|
||||
|
|
|
|||
116
docs/development/virtual_printer.rst
Normal file
116
docs/development/virtual_printer.rst
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
.. _sec-development-virtual-printer:
|
||||
|
||||
Setting up the virtual printer for debugging
|
||||
============================================
|
||||
|
||||
OctoPrint includes, by default, a virtual printer plugin. This plugin allows you to debug OctoPrint's serial
|
||||
communication without connecting to an actual printer. Furthermore, it is possible to create certain edge conditions
|
||||
that may be hard to reproduce with a real printer.
|
||||
|
||||
.. _sec-development-virtual-printer-enable:
|
||||
|
||||
Enabling the virtual printer
|
||||
----------------------------
|
||||
|
||||
The virtual printer is enabled by editing OctoPrint's config.yaml file. Details on the configuration file can
|
||||
be found in the full :ref:`config.yaml documentation <sec-configuration-config_yaml>`.
|
||||
|
||||
The steps to take are as follows:
|
||||
|
||||
* Find config.yaml in the OctoPrint settings folder. Usually in ``~/.octoprint`` on Linux, in ``%APPDATA%/OctoPrint`` on Windows and in ``~/Library/Application Support/OctoPrint`` on MacOS.
|
||||
* Add or extend the ``devel`` section with:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
devel:
|
||||
virtualPrinter:
|
||||
enabled: true
|
||||
|
||||
* Restart OctoPrint.
|
||||
* In the connection panel, a new option will appear in the Serial Port dropdown labeled ``VIRTUAL``.
|
||||
* Select this option and click ``connect``.
|
||||
* The virtual printer is now active.
|
||||
|
||||
.. _sec-development-virtual-printer-config:
|
||||
|
||||
Virtual printer configuration options
|
||||
-------------------------------------
|
||||
|
||||
The config.yaml file has many configuration options for the virtual printer that allow you to fine-tune its behavior.
|
||||
|
||||
Please see the relevant :ref:`config.yaml section <sec-configuration-config_yaml-devel>` for the full details.
|
||||
|
||||
.. _sec-development-virtual-printer-log:
|
||||
|
||||
Log file
|
||||
--------
|
||||
|
||||
Once activated, the virtual printer will log all serial communication in the ``plugin_virtual_printer_serial.log`` file
|
||||
that can be found in the OctoPrint settings folder.
|
||||
|
||||
.. _sec-development-virtual-printer-debug:
|
||||
|
||||
Debug commands
|
||||
--------------
|
||||
|
||||
You can simulate certain conditions and communications through the terminal tab in OctoPrint's interface.
|
||||
|
||||
All commands start with ``!!DEBUG:`` and are followed by the command you want to execute. For instance, sending
|
||||
``!!DEBUG:action_disconnect`` will disconnect the printer. Sending ``!!DEBUG`` without command will show a help
|
||||
message with all the available commands.
|
||||
|
||||
Action Triggers
|
||||
...............
|
||||
|
||||
``action_pause``
|
||||
Sends a "// action:pause" action trigger to the host.
|
||||
|
||||
``action_resume``
|
||||
Sends a "// action:resume" action trigger to the host.
|
||||
|
||||
``action_disconnect``
|
||||
Sends a "// action:disconnect" action trigger to the host.
|
||||
|
||||
``action_custom <action>[ <parameters>]``
|
||||
Sends a custom "// action:<action> <parameters>" action trigger to the host.
|
||||
|
||||
Communication Errors
|
||||
....................
|
||||
|
||||
``dont_answer``
|
||||
Will not acknowledge the next command.
|
||||
|
||||
``go_awol``
|
||||
Will completely stop replying.
|
||||
|
||||
``trigger_resend_lineno``
|
||||
Triggers a resend error with a line number mismatch
|
||||
|
||||
``trigger_resend_checksum``
|
||||
Triggers a resend error with a checksum mismatch
|
||||
|
||||
``drop_connection``
|
||||
Drops the serial connection
|
||||
|
||||
``prepare_ok <broken ok>``
|
||||
Will cause <broken ok> to be enqueued for use, will be used instead of actual "ok"
|
||||
|
||||
Reply Timing / Sleeping
|
||||
.......................
|
||||
``sleep <int:seconds>``
|
||||
Sleep <seconds> s
|
||||
|
||||
``sleep_after <str:command> <int:seconds>``
|
||||
Sleeps <seconds> s after each execution of <command>
|
||||
|
||||
``sleep_after_next <str:command> <int:seconds>``
|
||||
Sleeps <seconds> s after execution of next <command>
|
||||
|
||||
Misc
|
||||
....
|
||||
|
||||
``help``
|
||||
Show the available commands.
|
||||
|
||||
``send <str:message>``
|
||||
Sends back <message>
|
||||
Loading…
Reference in a new issue