Qwiic Twist Hookup Guide

Contributors: Nate

Qwiic Twist Arduino Library

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:

• Example 1 - Basic reading of the encoder value
• Example 2 - Set the Knob Color
• Example 3 - Displaying Crazy Colors on Knob
• Example 4 - Connect Colors: Change knob color from blue to red based on position
• Example 5 - Reading Time Stamps
• Example 6 - Display encoder difference since last reading
• Example 7 - Set the encoder count value
• Example 8 - Enabling and reading interrupts
• Example 7 - Set the encoder count value
• Example 9 - Change the I²C address
• Example 10 - Advanced Wire settings

Below are the various functions that can be called from the library. Most of these functions are demonstrated in the examples so we recommend you go through each example first.

• boolean begin(TwoWire &wirePort, uint8_t deviceAddress);
• int16_t getCount(); -- Returns the number of indents the user has turned the knob
• boolean setCount(int16_t amount); -- Set the number of indents to a given amount
• int16_t getDiff(boolean clearValue = true); -- Returns the number of ticks since last check. Clears the difference once read.
• boolean isMoved(); -- Returns true if knob has been twisted
• boolean isPressed(); -- Return true if button is currently pressed.
• boolean isClicked(); -- Returns true if a click event has occurred. Event flag is then reset.
• uint16_t timeSinceLastMovement(boolean clearValue = true); -- Returns the number of milliseconds since the last encoder movement. Clears value once read.
• uint16_t timeSinceLastPress(boolean clearValue = true); -- Returns the number of milliseconds since the last button event (press and release). Clears value once read.

Color functions set the brightness of each LED.

• boolean setColor(uint8_t red, uint8_t green, uint8_t blue); -- Sets the color of the encoder LEDs, 0-255
• boolean setRed(uint8_t); -- Set the red LED, 0-255
• boolean setGreen(uint8_t); -- Set the green LED, 0-255
• boolean setBlue(uint8_t); -- Set the blue LED, 0-255
• uint8_t getRed(); -- Get current value
• uint8_t getGreen(); -- Get current value
• uint8_t getBlue(); -- Get current value

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).

• boolean connectColor(int16_t red, int16_t green, int16_t blue); -- Connect all colors in one command
• boolean connectRed(int16_t); -- Connect individual colors
• boolean connectGreen(int16_t); -- Connect individual colors
• boolean connectBlue(int16_t); -- Connect individual colors
• int16_t getRedConnect(); -- Get the connect value for each color
• int16_t getGreenConnect();
• int16_t getBlueConnect();

General functions get and set various aspects of the Twist.

• uint16_t getIntTimeout(); -- Get number of milliseconds that must elapse between end of knob turning and interrupt firing
• boolean setIntTimeout(uint16_t timeout); -- Set number of milliseconds that elapse between end of knob turning and interrupt firing
• void clearInterrupts(); -- Clears the moved and button interrupts as well as the pressed and clicked event bits
• boolean isConnected(); -- Returns true if sensor is detected
• uint16_t getVersion(); -- Returns a two byte firmware version
• void changeAddress(uint8_t newAddress); -- Change the I²C address to newAddress