todbot / qtpy-knob

QT Py Media Knob using rotary encoder & neopixel ring

QTPy-Knob

QT Py USB Media Knob using rotary encoder & neopixel ring

The QTPy-Knob features:

• Media knob for volume up/down/mute with "qtpy-knob.py" CircuitPython program
• Stylish design reminiscent of Griffin Powermate
• Recessed USB-C connector to for safety
• No screws needed for assembly
• Only 3 wires needed to solder (none if you want to forgo LED lighting)
• Reprogrammable for any USB macro key action via CircuitPython

A small video about it: https://www.youtube.com/watch?v=pt7JgoSlgOg

This is an attempt to make a minimal and easy-to-build version of similar, previous projects like:

• https://learn.adafruit.com/trinket-usb-volume-knob
• https://learn.adafruit.com/media-dial

Components

Parts needed:

• Adafruit QT Py (Originally for QTPy M0 or XIAO SAMD21, but QTPy RP2040 does work via a fakerotaryio hack)
• Adafruit Neopixel Ring (https://www.adafruit.com/product/1463 or equiv)
• Rotary encoder (PEC11-4120F-S0018 or equiv. The 3D printed case expects encoder w/ 20mm shaft & 7mm threaded barrel, see here for mods if using a 15mm encoder)
• 3D printed enclosure (see "cad" folder)

Software

For some of the scripts and for some QT Py variants, there are prebuilt UF2 firmware images in Releases.

Otherwise, software installation consists of:

• Install CircuitPython on the QT Py
• Install required CircuitPython libraries to QT Py
• Copy qtpy_knob.py to QT Py

The CircuitPython installation step is described here: https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython

The last two steps can be accomplished with the below

git clone https://github.com/todbot/qtpy-knob
cd qtpy-knob
pip3 install circup
circup install -r requirements.txt
cp qtpy_knob.py /Volumes/CIRCUITPY/code.py

RP2040 NOTE: And if you have a QTPy RP2040, be sure to copy the "fakerotaryio.py" file to CIRCUITPY as well.

Variations

There are a few variations of the code provided:

• qtpy_knob.py -- volume up / down and mute
• qtpy_knob_scroller.py -- performs vertical & horizontal scrolling
• qtpy_knob_midi_cc.py -- sends MIDI CC instead of keyboard/mouse
• qtpy_knob_simple.py -- no neopixel stuff, just encoder and USB vol up/down sending

Assembly

Steps:

1. Plug rotary encoder to bottom of QT Py. If your encoder has metal on the bottom, add a bit of tape (Kapton, Scotch, electrical) in between the QT Py and the encoder. If your encoder has mounting tabs, cut them off. Solder the five pins.

2. Print out the enclosure on your 3d printer. Standard 0.2mm at 20% infill is fine. The STL files are:

• qtpyknob-base.stl -- Base that houses the QT Py & rotary encoder
• qtpyknob-basecap.stl -- Cap that goes on the bottom of the base
• qtpyknob-knob.stl -- Knob that you turn
• qtpyknob-diffuser.stl -- Light diffuser that goes between base & knob, should be printed with translucent or clear plastic. Or you can leave it out. Or you can approxiate it with a disk cut out clear plastic like a CD case

Use the rotary encoder's washer & screw to hold QTPy+encoder assembly

3. Solder three wires to the Neopixel ring, insert the ring into the enclosure and solder the wires to the 3V, Gnd, and MI pins of the QT Py. Use a bit of hot glue to secure the Neopixel ring if it doesn't snap in.

4. Snap the bottom cap on and the knob top on and you're done with physical assembly!

Wiring diagram

Assembly animation

Useful links

Resources that helped me out on this:

• https://learn.adafruit.com/media-dial
• https://learn.adafruit.com/make-it-a-keyboard/circuitpython
• https://github.com/adafruit/Adafruit_CircuitPython_HID/tree/master/examples
• https://circuitpython.readthedocs.io/projects/hid/en/latest/api.html#adafruit-hid-consumer-control-consumercontrol
• https://learn.adafruit.com/trinket-usb-volume-knob

qtpy-knob's Issues

Renaming to avoid "-" and use "_".

Thank you for this piece of code and great idea.

Just a suggestion to avoid "-" into python file name and user "_" instead.

This permit to never rename the original file from the project and have a code.py like this:

import qtpy_knob_simple
#import qtpy_knob_scroller
#import qtpy_knob

PS: I have both QT-Py and Seeduino XIAO in the same form factor... my QT-Py is more precious because it has reset button, Stemma-QT pin, RGB. So I wanted to rename the pin for XIAO use... but there is no need, your code works out of the box on the same physical pin with the same code. Only the through hole seems smaller on the XIAO so it does not fit perfectly flush. Did I mention it does also kind of work without soldering!!!

minor issues around encoder fit

Noticed a couple of things when using the specified Bourns PEC11-4215F-S24 encoder:

1. The diffuser ring is too thick for the lock nut to fasten. It's 2 mm thick, and there's exactly 2 mm of thread left on the encoder.
2. The D-shaft cutout in the top is too deep to allow the encoder shaft switch to trigger.

Otherwise, it's a fantastic project and very easy to make. Yes, I used a Seeeduino XIAO, too

Workarounds

I made the central part of the diffuser thinner so the lock nut would fasten. Excuse the OpenSCAD, it's all I know:

bbox = [ 49.988811, 49.994404, 2.000000 ];
minima = [ -25.000000, -24.997202, 2.700000 ];

difference() {
    translate([-bbox.x/2, -bbox.y/2, 0])translate(-minima)import("qtpyknob-diffuser.stl");
    translate([0,0,0.8])cylinder(d=bbox.x/2, h=bbox.z);
}

For the D-shaft cutout, a blob of Blu Tack of just the right size mostly fixes the issue.

2023 - circuit python 8.0.3 - sequential pins rotaryio?

le.
main.py output:
Traceback (most recent call last):
File "main.py", line 30, in
RuntimeError: Pins must be sequential GPIO pins

Code done running.

Press any key to enter the REPL. Use CTRL-D to reload.

GIF playback control?

Can this knob be used to control gif playback?