What’s New, ESP-32? Testing the Arduino Library

In case you missed it, the big news is that a minimal Arduino core is up and working on the ESP32. There’s still lots left to do, but the core functionality — GPIO, UART, SPI, I2C, and WiFi — are all up and ready to be tested out. Installing the library is as easy as checking out the code from GitHub into your Arduino install, so that’s exactly what I did.

I then spent a couple days playing around with it. It’s a work in progress, but it’s getting to the point of being useful, and the codebase itself contains some hidden gems. Come on along and take a sneak peek.

The Core

arduino_logo_pantoneAn Arduino isn’t worth very much unless it can talk to the outside world, and making the familiar Arduino commands work with the ESP32’s peripheral hardware is the job of the core firmware. As of this writing, GPIO, WiFi, SPI and I2C were ready to test out. GPIO means basically digitalWrite() and digitalRead() and there’s not much to say — they work. WiFi is very similar to the ESP8266 version, and aside from getting the ESP32 onto our home WiFi network, I didn’t push it hard yet. When other libraries come online that use WiFi, I’ll give it a second look.

SPI

The SPI routines in the ESP32 Arduino port both work just fine. I tested it out by connecting a 25LC256 SPI EEPROM to the chip. The ESP’s extremely flexible hardware peripheral routing matrix allows it to assign the SPI functions to any pins, but the Arduino implementation is preset to a default pinout, so you just need to look it up, and hook up MOSI to MOSI and so on. As of now, it only uses one of the ESP32’s two free SPI units.

With SPI, some of the weirdness of using Arduino on a powerful chip like the ESP32 start to poke through. To set the speed of the SPI peripheral, you can use the familiar SPI_CLOCK_DIV_XX macros, only they’re scaled up to match the ESP32’s faster CPU clock speed. The end result is that SPI_CLOCK_DIV_16 gives you a 1 MHz SPI bus on either the 16 MHz Uno or the 240 MHz ESP32, which is probably what you want for compatibility with old code. But 240 divided by 16 is not 1. In retrospect, the macros would be better defined in terms of the desired frequency rather than the division factor, but you can’t go back in time.

There were also two extra definitions that I had to add to the program to make it run, but they’ve both been streamlined into the mainline in the last eighteen hours. That’s the deal with quickly evolving, openly developed software. One day you write that the macro MSBFIRST isn’t defined, and before you can go to press, it’s defined right there in Arduino.h. Great stuff!

I2C: The Wire

esp32_pinmapThe I2C (“Wire”) library has also gotten the ESP32 treatment, and worked just as it should with an LM75 temperature sensor. This is my standard I2C test device, because it lets you read a few registers by default, but you can also send the sensor a few configuration options and read them back out. It’s not a particularly demanding device, but when it works you know the basics are working. And it did.

The ESP’s dedicated I2C pins are on GPIO 21 and 22 for data and clock respectively. Some I2C implementations will use the microcontroller’s pullup resistors to pull the I2C bus lines high, so I tested that out by pulling the 10 KOhm resistors out. The ESP stopped getting data back instantly, so that answers that. Don’t forget your pullup resistors on the I2C lines and all is well. Otherwise, it’s just connecting up two wires, double-checking the I2C device address, and reading in the data. That was easy.

External Libraries

More than half of the reason to use Arduino is the wide range of external, add-on libraries that make interfacing with all sorts of hardware easy and painless. Many of these libraries are built strictly on top of the Arduino core, and should “just work”. Of course, when you’re actually coding this close to the hardware, nothing is going to be as portable as it is a few layers of abstraction higher up on your desktop computer. Let’s go test this hypothesis out.

El Cheapo IL9341 TFT Display

Mocking Arduino
Uno Lauging at ESP32

Since the SPI library works out of the box, the other various libraries that depend on it should as well, right? Well, kinda. I wasted an afternoon, and still failed. Why? I have a cheapo ILI9341 screen that only works with an old TFTLCD library, rather than with the nice Adafruit_ILI9341 libs. The former is so full of AVR-specific voodoo that it completely fails to compile, and is probably easier to re-write from scratch for the ESP32 than make work in its present form. The Adafruit library compiles fine, because it only depends on the SPI library, but it doesn’t work with my lousy screen.

