This is a Stellaris/Tiva driver intended to be used with RGB LED lighting strip based on the LPD8806 controller. More...

Macros
#define	LPD8806_LEDSTRIP_ALLOW_DMA
	Existence of this macro allows DMA support to be built in. More...

#define	LPD8806_LEDSTRIP_NUM_INSTANCES
	This macro defines the number of LedStrip instances that are supported by the driver. More...

#define	LPD8806_LEDSTRIP_FRAMEBUF_SIZE(numPixels)
	This convenience macro computes the number of bytes that are required for a frame buffer given the number of pixels. More...

Typedefs
typedef void *	LPD8806_LedStrip_Handle_t
	Define the instance handle to be used for all LedStrip API functions. More...

Enumerations
enum	LPD8806_LedStrip_Channel_t { CHAN_RED, CHAN_GREEN, CHAN_BLUE }
	Define channel values that can be used for LPD8806_LedStrip_SetPixelChannel() and LPD8806_LedStrip_GetPixelChannel() More...

Functions
void	LPD8806_LedStrip_SetPixelValue (LPD8806_LedStrip_Handle_t h, uint32_t pixelNum, uint32_t rgb)
	Set the RGB value of a pixel directly. More...

uint32_t	LPD8806_LedStrip_GetPixelValue (LPD8806_LedStrip_Handle_t h, uint32_t pixelNum)
	Get the pixel color as a single RGB value. More...

void	LPD8806_LedStrip_SetPixelRgb (LPD8806_LedStrip_Handle_t h, uint32_t pixelNum, uint8_t r, uint8_t g, uint8_t b)
	Set the pixel color using color channels. More...

void	LPD8806_LedStrip_GetPixelRgb (LPD8806_LedStrip_Handle_t h, uint32_t pixelNum, uint8_t pr, uint8_t pg, uint8_t *pb)
	Get the pixel color as separate color channels. More...

void	LPD8806_LedStrip_SetPixelChannel (LPD8806_LedStrip_Handle_t h, uint32_t pixelNum, LPD8806_LedStrip_Channel_t channel, uint8_t channelValue)
	Set an individual color channel for a pixel. More...

uint8_t	LPD8806_LedStrip_GetPixelChannel (LPD8806_LedStrip_Handle_t h, uint32_t pixelNum, LPD8806_LedStrip_Channel_t channel)
	Get a pixel individual color channel. More...

void	LPD8806_LedStrip_Update (LPD8806_LedStrip_Handle_t h)
	Update the LED string with the buffered values. More...

uint32_t	LPD8806_LedStrip_NumPixels (LPD8806_LedStrip_Handle_t h)
	Get the number of pixels in the instance. More...

LPD8806_LedStrip_Handle_t	LPD8806_LedStrip_Init (uint32_t sysClock, uint32_t spiIdx, uint32_t spiRate)
	Initialize the LED strip driver hardware. More...

void	LPD8806_LedStrip_SetFrameBuffer (LPD8806_LedStrip_Handle_t h, void *pFrameBuffer, uint32_t numPixels)
	Set the frame buffer for an LedStrip instance. More...

void	LPD8806_LedStrip_Clear (LPD8806_LedStrip_Handle_t h)
	Clear the frame buffer. More...

void	LPD8806_LedStrip_EnableDma (LPD8806_LedStrip_Handle_t h, uint32_t dmaChannel)
	Enable the use of DMA by the driver. More...

Detailed Description

This is a Stellaris/Tiva driver intended to be used with RGB LED lighting strip based on the LPD8806 controller.

These lighting strips can be found on adafruit and other places. They are typically 32 LEDs in a strip but can be longer and can be joined in series.

This has been tested using an Stellaris EK-LM3S6965, but should work with any Stellaris or Tiva part with little or no modifications.

The LED strip must be powered appropriately and connected to the data and clock lines of one of the Stellaris SSI/SPI ports. This driver is attached to a SPI peripheral when it is initialized.

This driver maintains a pixel "frame buffer". The provided functions allow to set and get the RGB value of any pixel in the buffer and to update the entire string at once.

Each pixel is 7-bit * 3 channels (total of 21 bits) RGB. You can manipulate the pixel values by individual color channel or as a single value.

Todo:: make driver interrupt driven (presently is polled or DMA)

EXAMPLE: Here is code showing how you might use this driver in an example:

// Allocate a frame buffer for a 32 pixel strip
#define NUM_PIXELS 32
uint8_t frameBuffer[LPD8806_LEDSTRIP_FRAMEBUF_SIZE(NUM_PIXELS)];
// init the driver for SPI 0, and 500 kHz clock rate
LPD8806_Handle_t hLed = LPD8806_LedStrip_Init(SysCtlClockGet(), 0, 500000);
if(!hLed)
{
    // handle error
    ...
}
// Assign the frame buffer
LPD8806_LedStrip_SetFrameBuffer(hLed, frameBuffer, NUM_PIXELS);
// Clear out the pixel data
LPD8806_LedStrip_Clear(hLed);
// Update the strip so everything will be turned off
LPD8806_LedStrip_Update(hLed);
// set pixel 0 to full red, half green, quarter blue
LPD8806_LedStrip_SetPixelRgb(hLed, 0, 0x7f, 0x40, 0x20);
// update the light string
LPD8806_LedStrip_Update(hLed);

Macro Definition Documentation

#define LPD8806_LEDSTRIP_ALLOW_DMA

Existence of this macro allows DMA support to be built in.

This leaves use of DMA as a run-time option. If this macro is not defined or undef'd then all DMA support is compiled out and it will not be a run-time option. This value can be changed by editing the header file, or by defining or undefining the macro on the command line. This macro is defined by default.

#define LPD8806_LEDSTRIP_NUM_INSTANCES

This macro defines the number of LedStrip instances that are supported by the driver.

The larger the number of instances, the more memory used by the driver. The default value is 2. If you have a system with more RGB LedStrips than that, then you can increase this number.

#define LPD8806_LEDSTRIP_FRAMEBUF_SIZE ( numPixels )

This convenience macro computes the number of bytes that are required for a frame buffer given the number of pixels.

It can be used by the application to allocate memory for the frame buffer before calling LPD8806_LedStrip_SetFrameBuffer(). The frame buffer must be one place longer than the number of pixels.

Typedef Documentation

typedef void* LPD8806_LedStrip_Handle_t

Define the instance handle to be used for all LedStrip API functions.

This value is returned from LPD8806_LedStrip_Init() and must be passed to all other functions.

Enumeration Type Documentation

enum LPD8806_LedStrip_Channel_t

Define channel values that can be used for LPD8806_LedStrip_SetPixelChannel() and LPD8806_LedStrip_GetPixelChannel()

Enumerator
CHAN_RED	Red color channel.
CHAN_GREEN	Green color channel.
CHAN_BLUE	Blue color channel.

Function Documentation

void LPD8806_LedStrip_SetPixelValue	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	pixelNum,
		uint32_t	rgb
	)

Set the RGB value of a pixel directly.

Parameters

h	is the LedStrip instance handle from _Init()
pixelNum	is the pixel number to modify
rgb	is the 24-bit RGB value ([23:16]red, [15:8]green, [7:0]blue)

This function is used to set the color value of a pixel using a combined RGB value in a uint32_t. The RGB color channel values are 7 bits each and arranged as follows:

Bits	Color Channel
31:24	Not used
23	Reserved (set to 0)
22:16	Red
15	Reserved (set to 0)
14:8	Green
7	Reserved (set to 0)
6:0	Blue

uint32_t LPD8806_LedStrip_GetPixelValue	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	pixelNum
	)

Get the pixel color as a single RGB value.

Parameters

h	is the LedStrip instance handle from _Init()
pixelNum	is the pixel number to read

The value is returned as a 24-bit RGB value with color channels arranged as: ([23:16]red, [15:8]green, [7:0]blue)

Returns: Returns the RGB color value of the pixel. If there is any error then 0 is returned.

void LPD8806_LedStrip_SetPixelRgb	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	pixelNum,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Set the pixel color using color channels.

Parameters

h	is the LedStrip instance handle from _Init()
pixelNum	is the pixel number to modify
r	is the 7-bit value of the red color channel
g	is the 7-bit value of the green color channel
b	is the 7-bit value of the blue color channel

This function is used to set the color of a specific pixel by specifying the individual color channel values. Each color channel is 7 bits.

void LPD8806_LedStrip_GetPixelRgb	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	pixelNum,
		uint8_t *	pr,
		uint8_t *	pg,
		uint8_t *	pb
	)

Get the pixel color as separate color channels.

Parameters

	h	is the LedStrip instance handle from _Init()
	pixelNum	is the pixel number to read
[out]	pr	is a pointer for the returned value of the red color channel
[out]	pg	is a pointer for the returned value of the green color channel
[out]	pb	is a pointer for the returned value of the blue color channel

The color channel values are returned via 3 caller supplied pointers, each as a 7-bit value. The values will all be set to 0 if there is any error.

void LPD8806_LedStrip_SetPixelChannel	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	pixelNum,
		LPD8806_LedStrip_Channel_t	channel,
		uint8_t	channelValue
	)

Set an individual color channel for a pixel.

Parameters

h	is the LedStrip instance handle from _Init()
pixelNum	is the pixel number to modify
channel	is the color channel to modify: CHAN_RED, CHAN_GREEN, CHAN_BLUE
channelValue	is the 7-bit value for the color channel

This function can be used to set just a single color channel of a pixel.

uint8_t LPD8806_LedStrip_GetPixelChannel	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	pixelNum,
		LPD8806_LedStrip_Channel_t	channel
	)

Get a pixel individual color channel.

Parameters

h	is the LedStrip instance handle from _Init()
pixelNum	is the pixel number to read
channel	is the color channel to read: CHAN_RED, CHAN_GREEN, CHAN_BLUE

Returns: Returns the value of the specified color channel as 7-bits, or 0 if there is an error.

void LPD8806_LedStrip_Update ( LPD8806_LedStrip_Handle_t h )

Update the LED string with the buffered values.

Parameters

h	is the LedStrip instance handle from _Init()

The pixel values that were written to the LED "frame buffer" with the above functions are copied to the physical LED string via the SSI/SPI port.

If DMA support is enabled, then this function will return right away while the DMA runs in the background. If DMA is not enabled, then this function uses polled IO to copy the data to the SPI port until the entire buffer has been copied to the output FIFO.

uint32_t LPD8806_LedStrip_NumPixels ( LPD8806_LedStrip_Handle_t h )

Get the number of pixels in the instance.

Parameters

h	is the LedStrip instance handle from _Init()

Returns: Returns the number of pixels supported for the specified LedStrip instance.

LPD8806_LedStrip_Handle_t LPD8806_LedStrip_Init	(	uint32_t	sysClock,
		uint32_t	spiIdx,
		uint32_t	spiRate
	)

Initialize the LED strip driver hardware.

Parameters

sysClock	is the value of the system clock
spiIdx	is the index of the SPI peripheral to use (0-origin)
spiRate	is the data rate to use for SPI

The application must call this function before using any other functions in this driver. It is used to set up a hardware instance for use by the driver. The parameter sysClock is the value of the MCU system clock frequency. It is needed for initializing the SPI peripheral. The parameter spiIdx is the SPI peripheral number to use (0, 1, etc). It is limited to the number of SPI peripherals in the system. The spiRate is the desired clock frequency of the SPI peripheral. There is no validation of this parameter. The driver will attempt to set the specified value of the SPI clock rate but if it is not valid then the init will probably fail silently.

Note: The application must also call LPD8806_LedStrip_SetFrameBuffer() before this driver can be used.

Returns: Returns a handle that is used for the other LedStrip function. The returned value will be NULL if there is any error with the initialization.

void LPD8806_LedStrip_SetFrameBuffer	(	LPD8806_LedStrip_Handle_t	h,
		void *	pFrameBuffer,
		uint32_t	numPixels
	)

Set the frame buffer for an LedStrip instance.

Parameters

h	is the LedStrip instance handle from _Init()
pFrameBuffer	is a pointer to storage for the frame buffer
numPixels	is the number of pixels for the frame buffer

This function assigns a frame buffer to the LedStrip instance. This must be called at least once following LPD8806_LedStrip_Init(). It can be called other times if needed to change the frame buffer for an LedStrip. For example if there is a pre-rendered frame buffer it could be used to switch between computed and pre-rendered frame buffer.

The caller must allocate the space for the frame buffer, pFrameBuffer. The macro LPD8806_FRAMEBUF_SIZE can be used to get the number of bytes that are needed for a frame buffer given the number of pixels to store.

void LPD8806_LedStrip_Clear ( LPD8806_LedStrip_Handle_t h )

Clear the frame buffer.

Parameters

h	is the LedStrip instance handle from _Init()

This is a convenience function the clear the contents of the frame buffer back to "zero", meaning all pixels are off. This function does not update the hardware.

void LPD8806_LedStrip_EnableDma	(	LPD8806_LedStrip_Handle_t	h,
		uint32_t	dmaChannel
	)

Enable the use of DMA by the driver.

Parameters

h	is the LedStrip instance handle from _Init()
dmaChannel	is the DMA channel number that should be used for the SSI/SPI

This function assigns the DMA channel to the LedStrip instance and enables use of DMA when writing pixel data using the SPI peripheral. The caller must provide a valid DMA channel and configuration - nothing is done to validate the DMA channel.

The application must first set up the DMA controller and configure the correct DMA channel for this peripheral before calling this function.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation