Duppa I2C MIDI Controller – Part 4

This is revisiting my Duppa I2C MIDI Controller this time using a Waveshare Zero format device.

• Part 1 – getting to know the devices and testing them out.
• Part 2 – adding MIDI to the LED ring and I2C encoder.
• Part 3 – adding normal encoder, plain potentiometer, and endless potentiometer control.
• Part 4 – revisits the idea with Waveshare Zero format devices and adds USB MIDI.

Warning! I strongly recommend using old or second hand equipment for your experiments.  I am not responsible for any damage to expensive instruments!

If you are new to Arduino, see the Getting Started pages.

Parts list

• Waveshare Zero ESP32-S3 or RP2040.
• DuPPa small RGB LED Ring.
• 10K potentiometer.
• Bespoke hook-up wires (available from duppa.net).
• Optional: 3V3 MIDI Interface.
• Breadboard and jumper wires.

Waveshare Zero, Duppa LED Ring, Potentiometers

I’m planning on being able to use any Waveshare Zero format board that I have (so that includes ESP32-S3, ESP32-C3 and RP2040) with the Duppa Ring so that means finding common pins to support I2C.

From the various pinouts (see Waveshare Zero, Pimoroni Tiny, and Neopixels) I can see I can use two pins in the bottom right-hand (with the USB connector at the top) corner of the board.

I’ll also need an analog connection and potentially connecting RX/TX to MIDI.

The various pins I’ll be using are as follows:

Note, I’m not using physical pins 11 and 12, even though they also support I2C, as for the RP2040, these are on I2C bus 1, not 0 (see note later).

As the Pimoroni Tiny2040 is largely compatible too, that could also be used, but it will be physical pins 11 and 12, corresponding to GP5 and GP4, and 15 and 16 for GP1, GP0 (RX,TX).

The LEDs on the LED ring are powered from 5V, which comes directly off the Waveshare Zero USB port. The logic “VIO” is powered from 3V3.

The Code

I2C LED Ring

As the I2C pins to be used are configurable, this means changing the Duppa example code (and any other Arduino code) to initialise the I2C bus on specific pins as follows:

Wire.begin(11,10);    // SDA, SCL for ESP32-S3
Wire.begin(10,9);     // SDA, SCL for ESP32-C3

Using the ESP32 Arduino Core, there is a specific board entry for the Waveshare Zero ESP32-S3. There isn’t one for the ESP32-C3 so I just used “ESP32C3 Dev Module”.

I used the Arduino core for RP2040 from here rather than the official core: https://github.com/earlephilhower/arduino-pico

But the I2C initialisation is a little different.

  Wire.setSDA(4);
  Wire.setSCL(5);
  Wire.begin();

If I’d have been using GP6 and GP7, then these would have required the initialisation of Wire1 rather than Wire with the RP2040 core.

Note: to use the serial port once a sketch has been loaded onto the board, requires the following to be set (via the Arduino Tools menu):

USB CDC On Boot -> Enabled

Once again, I’ve soldered the jumpers on the LED ring to enable pull-ups and set the address for S1 and S5, so that has to be changed in the demo code too.

Analog Potentiometer

In terms of analog read, the ESP32 has a resolution of 0..4095 compared to the Arduino’s 0..1023, so that has to be taken into account when calculating the MIDI CC values.

To do this, the reading has to be divided by the ratio of Pot Range / 128.

int newpot = algpot.avgeAnalogRead(PIN_ALG) / ((MAX_POT_VALUE+1)/128);

Serial MIDI

For these boards, the serial port has to be specified. There are different options depending on the board being used (more here).

To use the pins nominally designated as RX/TX on all of these boards, use:

// ESP32-S3 GP43,GP44 or ESP32-C3 GP20,GP21
MIDI_CREATE_INSTANCE(HardwareSerial, Serial0, MIDI);
// RP2040 GP1,GP0
MIDI_CREATE_INSTANCE(HardwareSerial, Serial1, MIDI);

It is a quirk of the RP2040 Arduino core that UART0 appears on Serial1 and UART1 on Serial2. Serial0 does not exist but USB is Serial (more here).

Also, for the RP2040 the pins can be changed prior to calling MIDI.begin() if required as follows:

Serial1.setRX(rxpin);
Serial1.setTX(txpin);
MIDI.begin();

MIDI USB

I want to make this a fairly stand-alone MIDI USB device, so for the ESP32 and RP2040 this means using the TinyUSB stack. There is an Adafruit library for Arduino that supports both and also works with the Arduino MIDI Library. References:

• Adafruit_TinyUSB – https://github.com/adafruit/Adafruit_TinyUSB_Arduino/tree/master
• USB MIDI Transport – https://github.com/lathoub/Arduino-USBMIDI (for AVR)
• Arduino MIDI Library – https://github.com/FortySevenEffects/arduino_midi_library

I’ve cribbed most of the code from: https://github.com/adafruit/Adafruit_TinyUSB_Arduino/blob/master/examples/MIDI/midi_test/midi_test.ino

And added the appropriate parts to my own midiSetup() and midiLoop() functions.

MIDI USB – ESP32-S3

For this to work on the ESP32-S3, the board settings (via the Arduino Tools menu) need to be changed as follows:

USB CDC On Boot -> Enabled
USB Mode -> USB-OTG (TinyUSB)
USB Firmware MSC On Boot=Disabled
USB DFU On Boot=Disabled

Naturally this means USB can’t be used for serial output anymore.

It also means that automatic sketch reset and download often didn’t work for me. It was quite normal to now have to use the BOOT and RESET buttons to get the ESP32 back into listening for a new sketch – not always, but also not uncommon. But this might be some serial port remapping weirdness that often occurs when the USB stack is running on the same microprocessor as the main code…

