Pixled ESP 🌈 🐑

pixled-esp is an ESP-IDF component that integrates the Pixled animation library pixled-lib and the esp-pixled-driver led strip control ESP-IDF component to easily :

1. Build some complex animations using the powerfull Pixled syntax
2. Transmit them to led strips, panels or any other system without struggling with low-level hardware issues.

Installation

This guides assumes that you have already set up your ESP-IDF environment. Moreover you must know how to build an ESP-IDF project and install an ESP-IDF component.

Important note

pixled-esp requires ESP-IDF version 4.1 or above. Even if the latest ESP-IDF version is supposed to work, its instability has led to unexpected results, so we recommend to use a release / prelease version. More particularly, the esp-idf release-v4.2 has been used to test the library. See the corresponding ESP-IDF documentation to install this version.

As a reminder, to install a component, you can add a component folder into the $IDF_PATH/components folder to make it available to any component in any project, add it locally to your project in your components sub-directory or eventually store it in any custom directory and manually add it to your build using the EXTRA_COMPONENT_DIRS ESP-IDF project variable. (see the ESP-IDF documentation for more information on component management )

In any case, the following 3 ESP-IDF components must be available from your current project :

• esp-pixled-driver
• pixled-lib
• pixled-esp (this repository)

Installation example

From a terminal with a loaded ESP-IDF environment, the following script describes the simplest installation process :

cd $IDF_PATH/components
git clone https://github.com/pixled/esp-pixled-driver
git clone https://github.com/pixled/pixled-lib
git clone https://github.com/pixled/pixled-esp

and that's it, pixled-esp is now available from all your ESP-IDF projects.

Get started

Project configuration

Once the pixled-esp component is installed, it should be automatically added as a requirement of the main component of your project (see the ESP-IDF documentation for more details).

You can then use #include <pixled_esp.hpp> to have both an access to the driver and animation library.

Finally, because the Pixled libraries are written in C++11, you need to :

• use *.cpp files (instead of *.c files) for the source code that requires Pixled (e.g. main.cpp)
• wrap your ESP-IDF main function with extern "C" as follow :

extern "C" void app_main() {
...
}

Sample project

A minimal working main.cpp is provided here :

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "pixled_esp.hpp"

#define PIN GPIO_NUM_12
#define NUM_LED 30 
#define FPS 25

// Brings all pixled classes into scope (recommended)
using namespace pixled;

// Defines an RGB strip
RgbStrip strip(PIN, NUM_LED, RMT_CHANNEL_0, WS2812());

// Binds animation output to the strip
EspOutput out(strip);

// Defines a simple strip mapping
StripMapping mapping(NUM_LED);

// Sample animation
hsb animation = hsb(RainbowWave(5, 0, 10), 1., .5);

// Outputs `animation` frames to `out` using `mapping`
EspRuntime runtime(mapping, out, animation, strip, FPS);

extern "C" void app_main() {
	runtime.start();
}