{
    "info": {
        "author": "Christian Vogelgsang",
        "author_email": "chris@vogelgsang.org",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "tentacle - An OctoPrint frontend for small displays\n###################################################\n\n.. image:: tentacle.png\n    :alt: tentacle screenshots\n    :align: center\n\n.. class:: no-web no-pdf\n\n.. image:: https://img.shields.io/pypi/v/tentacle.svg?style=flat-square\n   :target: https://pypi.python.org/pypi/tentacle\n\n.. contents::\n\n.. section-numbering::\n\nFeatures\n========\n\n* Stylus-friendly UI suitable for tiny TFTs\n* TFT Resolution of 320x240 and upwards supported\n* Low resource usage: PyQt5 running directly on framebuffer without X11\n* All relevant OctoPrint parameters are available in UI Tabs:\n\n  * Shows details on current print ``Job``\n  * Shows available print ``Files`` and allows to select one for printing\n  * Shows ``Temperature Curves`` of Hotends and Bed\n  * A ``Move Panel`` allows to move the tools\n  * A ``GCode Display`` shows the current layer while printing\n  * A ``Camera View`` shows your streamed camera\n\nInstallation\n============\n\nLinux / Raspberry Pi\n--------------------\n\n* First setup your TFT and the (calibrated) touch input.\n  Typically your TFT's framebuffer device is ``/dev/fb1``\n  See `Appendix`_ for details on my setup.\n\nInstall with PIP3\n+++++++++++++++++\n\n* Install the PyQt5 package for Python 3 with ``apt``:\n\n.. code-block:: bash\n\n    $ sudo apt install python3-pyqt5\n\n* Install ``tentacle`` with ``pip``\n\n.. code-block:: bash\n\n    $ sudo apt install python3-pip\n    $ pip3 install tentacle\n\nThis will install ``tentacle`` for the current user only.\nIf you want to install the package system-wide use ``sudo``:\n\n.. code-block:: bash\n\n    $ sudo pip3 install tentacle\n\nManual startup\n++++++++++++++\n\nNow you can test run the binary from a remote shell (ssh):\n\n    $ tentacle -v\n\nUse manual startup to tweak your Configuration_\n\nAutostart with ``systemd``\n++++++++++++++++++++++++++\n\nIn ``systemd/tentacle.service`` you'll find a template service file for\nsystemd. Adjust and copy this file to ``/etc/systemd/system/``.\n\nMake sure the user is setup correctly. Default is ``pi``.\n\nTry to run the service with:\n\n.. code-block:: bash\n\n    $ sudo systemctl start tentacle\n\nSee the status with:\n\n.. code-block:: bash\n\n    $ sudo systemctl status tentacle\n\nStop the service with:\n\n.. code-block:: bash\n\n    $ sudo systemctl stop tentacle\n\nTo permanently enable the service for the next boot use:\n\n.. code-block:: bash\n\n    $ sudo systemctl enable tentacle\n\nDone!\n\nmacOS\n-----\n\nYou can run ``tentacle`` on your Mac in a window to test the UI.\n\n* First install PyQt5 with:\n\n.. code-block:: bash\n\n    $ pip install pyqt5\n\n* Then install ``tentacle``:\n\n.. code-block:: bash\n\n    $ pip install tentacle\n\n\nConfiguration\n=============\n\nWhile ``tentacle`` already ships with a sensible set of default configuration\nparameters you can adjust them as you need.\n\nThe configuration file is called ``tentacle.cfg`` and searched at the\nfollowing locations:\n\n* current working directory (suitable for test runs)\n* ``$HOME/.tentacle.cfg``\n* ``/etc/tentacle.cfg`` (suitable for systemd setup)\n\nThe config has INI like syntax and is split into sections.\nTo get the default configuration just run ``tentacle --dump-config`` to write\nit into a file:\n\n.. code-block:: bash\n\n    $ tentacle --dump-config tentacle.cfg\n\nSection ``octoprint``\n---------------------\n\n``url``\n    The URL to reach OctoPrint. Either use ``http:`` or ``https:``. Make sure\n    the hostname matches (default: ``octopi``).\n\n    Default::\n\n        http://octopi\n\n``api_key``\n    Give the API key you created in ``OctoPrint`` to allow to execute commands\n    via the REST API.\n\nSection ``qt``\n--------------\n\n``fb_dev``\n    The frame buffer device of your TFT display.\n\n    Default::\n\n        /dev/fb0\n\n``ts_dev``\n    The touch screen input device.\n\n    Default::\n\n        /dev/input/touchscreen\n\nSection ``app``\n---------------\n\nGlobal settings for the whole UI.\n\n``font_family`` and ``font_size``\n    Specify the font used for the UI.\n\n``width`` and ``height``\n    The size of your display\n\n``dark``\n    Enable ``dark`` mode. Disable to see ``light`` mode.\n\n``style``\n    Select a specific Qt widget style\n\nSection ``temp``\n----------------\n\nSettings for the ``temp`` tab in the UI.\n\n``font_family`` and ``font_size``\n    Specify the font used for the UI temperate labels\n\n``min`` and ``max``\n    Set the minimum and maximum temperature shown in graph.\n\n``step``\n    Set the line and label stepping in the graph display.\n\nSection ``move``\n----------------\n\nSettings for the ``move`` tab in the UI.\n\n``unload_z``\n    The Z axis position to move to when selecting the ``Unload`` button.\n\n``label_a`` and ``label_b``\n    The label text to be displayed for the custom move buttons.\n\n``pos_a`` and ``pos_b``\n    The X,Y,Z position to move to when selecting a custom button.\n\nSection ``tool``\n----------------\n\nSettings for the ``tool`` tab in the UI.\n\n``t{0,1}_temp{1,2}`` and ``bed_temp{1,2}``\n    Set the default temperature for the tools 0, 1, and the bed.\n\nSection ``ser``\n---------------\n\nSettings for the ``ser`` tab in the UI.\n\n``font_family`` and ``font_size``\n    Specify the font used for the UI serial log output\n\nSection ``cam``\n---------------\n\nSettings for the ``cam`` tab in the UI.\n\n``url``\n    The the URL of ``mjpeg streamer`` to get the mjpeg stream from your camera.\n\n    Default::\n\n        http://octopi:8080/?action=stream\n\n\nSection ``commands``\n--------------------\n\nConfigure various external commands triggered by ``tentacle``.\n\nNote: Make sure the user running ``tentacle`` is allowed to perform these\ncommands. You may need to add ``sudo`` and configure it to run the\ncommands without password input.\n\n``restart_octoprint``\n    Restart the OctoPrint server.\n\n    Default::\n\n        /bin/systemctl restart octoprint\n\n``reboot_sys``\n    Reboot the whole system.\n\n    Default::\n\n        /sbin/reboot\n\n``poweroff_sys``\n    Power off the system.\n\n    Default::\n\n        /sbin/poweroff\n\n``backlight_on``\n    Enable the backlight of the TFT display.\n\n    Default::\n\n        +/scripts/backlight 1\n\n``backlight_off``\n    Disable the backlight of the TFT display.\n\n    Default::\n\n        +/scripts/backlight 0\n\nNote: A path starting with ``+/`` is automatically expanded to the ``scripts``\ndirectory in the ``tentacle`` module.\n\nUser's Manual\n=============\n\nHard keys\n---------\n\nThe following keys are recognized:\n\n``escape``\n    Enter the system menu to execute control commands.\n    In the menu abort the menu and close it.\n\n``return``\n    Save a screen shot.\n    In the menu select and activate an item.\n\n``cursor up``\n    Enable the backlight of the display.\n    In the menu move one item up.\n\n``cursor down``\n    Disable the backlight of the display.\n    In the menu move one item down.\n\n\nAppendix\n========\n\nRaspberry Camera Setup\n----------------------\n\nIn my OctoPi_ based setup I added a Raspberry Pi Cam.\nIn order to make it work I enabled the ``Video4Linux`` driver in\n``/etc/modules``::\n\n    bcm2835_v4l2\n\nIf the image has the wrong orientation you can flip it in any direction with\nthe ``v4l2-ctl`` tool found in the ``v4l-utils`` package.::\n\n    v4l2-ctl --set-ctrl vertical_flip=1 --set-ctrl horizontal_flip=1\n\nTo make this change persistet simply add the line to ``/etc/rc.local``.\n\nThe camera is then auto detected by ``mjpeg streamer`` running on the OctoPi\nsystem.\n\n.. _OctoPi: https://octoprint.org/download/\n\nSetup an Adafruit PiTFT Plus 2.8\"\n---------------------------------\n\nAdafruit_ offers a nice small 2.8\" display with 320 x 240 pixels, a resistive\ntouch panel and four hard keys.\n\nFollow the Instructions_ for initial setup. It boils down to adding the HAT\nin ``/etc/config.txt`` with::\n\n    dtparam=spi=on\n    dtparam=i2c1=on\n    dtparam=i2c_arm=on\n    dtoverlay=pitft28-resistive,rotate=90,speed=64000000,fps=30\n\nNote the *rotation of 90 degrees* so I can use landscape mode with the correct\norientation.\n\n.. _Adafruit: https://www.adafruit.com/product/2298\n.. _Instructions: https://learn.adafruit.com/adafruit-pitft-28-inch-resistive-touchscreen-display-raspberry-pi\n\nSetup Hard keys\n+++++++++++++++\n\nHard keys are not essential to run *tentacle*, but they offer useful functions\nincluding controlling of the backlight without the need for touching.\n\nThe following GPIOs are connected to the PiTFT+ Hardkeys (from top to bottom):\n\n* 17\n* 22\n* 23\n* 27\n\nI added a device tree file that maps these to the following input keys (see\nthe `Linux Kernel input event header`_ for the codes):\n\n* 17: Escape (code 1)\n* 22: Cursor Up (code 103)\n* 23: Enter (code 28)\n* 27: Cursor Down (code 108)\n\nEnter the directory ``contrib/pitft-keys`` and run the the supplied\n``Makefile`` there to build the device tree overlay binary and\ninstall it in `/boot/`.\n\n.. code-block:: bash\n\n    $ cd contrib/pitft-keys\n    $ make install\n\nNote: It will ask for your user password to install the file via ``sudo``.\n\n.. _Linux Kernel input event header: https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h\n\nTouchscreen Calibration\n+++++++++++++++++++++++\n\nIt is essential to calibrate your touchscreen. Otherwise exact picking of UI\nelements with a stylus or even your fingers is not possible.\n\nPyQt5 in frame buffer mode is compiled for Raspbian to use libinput_ for\nreceiving touch panel events.\n\nUnfortunately, all documented ways I found on the net either assume ``tslib``\nor even ``X11`` support for calibration. Here is my own way I found with lots\ntrial and error.\n\n.. _libinput: https://www.freedesktop.org/wiki/Software/libinput/\n\nRunning the Calibration Tool on X11\n...................................\n\nYes, we want to run on frame buffer only but the only calibration tool I found\nstill uses X11. So we install a minimal X11 runtime just to start the tool.\n\nA minimal X11 server can be installed with:\n\n.. code-block:: bash\n\n    sudo apt-get install xserver-xorg xserver-xorg-video-fbdev xinit\n\nEdit ``/etc/X11/Xwrapper.config`` to allow everybody to start the server::\n\n    ...\n    allowed_users=anyboady\n\nNow selec the frame buffer of your display to run X11 on. My display uses\n``/dev/fb1``. Edit ``/usr/share/X11/xorg.conf.d/99-fbdev.conf``::\n\n    Section \"Device\"\n    Identifier \"myfb\"\n    Driver \"fbdev\"\n    Option \"fbdev\" \"/dev/fb1\"\n    EndSection\n\nNow run the X11 server once (preferrably from a ssh shell):\n\n.. code-block:: bash\n\n    $ startx &\n\nMake sure your current calibration matrix is reset:\n\n.. code-block:: bash\n\n    $ DISPLAY=:0.0 xinput set-prop \"stmpe-ts\" 'Coordinate Transformation Matrix' 1 0 0 0 1 0 0 0 1\n\nRun the calibration tool with:\n\n.. code-block:: bash\n\n    $ DISPLAY=:0.0 ./xtcal -geometry 320x240\n\nPick the drawn crosshairs with a stylus each and after that you get the matrix\nreported::\n\n    xinput set-prop <device name> 'Coordinate Transformation Matrix' 0.015731 -1.135927 1.014818 1.123037 0.017117 -0.062198 0 0 1\n\nWe are interested in the values of this matrix! So copy them in your\nclipboard.\n\nStop the X11 server as it is not needed anymore:\n\n.. code-block:: bash\n\n    $ pkill startx\n\nSave the Calibration Matrix for ``libinput``\n............................................\n\nWe need to assign the calibration matrix in an environment variable called\n``LIBINPUT_CALIBRATION_MATRIX``. This variable has to be set any time the\ntouchpanel device is detected and setup.\n\nThe PiTFT installer already has created a ``udev`` rule file\nthat creates a ``input/touchscren`` link for the touchpanel device.\nIn ``/etc/udev/rules.d/95-stmpe.rules`` we add the environment variable::\n\n    SUBSYSTEM==\"input\", ATTRS{name}==\"*stmpe*\", ENV{DEVNAME}==\"*event*\", SYMLINK+=\"input/touchscreen\", ENV{LIBINPUT_CALIBRATION_MATRIX}=\"0.015731 -1.135927 1.014818 1.123037 0.017117 -0.062198\"\n\nNote that only the first 6 values of the matrix are used here.\n\nReboot your Pi to make this matrix active.\n\nYou can check if the matrix is setup correctly with the\n``libinput-list-devices`` tool.\n\n.. code-block:: bash\n\n    $ sudo libinput-list-devices\n    Device:           stmpe-ts\n    ...\n    Calibration:      0.02 -1.14 1.01 1.12 0.02",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/cnvogelg/tentacle",
        "keywords": "",
        "license": "GPLv3+",
        "maintainer": "",
        "maintainer_email": "",
        "name": "tentacle",
        "package_url": "https://pypi.org/project/tentacle/",
        "platform": "",
        "project_url": "https://pypi.org/project/tentacle/",
        "project_urls": {
            "Homepage": "https://github.com/cnvogelg/tentacle"
        },
        "release_url": "https://pypi.org/project/tentacle/1.0.0/",
        "requires_dist": null,
        "requires_python": "~=3.4",
        "summary": "An OctoPrint frontend suitable for small displays",
        "version": "1.0.0"
    },
    "last_serial": 4919512,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e9cdabe6ee3f0d378ab6bce6d7e39c87",
                    "sha256": "1d3ac4a1fc34dba6d5f7c5c173821d5cfe6e0269a76bd829fa83549d1c2003b2"
                },
                "downloads": -1,
                "filename": "tentacle-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "e9cdabe6ee3f0d378ab6bce6d7e39c87",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": "~=3.4",
                "size": 49320,
                "upload_time": "2019-03-09T20:13:25",
                "url": "https://files.pythonhosted.org/packages/3e/93/7bf4cc7205060d4915fe78e235c60ae38be83048757aa494dffe5bb2ee8c/tentacle-1.0.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "e9cdabe6ee3f0d378ab6bce6d7e39c87",
                "sha256": "1d3ac4a1fc34dba6d5f7c5c173821d5cfe6e0269a76bd829fa83549d1c2003b2"
            },
            "downloads": -1,
            "filename": "tentacle-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "e9cdabe6ee3f0d378ab6bce6d7e39c87",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "~=3.4",
            "size": 49320,
            "upload_time": "2019-03-09T20:13:25",
            "url": "https://files.pythonhosted.org/packages/3e/93/7bf4cc7205060d4915fe78e235c60ae38be83048757aa494dffe5bb2ee8c/tentacle-1.0.0.tar.gz"
        }
    ]
}