As part of the mission to build out some hardware for sound & light shows at Halloween (yes, I know it is only a few days away; my kids keep reminding me), and Christmas, I picked up an ESPixelStick from Amazon. These come fully assembled, but unprogrammed. How hard can that be I thought?

I will comment that it would have been nice to have some documentation, or at least a pointer to an up to date website in the bag with the board…

Version 3 Hardware

First discovery, the Forkineye website describes the version 2 hardware, but I can find no mention of the version 3 hardware that I was sent, and visually at least they are very different. Also, version 3 does not require a separate USB to serial dongle.

Problem 1: The micro-USB port is on the side of the top board that faces the fuse and green connector. There is no space there to insert any of the micro-USB cables I had.

Solution 1: Remove the module from the carrier board; you can program it without the lower board, and power it from the micro-USB as well.

Problem 2: How to program the board with the firmware (downloaded from the project’s GitHub page). The ZIP file includes a Java tool, ESPSFlashTool.jar, which is meant to handle programming the initial configuration (WiFi network details etc) and flashing the whole thing to the board. For me, even after jumping through all the security hoops MacOS Catalina throws up when running this, the tool failed to work.

Solution 2: The solution is to build the required configuration image manually and then use the Python based esptool.py to flash the image on the board. Here’s the steps:

Unzip the firmware bundle and locate the spiffs/config.json file. Edit this in your favorite text editor and set the following values: ssid, passphrase and hostname under network, and the id under device. I just added a serial number (01) to the end of the device ID. Then type the following command from the top of the unpacked firmware bundle:

bin/osx/mkspiffs -c spiffs/ -p 256 -b 4096 -s 131072 firmware/spiffs.bin

You may have to open System Preference and go to the Security & Privacy area to allow the mkspiffs command to run the first time.

That should get you a firmware/spiffs.bin file. Now you are set to program the flash using the Python tool instead of the Java one that came with the bundle. The command for that is:

esptool.py -p /dev/cu.usbserial-14340 write_flash \
    0x000000 firmware/pixel-3.1-1m_128k.bin \
    0xDB000 firmware/spiffs.bin

If you don’t have esptool.py, install it using pip3 install esptool (you may need to be root for that to work). If the programming goes well, you should see something like this in the terminal window:

esptool.py v2.8
Serial port /dev/cu.usbserial-14340
Connecting....
Detecting chip type... ESP8266
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 8c:aa:b5:1b:91:84
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0340
Compressed 445040 bytes to 312111...
Wrote 445040 bytes (312111 compressed) at 0x00000000 in 30.2 seconds (effective 117.7 kbit/s)...
Hash of data verified.
Compressed 131072 bytes to 60612...
Wrote 131072 bytes (60612 compressed) at 0x000db000 in 5.9 seconds (effective 178.7 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...

The device should reset at the end and join your WiFi network. After that, find its IP address and connect using the browser to do further configuration.