WOW Pixel Driver, LED Mapping & Animation System

A complete solution for pixel mapping, animation and driving for addressable LEDs

Why?

The real-time programmatic animation system used in all commerical products made by Elec Dash Tron is Private IP. I want to make the entire system accessible to the public without having to distribute the source code publicly. I want to also restrict usage to specific hardware modules

How does it work

The system consists of 2 physical, ESP8266 based, modules. The Driver Module (LABELED D) contains the pixel mapping, animation system and LED Driver. The Control module (LABELED C) is user programmable and runs your script of animations. The Control module communicates via the ESP-NOW protocol for realtime execution of commands.

What pixels are supported

The driver uses the ESP8266 SPI port to drive both Clocked and Unclocked Chipsets:

• APA102 APA102C & variants from AP Corp NeonWorld
• SK9822
• WS2812 5050
• WS2812B 5050
• WS2812 2020
• SK6812 5050, 3535 & 2427(With Opaque Lense)(The CLEAR Lense model is unsupported)

Some limitations

• The maximum pixel map size is 255x255 bytes
• I recommend the maximum amount of pixels to be under 1000 for best perfomance. There are A LOT of variables to consider here such as:
  • Power use
  • Your soldering skills
  • Cable and connection types
  • Environmental noise
  • Specific requirements for specific pixel chipsets
• The Control module uses the ESPNOW protocol to communicate with the Driver module. I have tested this to be pretty good at about 50 meters line of sight with a clean RF environment. When you start introducing RF noise, walls, pockets, cases etc... your range will be smaller
• A lot of the functions use BYTE (uint_8) for input vars. Please be mindful of any overun maths you need to do for your code

Basic Workflow

• Create a pixel map
• Upload it to the Driver module
• Upload the Driver Binary to the driver module
• Create your animations and upload them to your Controller module

Prerequisite Software

• The Arduino IDE via Arduino
  • With the ESP8266 Development Library, install instructions from here
  • You may also need the driver used to conect the USB to Serial IC on the Wemos mouldes located HERE for Most platforms
• The Espressif Flash Download Tools from Espressif
• The spreadhseet app from Open Office or Libre Office DO not use MS EXCEL unless you know how to mofiy the CONCAT() functions in the template doc

PIN OUTs of the 4PIN JST MALE port on the DRIVER Module

• Red: +5v
• Yellow: Clock Pin (only active for APA102/SK9822 pixels) Level shifted to 5V Logic Level via the SN74HCT245N
• Green: Data Pin (active for all pixels) Level shifted to 5V Logic Level via the SN74HCT245N
• Blue: Ground

The Driver module will come with 2 FEMALE JST cables for you to use depending on the type of pixel you wish to use. Both connect to the same 4 Pin MALE connector

• A 3pin cable for driving WS2812 & SK6812 Pixels
• A 4pin cable for driving APA102 & SK9822 Pixels

Connecting the modules to your computers USB port

You will need a USB to Micro USB cable to conect both modules for programming via the Arduino IDE. The Wemos D1 Mini boards included in this kit use the CH341 USB to Serial chip. Drivers are located HERE for Most platforms

Powering your LEDs (on the driver module)

The Driver module comes with a USB cable with a power switch, you will need to conect this to a power sources with enough current to drive your LED count. A powerbank with a 2A output is a great start. DO NOT CONECT YOUR LEDS TO THE DRIVER MODULE UNLESS YOU ARE DELIVERING POWER VIA THIS USB CABLE or you risk blowing up the 500mA power regulator on the driver board

If you are powering your pixel array with a seperate power supply, and have LOTS of pixels, you can remove/not use the BLACK USB Cable from the driver module. Your pixel array will backfeed the driver module via the JST plug. EG...

<img src="https://github.com/leonyuhanov/WOWPixelDriver/blob/master/pics/extpower.jpg" width="900" />

Setting up your pixel map

A template spreadsheet is provided here This doc will focus on a simple matrix, but I'm adding more complex examples into the file as we go

• The template is set up for a 17Px Wide X 15px Tall panel
• The pixels start at the top right and are connected in a zig-zag configuration(down, left, up, left, down, left etc....)
• The panel has 255 pixels in total
• The pixel map uses "-1" as an indicator of a NULL pixel. A NULL pixel is simply a space where a pixel doesn't exist. This becomes very obvious when your layout is complex
• The pixel map requires a buffer of these null pixels at the top, bottom, left and right sides of your pixel map. These buffer lines can be used as off-screen animation helpers
• Each cell inside your map MUST be filled in. A cell is either a physical address/order of a pixel or "-1" meaning a blank space or NULL pixel. If you have ANY cells that are empty, the driver will NOT boot
• You can reuse a pixel's physical address in multiple cells, but note that any pixel render meant for that location will be rendered to each location mapped to that address. I can not see any instance where this is useful, but it's definitely something you CAN do

