Comparing YLed, YColorLed, and YColorLedCluster

Last week, we announced the Yocto-MaxiBuzzer, which is a doped up version of the Yocto-Buzzer. One of the differences is the use of RGB leds instead on the two red and green monochrome leds. Therefore, you must use the YColorLedCluster or YColorLed classes to drive the RGB leds while the Yocto-Buzzer used the YLed class. So, we thought that it would be useful to write a post to explain the differences between these three APIs which allow you to drive the different leds that you can find Yoctopuce modules.



In this post, we are going to speak about functions present on Yoctopuce modules. If you have never used a Yoctopuce module, we recommend that you start by reading our post on the logical structure of Yoctopuce devices.

In all the Yoctopuce programming APIs, there are three classes that enable you to drive leds: YLed, YColorLed, and YColorLedCluster.

As we are about to see, you cannot interchange these classes and the class that you must select depends on the Yoctopuce module that you are using.

YLed

The YLed class enables you to drive only one monochrome led. Currently, only the Yocto-Buzzer uses this class.

This class enables you to control the led intensity, but also to assign pre-programmed blinking sequences (slow blinking, fast blinking, and so on). Blinking sequences are run directly by the module, which allows the led to go on blinking even if the program stops running.

The following code makes the led blink at 1Hz:

Obviously, the color of the monochrome led can't be changed, but some modules have several leds with different colors. For example, the Yocto-Buzzer has two leds, led1 drives the green led while led2 drives the red led.

YColorLed

The YColorLed class enables you to drive only one RGB led. Currently, the modules using this class are the Yocto-Color, the Yocto-Color-V2, the Yocto-PowerColor, and the Yocto-MaxiBuzzer.

There is a YColorLed function per RGB led present on the module. For example, the Yocto-Color has two colorLed1 and colorLed2 functions while the Yocto-MaxiBuzzer has only one colorLed function.

Note: You cannot drive the additional leds connected on the extension port of the Yocto-MaxiBuzzer or Yocto-Color-V2 modules with the YColorLed class. You must use the YColorLedCluster class as explained below.

This class allows you to control the intensity and the color of the led. You can specify the color in the RGB (Red Green Blue) format or in the HSL (Hue Saturation Lightness) format. You can also change the color instantaneously, or perform a transition over a given period, for example switch from the current color to blue in 2 seconds.

The following code lights the led in blue:

On top of specifying the color of the RGB led, the YColorLed class enables you to create your own blinking sequences. For example, the following code makes the led blink from red to off over a period of 1 second.

Sequences are not limited to two instructions. You can add several instructions to a sequence and use distinct tempo. You can for example alternate between two colors.

The following code alternates between red, green, and blue.

YColorLedCluster

The YColorLedCluster class enables you to control a string of RGB leds. That is, with this function, you can drive all the RGB leds of the module. Currently, the modules using this class are the Yocto-Color-V2 and the Yocto-MaxiBuzzer.

It is the only function which allows you to drive the leds which are connected to the extension port. You can control a maximum of 150 RGB leds, as long as they are models WS2812B, WS2812C, SK6812 (RGB), or SK6812RGBW (RGBW).

You can individually control the intensity and the color of each led. As for the YColorLed function, you can specify the color using either the RGB (Red Green Blue) or the HSL (Hue Saturation Lightness) format. You can also change the color instantaneously or perform a transition over a given period, for example switching from blue to green in 2 seconds.

The following code lights the first 15 leds in blue:

You can program animation which are run directly by the module with the help of sequences. A sequence is a string of color transitions. A transition is defined by three parameters: the color space to be used, the final color, and its duration in ms. For example, "transition to the 0xff0000 RGB color in 500ms".

The following code, for example, makes all the leds blink from red to off over a period of 1 second.

The YColorLedCluster class supports up to 8 sequences, which allows you to animate different parts of the led string independently. You can also desynchronize the leds by specifying an offset, which enables you to create more elaborate animations:

An animation performed with sequences

For more details on the sequences of the YColorLedCluster class, you can read our post on the topic: Animating RGB leds using a Yocto-Color-V2.

With the YColorLedCluster class, you can also configure a default sequence which is run as soon as the module is powered on. This feature allows you, for example, to create programmable light beacons.

Which class should I use?

To conclude, if you wonder which class you should use, here is a summary table: