ws2812.h File Reference

Exposes the Tiny-WS2812 library interface. More...

#include "ws2812_avr.h"
#include "ws2812_stm8s.h"
#include <stddef.h>
#include <stdint.h>
#include "ws2812_common.h"

Include dependency graph for ws2812.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
void	_ws2812_get_rgbmap (uint8_t(*rgbmap)[3], ws2812_order order)
	Initializes a rgb map for a given color order. More...
uint8_t	ws2812_config (ws2812 *dev, ws2812_cfg *cfg)
	Configures a WS2812 device struct. More...
void	ws2812_prep_tx (ws2812 *dev)
	Prepares the host device for data transmission. More...
void	ws2812_tx (ws2812 *dev, ws2812_rgb *pxls, size_t n_pxls)
	Transmits RGB values to the provided WS2812 device. More...
void	ws2812_wait_rst (ws2812 *dev)
	Waits for the WS2812 device to reset. More...
void	ws2812_close_tx (ws2812 *dev)
	Closes a WS2812 transmission. More...

Detailed Description

Exposes the Tiny-WS2812 library interface.

Author

Patrick Pedersen

Date

2021-04-09

The Tiny-WS2812 library initially derives from the driver code of an open source WS2812 LED controller that I had worked on prior, and provides a nearly barebone interface to communicate with WS2812 LED devices.

The following platforms and frameworks are currently supported:

• Barebone AVR
• The Arduino Framework (Currently only AVR based (eg. Uno, Leonardo, Micro...))

It has been developed out of the necessity to have an extremely light weight and flexible cross-platform library that can be further abstracted and used troughout my WS2812 projects, particullary on MCUs with severe memory constraints (ex. ATTiny chips), where one cannot just define an RGB array equivalent to the number of LEDs. This libraries purpose is NOT to provide fancy abstractions and functions for color correction, brightness settings, animations etc.

To summerize, this library is inteded to:

• be used on MCUs with limited computing resources.
• act as a base for more abstract WS2812 libraries.
• be easily portable to other platforms or programming frameworks (ex. Arduino).

Note

Because the motivation of this library is to be as barebone as possible, it relies on a superficial understanding of the WS2812 protocol and may demand an understanding of the host platforms platform (eg. registers etc.). For quick and simple programming of WS2812 devices, where memory and processing power are not a big issue, other libraries should probably be consulted.

Definition in file ws2812.h.

Function Documentation

_ws2812_get_rgbmap()

void _ws2812_get_rgbmap	(	uint8_t(*)	rgbmap[3],
		ws2812_order	order
	)

Initializes a rgb map for a given color order.

The following function is intended only to be used for internal library code, hence the _ prefix. It fills a 3 element byte array with the necessary offsets to map/convert RGB values to a different color order. For example, setting the order to rgb fills the rgb map with 0, 1, 2 and bgr fill the rgb map with 2, 1, 0, etc.

Definition at line 43 of file ws2812_common.c.

{
        switch (order) {
                case rbg:
                        memcpy(rgbmap, ws2812_order_rbg, 3);
                        break;
                case brg:
                        memcpy(rgbmap, ws2812_order_brg, 3);
                        break;
                case bgr:
                        memcpy(rgbmap, ws2812_order_bgr, 3);
                        break;
                case grb:
                        memcpy(rgbmap, ws2812_order_grb, 3);
                        break;
                case gbr:
                        memcpy(rgbmap, ws2812_order_gbr, 3);
                        break;
                default: // rgb
                        memcpy(rgbmap, ws2812_order_rgb, 3);
                        break;
        }
}

ws2812_close_tx()

void ws2812_close_tx

(

ws2812 *

dev

)

Closes a WS2812 transmission.

The following function should be called after ending data transmission with a WS2812 device. The exact closing procedure is platform specific but will typically involve restoring stashed registers to their previous states, re-enable interrupts, wait for the WS2812 to reset by calling ws2812_wait_rst(), and potentially alter fields of the provided WS2812 device struct.

Definition at line 275 of file ws2812_avr.c.

