Trials and tribulations building and flashing ColorChord from scratch

In my efforts to create yet another improved version of my sound-response Light Suit, I elected to move to Charles Lohr’s excellent ColorChord project for sound analysis and LED driving. I wanted to add some functionality, though; mainly the ability to broadcast LED values as rapid UDP packets and some custom “modes” that didn’t involve sound (cycling rainbow, twinkle, all-on, etc). This meant tackling a task a bit more daunting than tweaking Arduino sketches – modifying and building the whole project, which is pure C code, not namby-pamby Arduino or LUA.

To document what I learned getting past some challenges for my own, increasingly poor, recollection, and for anyone else who wants to tackle this, I am writing this doc.

Since the directions are unix-oriented, I got a VirtualBox Ubuntu image to perform the build in. I used a version 16 build, but I don’t think the build is particularly sensitive to the version. I DID need to expand the root FS to 15GB and I allocated 2MB of RAM.

Create a work directory and change to it:

mkdir esp
cd esp

Clone the ColorChord repo, including the esp82xx subrepo:

git clone --recursive

Note: between October 2018 and now (Feb 2019), a bunch of changes to the esp82xx repo where merged in and seem to have resulted in this issue where setting the esp8266 to AP mode cause a crash loop. Hopefully the contributors will get that sorted out, but if you need AP mode now, you’ll have to figure out which versions of the main ColorChord repo and the esp82xx subrepo to pull in order to compile successfully and have AP mode working. 

Following cnlohr’s directions at

Create a shell script using the contents of This is a script that will download and install the Espressif SDK and all the toolchain components and dependencies, then builds it.

NOTE: I had to first run the script as root (sudo su -) since it installs additional Debian packages. I did this from a directory under root’s home dir, since it goes on to download a bunch of files which are later built, but the actual build fails if run as root. So I run it in the directory under root, it fails with “[ERROR] You must NOT be root to run crosstool-NG”. I then deleted that temp directory and exited root back to my own user. Then I ran the script again. Since all the dependent OS modules are not installed, it gets past those steps and goes on to download the SDK files (again), and run the build.

ALSO, the script installs version 1.5.2 of the Espressif SDK. This version tends to not provide enough available “iram” to build colorchord. I got error messages like “image.elf section `.text’ will not fit in region`iram1_0_seg'”. This is a known issue with SDK’s after 1.5.1. To build using 1.5.1, after getting the toolchain built using the above, next follow this process as described here:

Download the ESP8266 nonos sdk v1.5.1 from espressif & delete the sdk provided because the provided sdk is v2.0 and above:

rm sdk
wget --content-disposition ""

Finally, enter esp-open-sdk and link the sdk v1.5.x back.

cd esp-open-sdk/
ln -sf ./esp_iot_sdk_v1.5.1 sdk

I then modified the SDK_DEFAULT and SDK paths in   <colorchord_install_dir>/esp8266/user.cfg to point explicitly to the toolchain and SDK locations.

At this point, it should be ready for compiling ColorChord and flashing to your ESP.

“Attach” the USB serial port via the Virtualbox. To do this, you have to enable the USB driver and 2.0 support in the guest settings and install the driver in the guest. Then, you have to attach it once the guest is started via the little USB icon in the status bar at the bottom of the guest window. I also have to change permissions on the serial device every time I mount it since I am executing all the build stuff as myself, not as root.

sudo chmod 666 /dev/ttyUSB0

After that, you build and burn – but NOTE – I also needed the to run the “initdefault” make stage. Without it, I had an esp that just crashed on startup:

make all
make initdefault
make burn
make burnweb

After all that, you should have an esp that starts up, logs stuff to serial, and enters AP mode, at which point you should be able to connect to it via wifi, browse to and see the cool sh!t!

This entry was posted in ESP8266, Technical. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s