What does that mean? Send the command twist.getCount() and you’ll get the number of steps the user has twisted the knob. For example, 312 or -23 depending on the direction and amount the user and turned the knob. The Twist takes care of all the various interrupts, switches, PWM'ing of LEDs and presents all those features over an easy-to-use I2C interface. The Qwiic Twist was designed to get rid of the large mass of wires that are needed to implement an RGB encoder in a breadboard. Now you can get encoder position with something as twist.getCount(); and your microcontroller can keep focused on other more important tasks.

The Qwiic Twist has an indent type encoder which gives the user a great ‘clicky’ feel as they turn. The Qwiic Twist also has an RGB LED and a built-in button. We’ve written an Arduino library to make controlling these features as easy as:

And finally, the I2C address of Qwiic Twist is software configurable which means you can hookup over 100 Twists on a single I2C bus!

Required Materials

To follow along with this hookup guide, you will need one of the following Qwiic shields with an Arduino. You may not need everything though depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary.

Tip: You could also use the SparkX BlackBoard. It's basically a RedBoard with additional features. This would reduce the amount of components and time soldering headers to the board. Keep in mind that SparkX products are rapidly produced to bring you the most cutting edge technology as it becomes available. SparkX products are tested but come with no guarantees. Live technical support is not available for SparkX products.

You will also need a Qwiic cable to connect the shield to your Twist, choose a length that suits your needs. The Qwiic to breadboard cable is good if you want to easily plug the Qwiic Twist into a 3.3V platform such as Teensy.

Tools

The Qwiic Twist is designed to be easily connected to a Qwiic bus without soldering. But if you choose to connect to the I2C pins directly you may need a soldering iron, solder, and general soldering accessories.

Hardware Overview

The encoder works best with the Clear Plastic Knob but is compatible with any knob with a 6mm knurled hole. The encoder output is filtered through a series of resistors, capacitors, and error checked in software to be sure the accurate number of ticks is being output.

The encoder has an RGB LED built into it. To get the full light effect we recommend a clear knob but depending on your setup you may also be able to get a ‘backlit’ effect with an opaque knob. The RGB LEDs are pulse-width-modulated and controlled via software (and backed by non-volatile memory) so you can tell the Qwiic Twist to go to any color you want and it will be that color now and even after the Twist is power cycled (it remembers the last color setting).

The encoder has a built-in momentary button. This is useful for selecting menu items and getting general feedback from the user.

Qwiic I2C Pins

The Qwiic Twist is best used with the Qwiic system. Simply plug a Qwiic Cable into the Twist and start talking to it.

Alternatively you can solder to the I2C pins on the board.

Heads Up! The Qwiic Twist is designed to operate at 3.3V so please don’t drive it at 5V. Your I2C pins, however, can be 5V logic.

RST and INT

The reset pin is an active low input. When pulled low Qwiic Twist will be held in reset.

The INT pin is active low and is open drain output. The interrupt pin will go low when any of the follow events happen:

The user presses the button is pressed or released.

The user has turned the knob and no movement has been detected for a certain amount of time.
This amount of time is called the turnInterruptTimeout and is 250ms by default. This means that once the user has stopped turning the knob for 250ms the interrupt will fire. This is helpful when the user is doing lots of knob changes. The Qwiic Twist won’t fire the interrupt until the user has stopped fidgeting. The turnInterruptTimeout is software configurable from 1ms to 65000ms (65 seconds).

The INT pin is open drain and is pulled up through a 10k resistor but if you want to connect multiple Twists and share the interrupt pins among many Twists then you can optionally cut the jumper to remove the 10k pull up on each Twist board.

Jumpers

The ADR jumper is normally open and controls the I2C address of the device. By default the Qwiic Twist 7-bit unshifted address is 0x3F. If the jumper is closed with solder, the address will become 0x3E.

The Twist is unique in that it can have any address assigned to it between 0x08 and 0x77. This means over 100 Twists can be connected on a single bus!

Note: If the ADR jumper is closed then Qwiic Twist will resort to address 0x3E regardless of what address may have been configured via software commands. This is a safety mechanism in case the Twist gets set to an unknown address.

The INT jumper is a normally closed jumper; there is a small trace connecting the two pads. This jumper connects the INT pin on the ATtiny84 through a 10k resistor to 3.3V. Cutting the small trace disconnects the 10k resistor from the INT pin on the ATtiny84.

The INT pin on Qwiic Twist is open drain, meaning the pin will actively go low when an interrupt occurs but will then float when there is no interrupt. This open drain type of setup is handy if you have multiple devices sharing a single interrupt line. For advanced applications (such as many many Twists all sharing the same INT pin) you may want to cut this jumper on each Twist to remove the 10k pull ups. For general use you can leave this jumper unmodified.

The Qwiic Twist has built-in 2.2k pull-up resistors on the SDA and SCL lines. These are needed for normal I2C communication. The I2C jumper has two small traces connecting the pull-ups to 3.3V. For general use you can leave this jumper unmodified. If you have many (over 7) devices on the I2C bus, each with their own pull up resistors, then you may want to cut the I2C jumpers to disconnect the 2.2k resistors on each Qwiic board.

Qwiic Twist Arduino Library

Note: This example assumes you are using the latest version of the Arduino IDE on your desktop. If this is your first time using Arduino, please review our tutorial on installing the Arduino IDE. If you have not previously installed an Arduino library, please check out our installation guide.

We’ve written an easy to use Arduino library that covers the gamut of features on the Qwiic Twist. The easiest way to install the library is by searching SparkFun Twist within the Arduino library manager. We’ve even got a tutorial on installing an Arduino library if you need it. You can also manually install the Qwiic Twist library by downloading a zip:

Connect functions set the relation between each color and the twisting of the knob. These functions connect the LED so it changes [amount] with each encoder tick without the master intervening. Negative numbers are allowed (so LED gets brighter the more you turn the encoder down).

Register Map

The Qwiic Twist behaves as a normal I2C slave. First write the address of the register you would like to read or write, then follow that I2C command with a Read to read the given register or a Write and a data byte to write to a register. The register address pointer is auto-incrementing so you can read and write multiple registers at a time.

Connecting Colors

One of the more advanced (but really handy) features of Qwiic Twist is the ability to connect the color control to the knob movement. What this means is that you can have the red LED brightness increase or decrease as the user turns the knob without sending commands to the Qwiic Twist. This greatly increases the responsiveness of the knob illumination and dramatically reduces I2C traffic.

In the above photo we have connected blue to increase brightness by 10 for every tick increment, and connected red to -10 per tick. The color changes automatically without the need for intervention from the I2C master. The color connect values are stored in the Qwiic Twist and will be loaded after each power-on.

Resources and Going Further

SparkFun Qwiic Twist Arduino Library - for easy interfacing to the Qwiic Twist including a litany of examples. This is most easily installed by searching the Arduino Library Manager for ‘SparkFun Twist’.

Hardware repo - For Qwiic Twist that includes the firmware for the ATtiny84

In 2003, CU student Nate Seidle fried a power supply in his dorm room and, in lieu of a way to order easy replacements, decided to start his own company. Since then, SparkFun has been committed to sustainably helping our world achieve electronics literacy from our headquarters in Boulder, Colorado.

No matter your vision, SparkFun's products and resources are designed to make the world of electronics more accessible. In addition to over 2,000 open source components and widgets, SparkFun offers curriculum, training and online tutorials designed to help demystify the wonderful world of embedded electronics. We're here to help you start something.