MIDI USB – RP2040

For the RP2040, the USB stack needs to be changed from the Pico SDK to TinyUSB, so in the Tools menu:

USB Stack -> Adafruit TinyUSB

There are some other RP2040 specific notes here, but I don’t believe they apply unless one is interested in rebuilding the core, default TinyUSB support directly.

USB MIDI – ESP32-C3

I don’t believe USB MIDI works on the ESP32-C3

Adafruit TinyUSB doesn’t seem to anyway and I haven’t looked into what the options might be yet.

Other Notes

I’ve left in all the conditional compilation from Duppa I2C MIDI Controller – Part 3 but for now am just working with potentiometer control.

Pretty much everything is configurable, but the most important config option is to specify the board at the top:

//#define WAVESHARE_ESP32S3
//#define WAVESHARE_ESP32C3
#define WAVESHARE_RP2040

I could probably auto detect from the build settings but for now, this will do.

Other options include GPIO pins, whether to include serial or USB MIDI (or both), and whether to enable MIDI THRU or not.

Find it on GitHub here.

Closing Thoughts

This is the first go at getting my Duppa controller working on 3V3 Waveshare Zero format boards, and so far it looks pretty good.

For the ESP32-S3 and RP2040 being able to enable MIDI USB is particularly useful. I might see if I can support MIDI THRU across the interfaces, which might be handy for a built-in USB to serial MIDI converter, but for now MIDI THRU is on the same port only.

I’ve not tested this with encoders or the endless potentiometer, but in theory it ought to work. I’d have to add some conditional compilation for GPIO numbers if I want to keep the same physical pins again.

Kevin

Duppa I2C MIDI Controller – Part 3

This is a follow up post to Part 2 expanding on the code and adding in some of the alternative control options I mentioned.

• Part 1 – getting to know the devices and testing them out.
• Part 2 – adding MIDI to the LED ring and I2C encoder.
• Part 3 – adding normal encoder, plain potentiometer, and endless potentiometer control.
• Part 4 – revisits the idea with Waveshare Zero format devices and adds USB MIDI.

https://makertube.net/w/ncLFMqBwCUcrrM4r3mHJwd

Warning! I strongly recommend using old or second hand equipment for your experiments.  I am not responsible for any damage to expensive instruments!

If you are new to Arduino, see the Getting Started pages.

Parts list

• Arduino Uno/Nano.
• DuPPa small RGB LED Ring.
• 10K potentiometer.
• KY-040 rotary encoder module.
• Bespoke hook-up wires (available from duppa.net).
• Breadboard and jumper wires.

The Circuit

This circuit shows all three control options on the same diagram, but naturally use whichever one you require. There are the following three options:

• Duppa I2C Encoder (from the previous project) on A4, A5 (SDA, SCL).
• Plain potentiometer on A0.
• Rotary encoder on D10, D11, D12.

In addition to the I2C LED Ring on A4, A5 (SDA, SCL) of course.

Here is a separate diagram for the endless potentiometer. I can be used alongside the above, but I’ve drawn it on its own for clarity.

Mine has the pins in the following order: Wiper A, GND, Wiper B, VCC.

The Code

This uses the code from Part 2 as a starting point and adds in some additional features.

The main aim is to add additional control options and then make them selectable in code. There are several definitions at the top of the file. One of them should be uncommented to enable that control option.

//#define CC_ENCODER
#define CC_POTENTIOMETER
//#define CC_I2CENCODER
//#define CC_ENDLESSPOT

Each control method will have some associated functions, but the interface will be hidden away behind these definitions and called from the main code, something like the following.

#ifdef CC_ENCODER
#include <librarycode.h>
... control specific definitions ....

void encSetup() {
// Control specific setup code
}

void encLoop() {
// Control specific loop code
}
#else
void encSetup() {}
void encLoop() {}
#endif

If that control option is not enabled, then it will just end up with the two empty functions.

Normal Potentiometer

This is fairly straightforward. I’m using the averaging technique I’ve mentioned before (details here) and include a counter so that the pot isn’t read on every scan, otherwise it slows down all other processing significantly.

The pot reading is scaled down to 7-bits from the default 10-bit value with a bitshift.

I’ve opted to have a jump if the CC value is updated over MIDI rather than anything more sophisticated, as that is probably the simplest.

All the same display options are available as used previously: one LED per CC; scaled to multiples of the ring size; or scaled to a single ring.

This works quite well with all of them, but probably makes most sense when the MIDI CC range is scaled to a single revolution of the LED ring.

CC_WRAP has no effect when used with a normal potentiometer, as the pot itself does not wrap around.

Rotary Encoder

This is using the same encoder library I’ve used before in my Arduino MIDI Rotary Encoder Controller. This makes the scanning code relatively straight forward.

I’ve refactored out the increment/decrement functions from the I2C encoder code into midiCCIncrement and midiCCDecrement, so these can now be used by both encoder options.

These encoder modules are often switched, but I’m not making use of the switch here.

Once again, all the same display options are available: one LED per CC; scaled to multiples of the ring size; or scaled to a single ring. CC_WRAP can be on or off.

Endless Potentiometer

There is a detailed discussion of how these work here: https://hackaday.io/project/171841-driveralgorithm-for-360-deg-endless-potentiometer
My initial thought was that I could just use one of the wipers, assuming it would go from 0 to full resistance and immediately back to zero, but they don’t – they gradually go from 0 to full resistance and then gradually back to 0 again. See the diagram in the above link.

This means that some processing is required to get a single reading out of them, so I ended up using a library from here:

• https://github.com/juanlittledevil/EndlessPotentiometer

Well actually, I ended up using the slight variant of the library as used on the “Ottopot” MIDI controller, which can be found here:

• https://codeberg.org/gerotakke/ottopot

