Published September 25, 2018 © GPL3+

Xlights FSEQ Sequence Player

Example program using FastLED and my library for reading the header on FSEQ files generated by Xlights for displaying Xlights sequences.

IntermediateFull instructions provided1 hour12,122

Things used in this project

Hardware components

Espressif ESP32S

The example was developed using a Wemos Lolin32 Lite and a Wemos D1 R2 mini but any ESP32, ESP8266 or similar fast Arduino will work. The WiFi and Bluetooth were not used.

Espressif Wemos D1 Mini

The example was developed using a Wemos Lolin32 Lite and a Wemos D1 R2 mini but any ESP32, ESP8266 or similar fast Arduino will work. The WiFi and Bluetooth were not used.

MicroSD Module (Generic)

I've used both the Adafruit and Polulu breakout boards which both have the Card Detect (CD) pin used in the example.

NeoPixel strip

Any strip compatible with the FastLED library will work. The example was created using a generic 240 pixel strip of WS2812 pixels.

Delkin Commercial MLC microSD

Any MicroSD card will work. I used a SanDisk Ultra 16Gb in the example.

NeoPixel strip

You'll need a power supply for the lights you're using. I used a lab power supply for the demo set at 5VDC. With the 240 WS2812 pixels it was running between 5 to 6 Amps. Select the supply based on you lights voltage and current draw.

Story

Example program for the FSEQLib Arduino Library using an ESP32

Required Hardware

You're going to need a couple of things to get started as follows:

1 x ESP32 or an ESP8266 board. I used the Wemos Lolin32 Lite (ESP32) and a Wemos D1 R2 mini (ESP8266) but Arduino compatible boards will work as long as they are fast enough.
1 x microSD card reader. I've tested is with the [Adafruit MicroSD card breakout board] (https://www.adafruit.com/product/254) and the Polulu Breakout Board for MicroSD Card.
1 x microSD card
1 x LED light strip. The example uses a strip of WS2811/WS2812's but the Xlights FSEQ file jus supplies the colour values and is not specific to any lights.
1 x FSEQ file. The open source and free Xlights program generates these files when it saves sequences. The standard Arduino file does not support long filenames so you'll need to rename it into the 8.3 format. As an example, I renamed my file from single.fseq to show.dat.

Note: If you wish to play the FSEQ as in the example project you'll either need to save the FSEQ file in uncompressed format (V1 or V2 Uncompressed) or implement the decompression function in your code. The version settings for the sequences are set in [File][Preferences] on the Sequences tab as shown below.

The Code

Start by download the library and example code from GitHub (https://github.com/ShaunPrice/FSEQLib). If you download the GitHub repository as a zip file you can use the Arduino IDE to load the library as a zip file. The examples will appear in your Arduino Examples.

Install it using the Arduino Library manager and install it using the IDE ("Sketch" -> "Include Library" -> "Add.ZIP Library..."

Select the Zip file you just downloaded from GitHub.

Now the FSEQLib library is installed you can open the example application.

Don't forget to select your development board and the COM port for you development board.

For more information, see https://www.arduino.cc/en/Guide/Libraries

Next, check that you SPI pin's used to read the data from the SD card are correct. The SD Card VSPI PINS on the Wemos Lolin32 Lite (ESP32) card are as follows:

SCLK = 18
MISO = 19
MOSI = 23
SS = 5

The SD Card SPI PINS on the Wemos D1R2 mini (ESP8266) card are as follows:

SCLK = D5/GPIO 5
MISO = D6/GPIO 12
MOSI = D7/GPIO 13
SS   = D8/GPIO 15

If you're using the card detect pin you'll also need to define it. You may need a 10k pull-up resistor connected to this pin to make sure it goes high. The Card Detect (CD) pin gets pulled to ground when there's no card inserted but it will be floating if there's no pull-up resistor (resistor connected to positive).

The Card Detect (CD) pin is defined as follows in the example:

For the ESP8266:

#define CARD_DETECT_PIN  D2

For the ESP32:

#define CARD_DETECT_PIN  17

Check that you have the correct number of nodes/pixels per strip defined and if you're using universes in the example make sure they're also defined. The example uses only one universe (output) but can be configured to use more.

Finally, you'll also need to tell the FastLED,Adafruit Neopixel or other library which pin you're using and how many LED's/Nodes/Pixels are on that pin. I've used both the FastLED, Adafruit and sent the data via a second SPI interface to an FPGA. The example uses the FastLED libraries.

The Card Detect (CD) pin is defined as follows in the example:

For the ESP8266:

#define DATA_PIN_1 D1

For the ESP32:

#define DATA_PIN_1 13

You'll also need to configure your lights with the following defines:

Name of the FSEQ file to play:

#define FSEQ_FILE "/show.dat"

Universes aren't really defined here but I use the term to define the // number of times I want to split up the sequence step channels into.

#define UNIVERSES 1

Number of Nodes/Pixels. The example below is 240 pixels (4 meters of 60 per meter WS2812/Neopixel).

#define NUM_NODES 240

Compile the example code and upload it to the ESP8266 or ESP32.

Next, follow the Xlights process below to create you sequence file, rename it and copy it to the MicroSD card that you'll run on the ESP8266, ESP32 or other board.

If it's not working change the following line in the example to turn debug on as shown. Don;'t forge to recompile and upload again.

#define DEBUG 1 // 0=OFF, 1=Serial

You'll be able to see the FSEQ header and any error messages in you Serial terminal.

Don't forget to set debug off and recompile and upload when your finished.

#define DEBUG 0 // 0=OFF, 1=Serial

Xlights

Download Xlights from https://xlights.org/ and install it.

Set up the Xlights show directory or use the default. You'll need to know where this directory is located later.

Add a Null lighting network

Set the number of channels to three times the number of nodes or pixels. Three times because each node or pixel has three LED's (Red, Green and Blue) and each channel represents an LED.

Click on Save Setup to save the Lighting Network.

Go to the Layout tab and select the String icon as shown.

Draw the string then update the Nodes/String setting to the number of nodes or pixels your string has. The end channel will update to the correct number of channels for the number of nodes entered.

Next select the sequence tab and then create a new sequence by clicking the icon show.

In the dialogue box that displays click on Animation.

Select the frame rate you want or select custom. The video shown uses custom with a frame rate of 50fps (20mS). The higher the frame rate the smoother the display will be but you'll limit the number of pixels you can display. I had no issues with 240 on either the ESP32 or ESP8266.

On the next dialogue page click on Quick Start.

Your sequence is now ready to add effect to. A new line named single line is now available. Left click and drag the desired effect to it. I used the butterfly effect.

Left click the end of the line and drag it to the time you want it to end. You may also need to drag the start to the where you want it to start. You can use multiple effects one after the other of even overlay-ed on each other. Check out the Xlights tutorials linked to in the getting help section below to find out how.

Save your sequence. You can also clock on the Xlights play button (show below) to test them in the preview.

Now open the show folder you set at the start and you should have a file ending in .fseq. This is the file you need to copy to the MicroSD card and rename to the value you defined for the filename in the #define FSEQ_FILE shown below.

#define FSEQ_FILE "/show.dat"

Note that you need to rename the FSEQ file to the 8.3 format if you're not using a file system library that uses long file names (e.g. this_is_a_long_file_name.fseq could be renamed to short.fsq). The example uses the default FS library with doesn't support long file names.

Getting Help on LED lighting and Xlights

I recommend:

AusChristmas Lighting (https://auschristmaslighting.com/forums/)
Adafruit's The Magic of NeoPixels (https://learn.adafruit.com/adafruit-neopixel-uberguide/the-magic-of-neopixels)
Xlights/Nutcracker Wiki (http://www.nutcracker123.com/wk/index.php?title=Main_Page)

Additional Information

For Vixen users, the code does work with files exported from Vixen as FSEQ. The dummy nodes won't work as nothing gets exported other than the header. I found setting the controller to Generic Serial is the best option.
If you're a C++ programmer you might have noticed that the library has some compile time directives to see if it's being compiled for Arduino. That's because I also use the library in a Windows command line application for testing that's compiled with Visual Studio. The code for the Command Prompt executable is in the code section.

Code

/*
Name:		FSEQLib.cpp
Created:	9/18/2018 5:04:31 PM
Author:	Shaun Price
Contact:	Via Github website below
Copyright (C) 2018-2020 Shaun Price
Website:	https://github.com/ShaunPrice/FSEQLib

Version 2.0.0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

*/
/*
SD Card VSPI PINS (ESP32 - Wemos Lolin32 Lite)
==============================================
SCLK = 18
MISO = 19
MOSI = 23
SS = 5

SD Card SPI PINS (ESP8266 - Wemos D1 R2 mini)
==============================================
SCLK = D5/GPIO 14
MISO = D6/GPIO 12
MOSI = D7/GPIO 13
SS   = D8/GPIO 15

Also note Card Detect (CD) and Data Pin defines.
*/

#ifdef ESP8266
#include <SDFSFormatter.h>
#include <SDFS.h>
#endif
#include <SPI.h>
#include <SD.h>
#include <FastLED.h>
#include "FSEQLib.h"


#define DEBUG 0 // 0=OFF, 1=Serial

// Serial Debug Info
#if (DEBUG == 1)
#define SERIAL_BEGIN(x) Serial.begin(x)
#define DEBUG_PRINT(x) Serial.print(x)
#define DEBUG_PRINTLN(x) Serial.println(x)
#else
#define SERIAL_BEGIN
#define DEBUG_PRINT
#define DEBUG_PRINTLN
#endif

#ifdef ESP8266
// ESP8266
#define DATA_PIN_1 4			// Data pin for universe 1. // D2 - Wemos D1 R2 mini
#define CARD_DETECT_PIN  0		// May require 10k pull-up  // D3 - Wemos D1 R2 mini
#else
// ESP32
#define DATA_PIN_1 13			// Data pin for universe 1.
#define CARD_DETECT_PIN  17		// May require 10k pull-up
#endif

// This is where the second universe would go if using more than one universe
//#define DATA_PIN_2 14	// Data pin for universe 2. 

#define FSEQ_FILE "/show.dat"	// Name of the FSEQ file to play
#define UNIVERSES 1				// Universes aren't really defined here but I use the term to define the 
								//  number of times I want to split up the sequence step channels into.
#define NUM_NODES 150			// Nodes/Pixels
#define NUM_CHANNELS_PER_NODE 3 // Number of channels/LEDs per Node/Pixel
#define LEDS_PER_UNIVERSE NUM_NODES * NUM_CHANNELS_PER_NODE	// LEDs/channels per universe
#define BUFFER_LENGTH (UNIVERSES * LEDS_PER_UNIVERSE) + ((4 - (UNIVERSES * LEDS_PER_UNIVERSE) % 4) % 4) // Buffer is 32 bit (4 byte) padded.
// Adjust the brightness of the display
// For best results leave brightness at 255 (100%)
// and correct the brightness with Xlights.
#define BRIGHTNESS 255

size_t bytesRead = 0;

File dataFile;

// SPI
char stepBuffer[BUFFER_LENGTH];
CRGB leds[UNIVERSES][NUM_NODES];
//uint8_t universeBuffer[LEDS_PER_UNIVERSE]; // If using uint8_t buffer rather than CRGB buffer

uint32_t sequenceDelay = 50; // This will get set from the FSEQ header
int32_t currentStep = 0;
HeaderData rawHeader;
FSEQLib header;

bool cardInitialised = false;
bool cardDetected = false;

void setup()
{
	SERIAL_BEGIN(115200);

	pinMode(SS, OUTPUT); // SD Card VSPI SS
	pinMode(CARD_DETECT_PIN, INPUT_PULLUP); // SD Card Detected CD 

	FastLED.addLeds<NEOPIXEL, DATA_PIN_1>(leds[0], NUM_NODES);
	// The second universe would be:
	//FastLED.addLeds<NEOPIXEL, DATA_PIN_2>(leds[1], NUM_NODES);

	// Adjust the brightness of the display
	// For best results leave brightness at 255 (100%)
	// and correct the brightness with Xlights.
	FastLED.setBrightness(BRIGHTNESS);
}

void loop()
{
	unsigned long startMillis = millis();
	cardDetected = (digitalRead(CARD_DETECT_PIN) == 1) ? true : false;
	// Initialise SPI Master

	// See if the card is present and can be initialized:
	if (cardDetected && !cardInitialised)
	{
		DEBUG_PRINTLN("Initializing SD card...");
		//SDFS.setConfig(SDFSConfig(SS));

		if (SD.begin(SS))
		{
			DEBUG_PRINTLN("card initialized.");

			// Open the file.
			// Note that only one file can be open at a time,
			// so you have to close this one before opening another.
			// Also, this only supports 8.3 format so we need to 
			// rename the file from xxx.fseq to something else.
			dataFile = SD.open(FSEQ_FILE, "r");

			DEBUG_PRINTLN("File size: " + String(dataFile.size()));
			
			if (dataFile.size() > 0)
			{
				cardInitialised = true;
				
				dataFile.readBytes(rawHeader.rawData, 28);
				header = FSEQLib(rawHeader);

				// DEBUG code to print out the header details
				if (header.majorVersion() == 1)
				{
					DEBUG_PRINTLN( "======================");
					DEBUG_PRINTLN( "== Xlights FSEQ V1.0 Header");
					DEBUG_PRINTLN( "======================");
					DEBUG_PRINTLN( "Magic: " + String(header.magic()));
					DEBUG_PRINTLN( "Data Offset: " + String(header.dataOffset()));
					DEBUG_PRINTLN( "Version: " + String(header.majorVersion()) + "." + String(header.minorVersion()));
					DEBUG_PRINTLN( "Header Length: " + String(header.headerLength()));
					DEBUG_PRINTLN( "Channels per Step: " + String(header.channelsPerStep()));
					DEBUG_PRINTLN( "Number of Steps: " + String(header.sequenseSteps()));
					DEBUG_PRINTLN( "Step Time (ms): " + String(header.stepTime()));
					DEBUG_PRINTLN( "Universes: " + String((header.universes() == 0) ? 0 : header.universes()));
					DEBUG_PRINTLN( "Size of Universe: " + String((header.sizeofUniverses() == 0) ? 0 : header.sizeofUniverses()));
					DEBUG_PRINTLN( "Gamma: " + String(header.gamma()));
					DEBUG_PRINTLN( "Color Order: " + header.colorOrder());
					DEBUG_PRINTLN( "======================");
				}
				else
				{
					DEBUG_PRINTLN("======================");
					DEBUG_PRINTLN("== Xlights FSEQ V2.0 Header");
					DEBUG_PRINTLN("======================");
					DEBUG_PRINTLN( "Magic: " + header.magic());
					DEBUG_PRINTLN( "Data Offset: " + String(header.dataOffset()));
					DEBUG_PRINTLN( "Version: " + String(header.majorVersion()) + "." + String(header.minorVersion()));
					DEBUG_PRINTLN( "Header Length: " + String(header.headerLength()));
					DEBUG_PRINTLN( "Channels per Step: " + String(header.channelsPerStep()));
					DEBUG_PRINTLN( "Number of Steps: " + String(header.sequenseSteps()));
					DEBUG_PRINTLN( "Step Time (ms): " + String(header.stepTime()));					DEBUG_PRINTLN( "Compression Type: " + header.compressionTypeName());
					DEBUG_PRINTLN( "Compressed Blocks: " + String(header.compressedBlocks()));
					DEBUG_PRINTLN( "Sparse Ranges: " + String(header.sparseRanges()));
					DEBUG_PRINTLN( "UUID: " + String((char)header.uuid()));
					DEBUG_PRINTLN( "======================");
				}
				DEBUG_PRINTLN("done!");

				// Set the data offset
				dataFile.seek(header.dataOffset());
				sequenceDelay = header.stepTime();
			}
			else
			{
				cardInitialised = false;
				dataFile.close();
			}
		}
		else
		{
			DEBUG_PRINTLN("Card failed, or not present");
			delay(500);
		}
	}
	else if (!cardDetected && cardInitialised)
	{
		DEBUG_PRINTLN("Card removed");
		cardInitialised = false;
		dataFile.close();
	}
	else if (cardDetected && cardInitialised)
	{
		// Read the channels for the next step
		int datalen = dataFile.readBytes(stepBuffer, BUFFER_LENGTH);

		if (datalen != BUFFER_LENGTH)
		{
			DEBUG_PRINTLN("Buffer Failed to load. Closing File and SD card");
			cardInitialised = false;
			dataFile.close();
		}
		else
		{
			// Output data
			for (uint8_t current_universe = 0; current_universe < UNIVERSES; current_universe++)
			{
				// Copy the led values into the universe buffer
				memcpy(&leds[current_universe], &stepBuffer[current_universe * LEDS_PER_UNIVERSE], LEDS_PER_UNIVERSE);
				//memcpy(&universeBuffer[0], &stepBuffer[current_universe * LEDS_PER_UNIVERSE], LEDS_PER_UNIVERSE); // If using uint8_t buffer rather than CRGB buffer

				// Send the data
				FastLED.show();
			}

			currentStep++;

			// Reset to first step if we have gone past the last step
			if (currentStep == header.sizeofUniverses())
			{
				// Restart at first step
				currentStep = 0;
				// Restart file after header 
				//Corrected offset starting point or it will overlap with multiple universes
				dataFile.seek(header.dataOffset());
			}
		}
	}
	// Delay to make sure we send the number of times specified per second.
	// The delay is constrained between 1ms and 50ms
	delay(constrain(sequenceDelay - (millis() - startMillis), 1, 50));
}

/*
Name:		FSEQLib Windows application example
Created:	9/18/2018 5:04:31 PM
Author:		Shaun Price
Contact:	Via Github website below
Copyright (C) 2018-2020 Shaun Price
Website:	https://github.com/ShaunPrice/FSEQLib

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

*/
// FSEQReader.cpp : Defines the entry point for the console application.
//
#include "stdint.h"
#include <iostream>
#include <fstream>
#include <string>
#include "FSEQLib.h"


HeaderData rawHeader;
FSEQLib header;

int main(int argc, const char* argv[])
{
	std::string filename = argv[1];
	std::cout << "Reading FSEQ file: " << filename << std::endl << std::endl;
	std::ifstream fseqFile;
	fseqFile.open(filename, std::ifstream::binary);
	fseqFile.read((char*)&rawHeader.rawData, 28);
	fseqFile.close();

	header = FSEQLib(rawHeader);

	if (header.majorVersion() == 1)
	{
		std::cout << "======================\n";
		std::cout << "== Xlights FSEQ V1.0 Header\n";
		std::cout << "======================\n";
		std::cout << "Magic: " + header.magic() + "\n";
		std::cout << "Data Offset: " << header.dataOffset() << "\n";
		std::cout << "Version: " << (int)header.majorVersion() << "." << std::to_string((int)header.minorVersion()) + "\n";
		std::cout << "Header Length: " << (int)header.headerLength() << "\n";
		std::cout << "Channels per Step: " << (int)header.channelsPerStep() << "\n";
		std::cout << "Number of Steps: " << (int)header.sequenseSteps() << "\n";
		std::cout << "Step Time (ms): " << (int)header.stepTime() << "\n";
		std::cout << "Universes: " << (int)((header.universes() == 0) ? 0 : header.universes()) << "\n";
		std::cout << "Size of Universe: " << (int)((header.sizeofUniverses() == 0) ? 0 : header.sizeofUniverses()) << "\n";
		std::cout << "Gamma: " << (int)header.gamma() << "\n";
		std::cout << "Color Order: " << header.colorOrder() << "\n";
		std::cout << "======================\n";
	}
	else if (header.majorVersion() == 2)
	{
		std::cout << "======================\n";
		std::cout << "== Xlights FSEQ V2.x Header\n";
		std::cout << "======================\n";
		std::cout << "Magic: " + header.magic() + "\n";
		std::cout << "Data Offset: " << (int)header.dataOffset() << "\n";
		std::cout << "Version: " << (int)header.majorVersion() << "." << std::to_string((int)header.minorVersion()) + "\n";
		std::cout << "Header Length: " << (int)header.headerLength() << "\n";
		std::cout << "Channels per Step: " << (int)header.channelsPerStep() << "\n";
		std::cout << "Number of Steps: " << (int)header.sequenseSteps() << "\n";
		std::cout << "Step Time (ms): " << (int)header.stepTime() << "\n";
		std::cout << "Compression Type: " << header.compressionTypeName() << "\n";
		std::cout << "Compressed Blocks: " << (int)header.compressedBlocks() << "\n";
		std::cout << "Sparse Ranges: " << (int)header.sparseRanges() << "\n";
		std::cout << "UUID: " << header.uuid() << "\n";
		std::cout << "======================\n";
	}
	else
	{
		std::cout << "No file to parse" << std::endl;
		std::cout << "Press ENTER to exit" << std::endl;
		std::cin.get();
	}
	return 0;
}

Credits

Shaun Price

1 project • 5 followers

Consultant and hacker with a 30+ year career covering industrial control and robotics, cyber security, software development and management.

Xlights FSEQ Sequence Player

Things used in this project

Hardware components

Story

Required Hardware

The Code

Xlights

Getting Help on LED lighting and Xlights

Additional Information

Schematics

Fritzing Wiring Diagram for ESP8266

Fritzing Wiring Diagram for ESP32

FSEQLib Example Program Schematic

Code

FSEQLib Example Program

C++ Windows Console Application

FSEQLib

Credits

Shaun Price

Comments

Embed the widget on your own site

Xlights FSEQ Sequence Player

Xlights FSEQ Sequence Player

Things used in this project

Hardware components

Story

Required Hardware

The Code

Xlights

Getting Help on LED lighting and Xlights

Additional Information

Schematics

Fritzing Wiring Diagram for ESP8266

Fritzing Wiring Diagram for ESP32

FSEQLib Example Program Schematic

Code

FSEQLib Example Program

C++ Windows Console Application

FSEQLib

Credits

Shaun Price

Comments

Related channels and tags