<img src="https://github.com/leonyuhanov/WOWPixelDriver/blob/master/pics/pixelmap.jpg" width="900" />

The template spreadsheet concatenates each Column cell into a single C++ array representing that ROW. It then concatenates each ROW into a C++ array. Once done, COPY the text in the cell (marked in the above image as "Your Pixel Map array") this text is the full string you will need in the next section for the pixelMap array

Setting up the configuration code uploader utility

The uploader, located the Uploader.ino contains all the config variables you need to fill out and is responsible for writing this to the Driver modules SPIFFS. Open the file in the Arduino IDE and fill out the following:

• cols: Number of Columns (X range)
• rows: Number of Rows (Y range)
• numLeds: Number of Pixels in your layout
• bytesPerLed: Set to 3 for Neopixels/SK6812/WS2812 or 4 for APA102/SK9822
• maxSPIFrequency: The Default SPI Clock Frequency in (Mhz/1000000) for Driving Clocked Pixels (default is 10 which is 10Mhz). If you are using Neopixels leave this set to 10.
  • In reality your pixel layout may require a much lower drive speed. When starting out set this to 1(for 1Mhz) and ramp it up as you go
• controllerMAC: The MAC Address of the Controller Modules "WIFI_STA"
  • You will be provided with the MAC address
  • If you want to use your own ESP8266 module you will need to identify its WIFI_STA address. Use this code it will print the MAC address to the serial console and halt
• driverMAC: The MAC Address of the Driver modules "WIFI_STA"
  • You will be provided with the MAC address
• maskMap: The pixel map array you created in the template file, you can simply paste the text from the pixel map template

The Uploader code will look something like this for the example we will be working with:

//Number of Physical Pixels in your system
const short int numLeds = 255;
//bytesPerLed lets the system know if you are working with WS2812/SK6812 (3 Bytes) or APA102/SK9822 (4 Bytes) pixels 
const short int bytesPerLed = 4;
//rows =  is the total number of Rows(Y Axis) in your LED set up, this is usually the number of pixels TALL+2(1 NUll line at the top and bottom)
//cols =  is the total number of Columns(X Axis) in your LED set up, this is usually the number of pixels WIDE+2(1 NUll line at the LEFT and RIGHT)
const short int rows = 17, cols = 19;
//SPI Frequency for clocked Pixels
const short int maxSPIFrequency = 10;
//MAC Address of Controller modules "WIFI_STA"
const short int controllerMACAddress[6] = {0x00,0x00,0x00,0x00,0x00,0x00};
//This is the array you create in the template spreadsheet above
const short int maskMap[rows][cols] = {{-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1},
{-1,240,239,210,209,180,179,150,149,120,119,90,89,60,59,30,29,0,-1},
{-1,241,238,211,208,181,178,151,148,121,118,91,88,61,58,31,28,1,-1},
{-1,242,237,212,207,182,177,152,147,122,117,92,87,62,57,32,27,2,-1},
{-1,243,236,213,206,183,176,153,146,123,116,93,86,63,56,33,26,3,-1},
{-1,244,235,214,205,184,175,154,145,124,115,94,85,64,55,34,25,4,-1},
{-1,245,234,215,204,185,174,155,144,125,114,95,84,65,54,35,24,5,-1},
{-1,246,233,216,203,186,173,156,143,126,113,96,83,66,53,36,23,6,-1},
{-1,247,232,217,202,187,172,157,142,127,112,97,82,67,52,37,22,7,-1},
{-1,248,231,218,201,188,171,158,141,128,111,98,81,68,51,38,21,8,-1},
{-1,249,230,219,200,189,170,159,140,129,110,99,80,69,50,39,20,9,-1},
{-1,250,229,220,199,190,169,160,139,130,109,100,79,70,49,40,19,10,-1},
{-1,251,228,221,198,191,168,161,138,131,108,101,78,71,48,41,18,11,-1},
{-1,252,227,222,197,192,167,162,137,132,107,102,77,72,47,42,17,12,-1},
{-1,253,226,223,196,193,166,163,136,133,106,103,76,73,46,43,16,13,-1},
{-1,254,225,224,195,194,165,164,135,134,105,104,75,74,45,44,15,14,-1},
{-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1}};

Once you have filled out all the details, check that your IDE is set up for the correct module and settings. The most important things to set are:

• Bo