A ws813b led strip library written in C for the microcontroller esp32. This library is created to give a complex set of visual effects with minimal effort from the user.
The library have a range of predefined functions which operates/changes the color of the leds in different behaviours. Theese functions belong to different modes which are operated by an engine/server (freertos task). The engine reads a configuration file and cotrols the execution of a mode. Each mode can be enabled in combination with one and another for a unique visual effect.
This readme is a bit outdated so please refer to the examples in the examples directory. A short description for each example is available here.
To compile one of the examples copy it to the main folder and rename it to main.c
A minimal example of what is required to use the library.
Example showcasing all the modes and their respective settings. However not all modes are activated.
Example showcasing how the configuration can be accessed and altered during execution from another task/process.
showcases the music mode. This requires a mic input on GPIO34. Its specifically tuned for a electret microphone - Amplifier - MAX4466.
For a super quick introduction see Minimal Example.
The library works by enabling and configuring modes which are enabled in the config structure led_config. A mode is an visual effect applied to the led strip, e.g. the mode walk which rotates the leds one step at a configurable rate. Several modes can be enabled at the same time for a unique visual effect. Each mode have some common configurations such as rate. Rate will determine how often a function operates on the led strip. The modes are enables by setting the respective variable (in the config) to a non-zero value.
The colors of the led strip are divided into sections and the number of leds which belong to one section is automatically configured.
How to use in steps:
- Configure sdkconfig ( see sdkconfig ) or use the sdkconfig included
- Create an array of led_config
- Set desired modes ( see initRmt function and Config structures )
- Set desired colors ( see Set colors )
- Call ledEngine() with your led_config array as argument.
- Done!
The available modes can be found under Led Modes .
CONFIG_FREERTOS_HZ Must be set to 1000 in sdkconfig for the rate and frequency variables to function as intended. If not set the the default is 100 and the update rate might not be as fast as desired for some modes. It is however possible to leave it as is.
CONFIG_MAIN_TASK_STACK_SIZE must be increased to accomodate the size of all the structures. It is probably possible to use freertos xCreateTask() to create a task in which the library is used. This is the end goal inteded way of using the library but it has not yet been tested.
Call initRmt() with a led_config array as argument to initRmtialize the library. The function is required to initialize the rmt library correctly by defining rmt_conf and calling rmt_config and rmt_driver_install functions. InitRmt() will also initialize and allocate memory for a led_struct array.
TODO Add argument for pin out
- Library used: driver/rmt.h
- Variables and structures:
To be added:
- Different ways to set the colors
- Repeating sections
- Mixed sections
- etc..
- Set new colors in runtime
- setFadeColors function
Minimal Example for 60 leds on a strip divided into 10 different colored sections. The colors will be smoothed out and rotate once every 15 mS. testColors is defined in colors.h.
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "ws813b.h"
#include "colors.h"
void app_main(){
volatile struct mode_config conf[2];
initModeConfigs(conf, 1, 60 , 10);
initRmt(conf);
conf[0].smooth = 30;
conf[0].walk = 1;
conf[0].walkRate = 15;
initColors(&conf, testColors);
setSectionColors(conf[0], leds);
while(1)
ledEngine(conf);
}This section describes all the structures in the library. Under manually configured you’ll find the structures you need to configure, under automatically configured you’ll find structures the initiliazing function will take care of (you can ignore theese).
Configuration structures which needs to be set manually.
The mode configuration structure. Used to set modes and some basic configurations. To enable a mode set its respective variable named after the mode to a non-zero value. Each mode also have a set of configuration variables which needs to be set, you can find documentation for each mode under Led Modes.
There are some variables which need to be set to let the initRmt() function know how to initialize the library correctly.
- Set length to number of leds you are gonna use on the led strip.
- Set sectionLength to the number of section you are gonna use
Note: Set the the sectionLength so that length is evenly divisible by sectionLength. It might cause errors if this is not true. A feature is to be implemented which handles this.
| variable | type | is required | function |
|---|---|---|---|
| length | uint8_t | yes | n of leds |
| sectionLength | uint8_t | yes | n of section |
| ledOffset | uint8_t | no | dont change |
| fadeRate | uint8_t | no | rate of function fade |
| !step | uint8_t | no | enable step |
| fade | uint8_t | no | enable fade |
| fadeRate | uint8_t | no | Rate of fade |
| fadeWalk | uint8_t | no | enable of fadeWalk |
| fadeWalkRate | uint8_t | no | Rate of fadeWalk |
| !pulse | uint8_t | no | enable of pulse |
| pulseRate | uint8_t | no | rat of pulse |
| walk | uint8_t | no | enable of walk |
| smooth | uint8_t | no | “smooths” the colors |
TODO make an struct section_colors
The structure color_t is meant to be used as an array. Each element corresponds to one sections color.
| Variable | type | fuctionality |
|---|---|---|
| red | uint8_t | value of red |
| blue | uint8_t | value of blue |
| green | uint8_t | value of red |
A list of structures which do not need to be configured or altered when using this library. If you have no intrestest in tinkering or learning how the internals of this library works you can skip this section.
An array of Led_struct is used to hold current colors of each led as well as an item used by the remote controller library to transmit the data to the led strip.
The led_struct structure holds an array of 24 rmt_item32_t structures, 7 integers of which three represents the current color setting for a led, three representing a target color for modes such as fade which requires a target color. The last integer is a direction teller, however no mode is currently using it.
- The led_struct:
| Variable name | type | function |
|---|---|---|
| r | uint8_t | red value |
| g | uint8_t | green value |
| b | uint8_t | blue value |
| fadeR | uint8_t | red target value |
| fadeG | uint8_t | green target value |
| fadeB | uint8_t | blue target value |
| Dir | uint8_t | direction value |
Configuration file for the remote control driver library. Note: Output pin is set by gpio_num.
| Variable | Value |
|---|---|
| struct rmt_conf | |
| rmt_mode | RMT_MODE_TX |
| channel | RMT_CHANNEL_0 |
| gpio_num | 4 |
| mem_block_num | 1 |
| clk_div | 8 |
| rmt_conf.tx_config | |
| loop_en | 0 |
| carrier_en | 0 |
| idle_outpu_en | 1 |
| idle_level | 0 |
| carrier_duty_percent | 50 |
| carrier_freq_hz | 10 000 |
| carrier_level | 1 |
Moves each led one step backwards on the strip each update. The first led will jump the the last place.
| conf. variables | Purpose | Type |
|---|---|---|
| WalkRate | Update rate (Hz) | integer |
| Walk | Enable/disable | bool |
- Associated Function: stepForward