In my case I just dropping in the endlesspotentiometer.cpp/h files into my Arduino sketch (swapping any includes from <> to “” in the process). There was one reference to main.h that needed removing, and it required a definition of MAX_POT_VALUE which is 1023 for an Arduino Uno.

Then the code is fairly straight forward as the library is able to give an indication of direction and how much the pot has moved.

One thing to watch out for – I wanted this to be able to act on midiCC in a relative manner, replication the benefits of an encoder, but with a potentiometer, so I needed to know how much the pot had changed and then add that to the current midiCC value, rather than set it directly.

To do this I allowed midiCCIncrement/Decrement to take a parameter – how far to increase or decrease midiCC.

The core code for handling the endless pot was thus:

endpot.updateValues(epot1.avgeAnalogRead(PIN_EALG_1),
                    epot2.avgeAnalogRead(PIN_EALG_2));
if (endpot.isMoving) {
  if (endpot.direction == endpot.CLOCKWISE) {
    midiCCIncrement(endpot.valueChanged);
  } else if (endpot.direction == endpot.COUNTER_CLOCKWISE) {
    midiCCDecrement(endpot.valueChanged);
  }
}

I also turned the potentiometer averaging code into a class of its own so I could also use it here for both analog readings of the endless pot.

It took a bit of experimentation with the sensitivity and threshold settings and how they interacted with the frequency of reading, but I’ve ended up with something that seems to work ok for me.

Summary

Although at the start I said that one of the options should be commented out to select it, in reality, if the devices are all on separate IO pins, then actually they can all be enabled at once.

And it does seem to work pretty well, with all four methods: I2C encoder, plain encoder, potentiometer – all interacting as you might expect they would.

Find it on GitHub here.

Closing Thoughts

I was quite surprised how usable everything was with all four input methods enabled. I probably wouldn’t recommend it for typical use, but it was a bit of fun.

It is particularly satisfying to sweep through the entire range using the pot with “one LED per CC” enabled, even though scaling a single ring to the potentiometers range makes more sense (to me).

At some point I will try to get several controls up and running.

Kevin

Duppa I2C MIDI Controller – Part 2

This is a follow up post to Part 1 where I’m starting to look at MIDI applications and a range of control options.

• Part 1 – getting to know the devices and testing them out.
• Part 2 – adding MIDI to the LED ring and I2C encoder.
• Part 3 – adding normal encoder, plain potentiometer, and endless potentiometer control.
• Part 4 – revisits the idea with Waveshare Zero format devices and adds USB MIDI.

Since posting the first part, I’ve stumbled across a rather excellent DIY MIDI controller that uses 8 of these Duppa LED rings and 8 endless potentiometers (which I hadn’t realised was even a thing!). It is a fantastic build, based on a Teensy and PlatformIO and I totally recommend going and taking a look. Read about it here: https://gerotakke.de/ottopot/.

https://makertube.net/w/2oKgvpZ29L2oExanSaUXjE

Warning! I strongly recommend using old or second hand equipment for your experiments.  I am not responsible for any damage to expensive instruments!

If you are new to Arduino, see the Getting Started pages.

Parts list

• Arduino Uno/Nano.
• DuPPa small RGB LED Ring.
• Mini I2C Encoder.
• Bespoke hook-up wires (available from duppa.net).
• Breadboard and jumper wires.

The Circuit

I eventually want to include various options for controlling the ring and MIDI:

• Duppa I2C rotary encoder.
• Plain rotary encoder.
• Simple potentiometer.
• Endless potentiometer.

I don’t have any endless potentiometers yet, they are something I’ve only recently found exist, but I’ll post again when I get a chance to try them!

The required connections, naturally, are quite different for each case:

• Duppa I2C encoder: connects to SDA/SCL.
• Plain rotary encoder: requires two digital IO pins.
• Simple potentiometer: requires a single analog input.
• Endless potentiometer: requires two analog inputs.

In this first post, I’m just looking at the same Duppa I2C Encoder and LED Ring that I used in Part 1 but am adding a 5V compatible MIDI module.

The Code

Once again, this is using the Duppa Arduino library: https://github.com/Fattoresaimon/ArduinoDuPPaLib/

CC, Pots, Encoders…

The biggest issue I find with attempting to develop a MIDI CC controller is where is the authoritative definition of what the CC value actually is? What do I mean by that? Well we have the value in the synthesizer, defined on power up or via the on-board controls. And then we have the setting in the external MIDI controller. Until the MIDI controller sends an updated value to the synth, these will be different. And if the value on the synth changes locally, e.g. using knobs or controls on the synth, then they will be out of sync.

I’ve not found an easy answer to this, but what I’m planning is having the CC controller receive MIDI CC messages as well as send them. This means that if the CC value is changed directly on the synth, if the synth transmits that over MIDI, then it will be received by the external controller which can update its own value accordingly.

One problem with this is that there are two types of hardware controller: relative or absolute.

A rotary encoder is a relative controller – it turns in a direction and the value will increase or decrease accordingly. If the internal knowledge of the CC value changes, the encoder will just continue to increase of decrease from that new value instead.

A potentiometer is (usually) an absolute controller – it turns and has a value. If the internal knowledge of the CC value changes, then unless you have a motorised potentiometer, it will still be in the same place so on turning there will be a jump in value from the stored value to the new setting of the potentiometer.

One option to deal with absolute values is to have the new position value only become relevant once the turning “catches up” with the internal value and the starts adjusting it from that point onwards. But this can create a disjoint between the user experience of turning the knob and it actually changing anything. But on the plus side, absolute values are “remembered” when powered off – providing the knobs are left in the same place.