Going repeatedly back and forth between these two libraries, my LCD experiment ended in tears and frustration: I couldn’t make either of them work. I scoped out the SPI data on a logic analyser, and it looked good, but it wasn’t drawing on the screen. At this point, a full line-by-line protocol analysis would have been needed, and that’s a few days worth of work. If I just wanted a running ILI9341 driver, I would go grab [Sprite_tm]’s NES emulator demo and use the one there, but it’s not Arduinified yet, so it’s out of bounds for the scope of this article.

DHT22 Humidity and Temperature Sensor

dscf8971
The Way It Should Work: Three Wires and Ten Lines of Code

Seeking a quick-and-dirty success, and beaten down by hours of hacking away for naught, I pulled a DHT22 sensor out of the eBay bin, and cloned Adafruit’s DHT library. Of course it didn’t compile straight out of the box, but there were only a couple of things that were wrong, and both turned out to be easily fixable.

ESP32’s Arduino didn’t have a microsecondsToClockCycles() function yet so I commented it out, multiplied by 240 MHz, and left a hard-coded constant in my code. This value was just used for a timeout anyway, so I wasn’t too worried. There are also some timing-critical code sections during which the Adafruit code uses an InterruptLock() function to globally enable and disable interrupts, but these functions weren’t yet implemented, so I just commented it all out and crossed my fingers.

After reassigning the data pin to one of the ESP32’s free ones (GPIO 27, FWIW), it compiled, uploaded, and ran just fine. I now know exactly how hot and humid it is up here in my office, but moreover have had a quick success with an Arduino external library, and my faith is restored.

Lessons from the Libraries

I suspect that these two examples are going to be representative of the ESP32-Arduino experience for a little while. Oddball hardware is going to take some time to get supported. Highly optimized libraries with cycle-correct timings or other microcontroller-architecture specific code in them will need to be ported over as well, despite being “Arduino” code. If you’re a code consumer, you’ll just have to wait while the wizards work their behind-the-scenes magic.

But there will also be a broad group of libraries that are written in a more-or-less device-independent way, and these should be easy enough to get working within fifteen minutes or so, as with the DHT sensor library. If you’re willing to compile, read the errors, and comment out or fix whatever shows up, some codebases will work in short order.

What’s Next? Turning Servos

Given that the Arduino-ESP32 port is brand new, indeed it’s still in progress, there is a lot of work for the community to do in getting it up to speed. Suppose that you need to drive a lot of servos, but the “Servo” library isn’t implemented yet. You’re an impatient coder. What to do? Get hacking!

The good news is that the Arduino-ESP32 libraries themselves are full of hints and examples for getting started. Open up the ESP32-specific directory that you cloned from GitHub. The usual *.cpp files provide the standard Arduino core functionality. The esp32-hal-xxx.h and esp32-hal-xxx.c files are chip-specific, and a tremendous help in taking advantage of the chip’s stranger options. For instance, esp32-hal-matrix.* gives you nice and easy access to the pin-routing matrix, which is a daunting task if you’re starting just from the datasheet.

scope_23
Spot-On and Jitter-Free

But let’s get back to servos. The ESP32 chip has an intriguing hardware LED PWM peripheral that lets you assign up to sixteen channels to individual LEDS, specify the PWM frequency and bit-depth, and then control them by appropriately setting bits in hardware registers. If you think this would be hard to do by hand, you’d be right. The esp32-hal-ledc.* files provide helper functions to set up the hardware PWM generator, and with these libraries, getting a 16-bit LED fade in straight C or “Arduino” is easy. But our sights are set on servos.

To drive a hobby servo, one needs pulses between 1,000 and 2,000 microseconds each, repeated every twenty milliseconds or so. Setting the repetition rate to 50 Hz takes care of the first part, and each count is 20 ms / 65,635 ticks long, or roughly 0.3 microseconds. Setting the PWM width value to something between 3,300 and 6,500 generates pulses in the right ballpark, and my servo ran jitter-free (and a clean signal was confirmed on the oscilloscope). Here’s all it took:

#include "esp32-hal-ledc.h"
void setup() {
   ledcSetup(1, 50, 16); // channel 1, 50 Hz, 16-bit depth
   ledcAttachPin(22, 1);   // GPIO 22 on channel 1
}

void loop() {
   for (int i=3300 ; i < 6500 ; i=i+100){
    ledcWrite(1, i);       // sweep the servo
    delay(100);
   }
}

That wasn’t so hard, was it? It’s not “Arduino”-style — there’s no objects or classes or methods anywhere in sight — but thanks to a straightforward and well-written hardware abstraction layer, using the very complicated peripherals is made pretty simple. Kudos to [me-no-dev] for his work on the back-end here. The HAL inside the Arduino libraries is currently the best source of code examples on many of the chip’s more esoteric and interesting peripherals.

