tentacle 1.0.0

An OctoPrint frontend suitable for small displays

Contents

• 1 Features

• 2 Installation

  • 2.1 Linux / Raspberry Pi

    • 2.1.1 Install with PIP3

    • 2.1.2 Manual startup

    • 2.1.3 Autostart with systemd

  • 2.2 macOS

• 3 Configuration

  • 3.1 Section octoprint

  • 3.2 Section qt

  • 3.3 Section app

  • 3.4 Section temp

  • 3.5 Section move

  • 3.6 Section tool

  • 3.7 Section ser

  • 3.8 Section cam

  • 3.9 Section commands

• 4 User’s Manual

• 5 Appendix

  • 5.1 Raspberry Camera Setup

  • 5.2 Setup an Adafruit PiTFT Plus 2.8”

    • 5.2.1 Setup Hard keys

    • 5.2.2 Touchscreen Calibration

      • 5.2.2.1 Running the Calibration Tool on X11

      • 5.2.2.2 Save the Calibration Matrix for libinput

1 Features

• Stylus-friendly UI suitable for tiny TFTs

• TFT Resolution of 320x240 and upwards supported

• Low resource usage: PyQt5 running directly on framebuffer without X11

• All relevant OctoPrint parameters are available in UI Tabs:

  • Shows details on current print Job

  • Shows available print Files and allows to select one for printing

  • Shows Temperature Curves of Hotends and Bed

  • A Move Panel allows to move the tools

  • A GCode Display shows the current layer while printing

  • A Camera View shows your streamed camera

2 Installation

2.1 Linux / Raspberry Pi

• First setup your TFT and the (calibrated) touch input. Typically your TFT’s framebuffer device is /dev/fb1 See Appendix for details on my setup.

2.1.1 Install with PIP3

• Install the PyQt5 package for Python 3 with apt:

$ sudo apt install python3-pyqt5

• Install tentacle with pip

$ sudo apt install python3-pip
$ pip3 install tentacle

This will install tentacle for the current user only. If you want to install the package system-wide use sudo:

$ sudo pip3 install tentacle

2.1.2 Manual startup

Now you can test run the binary from a remote shell (ssh):

$ tentacle -v

Use manual startup to tweak your Configuration

2.1.3 Autostart with systemd

In systemd/tentacle.service you’ll find a template service file for systemd. Adjust and copy this file to /etc/systemd/system/.

Make sure the user is setup correctly. Default is pi.

Try to run the service with:

$ sudo systemctl start tentacle

See the status with:

$ sudo systemctl status tentacle

Stop the service with:

$ sudo systemctl stop tentacle

To permanently enable the service for the next boot use:

$ sudo systemctl enable tentacle

Done!

2.2 macOS

You can run tentacle on your Mac in a window to test the UI.

• First install PyQt5 with:

$ pip install pyqt5

• Then install tentacle:

$ pip install tentacle

3 Configuration

While tentacle already ships with a sensible set of default configuration parameters you can adjust them as you need.

The configuration file is called tentacle.cfg and searched at the following locations:

• current working directory (suitable for test runs)

• $HOME/.tentacle.cfg

• /etc/tentacle.cfg (suitable for systemd setup)

The config has INI like syntax and is split into sections. To get the default configuration just run tentacle --dump-config to write it into a file:

$ tentacle --dump-config tentacle.cfg

3.1 Section octoprint

url

The URL to reach OctoPrint. Either use http: or https:. Make sure the hostname matches (default: octopi).

Default:

http://octopi

api_key

Give the API key you created in OctoPrint to allow to execute commands via the REST API.

3.2 Section qt

fb_dev

The frame buffer device of your TFT display.

Default:

/dev/fb0

ts_dev

The touch screen input device.

Default:

/dev/input/touchscreen

3.3 Section app

Global settings for the whole UI.

font_family and font_size

Specify the font used for the UI.

width and height

The size of your display

dark

Enable dark mode. Disable to see light mode.

style

Select a specific Qt widget style

3.4 Section temp

Settings for the temp tab in the UI.

font_family and font_size

Specify the font used for the UI temperate labels

min and max

Set the minimum and maximum temperature shown in graph.

step

Set the line and label stepping in the graph display.

3.5 Section move

Settings for the move tab in the UI.

unload_z

The Z axis position to move to when selecting the Unload button.

label_a and label_b

The label text to be displayed for the custom move buttons.

pos_a and pos_b

The X,Y,Z position to move to when selecting a custom button.

3.6 Section tool

Settings for the tool tab in the UI.

t{0,1}_temp{1,2} and bed_temp{1,2}

Set the default temperature for the tools 0, 1, and the bed.

3.7 Section ser

Settings for the ser tab in the UI.

font_family and font_size

Specify the font used for the UI serial log output

3.8 Section cam

Settings for the cam tab in the UI.

url

The the URL of mjpeg streamer to get the mjpeg stream from your camera.

Default:

http://octopi:8080/?action=stream

3.9 Section commands

Configure various external commands triggered by tentacle.

Note: Make sure the user running tentacle is allowed to perform these commands. You may need to add sudo and configure it to run the commands without password input.

restart_octoprint

Restart the OctoPrint server.

