Package: pimoroni-encoderwheel
RGB Encoder Wheel BreakoutRGB Encoder Wheel is a breakout for the ANO directional navigation and scroll wheel rotary encoder. It uses a Nuvoton MS51 microcontroller to read the encoder and direction buttons via I2C, and features a IS31FL3731 LED driver to control a ring of 24 RGB LEDs that surround the encoder.Buy it from:https://shop.pimoroni.com/products/rgb-encoder-wheel-breakoutGetting the LibraryStable library only (no examples) from PyPi:Just runpython3 -m pip install pimoroni-encoderwheelIn some cases you may need to install pip with:sudo apt install python3-pipStable library, with latest examples from GitHub:git clone https://github.com/pimoroni/encoderwheel-pythoncd encoderwheel-python./install.shLatest/development library and examples from GitHub:git clone https://github.com/pimoroni/encoderwheel-pythoncd encoderwheel-python./install.sh --unstableConfiguring your Raspberry PiEnable I2CIn order to use the Encoder Wheel, you need to enable the I2C interface of your Raspberry Pi. This can be done in the terminal by running:sudo raspi-config nonint do_i2c 0Alternatively, you can enable the I2C interface by:runningsudo raspi-configand enabling the option underInterfacing Options.opening the graphicalRaspberry Pi Configurationapplication from thePreferencesmenu.You may need to reboot after enabling I2C for the change to take effect.Examples and UsageThere are various examples to get you started with your Encoder Wheel. With the library installed on your Raspberry Pi, these can be found in the~/Pimoroni/pimoroni-encoderwheel/examplesdirectory.To take Encoder Wheel further, the full API is described in thelibrary reference.Removing the LibraryTo uninstall the library only (keeping all examples):Just runpython3 -m pip uninstall pimoroni-encoderwheelOr if you have grabbed the library from Github:cd encoderwheel-python./uninstall.shReferenceGetting StartedTo start coding for your Encoder Wheel breakout, you will need to add the following lines to the start of your code file.fromencoderwheelimportEncoderWheelwheel=EncoderWheel()This will create anEncoderWheelclass calledwheelthat will be used in the rest of the examples going forward.Reading the ButtonsEncoderWheel has five buttons, covering up, down, left, right, and centre. These can be read using the.pressed(button)function, which accepts a button number between0and4. For convenience, each button can be referred to using these constants:UP=0DOWN=1LEFT=2RIGHT=3CENTRE=4For example, to read the centre button you would write:centre_state=wheel.pressed(CENTRE)You can also get the number of buttons using theNUM_BUTTONSconstant.Reading the EncoderWithin the directional buttons of the Encoder Wheel breakout is a rotary encoder with 24 counts per revolution.Count and AngleThe current count can be read by calling.count(). It can also be read back as either the number of.revolutions()of the encoder, or the angle in.degrees()or.radians().Be aware that the count is stored as an integer, if it is continually increased or decreased it will eventually wrap at+2147483647and-2147483648. This will cause a jump in the returned by.revolutions(),degrees()and.radians(), that will need handling by your code.In practice this will take an extremely long time to reach.Count DeltaOften you are not interested in the exact count that the encoder is at, but rather if the count has changed since the last time you checked. This change can be read by calling.delta()at regular intervals. The returned value can then be used with a check in code, for the value being non-zero.Step and TurnSometimes it can be useful to know the encoder's position in the form of which step it is at and how many turns have occurred. The current step can be read by calling.step(), which returns a value from0to23, and the number of turns can be read by calling.turn().These functions differ from reading the.count()or.revolutions()by using separate counters, and so avoid the wrapping issue that these functions experience.Changing the DirectionThe counting direction of an encoder can be changed by calling.direction(REVERSED_DIR)at any time in code. TheREVERSED_DIRconstant comes from theioexpander.commonmodule. There is also aNORMAL_DIRconstant, though this is the default.Resetting to ZeroThere are times where an encoder's count (and related values) need to be reset back to zero. This can be done by calling.zero().LEDsThe Encoder Wheel breakout features 24 RGB LEDs arranged in a ring around the wheel. This is the same number as there are steps on the wheel, letting you use the LEDs to show the current step of the wheel.Setting an LEDYou can set the colour of a LED on the ring in either the RGB colourspace, or HSV (Hue, Saturation, Value). HSV is useful for creating rainbow patterns.RGBSet the first LED -0- to Purple255, 0, 255:wheel.set_rgb(0,255,0,255)HSVSet the first LED -0- to Red0.0:wheel.set_hsv(0,0.0,1.0,1.0)Clear all LEDsTo turn off all the LEDs, the function.clear()can be called. This simply goes through each LED and sets its RGB colour to black, making them emit no light.This function is useful to have at the end of your code to turn the lights off, otherwise they will continue to show the last colours they were given.ShowingChanges to the LEDs do not get applied immediately, due to the amount of I2C communication involved. As such, to have the LEDs show what they have been set to after calling the.set_rgb(),.set_hsv(), and.clear()functions, a specific call to.show()needs to be made.GPIOsThere are three spare GPIO pins on the edge of Encoder Wheel. These can be used as digital outputs, pwm outputs, digital inputs, and analog inputs.SetupTo start using a GPIO pin, first import one of the handy constants used to reference them (seeGPIO Constants). For example, to use the first GPIO pin:fromencoderwheelimportGP7Then you need to import the constants for the pin mode to use. These are on theioexpandermodule that Encoder Wheel is based on.# For inputfromioexpanderimportIN# or IN_PU of a pull-up is wanted# For outputfromioexpanderimportOUT# For PWMfromioexpanderimportPWM# For ADCfromioexpanderimportADCModeWith the intended constants imported, the mode of a GPIO pin can be set by calling.gpio_pin_mode(gpio, mode):wheel.gpio_pin_mode(GP7,<INorIN_PUorOUTorPWMorADC>)It is also possible to read the current mode of a GPIO pin by calling.gpio_pin_mode(gpio):mode=wheel.gpio_pin_mode(GP7)As Input or ADCThe current value of an GPIO pin in input or ADC mode can be read by calling.gpio_pin_value(gpio):value=wheel.gpio_pin_value(GP7)If the mode is digital, the value will either be0or1.
If the mode is analog, the value will be a voltage from0.0to3.3.As OutputThe current value of a GPIO pin in output mode can be set by calling.gpio_pin_value(gpio, value):wheel.gpio_pin_value(GP7,value)The expected value is either0or1, orTrueorFalse.As PWMThe GPIO pins can also be set as PWM outputs. ThePWMconstant can be imported from theioexpandermodule, and passed into the.gpio_pin_mode()function.The frequency of the PWM signal can then be configured by calling.gpio_pwm_frequency(), which accepts a frequency (in Hz). It returns the cycle period, which should be used to set duty cycles.Finally, the duty cycle of the PWM signal can be set by calling.gpio_pin_value()and providing it with a value between0and the cycle period.Below is an example of setting a gpio pin to output a 25KHz signal with a 50% duty cycle:fromioexpanderimportPWMfromencoderwheelimportEncoderWheel,GP7# Initialise EncoderWheelwheel=EncoderWheel()# Setup the gpio pin as a PWM outputwheel.gpio_pin_mode(GP7,PWM)# Set the gpio pin's frequency to 25KHz, and record the cycle periodperiod=wheel.gpio_pwm_frequency(25000)# Output a 50% duty cycle square wavewheel.gpio_pin_value(GP7,int(period*0.5))Delayed LoadingBy default, changes to a gpio pin's frequency or value are applied immediately. However, sometimes this may not be wanted, and instead you want all pins to receive updated parameters at the same time, regardless of how long the code ran that calculated the update.For this purpose,.gpio_pwm_frequency()and.gpio_pin_value()include an optional parameterload, which by default isTrue. To avoid this "loading" includeload=Falsein the relevant function calls. Then either the last call can includeload=True, or a specific call to.gpio_pwm_load()can be made.In addition, any function that performs a load, including the.gpio_pwm_load()function, can be made to wait until the new PWM value has been sent out of the pins. By default this is disabled, but can be enabled by includingwait_for_load=Truein the relevant function calls.LimitationsAll of Encoder Wheel's PWM outputs share the same timing parameters. This means that GP7, GP8, and GP9 share the same frequency. Keep this in mind if changing the frequency of one, as the others will not automatically know about the change, resulting in unexpected duty cycle outputs.Function ReferenceHere is the complete list of functions available on theEncoderWheelclass:EncoderWheel(ioe_address=0x13,led_address=0x77,interrupt_timeout=1.0,interrupt_pin=None,skip_chip_id_check=False)set_ioe_address(address)get_interrupt_flag()clear_interrupt_flag()pressed(button)count()delta()step()turn()zero()revolutions()degrees()radians()direction()direction(direction)set_rgb(index,r,g,b)set_hsv(index,h,s=1.0,v=1.0)clear()show()gpio_pin_mode(gpio)gpio_pin_mode(gpio,mode)gpio_pin_value(gpio)gpio_pin_value(gpio,value,load=True,wait_for_load=False)gpio_pwm_load(wait_for_load=True)gpio_pwm_frequency(frequency,load=True,wait_for_load=True)Constants ReferenceHere is the complete list of constants on theencoderwheelmodule:Address ConstantsDEFAULT_IOE_I2C_ADDR=0x13DEFAULT_LED_I2C_ADDR=0x77ALTERNATE_LED_I2C_ADDR=0x74Button ConstantsUP=0DOWN=1LEFT=2RIGHT=3CENTRE=4GPIO ConstantsGP7=7GP8=8GP9=9GPIOS= (7,8,9)Count ConstantsNUM_LEDS=24NUM_BUTTONS=5NUM_GPIOS=30.0.1Initial Release