Yes! It Failed!

Model railroad time for the past couple of weeks has gone toward learning to program the ESP32 that will drive the water tower’s functions. I found a good YouTube tutorial from Dave’s Garage that helped me get started with the typical blinking LED and a little serial port output.

Then I found the stepper motor tutorial from the Freenove RFID starter kit that my son received for Christmas a couple of years ago. This worked fine with the motor that came with the kit. However, when I plucked the linear actuator out of its foil anti-static bag, I found there were only four wires, not five like the tutorial motor. Fortunately, the excellent explanation in the Freenove kit tutorial provided enough background that with only a little experimenting, I was able to actuate linearly. (Seriously, if you’re thinking of getting into Arduino or ESP32 programming, get one of these starter kits!)

So, with the back of the animation problem broken, it became a simple matter of programming – something I feel I should be able to do. The only trouble was the number of new things in my tool chain. PlatformIO and GoogleTest are brand new, and C++ is so rusty it kind of needs a complete replacement. I spent a solid week tearing my hair out over questions like “Why can’t it find the compiler?”, “Was that a compile error or a link error?”, “Why can’t it find that file?”, and “Why isn’t it running any of my tests?”

After two weeks, I was getting frustrated. So this afternoon, when I finally managed to get a failing test, I jumped out of my chair, pumping my fist as I shouted “Yes! It failed!” This startled and confused The Girl because failure isn’t something we normally celebrate. In Test Driven Development, however, a failing test is the first, most important step to progress.

Before I get stuck into programming fun, here are some things I learned, mostly to keep myself from losing more hair unnecessarily in the future:

1. You need to tell Platform IO which part of the platformio.ini file to pay attention to when you are building, deploying or testing. The file is broken into different sections for different target platforms. In my case, I am using platform=espressive32; board=esp32dev to deploy and platform=native; test_framework=googletest to test.
2. When deploying, you need to ensure the platform and board are correct, otherwise Platform IO shrieks unhelpfully: Failed to connect to Espressif device: No serial data received. This error stumped me for days, as I changed out different cables, ports and even boards while reading endless Stack Overflow postings.
3. On Linux, you need to make sure the user doing the deploying can read and write to the serial port. Every time I unplugged the board from the USB cable, it reset this port. Platform IO gives the same very unhelpful error message as if the platform and board are incorrect.
4. For the native platform, PlatformIO wants to use the native gcc compiler, which doesn’t exist on Windows. PlatformIO suggest you install MSYS2, but you need to follow all the installation instructions, including the pacman -S mingw-w64-ucrt-x86_64-gcc bit before you get an actual compiler.
5. Both header (.h) and implementation (.cc) files for dependencies of the main program go in the lib directory. This confused me for ages because I felt the .h file belonged in the include directory.
6. Don’t forget to press and hold the Boot button on the board while uploading. Apparently this isn’t required on every ESP32 Dev Board.
7. You can use esptool to get better error messages about the state of the board. For example, esptool -p COM4 read_flash 0 0x2000000 flashContents.bin will not only read the contents of the flash memory into the given file into flashContents.bin, but will also give a useful error message like Failed to connect to Espressif device: Download mode successfully detected, but getting no sync reply: The serial TX path seems to be down. (which caused me to disconnect from the UART TX and RX pins, and corrected the error)
8. You can also use esptool to get yourself into trouble and blow away the factory firmware including the bootloader! To get it back, start here.
9. To see what esptool command platformio runs to upload the firmware, copy the platformio command from the VSCode terminal and tack a --verbose or -v on the end.
10. Incredibly, increasing the baud rate might make it work! For example, esptool --chip esp32 --port COM4 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size 4MB 0x1000 C:/Users/User/src/pembroke87/waterTank/.pio/build/esp32dev/bootloader.bin 0x8000 C:/Users/User/src/pembroke87/waterTank/.pio/build/esp32dev/partitions.bin 0xe000 C:/Users/User/.platformio/packages/framework-arduinoespressif32/tools/partitions/boot_app0.bin 0x10000 .pio/build/esp32dev/firmware.bin worked, but the same at –baud 9600 resulted in ‘A fatal error occurred: Failed to connect to ESP32: No serial data received.’