{
        if (_prep == true) {
                SREG = _sreg_prev;
                _prep = false;
                ws2812_wait_rst(dev);
        }
}

ws2812_config()

uint8_t ws2812_config	(	ws2812 *	dev,
		ws2812_cfg *	cfg
	)

Configures a WS2812 device struct.

The following function initializes/configures a WS2812 device struct using a ws2812_cfg configuration struct.

Definition at line 126 of file ws2812_avr.c.

{
        if (cfg->n_dev == 0)
                return 1; // No devices to be driven!
        
        uint8_t pin_msk = 0;
 
#ifdef WS2812_TARGET_PLATFORM_ARDUINO_AVR
        for (uint8_t i = 0; i < cfg->n_dev; i++) {
                if (i+1 < cfg->n_dev &&
                    digitalPinToPort(cfg->pins[i]) != digitalPinToPort(cfg->pins[i+1]))
                        return 2; // Pins do not share same port!
                pinMode(cfg->pins[i], OUTPUT);
                pin_msk |= digitalPinToBitMask(cfg->pins[i]);
        }
        dev->port = portOutputRegister(digitalPinToPort(cfg->pins[0]));
#else
        for (uint8_t i = 0; i < cfg->n_dev; i++)
                pin_msk |= 1 << cfg->pins[i];
 
        *cfg->ddr = pin_msk;
        dev->port = cfg->port;
#endif
        dev->rst_time_us = cfg->rst_time_us;
        dev->masklo = ~pin_msk & *(dev->port);
        dev->maskhi = pin_msk | *(dev->port);
        
        _ws2812_get_rgbmap(&dev->rgbmap, cfg->order);
        
        return 0;
}

ws2812_prep_tx()

void ws2812_prep_tx

(

ws2812 *

dev

)

Prepares the host device for data transmission.

The following function prepares the host device for data transmission. The exact preperation procedure is platform specific, but typically will involve disabling interrupts, stashing registers that may be modified when communicating to the WS2812 device and potentially preparing the passed WS2812 device struct for data transmission. For a more detailed understanding, please refer to the platform specific code of this function.

Warning

Always call this function before making any calls to ws2812_tx()! Not doing so may result in undefined behaivour!

Definition at line 159 of file ws2812_avr.c.

{
        if (_prep == false) {
                _sreg_prev = SREG;
                _prep = true;
        }
}

ws2812_tx()

void ws2812_tx	(	ws2812 *	dev,
		ws2812_rgb *	pxls,
		size_t	n_pxls
	)

Transmits RGB values to the provided WS2812 device.

The following function transmits RGB values to the provided WS2812 device. Calling this function consecutively for the same device will continue programming LEDs after the position where the last transmission has ended. In other words, calling the function consecutively for the same device will NOT program the device from the first LED, but rather take off from where it last ended. If this is not desired, call ws2812_wait_rst() after each transmission.

Definition at line 264 of file ws2812_avr.c.

{
        for (size_t i = 0; i < n_leds; i++) {
                for (uint8_t j = 0; j < sizeof(dev->rgbmap); j++) {
                        uint8_t *pxl = (uint8_t *) &(leds[i]);
                        ws2812_tx_byte(dev, pxl[dev->rgbmap[j]]);
                }
        }
}

ws2812_wait_rst()

void ws2812_wait_rst

(

ws2812 *

dev

)

Waits for the WS2812 device to reset.

The following function waits for the WS2812 device to reset, thus allowing it to be overwritten from the first LED again. The reset time is configuredin the ws2812_cfg object used to initialize/configure the passed WS2812 device struct, and is recommended to be 50us according to the WS2812 datasheet, but may be set significantly lower for some WS2812 devices. Call this function if you wish to overwritte the WS2812 device after a previous ws2812_tx() call.

Note

This function does not have to be called prior calling #ws2812_end_tx() as it already contains a call to ws2812_wait_rst().

Definition at line 168 of file ws2812_avr.c.

{
#ifdef WS2812_TARGET_PLATFORM_ARDUINO_AVR
        delayMicroseconds(dev->rst_time_us);
#else
        delay_us(dev->rst_time_us);
#endif
}