The WPI AddressableLED class provides a simple interface for programming an array of RGB (“full color”) LEDs. VMX-pi supports LED Arrays, as described in this guide.
To access WPI Library LED Array support, ensure that the VMX-specific Gradle Rio plugin version is updated to version 2020.3.2.2 or higher.
Supported LED Array Types
The WPI AddressableLED class supports arrays of LEDs which use a single “PWM” signal to program the state of each LED; arrays that implement this protocol are commonly referred to as “NeoPixels”. Several different types of LED Arrays are available, identified by the name of the integrated circuit that manages them. The “PWM” (“NeoPixel”) LEDArray types currently supported on VMX-pi are:
- SK6812
- WS2811* [See note in “Programming the LED Array” section below]
- WS2812
- WS2812B
NOTE: Several other completely different types of LED Array exist currently (DotStars which use a 2-wire protocol with separate clock and data line, WS2801 pixels, LPD8806 and “analog” strips). At this time, the WPI AddressableLED class only supports “PWM” (“NeoPixel”) LED Arrays, and does not support programming any of these other different types.
Supported VMX-pi Channels
Due to the very tight timing requirements (accuracy on the order of 100ns) used in the “PWM” (NeoPixel) one-wire LED controller protocol, LEDArrays are currently supported on only a single VMX-pi Channel:
- VMX-pi Channel 31 (WPI Library PWM 26)
This channel exists on the “MOSI” pin of the VMX-pi “SPI” connector, as shown below.
NOTE: The VMX-pi SPI Port may not be simultaneously used for external SPI communication when controlling an LED Array.
Basic Electrical Connectivity between the LEDArray and VMX-pi
This section summarizes the basic requirements and strategy for electrical connections between the LEDArray and VMX-pi. Note that additional considerations, depending upon your situation, are discussed in the References section below; for best results and to avoid damage, reviewing the additional Reference material and the datasheet for your chosen LED Array circuitry is highly recommended.
Supplying Power to the LEDArray
Although VMX-pi can supply up to 500 mA total to all of it’s power pins, because each LED can consume up to 60mA at full brightness, directly powering an LEDArray containing more than 7 LEDS via the VMX-pi is not usually practical. LEDArrays can consume significant amounts of current; for example at full power, an array of 1000 RGB LEDs could theoretically consume 60 Amps!
Rather, it’s recommended to provide a separate (typically, 5VDC) supply to provide power to the LEDArray. This separate supply would connect to the “Power (e.g., 5VDC) and Ground” wires in the above diagram.
Additional information regarding powering of LED Arrays can be found in the References section below; reviewing this material is highly recommended to help ensure proper operation.
Driving the LEDArray control signal
Connect the LEDArray control signal wire (labelled “Signal” in the diagram above) to the VMX-pi connector defined above.
Additionally, if using the recommended separate power supply – which may have a different ground potential than the VMX-pi – it is typically required to connect a ground signal from another VMX-pi connector to the “signal ground” terminal on the LEDArray (labelled “Signal Ground” in the diagram above). Without a well-referenced ground connection, the LEDArray may “flicker” unexpectedly during operation.
Finally, note that LEDArrays typically require a “high” signal voltage of at least 3.4VDC. For this reason, it is typically required to set the VMX-pi “CommDIO” Voltage to 5VDC, using the “COMM/DIO Power/Signal Voltage Select” jumper pin shown below:
Programming the LEDArray
Details including examples of programming the WPI AddressableLED class are provided in the online Addressable LEDs documentation.
Note that the WPI AddressableLED class does not provide a way to change the order which each Red/Green/Blue intensity value is transmitted to the LED Array, and the order Green, Red, Blue (GRB) is the only supported order. This may cause unexpected behavior when used with certain LED Arrays (e.g., the WS2811 which expects an order of Red, Green, Blue (RGB) instead).
References
The following references may provide a deeper understanding of LED Array technology, operation and troubleshooting: