Serial Wombat Arduino Library

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | List of all members
SerialWombatWS2812 Class Reference

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

`#include <SerialWombatWS2812.h>`

Inheritance diagram for SerialWombatWS2812:
[legend]
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 (int led, int 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.
int16_t | barGraph (SerialWombatDataSource 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 and SW8B only.
int16_t | enablePulldown (bool enabled)
| Enables the weak pull down on a pin. Implemented on SW18AB and SW8B only.
int16_t | enableOpenDrain (bool enabled)
| Enables open drain mode on a pin. Implemented on SW18AB and SW8B only.
int16_t | forceDMA (bool enabled)
| Forces use of DMA instead of hardware timing resources on SW18AB.
void | setPinNumberForTesting (uint8_t pin)
| A function designed for testing only. May have unpredictable results if used in real time. Not intended for general use.

## 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() [1/2]

int16_t SerialWombatWS2812::barGraph | ( | SerialWombatDataSource | 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 325 of file SerialWombatWS2812.h.

## ◆ barGraph() [2/2]

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 302 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 265 of file SerialWombatWS2812.h.

## ◆ write() [1/5]

int16_t SerialWombatWS2812::write | ( | int | led,
|  | int | color )
| inline

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

Definition at line 157 of file SerialWombatWS2812.h.

## ◆ write() [2/5]

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() [3/5]

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() [4/5]

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() [5/5]

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

Definition at line 170 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 219 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
  delay_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 240 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 201 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 207 of file SerialWombatWS2812.h.

## ◆ writeAnimationLED() [3/3]

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

Definition at line 194 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 253 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 287 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 332 of file SerialWombatWS2812.h.