Conclusion?

The short version of my dive into Arduino-esp32 is that there’s a lot here, even though it’s not done yet. Blinking LEDs and other simple GPIO is a given, and the core communication libraries that are already implemented worked for me: GPIO, WiFi, SPI, and I2C are up and running.

Non-core libraries are hit and miss. I suspect that a lot of them will work with just a little bit of tweaking. Others, especially those that are architecture-dependent, may not be worth the effort to port and will need to be re-written. The ESP32 has a bunch of interesting and innovative hardware peripherals onboard and there’s certainly no Arduino libraries written for them yet, but there’s some great HAL code hidden away in the Arduino-ESP32 codebase that’ll give you a head start. We could get lost in there for hours. Time to get hacking!

The ESP32 is still a new chip, but orders should be coming in soon. Have one? Want to see us put other libraries or languages through their paces? Let us know in the comments.

25 thoughts on “What’s New, ESP-32? Testing the Arduino Library

  1. First offers for complete development boards have been put on ebay on Sunday. Problem: they ship in the end of November and cost 25$. I guess the price will fall linearly in the next few months until they reach 5$.

    1. Both Adafruit & Sparkfun now have ESP32 dev boards for under $20. Of course, they’re normally out of stock but if you get on the notification list you can usually get one within a week or two.

      1. I just tried this library on ESP32 Arduino core but it does not yet work, there are allot of missing .h files
        #include
        #include
        #include
        #include

        And the “yield()” command is not in the ESP32 core

        1. My includes were taken out because of the greater than and less than brackets which are around the .h files to signify global includes.
          #include ets_sys.h
          #include osapi.h
          #include os_type.h
          #include gpio.h

  2. One of the things that intrigues me most about the ESP32 is the dual micros. I haven’t had a chance to play with mine yet. Anyone know what the plan is in regards to being able to program each of these via Arduino? Maybe that would make a nice part 2 article.

    1. In ESP32 Arduino core we run the “sketch” (setup and loop and everything they call) on CPU1, while the WiFi stack is running on CPU0. This allows messing with interrupts at will, and running more or less timing critical code. No more yield, yay! Interrupts attached through Arduino APIs also run on CPU1.

      If you want to run something on CPU0 from Arduino, you have to use FreeRTOS function to start a new task, with task affinity set to CPU0. That’s it! Then use some FreeRTOS synchronization primitives to communicate with the new task.

  3. “The end result is that SPI_CLOCK_DIV_16 gives you a 1 MHz SPI bus on either the 16 MHz Uno or the 240 MHz ESP32, which is probably what you want for compatibility with old code. But 240 divided by 16 is not 1. In retrospect, the macros would be better defined in terms of the desired frequency rather than the division factor, but you can’t go back in time.”

    Soo… what’s wrong with #define SPI_CLOCK_1_MHZ SPI_CLOCK_DIV_16? Just phase out the division factor over time.

    1. Already done with SPISettings and transactions. In fact, Hackaday covered the early develop of the SPI transactions a couple years ago. (full disclosure: I’m the primary developer of the transaction stuff, and Matthijs added the SPISettings syntax). Here is Arduino’s official documentation:

      https://www.arduino.cc/en/Reference/SPISettings

      Here’s their documentation of the old SPI.setClockDivider() function:

      https://www.arduino.cc/en/Reference/SPISetClockDivider

      Notice it says “This function should not be used in new projects”. Already a good portion of all the widely used Arduino libraries are using transactions and SPISettings, because it allows compatibility with any hardware rather than coding AVR hardware dependency. It’s unfortunate Elliot didn’t know about this when writing this article.

      Also, looking at the ESP32’s SPI library, it seems they have implemented SPISettings. However, their SPI.beginTransaction() function doesn’t do any interrupt or mutex locking.

  4. “In retrospect, the macros would be better defined in terms of the desired frequency rather than the division factor, but you can’t go back in time.” — Or, you could just use SPI.setFrequency() to set the frequency you want, instead of messing with divisors?

    1. Not at all. While we have a camera interface in the ESP32, video streaming has never been one of the applications we were aiming at. This is a very saturated market, and one needs hardware video encoder on chip to compete.
      That said, I have tried running a JPEG encoder on ESP32, and got about 20 fps at 320×240 when compiling with -Os. I suppose at least DCT can be optimized.

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s