Testing of NeoPixel libraries to do fire simulation with Fire2012 and ESP8266 using esp8266/Arduino.
Switch branches/tags
Nothing to show
Clone or download

readme.md

EspFire2012 Build Status

Testing of NeoPixel libraries to do fire simulation with Fire2012 and ESP8266 using esp8266/Arduino

EspFire2012 Demo

Introduction

Since I watched "Using I2S on the ESP8266 to drive WS2812Bs" by CNLohr (Charles Lohr) I have been looking for an opportunity to build an unconventional project to control NeoPixels with ESP8266.

In April 2016 I have noticed FastLED added to "Other libraries" of esp8266/Arduino. When checking what it can be used for, I found nice and realistic "Fire2012: fire simulation for Arduino and LEDs" by Mark Kriegsman. I rush looking for the code and got really impressed. The code was small, really well documented and contained couple of options to customize how the fire simulation will look like.

That is how Fire2012 became my first project using NeoPixels.

Initially FastLED library has not been working properly for me with Fire2012 and I ended up testing other libraries. I decided to document my findings and that is why I set up this repository.

Table of Contents

Requirements

This project is to implement Fire2012 application on ESP8266 with on-line set up of fire simulation parameters that meets the following requirements:

  • Implementation with WS2812B strip with 144 LEDs
  • Simulation at 60 frames/s
  • Accurate reproduction of fire colors
  • On-line set up of brightness, sparking and cooling
  • Implementation with Arduino IDE
  • Up time monitoring on Emoncms.org
  • Stable operation
  • Over the Air (OTA) application updates

Components

Software and hardware components that have been used to build this project.

Fire2012

The code of fire simulation has been released by Mark Kriegsman in his blog https://blog.kriegsman.org. It fascinated me with it's simplicity - the simulation itself is only about 25 or 30 lines of code. For more information please refer to the source code of this application - it contains very detailed in-line comments explaining all and every step of simulation.

There are two parameters to control fire simulation:

Cooling - how much does the air cool as it rises?

  • Less cooling = taller flames
  • More cooling = shorter flames

Sparking - what chance is there that a new spark will be lit?

  • Higher chance = more roaring fire
  • Lower chance = more flickery fire

There is also Brightness not directly used in simulation.

All above parameters are hard coded in Fire2012. I have decided to provide a simple web interface to set them up on-line and see instantly how they affect simulation.

Web interface to set up application parameters

Setting up such interface should be an easy task with ESP8266 module!

Hardware

To do the testing I have collected the following hardware:

  • Pixel strip WS2812B, 144 pixels/m. You can use other strips as well - to obtain good results select a strip with minimum 20 pixels and with minimum density of 60 pixels/m,
  • ESP8266 module - NodeMCU 1.0 (ESP-12E Module). I have selected this one to make my prototyping more convenient. It has USB / serial interface and power supply on board, so you do not need to provide them separately. You can use any other typical ESP8266 modules as well. One single pin GPIO3 (TXD0) is used for driving WS2812B and make sure it is broken out in your module.
  • Pixel strip power supply - Adjustable DC-DC power supply CN4015-3.1 together with AC-DC 12V power supply. You should be able to go away with a "wall wart" 5V DC power supply assuming it will match power consumption of your LED strip. To avoid potential issues with 3.3V logic of ESP8266, use an adjustable power supply and lover output voltage below 5V. For more details please check excellent guide "Powering NeoPixels" by Adafruit.
  • 1000uF/16V capacitor to improve quality of power supply to the pixel strip - see "Best Practices" by Adafruit.
  • 470 ohm resistor to separate ESP8266 and the pixel strip. For more details please check "Best Practices" by Adafruit.
  • Bread board and cables - see also "Basic Connections" by Adafruit.

Connection of NeoPixels to ESP8266 - schematic Connection of NeoPixels to ESP8266 - how it looks like

Schematic of connections in Fritzing format is available here.

Libraries

I have tested the following three libraries listed under "Other libraries (not included with the IDE)" of esp8266/Arduino:

  • NeoPixel - Adafruit's NeoPixel library, now with support for the ESP8266 (use version 1.0.2 or higher from Arduino's library manager).
  • NeoPixelBus - Arduino NeoPixel library compatible with ESP8266. Use the "DmaDriven" or "UartDriven" branches for ESP8266. Includes HSL color support and more.
  • FastLED - a library for easily & efficiently controlling a wide variety of LED chipsets, like the Neopixel (WS2812B), DotStar, LPD8806 and many more. Includes fading, gradient, color conversion functions.

Software

I have used the latest software versions available by the time of testing as follows:

The ESP8266 platform package and libraries ware installed from Arduino IDE except FastLED library that was installed from GitHub (ref #289 and #306).

EspFire2012

Application prepared for ESP8266 consists of the following files:

  1. Fire.ino together with Fire.h - fire simulation code that primarily contains original Fire2012 application.
  2. WebInterface.ino together with WebInterface.h - web interface shown on the picture above and Wi-Fi set up routines.
  3. Emoncms.ino together with Emoncms.h - routines to post data on Emoncms.org to monitor application up time, heap size and other parametrs if required. You need to set up an account on Emoncms.org to use it. This is quick and simple - please refer to my OnlineHumidifier repository that explains how to do it.
  4. EspFastLED.ino - a simple main sketch that integrates the above Fire, WebInterface and Emoncms.

EspFire2012 application has been tested with three previously described libraries for NeoPixel control. Respective application versions are available for your review in the following folders:

Within each application version the main sketch contains identical code:

In setup() the following functions are called once on module start up:

  setupWiFi(); // set up Wi-Fi to access web interface
  setupWebServer(); // set up web interface
  setupFire();  // set up library to operate NeoPixel strip and Fire2013 application

In loop() the following two functions are repeatedly called:

  server.handleClient();  // respond to commands from web browser
  logToEmoncms();  // Log aplication performance data to Emoncms.org
  keepFireAlive();  // simulate Fire2012

The main sketch file names have been changed to distinguish tested libraries.

The only important differences between application versions concern Fire.ino and Fire.h files. This is to accommodate calls to particular NeoPixel libraries. Details are described in separate chapters below and the rest of code in these files is identical for each version.

I will skip description of code to establish Wi-Fi access and setting up a web server. This code is very basic and identical for all versions of application. If you are new to EP8266 please check my other repository OnlineHumidifier that will walk you through ESP8266 basics.

EspAdafruit_NeoPixel

The lines specific to this library are contained in files Fire.ino and Fire.h.

  1. Include required in header file Fire.h:
#include <Adafruit_NeoPixel.h>
  1. Declaration before NeoPixel strip initialization in Fire.ino:
Adafruit_NeoPixel pixels = Adafruit_NeoPixel(NUM_LEDS, LED_PIN, NEO_GRB + NEO_KHZ800);
  1. Initialization of NeoPixel strip in function setupFire() :
  pixels.begin();
  1. Animation of NeoPixel strip in function keepFireAlive() :
  for (int i = 0; i < NUM_LEDS; i++)
  {
    pixels.setPixelColor(i, pixels.Color(leds[i].r, leds[i].g, leds[i].b));
  }
  pixels.setBrightness(brightness);
  pixels.show();

Complete code for this version of application is saved under EspAdafruit_NeoPixel.

EspNeoPixelBus

The lines specific to this library are contained in files Fire.ino and Fire.h.

  1. Include required in header file Fire.h:
#include <NeoPixelBus.h>
  1. Declaration before NeoPixel strip initialization in Fire.ino:
NeoPixelBus<NeoGrbFeature, Neo800KbpsMethod> strip(NUM_LEDS, LED_PIN);
  1. Initialization of NeoPixel strip in function setupFire() :
  strip.Begin();
  strip.Show();
  1. Animation of NeoPixel strip in function keepFireAlive() :
  RgbColor pixel;
  for(int i=0; i<NUM_LEDS; i++)
  {
    pixel = RgbColor(leds[i].r, leds[i].g, leds[i].b);
    pixel = RgbColor::LinearBlend(pixel, RgbColor(0, 0, 0), (255 - brightness)/255.0);
    strip.SetPixelColor(i, pixel);
  }
  strip.Show();

Complete code for this version of application is saved under EspNeoPixelBus.

EspFastLED

The lines specific to this library are contained in files Fire.ino and Fire.h.

  1. Defines and include required in header file Fire.h:
#define FASTLED_ESP8266_RAW_PIN_ORDER
#define FASTLED_ALLOW_INTERRUPTS 0
  1. Defines required before NeoPixel strip initialization in Fire.ino:
#define COLOR_ORDER GRB
#define CHIPSET     WS2812B
  1. Initialization of NeoPixel strip in function setupFire() :
  FastLED.addLeds<CHIPSET, LED_PIN, COLOR_ORDER>(leds, NUM_LEDS).setCorrection(TypicalLEDStrip);
  1. Animation of NeoPixel strip in function keepFireAlive() :
  FastLED.setBrightness(brightness);
  FastLED.show();

Complete code for this version of application is saved under EspFastLED.

Usage

Once you load the code to ESP8266, the application will report back on serial port as below:

Application reports back on terminal

After entering displayed IP address in a web browser it should reveal the following web interface:

Web interface to set up application parameters

Change of cooling, sparking or brightness should be immediately visible on the strip. How it looks in practice please check the following short (1 min 21 sec) videos:

Brightness Cooling Sparking
Brightness Control Cooling Control Sparking Control
https://youtu.be/ymsCrwRauSY https://youtu.be/tdtMMqTBR4E https://youtu.be/Tq5M-ZS9FgY

Testing

Each version of described above code has been loaded to ESP8266 module and tested. Results are documented in short (1 min 21 sec) video "Comparison of Libraries".

Comparison of Libraries

On left of video you can see selected fire simulation parameters, on right at the bottom - name of library. Particular comments are provided below.

Apart from functionality I have also compared size of flash and RAM code used by each version of application as provided by Arduino IDE.

Bytes Used EspAdafruit_NeoPixel EspNeoPixelBus EspFastLED
Flash 242,741 243,193 243,601
RAM 36,520 36,584 36,600

Results are in very similar range, but frankly saying I was expecting EspFastLED application to use the least Flash and RAM.

EspAdafruit_NeoPixel

This library worked for me out of the box.

It is worth mentioning that Adafruit has excellent and likely the most extensive NeoPixel Uberguide. It covers form factors, characteristics and selection of strip to meet your needs. It also provides detailed hardware and software guidelines on connecting and using the strips.

I believe this library is the easiest to start playing with NeoPixels.

EspNeoPixelBus

Library by Makuna (Michael Miller) also worked for me out of the box.

I cound not find a method to set brighness globally like in other libraries and had to do it individually for each pixel as below:

    pixel = RgbColor::LinearBlend(pixel, RgbColor(0, 0, 0), (255 - brightness)/255.0);

Adarfuit credited Michael Miller for ESP8266 work for the NeoPixelBus library in their esp8266.c file that is part of Adafruit_NeoPixel library.

EspFastLED

With first implementation of this library I have observed flicker towards end (top on the video) of the NeoPixel strip. This has been clarified by Daniel Garcia in reply to issue report #306.

The issue turned out to be very simple to resolve. Before #include <FastLED.h> the code should contain:

#define FASTLED_ALLOW_INTERRUPTS 0

Otherwise data transmission to the strip may be broken on random basis by interrupts. This depends on how many LEDs the NeoPixel strip has.

This library attracted me with detailed documentation, active community on Google+, several code examples and demos/effects.

Stability

As suggested by @TheAustrian I let the applications running for a longer time and noticed unexpected self-resets.

To identify the root cause of this issue, I have loaded each application version on a separate ESP module, added routines to post Up Time and free Heap Size on Emoncms.org and started checking the plots.

The cause of resets may be s/w, h/w or both. To eliminate h/w as the source of issue, I decided to move the s/w around using the same three modules in sequence below.

EspFire2012 Application Test 1 Test 2 Test 3
EspFastLED ESP A ESP C ESP B
EspNeoPixelBus ESP B ESP A ESP C
EspAdafruit_NeoPixel ESP C ESP B ESP A

Test started on 29-May-2015 at about 11:20 CET and ended on 2-Jun-2016 at 19:00 CET. Module changes were done on 30-May at 22.50 CET and on 1-Jun at 8:00 CET. Result is shown below:

EspFire2012 Stability Testing Plots

During test period I have recorded the following number of resets:

EspFire 2012 Application Number of Self Resets
EspFastLED 10
EspNeoPixelBus 0
EspAdafruit_NeoPixel 6

Each version of application was running on each one of the three ESP modules. There were no any self-resets of EspNeoPixelBus. Therefore with pretty high certainty I can eliminate h/w as the potential source of issues.

The next step is to troubleshoot the s/w. Please check this issue report for details. I will update this repository as well once I am done with testing

Credits

Software for this project has been prepared thanks to great work of the following teams and individuals:

Contribute

Feel free to contribute to the project in any way you like!

If you find any issues with code or descriptions please report them using Issues tab above.

Summary

This project is well advanced with the following results for each version of application so far. Results are updated as the project is progressing.

Application / Requirements EspAdafruit_NeoPixel EspNeoPixelBus EspFastLED
Implementation for WS2812B strip with 144 LEDs Passed Passed Passed
Simulation at 60 frames/s TBC TBC TBC
Accurate reproduction of fire colors Passed Passed Passed
On-line set up of brightness, sparking and cooling Passed Passed Passed
Implementation with Arduino IDE Passed Passed Passed
Up time monitoring on Emoncms.org Passed Passed Passed
Stable operation about 2 self-resets per 24h Passed about 3 self-resets per 24h
Over the Air (OTA) application updates TBC TBC TBC

Conclusion

When approaching this testing I was skeptical regarding performance of libraries like EspAdafruit_NeoPixel or FastLED. After all they have been prepared for other Arduino boards well before ESP8266 was even available.

Basing on tests so far, all libraries did it quite well. Simulation worked smoothly without any jams, no matter how often I have been accessing web page to update parameters.

Currently I am investigating an issue with self resets of EspFastLED and EspAdafruit_NeoPixel applications.

If you found this review interesting then stay tuned. I will provide an update on results of issue troubleshooting.

View of tube with Fire2012 simulation