I’m hoping to use the encoders as a pseudo potentiometer. But it isn’t going to be possible to have a complete rotation considered the same as a full sweep of a potentiometer, as that will be down to the number of “detents” per rotation and that won’t be anything like enough to support 128 MIDI CC values. But I do plan to indicate the value by LEDS, and use those to indicate the position in the full sweep. This will allow the starting point to change if a CC message is received.

One solution to this problem, and that used by the Ottopot controller mentioned at the start, is to use an endless potentiometer. This not-only allows a variable starting position, but it also represents a full-sweep of values with a single turn as per a simple potentiometer.

So when I get hold of some of those I’ll come back to revisit this code.

For this first version there is code for the I2C encoder implemented using the following functions:

• i2cEncSetup()
• i2cEncLoop()
• i2cEncIncrement()
• i2cEncDecrement()

These are based on the code I used in Part 1. The increment and decrement functions act on a global “midiCC” directly, which stores the CC value to use using the range of a single MIDI “byte” 0 to 127. There is a compilation option to allow wrapping around (between 0 and 127) or not.

MIDI Handler

The Arduino MIDI library is used for both send and receive and all MIDI functionality is wrapped up in the following functions:

• midiSetup()
• midiLoop()
• midiControlChange()

There are a few additional functions to give an optional LED indication of MIDI activity. Within the MIDI loop the midiCC value is checked and if it has changed then a MIDI control change message is transmitted:

void midiLoop() {
  MIDI.read();
  if (lastMidiCC != midiCC) {
    MIDI.sendControlChange(MIDI_CC, midiCC, MIDI_CHANNEL);
  }
}

There is an option to have software MIDI THRU enabled and this is handled as part of the MIDI.read() call. On setup midiControlChange() is installed as a handler function for MIDI CC messages and if the correct CC message is received on the correct MIDI channel then the midiCC value is updated directly.

One consequence of using midiCC directly and it being changed by either the encoder or from MIDI is that any change will also trigger the sending of the CC value out too.

This means that if MIDI THRU is enabled and a MIDI CC value is sent to the Arduino then it will almost certainly be sent back over MIDI twice – once as part of the THRU handling, and once as a consequence of it having changed the Arduino’s stored midiCC value.

LED Ring Indicator

The simplest implementation will be to scale the 24 LEDs of the ring to the 128 MIDI values and light up the LED that best represents the chosen value.

An alternative is to use one LED per MIDI CC value and allow the ring to loop round, possibly in a different colour. For 128 values across 24 LEDs this means there will be five full circles of the ring plus 8 more.

I’ve also provided the option to scale the MIDI CC values to a multiple of the LED ring so that the full MIDI 0..127 range wraps around back to 0 back at the start of the ring.

In the following, scalemax is the largest multiple of NUM_LEDS that will fit in 128, then the midiCC value is scaled to that new range and then used in the rest of the LED calculation.

int scalemax = 128 - 128 % NUM_LEDS;
int midiCC_scaled = (midiCC * scalemax / 128);
nextLed = midiCC_scaled % NUM_LEDS;
uint32_t col=0;
if (midiCC_scaled < NUM_LEDS) {
  col = 0x00003F;
} else if (midiCC_scaled < NUM_LEDS*2) {
  col = 0x003F3F;
} else if (midiCC_scaled < NUM_LEDS*3) {
  col = 0x003F00;
} else if (midiCC_scaled < NUM_LEDS*4) {
  col = 0x3F3F00;
} else if (midiCC_scaled < NUM_LEDS*5) {
  col = 0x3F0000;
} else {
  col = 0x3F003F;
}

One quirk to note is that the LEDs are numbered anti-clockwise, so at some point I’ll have to reverse the LED number when it comes to presenting an increasing CC value as a clockwise changing display.

I’d also like to have a bit of a lazy, dragging LED change, so I want to implement something that fades illuminated LEDs out as the value changes, leaving some kind of “tail” as the LED moves.

To do this, I’ve used an array to store the colour value used for any illuminated LEDs and then at regular intervals that colour is updated to fade back to OFF.

I’ve implemented a relatively simple fade – basically each of the R, G and B components of the colour is bit-shifted to the right by 1 on each “scan”. This has the effect of continually dividing the colour value by 2 until it reaches 0. The only thing to watch out for is that I don’t do this for the current illuminated LED.

Also note that I only pull out the most significant 7 bits of each 8 bit value (by & 0xFE) so that the shift doesn’t map the least significant bit of one value down into the next colour.

for (int i=0; i<NUM_LEDS; i++) {
  if (i != nextLed && ledMap[i] > 0) {
    uint32_t newcol = ((ledMap[i] & 0xFE0000) >> 1)
                    + ((ledMap[i] & 0x00FE00) >> 1)
                    + ((ledMap[i] & 0x0000FE) >> 1);
    LEDRingSmall.LEDRingSmall_Set_RGB(i, newcol);
    ledMap[i] = newcol;
  }
}

All the LED handling is wrapped up in the following functions:

• ledSetup()
• ledLoop()
• ledIndex()

The last function is responsible for swapping the LED numbers around to make them go clockwise. It isn’t as simple as doing NUMLEDS – led as I still want the first LED to be at “12 o’clock”, hence the function to return the correct index.

Find it on GitHub here.

Closing Thoughts

I am so pleased with that lazy LED change effect.

Having so many turns of the encoder isn’t particularly practical at the moment, but it does work. It is certainly good to have a few configuration options – especially the option to wrap around, as it takes quite a few turns to get from 0 to 127.

In a follow up post I’ll take a look at some of the other options, and when I get my endless encoders in the post that will definitely get a mention too.

I also want to wrap up the existing code somehow to allow for several LED CC controls if required and some kind of box might also be nice.

Kevin

Duppa I2C MIDI Controller – Part 1

