OSX ESPixel Stick Firmware Uploading

The ESPixelStick package provides a ZIP file which includes a Java tool, ESPSFlashTool.jar, which is meant to handle programming the initial configuration (WiFi network details, etc.) and flashing the whole package to the Wemos D1 Mini.

Without using one of the following methods, there will be some security hoops to jump through and java may need to be installed

Catalina (OSX 10.15) and Big Sur (OSX 11) now include the CH340 chip drivers that are used by a number of Arduino compatible boards, including the provided Wemos D1 mini, to provide USB connectivity, there is no need to install any driver packages, and we can just proceed with the upload.

If you are minimally proficient in using the command-line, you can flash the device with no additional tools.

Java GUI Method

Background

To use the GUI without getting multiple security warnings, you will need to remove the quarantine file attribute from the zip file before it is extracted. This gets added automatically when downloaded from the web browser. You can read more about them at this article from Eclectic Light Company

The gist is:

Open a command line prompt Change to the directory where the download is Run xattr to remove quarantine attribute Extract the files Plugin the D1 board, after removing it from the ESPixel Stick board, using a micro USB cable Run the flash tool

Steps

The below assumes the download is saved in the default Downloads directory and beta4 was used.

Open Terminal (You can press ''Command-Space'' and type ''Terminal'' as a quick shortcut, versus navigating to the app under Utilities).

From the command line, perform the following

> cd Downloads
> xattr -d com.apple.quarantine ESPixelStick_Firmware-4.0-beta4.zip

Using Finder, extract the zip file.
Run ESPSFlashTool.jar by double clicking on it.
Click the Serial Port dropdown and pick: cu.usbserial-14410 - USB Serial
Click the Upload button
Done!

Possible Issues

• Not all USB cables have the data lines, as they are used only for simple chargers. Swap the cable out if the flash tool doesn't list the correct USB serial port.
• If the board is plugged in after starting the flash tool, the correct serial port won't be listed in the drop down. Any selection that mentions bluetooth is incorrect.
• The serial port may have a number different than 14410, which is fine.

Command Line Method

Preparation

You will need to modify spiffs/config.json (not covered here), open Terminal and change to the directory where the extracted files are.

❯ cd Downloads/ESPixelStick_Firmware-3.2/

Permit the executables

Apple, by default, prevents unknown (downloaded command-line applications that are not signed) applications from running. So we have to permit mkspiffs to run.

Use xattr to remove the quarantine flag on mkspiffs and then add the execute permission.

For this process, you will need to enter your user account password.

❯ sudo xattr -d com.apple.quarantine ./bin/macos/esp8266/mkspiffs
Password:
❯ chmod +x ./bin/macos/esp8266/mkspiffs

Build the filesystem

Now that mkspiffs can run, we can use it to build our filesystem which includes our previously modified config.json and the webpages to configure the device.

❯ ./bin/macos/esp8266/mkspiffs -c spiffs/ -p 256 -b 4096 -s 131072 firmware/spiffs.bin
/config.json
/www/esps.css.gz
/www/esps.js.gz
/www/index.html.gz

Upload the firmware

This will write your newly created spiffs filesystem along with the official firmware to your device.

On Catalina (10.15), your device will most likely be on /dev/cu.usbserial-1410. On Big Sur (11), your Arduino device should be on /dev/tty.usbserial-1410.

❯ python bin/esptool/esptool.py -p /dev/tty.usbserial-1410 write_flash \
    0x000000 firmware/pixel-3.2-1m_128k.bin \
    0xDB000 firmware/spiffs.bin

esptool.py v2.8
Serial port /dev/tty.usbserial-1410
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...

That's it, there's no step 3!

Troubleshooting

If your upload fails, it is possible that your device is on a different port. That is ok, after plugging it in, you can find it easily.

❯ ls /dev/*usb*
/dev/tty.usbserial-1420