Default:

/bin/systemctl restart octoprint

reboot_sys

Reboot the whole system.

Default:

/sbin/reboot

poweroff_sys

Power off the system.

Default:

/sbin/poweroff

backlight_on

Enable the backlight of the TFT display.

Default:

+/scripts/backlight 1

backlight_off

Disable the backlight of the TFT display.

Default:

+/scripts/backlight 0

Note: A path starting with +/ is automatically expanded to the scripts directory in the tentacle module.

4 User’s Manual

Hard keys

The following keys are recognized:

escape

Enter the system menu to execute control commands. In the menu abort the menu and close it.

return

Save a screen shot. In the menu select and activate an item.

cursor up

Enable the backlight of the display. In the menu move one item up.

cursor down

Disable the backlight of the display. In the menu move one item down.

5 Appendix

5.1 Raspberry Camera Setup

In my OctoPi based setup I added a Raspberry Pi Cam. In order to make it work I enabled the Video4Linux driver in /etc/modules:

bcm2835_v4l2

If the image has the wrong orientation you can flip it in any direction with the v4l2-ctl tool found in the v4l-utils package.:

v4l2-ctl --set-ctrl vertical_flip=1 --set-ctrl horizontal_flip=1

To make this change persistet simply add the line to /etc/rc.local.

The camera is then auto detected by mjpeg streamer running on the OctoPi system.

5.2 Setup an Adafruit PiTFT Plus 2.8”

Adafruit offers a nice small 2.8” display with 320 x 240 pixels, a resistive touch panel and four hard keys.

Follow the Instructions for initial setup. It boils down to adding the HAT in /etc/config.txt with:

dtparam=spi=on
dtparam=i2c1=on
dtparam=i2c_arm=on
dtoverlay=pitft28-resistive,rotate=90,speed=64000000,fps=30

Note the rotation of 90 degrees so I can use landscape mode with the correct orientation.

5.2.1 Setup Hard keys

Hard keys are not essential to run tentacle, but they offer useful functions including controlling of the backlight without the need for touching.

The following GPIOs are connected to the PiTFT+ Hardkeys (from top to bottom):

• 17

• 22

• 23

• 27

I added a device tree file that maps these to the following input keys (see the Linux Kernel input event header for the codes):

• 17: Escape (code 1)

• 22: Cursor Up (code 103)

• 23: Enter (code 28)

• 27: Cursor Down (code 108)

Enter the directory contrib/pitft-keys and run the the supplied Makefile there to build the device tree overlay binary and install it in /boot/.

$ cd contrib/pitft-keys
$ make install

Note: It will ask for your user password to install the file via sudo.

5.2.2 Touchscreen Calibration

It is essential to calibrate your touchscreen. Otherwise exact picking of UI elements with a stylus or even your fingers is not possible.

PyQt5 in frame buffer mode is compiled for Raspbian to use libinput for receiving touch panel events.

Unfortunately, all documented ways I found on the net either assume tslib or even X11 support for calibration. Here is my own way I found with lots trial and error.

5.2.2.1 Running the Calibration Tool on X11

Yes, we want to run on frame buffer only but the only calibration tool I found still uses X11. So we install a minimal X11 runtime just to start the tool.

A minimal X11 server can be installed with:

sudo apt-get install xserver-xorg xserver-xorg-video-fbdev xinit

Edit /etc/X11/Xwrapper.config to allow everybody to start the server:

...
allowed_users=anyboady

Now selec the frame buffer of your display to run X11 on. My display uses /dev/fb1. Edit /usr/share/X11/xorg.conf.d/99-fbdev.conf:

Section "Device"
Identifier "myfb"
Driver "fbdev"
Option "fbdev" "/dev/fb1"
EndSection

Now run the X11 server once (preferrably from a ssh shell):

$ startx &

Make sure your current calibration matrix is reset:

$ DISPLAY=:0.0 xinput set-prop "stmpe-ts" 'Coordinate Transformation Matrix' 1 0 0 0 1 0 0 0 1

Run the calibration tool with:

$ DISPLAY=:0.0 ./xtcal -geometry 320x240

Pick the drawn crosshairs with a stylus each and after that you get the matrix reported:

xinput set-prop <device name> 'Coordinate Transformation Matrix' 0.015731 -1.135927 1.014818 1.123037 0.017117 -0.062198 0 0 1

We are interested in the values of this matrix! So copy them in your clipboard.

Stop the X11 server as it is not needed anymore:

$ pkill startx

5.2.2.2 Save the Calibration Matrix for libinput

We need to assign the calibration matrix in an environment variable called LIBINPUT_CALIBRATION_MATRIX. This variable has to be set any time the touchpanel device is detected and setup.

The PiTFT installer already has created a udev rule file that creates a input/touchscren link for the touchpanel device. In /etc/udev/rules.d/95-stmpe.rules we add the environment variable:

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"

Note that only the first 6 values of the matrix are used here.

Reboot your Pi to make this matrix active.

You can check if the matrix is setup correctly with the libinput-list-devices tool.

$ sudo libinput-list-devices
Device:           stmpe-ts
...
Calibration:      0.02 -1.14 1.01 1.12 0.02