I’ve had my eye on Duppa’s rather neat looking I2C LED rings and rotary encoders for some time and finally pushed “go” on getting a couple. I want to use them as the basis for a MIDI controller but this post is just my “getting to know them” post.

• Part 1 – getting to know the devices and testing them out.
• Part 2 – adding MIDI to the LED ring and I2C encoder.
• Part 3 – adding normal encoder, plain potentiometer, and endless potentiometer control.
• Part 4 – revisits the idea with Waveshare Zero format devices and adds USB MIDI.

A follow-up will build on this knowledge to get them going with MIDI.

Warning! I strongly recommend using old or second hand equipment for your experiments.  I am not responsible for any damage to expensive instruments!

If you are new to Arduino, see the Getting Started pages.

Parts list

• Arduino Uno/Nano
• DuPPa small RGB LED Ring and mini I2C Encoder.
• Bespoke hook-up wires (available from duppa.net).
• Breadboard and jumper wires

Duppa I2C Devices

There are several interesting devices, two variants of LED ring, and two variants of I2C connected rotary encoders. They are all pretty interesting devices, and the cascading nature of, especially the I2C encoders, has massive potential for a range of interesting MIDI controllers!

I have the following devices:

• I2CEncoder Mini
• RGB LED Ring Small

A couple of points to note about these:

• The LED ring has jumpers for I2C address and optional I2C pull-ups.
• The encoder has a software-configurable I2C address and optional I2C pullups.
• Both have a supporting library and code on GitHub here: https://github.com/Fattoresaimon/ArduinoDuPPaLib
• Both have hardware designs and additional information on GitHub too:
  • https://github.com/Fattoresaimon/I2CEncoderMini
  • https://github.com/Fattoresaimon/RGB_LED_Ring_Small

Duppa LED Rings

Both LED rings support the following (from the product pages):

• Individual 256 PWM control steps
• Individual 256 DC current steps
• Global 256 step current setting
• 29kHz PWM frequency
• Individual open and short error detect function
• 1MHz I2C-compatible interface
• Supply voltage range: 2.7V to 5.5V

And they share a cable interface using a Molex “Picoblade” connector at 1.25mm pitch, with the following pinout:

Note, at first glance, especially as these are I2C devices, it is easy to imagine that these are compatible with standards such as Qwicc, Stemma, Grove, and so on. They are not (more here).

These are designed so that the LEDs can be powered independently from the logic to allow for higher current if required. This includes using 5V for LEDs and 3V3 for the logic. Apparently both rings state a “all LEDs on” current of 450mA. I don’t know if this is a typo…

The connectors are paired so it is possible to have an “in” and “out” connection allowing for up to 15 or 16 rings to be cascaded, providing different I2C addresses are set via the configuration jumpers. The address range is 0x60 to 0x7E (in steps of two).

Naturally using more rings will definitely require an independent LED power supply that can provide the maximum required current.

Duppa I2C Encoders

There are two variants of I2C encoder (actually there are also some older versions of them too, which are not compatible, but I’m ignoring those).

Some common features:

• 3V3 to 5V operation.
• Available with 2.54mm pin headers or JST-XH sockets.
• 400 kHz I2C.
• Interrupt line.
• Optional I2C pull-ups via solder jumper.

Both share a common 2.54mm pitch connector and has options for pin headers or JST-XH sockets fitted. The pinout is slightly different to the LED rings, as follows:

Once again these might superficially appear compatible with the likes of Grove and other I2C common options, but they are not.

Also, pretty critically, it should be noted that GND and VCC are the opposite way round to the LED rings, and that SDA/SCL are in different places in the five pins.

The I2C Address for the Mini encoder has to be set in software. The default is 0x20, but it would appear that any of the 128 addresses (apart from 0) could be used. A utility sketch is provided on GitHub and as part of the support library (see below), to set the address.

Note: the full LED ring has 7 address jumpers which will set the 7-bit address in binary directly in hardware.

There are datasheets for both encoders in the respective GitHub repositories. Here is the one for the I2CEncoder Mini.

Getting Started

My plan is to use an LED ring and encoder as a pair, on the I2C bus as a MIDI controller. This means deciding on I2C addresses, pull-up configuration, and connections.

All Duppa devices have options for buying compatible cables, so I would advise getting a range for experimentation. My first task was to crimp some jumper header pins onto each of the cables.

For my initial experiments I’ve gone with the following configuration

• Enable I2C pull-ups on the LED ring.
• Use LED ring base address of 0x60 (solder S1, S5).
• Use Encoder default base address of 0x20.

This requires the I2C pull-up, S1, and S5 solder bridges making on the LED ring, but means I can use the encoder “as is” (for now).

The following shows the connections to an Arduino Nano.

Note that this is powering the LED ring directly from the Nano’s 5V, which itself is powered from the USB socket. Most standard USB sockets would be good for around 500mA I believe, so this should be ok, especially if all LEDs are not on at the same time at full brightness.

Other things to note:

• For the 5-wire links to the devices, I’ve used the colours that came with the wires I’d ordered from Duppa.net.
• Notice how 5V/GND are swapped for the two devices.
• I’ve used 5V for both the LED VCC and logic VIO for the LED ring.
• In both cases SDA/SCL are cascaded up to the Nanos A4 (SDA), A5 (SCL).
• The encoders interrupt line is connected to A3.

A note on pull-ups

As already mentioned, I’ve enabled hardware pull-up resistors on the I2C bus by enalbing the solder bridge on the LED ring to connect both on-board I2C 4K7 pull-ups to VCC. Another option would have been to add external 4K7 resistors on the solderless breadboard between both SDA and SCL and VCC (5V).

Another option would have been to solder bridge the I2C pull-ups on the encoder instead.

Generally speaking I2C needs pull-ups somewhere and there are several approaches:

