A Class representing a WS2812 or compatible RGB LED string connected to a Serial Wombat pin. More...

#include <SerialWombatWS2812.h>

Inheritance diagram for SerialWombatWS2812:

Collaboration diagram for SerialWombatWS2812:

[legend]

Public Member Functions
	SerialWombatWS2812 (SerialWombatChip &serialWombat)
	Constructor for SerialWombatWS2812 class.

int16_t	begin (uint8_t pin, uint8_t numberOfLEDs, uint16_t userBufferIndex)
	Initialize a WS2812 LED driver object.

int16_t	write (uint8_t led, uint32_t color)
	Set an LED color.

int16_t	write (uint8_t led, int16_t color)
	An overload for Write in case write(x,0); is interpreted as an int16_t rather than uint32_t.

int16_t	write (uint8_t led, int32_t color)
	An overload for Write in case write(x,0); is interpreted as an int32_t rather than uint32_t.

int16_t	write (uint8_t led, uint8_t length, uint32_t colors[])

int16_t	writeAnimationLED (uint8_t frame, uint8_t led, uint32_t color)

int16_t	writeAnimationLED (uint8_t frame, uint8_t led, int16_t color)
	An overload color is interpreted as an int16_t rather than uint32_t.

int16_t	writeAnimationLED (uint8_t frame, uint8_t led, int32_t color)
	An overload color is interpreted as an int32_t rather than uint32_t.

int16_t	writeAnimationFrame (uint8_t frame, uint32_t colors[])
	Store an array of colors for an entire animation frame.

int16_t	writeAnimationFrameDelay (uint8_t frame, uint16_t delay_mS)
	Set how long an animation frame should be displayed before moving to the next frame.

int16_t	writeAnimationUserBufferIndex (uint16_t index, uint8_t numberOfFrames)
	set the location in UserBuffer where the animation array will be stored and number of frames

int16_t	readBufferSize ()
	returns the number of bytes of UserBuffer required to service the configured number of LEDs

int16_t	writeMode (SWWS2812Mode mode)
	Sets the mode of the WS2812 LED Driver.

int16_t	barGraph (uint8_t sourcePin, uint32_t offRGB, uint32_t onRGB, uint16_t min, uint16_t max)
	Display a bargraph using the configured ws2812 class.

Public Member Functions inherited from SerialWombatPin
	SerialWombatPin (SerialWombatChip &serialWombatChip)
	Instantiates a Serial Wombat Pin.

	SerialWombatPin (SerialWombatChip &serialWombatChip, uint8_t pin)
	Instantiates a Serial Wombat Pin.

uint16_t	readPublicData ()
	Read the 16 Bit public data associated with this pin.

void	pinMode (uint8_t mode, bool pullDown=false, bool openDrain=false)
	Set pin to INPUT or OUTPUT, with options for pull Ups and open Drain settings.

void	digitalWrite (uint8_t val)
	Set output pin High or Low.

int	digitalRead ()
	Reads the state of the Pin.

uint16_t	writePublicData (uint16_t value)
	Write a 16 bit value to this pin.

uint8_t	pin ()
	Returns the current SW pin number. Used primarily for virtual calls by derived classes.

uint8_t	swPinModeNumber ()
	Returns the Mode number. Used primarily by derived classes to populate packet data.

int16_t	initPacketNoResponse (uint8_t packetNumber, uint8_t param0=0x55, uint8_t param1=0x55, uint8_t param2=0x55, uint8_t param3=0x55, uint8_t param4=0x55)

int16_t	initPacketNoResponse (uint8_t packetNumber, uint16_t param0=0x55, uint8_t param1=0x55, uint8_t param2=0x55, uint8_t param3=0x55)

int16_t	initPacketNoResponse (uint8_t packetNumber, uint16_t param0, uint16_t param1, uint8_t param2=0x55)

int16_t	disable ()
	Disables the pin mode (if applicable)

int16_t	enablePullup (bool enabled)
	Enables the weak pull up on a pin. Implemented on SW18AB only.

int16_t	enablePullDown (bool enabled)
	Enables the weak pull down on a pin. Implemented on SW18AB only.

int16_t	enableOpenDrain (bool enabled)
	Enables open drain mode on a pin. Implemented on SW18AB only.

Public Attributes
bool	swapRG = false
	Swap the Red and Green byte values. Set this to true for WS2811 chips which reverse the red and green byte order.

Additional Inherited Members
Protected Attributes inherited from SerialWombatPin
uint8_t	_pin = 255

SerialWombatChip &	_sw

uint8_t	_pinMode = 0

Detailed Description

A Class representing a WS2812 or compatible RGB LED string connected to a Serial Wombat pin.

This class is only supported on the Serial Wombat SW18AB chip. It is not supported on the Serial Wombat 4X line. This pin mode can only be used on enhanced capability pins (WP0-4, WP7, or WP9-19)

This class controls a State Machine driven driver for a WS2812 compatible RGB LED string.

Each instance of this class uses an average of approximately TBD% of the SW18's processing time. This varies by configuration options and usage.

The Serial Wombat WS2812 driver can be configured in a number of ways: The driver lights up the LEDs one at a time in sequence The driver shows colors as commanded by the host The driver cycles through arrays of colors at a specified rate

See the available examples in the Arduino Library for usage.

Warning: Different WS2812 pcbs behave differently based on how the manufacturer routed the LEDs on the PCB Board. For instance a square 4x4 matrix may not light in the order expected. This is not an issue with the library.; An array of WS2812 LEDs can pull lots of current. Lighting multiple LEDs at full brightness may consume more power than your supply can provide, causing the system voltage to become unstable. An unstable system voltage can cause unreliable operation of the Serial Wombat chip.

The Serial Wombat WS2812 driver is extremely efficient in terms of processor time since it uses the PIC24FJ256GA702's DMA and SPI hardware to generate the WS2812 signal. This allows the Serial Wombat firmware to easily clock out WS2812 signals while doing other thigns. However, this method is very RAM intensive, requiring about 50 bytes of ram for each LED.

The RAM used for buffering this signal is stored in the User Buffer RAM, an array available for the user to allocate to various PIN modes' uses. In Version 2.0.3 of the Serial Wombat 18AB firmware there is 8k of RAM allocated to User Buffer, allowing about 160 LEDs to be used if all RAM is allocated to the WS2812.

A number of frames to be shown in rotation with configurable delays inbetween can also be stored in the User Buffer. This is in additional to the rendering buffer. Each animation frame requires 2+3*NumberOfLEDs bytes.

The Update rate is variable with the number of LEDs so that rendering of colors into the User Buffer is spread across multiple Serial Wombat 1mS execution frames. The LEDs will be updated approximately every X mS, where X is the number of LEDs plus 20.

A tutorial is available here:

https://youtu.be/WoXvLBJFpXk

Definition at line 88 of file SerialWombatWS2812.h.

Constructor & Destructor Documentation

◆ SerialWombatWS2812()

SerialWombatWS2812::SerialWombatWS2812 ( SerialWombatChip & serialWombat )

inline

Constructor for SerialWombatWS2812 class.

Parameters

serialWombat SerialWombat chip on which the driver will run

Definition at line 95 of file SerialWombatWS2812.h.

Member Function Documentation

◆ barGraph()

int16_t SerialWombatWS2812::barGraph	(	uint8_t	sourcePin,
		uint32_t	offRGB,
		uint32_t	onRGB,
		uint16_t	min,
		uint16_t	max )

inline

Display a bargraph using the configured ws2812 class.

Parameters

sourcePin	The data source to use for the bargraph
offRGB	The color to use for LEDs beyond the bargraph level
onRGB	The color to use for LEDs lit by the bargraph
min	The public data value (or below) to be treated as the beginning of the bargraph
max	The public data value (or above) to be treated as the end of the bargraph

Definition at line 296 of file SerialWombatWS2812.h.

◆ begin()

int16_t SerialWombatWS2812::begin	(	uint8_t	pin,
		uint8_t	numberOfLEDs,
		uint16_t	userBufferIndex )

inline

Initialize a WS2812 LED driver object.

This function initializes hardware and data arrays for the WS2812 driver. It requires about 30uS per LED to initialize the data array. During this time pin processing is suspended. This can cause glitches in other pins. It is recommended that this pin mode be initialized once near the beginning of at power up and that begin() not be called during real-time operation.

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Parameters

pin	The pin connected to the WS2812. This must be an enhanced capability pin ( WP0-4, WP7, or WP9-19)
numberOfLEDs	The number of LEDs connected in series to the pin
userBufferIndex	The index in bytes into the User Buffer area where the signal train to be sent to the LEDs is stored. The amount of data bytes required for the configured number of LEDs can be queried with readBufferSize. This area must not be used by other pins, and cannot extend past the end of the 8k of space.

Definition at line 115 of file SerialWombatWS2812.h.

◆ readBufferSize()

int16_t SerialWombatWS2812::readBufferSize ( )

inline

returns the number of bytes of UserBuffer required to service the configured number of LEDs

This number does not include any animation frames.

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Definition at line 259 of file SerialWombatWS2812.h.

◆ write() [1/4]

int16_t SerialWombatWS2812::write	(	uint8_t	led,
		int16_t	color )

inline

An overload for Write in case write(x,0); is interpreted as an int16_t rather than uint32_t.

Definition at line 145 of file SerialWombatWS2812.h.

◆ write() [2/4]

int16_t SerialWombatWS2812::write	(	uint8_t	led,
		int32_t	color )

inline

An overload for Write in case write(x,0); is interpreted as an int32_t rather than uint32_t.

Definition at line 151 of file SerialWombatWS2812.h.

◆ write() [3/4]

int16_t SerialWombatWS2812::write	(	uint8_t	led,
		uint32_t	color )

inline

Set an LED color.

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Parameters

led	The index of the LED to be set to color
color	The color of the LED in 0x00RRGGBB format

Definition at line 131 of file SerialWombatWS2812.h.

◆ write() [4/4]

int16_t SerialWombatWS2812::write	(	uint8_t	led,
		uint8_t	length,
		uint32_t	colors[] )

inline

Definition at line 164 of file SerialWombatWS2812.h.

◆ writeAnimationFrame()

int16_t SerialWombatWS2812::writeAnimationFrame	(	uint8_t	frame,
		uint32_t	colors[] )

inline

Store an array of colors for an entire animation frame.

Parameters

frame	The index of the frame being stored
colors	an array of uint32_t colors in 0x00RRGGBB format to be stored in the frame. The length of the array must match the number of LEDs

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Definition at line 213 of file SerialWombatWS2812.h.

◆ writeAnimationFrameDelay()

int16_t SerialWombatWS2812::writeAnimationFrameDelay	(	uint8_t	frame,
		uint16_t	delay_mS )

inline

Set how long an animation frame should be displayed before moving to the next frame.

Parameters

frame	The index of the frame being set
dealy_mS	the amount of time to display the frame in mS

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Definition at line 234 of file SerialWombatWS2812.h.

◆ writeAnimationLED() [1/3]

int16_t SerialWombatWS2812::writeAnimationLED	(	uint8_t	frame,
		uint8_t	led,
		int16_t	color )

inline

An overload color is interpreted as an int16_t rather than uint32_t.

Definition at line 195 of file SerialWombatWS2812.h.

◆ writeAnimationLED() [2/3]

int16_t SerialWombatWS2812::writeAnimationLED	(	uint8_t	frame,
		uint8_t	led,
		int32_t	color )

inline

An overload color is interpreted as an int32_t rather than uint32_t.

Definition at line 201 of file SerialWombatWS2812.h.

◆ writeAnimationLED() [3/3]

int16_t SerialWombatWS2812::writeAnimationLED	(	uint8_t	frame,
		uint8_t	led,
		uint32_t	color )

inline

Definition at line 188 of file SerialWombatWS2812.h.

◆ writeAnimationUserBufferIndex()

int16_t SerialWombatWS2812::writeAnimationUserBufferIndex	(	uint16_t	index,
		uint8_t	numberOfFrames )

inline

set the location in UserBuffer where the animation array will be stored and number of frames

Parameters

index	The index into UserBuffer
numberOfFrames	The number of frames that make up the animation

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Definition at line 247 of file SerialWombatWS2812.h.

◆ writeMode()

int16_t SerialWombatWS2812::writeMode ( SWWS2812Mode mode )

inline

Sets the mode of the WS2812 LED Driver.

Returns: 0 or higher for success or a negative number indicating an error code from the Serial Wombat chip.

Definition at line 281 of file SerialWombatWS2812.h.

Member Data Documentation

◆ swapRG

bool SerialWombatWS2812::swapRG = false

Swap the Red and Green byte values. Set this to true for WS2811 chips which reverse the red and green byte order.

Definition at line 313 of file SerialWombatWS2812.h.

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SerialWombatWS2812()

Member Function Documentation

◆ barGraph()

◆ begin()

◆ readBufferSize()

◆ write() [1/4]

◆ write() [2/4]

◆ write() [3/4]

◆ write() [4/4]

◆ writeAnimationFrame()

◆ writeAnimationFrameDelay()

◆ writeAnimationLED() [1/3]

◆ writeAnimationLED() [2/3]

◆ writeAnimationLED() [3/3]

◆ writeAnimationUserBufferIndex()

◆ writeMode()

Member Data Documentation

◆ swapRG