Programming the ESP8266 on an M1 Mac

Feb 16 2021 2:30 PM

Programming microcontrollers is something I’ve always liked to do, there’s something very satisfying about writing code that controls things in “real life”, instead of just pixels on a screen. Recently, I decided it would be a fun side project to turn a cheap air humidifier into a HomeKit accessory. I started out with an Arduino board to test things out, but then people reminded me of the ESP32 and ESP8266 microcontrollers, which integrate BLE and WiFi and can run the HomeKit Accessory Protocol (HAP) natively.

To make things easier for me, I decided to program my boards with the Arduino Pro IDE, which I’m already familiar with, so I had to install the libraries for the ESP8266. That’s where I hit a problem, because I’ve been using the new M1 MacBook Air as my work computer for a while, but unfortunately the ESP support for the Arduino IDE doesn’t work out of the box. It wasn’t hard to figure out a workaround, so I decided to write it here both as a future reference for myself as well as a helpful resource for others.

Obligatory disclaimer: this is not a tutorial. I’m just laying out the steps that worked for me, but I am by no means an expert on the subject, so if this doesn’t work for you, it’s very unlikely that I’ll be able to help you out any further.

The first step is to install HomeBrew, if you don’t have it yet. HomeBrew has recently been updated with support for M1 Macs.

Then, use HomeBrew to install Python 3, which is required by the scripts in the ESP support for the Arduino IDE:

brew install python3

Use pip3 from the new python3 that’s just been installed to install the pyserial library:

pip3 install pyserial

Make sure you have added the ESP8266 URL to “additional boards manager URLs” in the Arduino IDE settings (this works for both the Arduino Pro IDE as well as the regular one):

https://arduino.esp8266.com/stable/package_esp8266com_index.json

After installing the ESP8266 boards, if you try to upload your sketch to a board, you’re likely going to run into an error:

pyserial or esptool directories not found next to this upload.py tool.
Upload error: Error: 2 UNKNOWN: uploading error: uploading error: exit status 1

For some reason, the upload tool included with the ESP8266 package seems to include its own version of Python, which for some other reason doesn’t really work in my particular environment. But since I have installed Python 3 using HomeBrew, I can tweak the package to use that version instead.

To do that, open ~/Library/Arduino15/packages/esp8266/hardware/esp8266/2.7.4/platform.txt in a text editor, then replace all occurrences of {runtime.tools.python3.path} with the path to your own Python install, in the case of HomeBrew on M1, it would be /opt/homebrew/bin. Restart the Arduino IDE and everything should work fine now.

I don’t feel particularly good about this, it seems that I should instead be replacing whatever is setting runtime.tools.python3.path to point to my own version of Python instead, but I don’t have enough knowledge about how the environment works in the Arduino IDE, and being able to flash my projects to the board was more important than learning that.

If you happen to know of a better solution, feel free to reach out on Twitter.