• Use a microcontroller with hardware pull-ups on SDA and SCL (internal pull-ups aren’t usually “strong” enough for I2C as a rule);
• Add pull-ups on one of the devices connected to the bus;
• Use external pull-ups.

There are pros/cons of each. The Arduino doesn’t include additional pull-ups on I2C, but the Raspberry Pi does. Adafruit devices often include an option for enabling pull-ups on each device. It might be possible to use the internal pull-ups on a microcontroller, but they are often considered to be “weak” pull-ups (on an ATMega328 internal pull-ups around ~20-50k) and may not be suitable for the higher speeds of the I2C bus.

Only one set of pull-ups is typically required on the bus. Enabling more may work, but essentially puts the pull-ups in parallel with each other, which lowers the resistance used. I2C seems pretty tolerant of a wide range of pull-up values, so it might be fine for many purposes, but eventually it could lead to current draw issues one presumes.

There is also the issue of what a pull-up should pull up to. If a device is powered using 5V, but the I2C bus is running at 3V3 because it is interfacing to a 3V3 logic microcontroller, then pull-ups need to be 3V3 too.

Some references for pull-up resistors:

• https://learn.sparkfun.com/tutorials/pull-up-resistors/
• https://learn.adafruit.com/working-with-i2c-devices/pull-up-resistors
• https://support.arduino.cc/hc/en-us/articles/11153357842588-I2C-and-pull-up-resistors

The interrupt signal for the I2CEncoder should also include a pull-up resistor, but in this case, as it is not part of the high-speed I2C bus, the internal resistor of either the microcontroller or encoder should suffice.

There is a configuration option for the encoder to tell it to enable the pull-up on the interrupt line, so this is used.

The Code

There is an Arduino library available for all of the Duppa products here: https://github.com/Fattoresaimon/ArduinoDuPPaLib/

This has to be downloaded as a ZIP file of the whole repository and then loaded into the Arduino environment using the “Include Library”->”Add ZIP Library” option.

To verify what I2C addresses are being used, a simple I2C scanner sketch can be used: https://playground.arduino.cc/Main/I2cScanner/

In my case this returns:

I2C Scanner
Scanning...
I2C device found at address 0x20  !
I2C device found at address 0x60  !
done

As already mentioned if the I2C address of the I2CEncoder Mini needs to be changed there is a sketch in the DuPPa library examples to do this:

• Examples -> DuPPa Library -> I2CEncoderMini -> Change_Address.

It is worth ensuring the provided examples work before going further.

LED Ring Demo

• Examples -> DuPPa Library -> RGB LED Ring Small -> LEDRingSmall_Demo

The I2C address can be set at the start as follows:

LEDRingSmall LEDRingSmall(ISSI3746_SJ1 | ISSI3746_SJ5);

I also limited the “global current” by changing 0xFF (255) in two places near the end of the loop() to 0x20 (32):

for (i = 0x20; i > 0; i--) {  // Was 0xFF
  LEDRingSmall.LEDRingSmall_GlobalCurrent(i);
  delay(20);
}
LEDRingSmall.LEDRingSmall_ClearAll();
LEDRingSmall.LEDRingSmall_GlobalCurrent(0x20);  // Was 0xFF

There are a few other calls to LEDRingSmall_GlobalCurrent() which the library API notes sets the Global Current Control Register in the IS31FL3746A according to Table 10 in the datasheet.

I must admit it isn’t totally clear to me exactly how this works, but various descriptions describe a limiting function on the global current used in 256 steps with 0 being the lowest and 255 (0xFF) being the highest/brightest. The datasheet says that the default is 0, so presumably if this call isn’t used then there will be no output. One section of the demo turns on all LEDs and steps through the global current values from 255 down to 0. I changed this to 32 (0x20) down to 0.

In fact this is a common feature of the library, it appears to be a fairly shallow shim over the direct registers of the IS31FL3746A, so some knowledge of the datasheet is required to use it properly. Although I suspect that for many cases, just starting with the default demo program and fiddling about will probably go quite a long way.

The main LED functions, once the setup is complete, take a LED number and will either set a RGB colour or can set the individual colour levels of red, green or blue from 0 to 255.

led = 0..23
rgb = 0x000000 .. 0xFFFFFF
LEDRingSmall_Set_RGB(led, rgb);

led = 0..23
level = 0 .. 255
LEDRingSmall_Set_RED(led, level);
LEDRingSmall_Set_GREEN(led, level);
LEDRingSmall_Set_BLUE(led, level);

I2C Encoder Demo

• Examples -> DuPPa Library -> I2CEncoderMini -> Basic_with_Callbacks

The I2C address and Interrupt pin are required:

const int IntPin = A3;
i2cEncoderMiniLib Encoder(0x20);

The demo code uses callbacks from the library to perform various actions depending on the state of the encoder. The following events are tracked (and reported via the serial console):

onIncrement
onDecrement
onMax
onMin
onButtonPush
onButtonRelease
onButtonDoublePush
onButtonLongPush

The interrupt pin is enabled using autoconfigInterrupt() and also relies on the internal pull-up being enabled on the encoder. This is part of the configuration provided on initialisation.

i2cEncoderMiniLib Encoder(0x20);

Encoder.reset();
Encoder.begin(  i2cEncoderMiniLib::WRAP_DISABLE
              | i2cEncoderMiniLib::DIRE_LEFT
              | i2cEncoderMiniLib::IPUP_ENABLE
              | i2cEncoderMiniLib::RMOD_X1
);

Whilst the interrupt pin is enabled at the encoder end, it doesn’t actually cause an interrupt on the Arduino. The main loop just polls the relevant INPUT pin and uses it to decide if the encoder needs checking:

void loop() {
  if (digitalRead(IntPin) == LOW) {
    /* Check the status of the encoder and call the callback */
    Encoder.updateStatus();
  }
}

I’m guessing this is better than continually scanning the I2C bus to see if there is anything to do, assuming there is a spare GPIO pin to connect up.

Some other points of note for use of the library:

• It is possible to enable/disable some of the interrupt sources using writeInterruptConfig(), but it can also be automatically configured by calling autoconfigInterrupt() once all the callbacks have been specified for just the sources that match the callbacks.
• There are three types of encoder supported, representing by the X1, X2, X4 definitions.
• There is a method for ChangeI2CAddress() but this should not be used in general purpose code. It only really makes sense in the utility sketch already mentioned for one-time setting of the I2C address of the encoder.
• There is a block of EEPROM that can be accessed using readEEPROM()/writeEEPROM() which might come in handy.

Encoder driven LED Ring

Combining elements of both demos here is a short sketch that uses the encoder to rotate an LED pattern around the ring.

#include <Wire.h>
#include <i2cEncoderMiniLib.h>
#include "LEDRingSmall.h"

const int IntPin = A3;
i2cEncoderMiniLib Encoder(0x20);
LEDRingSmall LEDRingSmall(ISSI3746_SJ1 | ISSI3746_SJ5);

#define MAX_RGB 0x7F

int tim,last;
int dir;
int r, g, b, rg, br, bg;
#define INCR(x) (x)+=dir; if ((x)>=24) {(x)=0;} else if ((x)<0) {(x)=23;}

void encoder_increment(i2cEncoderMiniLib* obj) {
  dir = 1;
  tim ++;
}

void encoder_decrement(i2cEncoderMiniLib* obj) {
  dir = -1;
  tim--;
}

void setup() {
  pinMode(IntPin, INPUT);
  dir = 0;
  tim = 0;
  last = 1;

  Wire.begin();
  Wire.setClock(400000);

  LEDRingSmall.LEDRingSmall_Reset();
  delay(20);

  LEDRingSmall.LEDRingSmall_Configuration(0x01); //Normal operation
  LEDRingSmall.LEDRingSmall_PWMFrequencyEnable(1);
  LEDRingSmall.LEDRingSmall_SpreadSpectrum(0b0010110);
  LEDRingSmall.LEDRingSmall_GlobalCurrent(0x10);
  LEDRingSmall.LEDRingSmall_SetScaling(0xFF);
  LEDRingSmall.LEDRingSmall_PWM_MODE();

  Encoder.reset();
  Encoder.begin(i2cEncoderMiniLib::WRAP_DISABLE
                | i2cEncoderMiniLib::DIRE_LEFT
                | i2cEncoderMiniLib::IPUP_ENABLE
                | i2cEncoderMiniLib::RMOD_X1 );

  Encoder.writeCounter((int32_t) 0); /* Reset the counter value */
  Encoder.writeStep((int32_t) 1); /* Set the step to 1*/

  Encoder.onIncrement = encoder_increment;
  Encoder.onDecrement = encoder_decrement;

  Encoder.autoconfigInterrupt();
}

void loop() {
  dir = 0;
  if (digitalRead(IntPin) == LOW) {
    Encoder.updateStatus();
  }

  if (tim != last) {

    if ((tim % 1) == 0) {
      LEDRingSmall.LEDRingSmall_Set_RED(r, 0);
      INCR(r);
      LEDRingSmall.LEDRingSmall_Set_RED(r, MAX_RGB);
    }

    if ((tim % 2) == 0) {
      LEDRingSmall.LEDRingSmall_Set_GREEN(g, 0);
      INCR(g);
      LEDRingSmall.LEDRingSmall_Set_GREEN(g, MAX_RGB);
    }

    if ((tim % 3) == 0) {
      LEDRingSmall.LEDRingSmall_Set_BLUE(b, 0);
      INCR(b);
      LEDRingSmall.LEDRingSmall_Set_BLUE(b, MAX_RGB);
    }

    if ((tim % 4) == 0) {
      LEDRingSmall.LEDRingSmall_Set_BLUE(br, 0);
      LEDRingSmall.LEDRingSmall_Set_RED(br, 0);
      INCR(br);
      LEDRingSmall.LEDRingSmall_Set_BLUE(br, MAX_RGB);
      LEDRingSmall.LEDRingSmall_Set_RED(br, MAX_RGB);
    }

    if ((tim % 5) == 0) {
      LEDRingSmall.LEDRingSmall_Set_BLUE(bg, 0);
      LEDRingSmall.LEDRingSmall_Set_GREEN(bg, 0);
      INCR(bg);
      LEDRingSmall.LEDRingSmall_Set_BLUE(bg, MAX_RGB);
      LEDRingSmall.LEDRingSmall_Set_GREEN(bg, MAX_RGB);
    }

    if ((tim % 6) == 0) {
      LEDRingSmall.LEDRingSmall_Set_RED(rg, 0);
      LEDRingSmall.LEDRingSmall_Set_GREEN(rg, 0);
      INCR(rg);
      LEDRingSmall.LEDRingSmall_Set_RED(rg, MAX_RGB);
      LEDRingSmall.LEDRingSmall_Set_GREEN(rg, MAX_RGB);
    }
  }
  last = tim;
}

This only uses the increment/decrement callbacks to set the direction (“dir”) and update the time (“tim”) that determines which direction the ring is moving.

It isn’t perfectly reversible – I liked the idea of winding the ring forward and back again – but it is pretty close. I suspect there is an off-by-one error somewhere that means it can get out of sync.

But it is plenty enough to show how it all works.

Closing Thoughts

These are great little boards. Having an I2C encoded in my case might be a bit over the top, but they are pretty easy to use.

The LED ring is awesome

Kevin

Stemma, Grove, QT, Gravity, Duppa, I2C

I’ve always liked the look of these “plug the sensors in using I2C” different options out there, but must admit I’ve never really got to grips with the different systems that one might come across.

Recently I found another bespoke, but related, system from Duppa.net and decided I just had to sit down and try to work them all out once and for all to have any hope of using these devices together.

Whilst researching the details for this post, I stumbled upon the following, which sort of helped a little:

• https://www.cable-tester.com/i2c-pin-out/ which has a summary of a number of different I2C cable options.
• https://www.tomshardware.com/features/stemma-vs-qwiic-vs-grove-connectors
• https://en.wikipedia.org/wiki/I%C2%B2C#Popular_cable_systems

As an aside, here are some resources on voltage levels and the use of pull-ups for I2C:

• https://learn.adafruit.com/working-with-i2c-devices/pull-up-resistors
• https://learn.sparkfun.com/tutorials/i2c/i2c-at-the-hardware-level

My general understanding is to be wary of devices with fixed pull-ups if you’re mixing logic levels as it might end up pulling up a voltage level to higher than the other end is expecting.

Also, it is generally useful to only have one set of pull-ups in any set of chained I2C modules, which is why some devices will have pull-ups configurable using solder bridges or jumpers.

• The Raspberry Pi has hardware pullups built in (more here).
• Arduino boards tend to not include hardware pullups, but apparently sometimes they can be added to solder pads on certain boards and the library may enable internal pull-ups if it is able to.

Also, whilst many GPIO pins will operate with “symmetrical drive characteristics” when in output mode (so can both drive an output HIGH and LOW), again my understanding is that for I2C output they will often be in “open drain” mode which allows other things on the bus to be driving the signals HIGH if required. But this is why the bus itself needs pull-ups, otherwise, when nothing is driving the bus the level will be left floating.

Note: this is my hand-wavy understanding of outputs and I2C, so take that as you will. As I learn more (or if someone corrects me) I’ll pop back and update this page.

Proper details can be found here in this TI application note for I2C:

• https://www.ti.com/lit/an/sbaa565/sbaa565.pdf

Adafruit Stemma and Stemma-QT

One of the best starting points is this guide from Adafruit on how their Stemma and Stemma QT system links up with some of the others: https://learn.adafruit.com/introducing-adafruit-stemma-qt

From this we can learn the following:

• Stemma is JST PH 3 or 4 pin with a 2.0mm pitch, which is kind of similar to Gravity and Grove, but not exactly, but will generally be physically compatible with either.
• Stemma QT is JST SH 4 pin with a 1.0mm pitch, which is kind is similar to Qwiic.
• Stemma 3-pin is for analog, digital or PWM devices.
• Stemma and Stemma QT 4 pin is I2C.
• Adafruit do a Stemma QT to Grove cable.

The main issues are: understanding which are 5V and which are 3V; which are wired up differently; and which are not standardised even within themselves (Grove can be I2C, UART, or general IO for example).

Seeed Grove

Another good reference is from Seeed with their introduction to Grove: https://wiki.seeedstudio.com/Grove_System/

From this we can note:

• Grove 4-pin is quite similar to the Stemma 4-pin.
• Grove comes in analog, digital, UART and I2C versions.
• Physically they are proprietary, but quite like the JST PH 4 pin, 2.0mm pitch connectors and can usually physically be plugged into JST PH headers (although the use of the pins might be different).
• Some connectors are latched (“buckled” – left below) and some are unlatched (“unbuckled” – right below).
• Latched/buckled are less likely to physically fit in Stemma JST PH sockets.

Sparkfun Qwiic

Sparkfun describe their Qwiic system here: https://www.sparkfun.com/qwiic

Points of note:

• Qwiic is 4-pin, 1.0mm pitch, I2C only.
• Qwiic and Stemma QT are essentially the same, but there are differences in terms of which end is expected to be doing level shifting, so read the Adafruit guide for details.

DFRobot Gravity

The DFRobot guide for Gravity is here: https://www.dfrobot.com/gravity, but to be honest I was struggling to find any technical specs, but from the previous guides (especially the Adafruit one), we can note:

• Gravity are JST PH 3 or 4 pin 2.0mm pitch connectors.
• 3-pin connectors support analog, digital and PWM.
• 4-pin connectors support UART or I2C.
• There is a high chance of compatibility with the physical I2C connectors provided logic levels are observed.
• HOWEVER – the wiring of Stemma and Gravity are apparently different even though the connectors are physically the same. Importantly, PWR/GND are swapped.

Duppa.net

But then there is the reason for my starting this post – finding the intelligent rotary encoders and LED rings provided by Duppa.net: https://www.duppa.net/product-category/i2c-devices/

These appear to have two different standards of their own:

• LED Ring: Molex Picoblade, 1.25mm pitch, 5-pin connectors.
• Encoder: JST XH 2.54mm pitch, 5-pin connectors.

Neither of these is directly compatible with each other or with any of the above, but it can be seen that both are essentially power, GND and I2C so it ought to be possible to build compatible converter cables.

The details of pinout and so on can be found in the GitHub repository here: https://github.com/Fattoresaimon?tab=repositories

Note, in some places online I’ve seen the 1.25mm pitch PicoBlade connectors listed erroneously as “JST 1.25” – but these don’t seem to exist on the official JST site.

Summary

This really has become a bit of an xkcd standards situation unfortunately, and I’ve not covered everything (Pimoroni have a different approach to I2C for example).

But hopefully now I’ve finally written it all down, I might be able to make some sense of it and actually start using them a bit more.

So I think the upshot of all the above is the following (the numbers are the pitch of the pins):

But I must admit I’m still not 100% sure I’ve got them all right…

Kevin