Adafruit ESP32 User Manual

Adafruit AirLift - ESP32 WiFi Co-Processor Breakout

Created by Kattni Rembor

Last updated on 2021-03-29 01:04:48 PM EDT

2 4 7 7 8 8 9

10 11 11

13

13 13 15 15 15 19

21 22 23

24 27 27

27

27 27 28 28 29 33 33 33 34 35 36 37 38 39 39

40

41 43

44

Guide Contents

Guide Contents Overview Pinouts Power Pins SPI & Control Pins LEDs Assembly

Prepare the header strip: Add the breakout board: And Solder!

CircuitPython WiFi

CircuitPython Microcontroller Pinout

CircuitPython Installation of ESP32SPI Library CircuitPython Usage Internet Connect! What's a secrets file? Connect to WiFi Requests

HTTP GET with Requests HTTP POST with Requests Advanced Requests Usage

WiFi Manager CircuitPython BLE CircuitPython BLE UART Example

Adafruit AirLift ESP32 Breakout Wiring

Update the AirLift Firmware Install CircuitPython Libraries Install the Adafruit Bluefruit LE Connect App Copy and Adjust the Example Program Talk to the AirLift via the Bluefruit LE Connect App Arduino WiFi Arduino Wiring Library Install First Test WiFi Connection Test Secure Connection Example JSON Parsing Demo Adapting Other Examples Upgrade External ESP32 Airlift Firmware External AirLift FeatherWing, Shield, or ItsyWing

Upload Serial Passthrough code for Feather or ItsyBitsy

External AirLift Breakout Code Usage

Install esptool.py

Burning nina-fw with esptool

45

45 45

46

46 46

Verifying the Upgraded Firmware Version

Arduino CircuitPython

Downloads

Files

Schematic Fab Print

Overview

Give your plain ol' microcontroller project a

lift

with the Adafruit AirLift - a breakout board that lets you use

the powerful ESP32 as a WiFi or BLE co-processor. You probably have your favorite microcontroller (like

the ATmega328 or ATSAMD51), awesome peripherals and lots of libraries. But it doesn't have WiFi or BLE

built in! So lets give that chip a best friend, the ESP32. This chip can handle all the heavy lifting of

connecting to a WiFi network and transferring data from a site, even if its using the latest TLS/SSL

encryption (it has root certificates pre-burned in).

Having WiFi managed by a separate chip means your code is simpler, you don't have to cache socket

data, or compile in & debug an SSL library. Send basic but powerful socket-based commands over 8MHz

SPI for high speed data transfer. You can use 3V or 5V Arduino, any chip from the ATmega328 or up,

although the '328 will not be able to do very complex tasks or buffer a lot of data. It also works great with

CircuitPython, a SAMD51/Cortex M4 minimum required since we need a bunch of RAM. All you need is an

SPI bus and 2 control pins plus a power supply that can provide up to 250mA during WiFi usage.

The ESP32 also supports BLE (Bluetooth Low Energy), though not simultaneously with WiFi. Many of our

CircuitPython builds include native support for ESP32 BLE. You use a few control pins and the RXI and

TXO pins to talk to the ESP32 when it's in BLE mode.

We placed an ESP32 module on a PCB with level shifting circuitry, a 3.3V regulator, and a tri-state chip for

MOSI so you can share the SPI bus with other devices. Comes fully assembled and tested, pre-

programmed with ESP32 SPI WiFi co-processor firmware that you can use in CircuitPython to use this into

a WiFi co-processsor over SPI + 2 pins (https://adafru.it/Evl). We also toss in some header so you can

solder it in and plug into a solderless breadboard.

The firmware on board is a slight variant of the Arduino WiFiNINA core, which works

great! (https://adafru.it/E7O) At this time connection to Enterprise WiFi is not yet supported.

Pinouts

Power Pins

Starting from the left are the power in/out pins.

 The ESP32 chip can use a lot of power when transmitting. Make sure your power source can handle

up to 250mA spikes of current during transmits!

VIN - This is the power input. Can be 3.3-5VDC, USE A POWER SOURCE THAT CAN HAPPILY

SUPPLY 250mA, we will regulate this down to 3.3V safely! This is probably a VBAT or USB pin not

a 3.3V regulated output.

3vo - The output from the onboard 3.3V regulator, you can use up to ~50mA for other devices if you

want to power them from the same chip

GND - Power and logic ground.

SPI & Control Pins

To keep transfers speedy, we use SPI

not UART Serial.

Serial is too slow and hard to synchronize. This

uses more pins but the experience is much better!

Classic SPI Pins:

SCK - SPI Clock from your microcontroller, level shifted so can be 3-5V logic

MISO - SPI Data

from

the AirLift to the microcontroller, this is 3.3V logic out, can be read by 3-5V

logic. This is tri-stated when not selected, so you can share the SPI bus with other devices.

MOSI- SPI Data

to

the AirLift

from

the microcontroller, level shifted so can be 3-5V logic

CS - SPI Chip Select from the microcontroller to start sending commands to the AirLift, level shifted

so can be 3-5V logic. Also used to choose WiFi or BLE on reset.

Required Control Pins:

BUSY - this pin is an input from the AirLift, it will let us know when its ready for more commands to

be sent. This is 3.3V logic out, can be read by 3-5V logic. This pin

must

be connected.

!RESET - this pin is an output to the AirLift. Set low to put the AirLift into reset. You should use this

pin, even though you might be able to run for a short while without it, it's essential to 'kick' the chip if

it ever gets into a locked up state. Level shifted so can be 3-5V logic

Optional Control Pins:

GP0 - this is the ESP32 GPIO0 pin, which is used to put it into bootloading mode. It is also used if

you like when the ESP32 is acting as a server, to let you know data is ready for reading. It's not

required in WiFi mode, so you can leave it disconnected. But you'll need to connect it for BLE mode.

RXI & TXO - Serial data in and Serial data out, used for bootloading new firmware, and for

communication when in BLE mode. Leave disconnected if not using BLE or when not uploading new

WiFi firmware to the AirLift (which is a rare occurrence).

LEDs

There are 3 very tiny red, green and blue LEDs to the left of the ESP32, these are available in the Arduino

library if you'd like to PWM them for a visual alert.

Assembly

Prepare the header strip:

Cut the strip to length if necessary. It will be easier to solder if

you insert it into a breadboard - long pins down

Add the breakout board:

Place the breakout board over the pins so that the short pins

poke through the breakout pads

And Solder!

Be sure to solder all 12 pins for reliable electrical contact.

(For tips on soldering, be sure to check out our Guide to

Excellent Soldering

(https://adafru.it/aTk)

).

You're done! Check your solder joints visually and continue

onto the next steps

CircuitPython WiFi

It's easy to use the Adafruit AirLift breakout with CircuitPython and the Adafruit CircuitPython

ESP32SPI (https://adafru.it/DWV) module. This module allows you to easily add WiFi to your project.

 The ESP32SPI library requires a microcontroller with ~128KB of RAM or more. The SAMD21 will not

work.

CircuitPython Microcontroller Pinout

First, wire up your AirLift as follows. The following example shows it wired to a Feather M4 using SPI:

Board VIN to Feather USB

Board GND to Feather GND

Board SCK to Feather SCK

Board MISO to Feather MI

Board MOSI to Feather MO

Board CS to Feather D10

Board BUSY to Feather D9

Board !RST to Feather D6

You must use USB or VBAT for powering the AirLift

Breakout!

CircuitPython Installation of ESP32SPI Library

You'll need to install the Adafruit CircuitPython ESP32SPI (https://adafru.it/DWV) library on your

CircuitPython board.

First make sure you are running the latest version of Adafruit CircuitPython (https://adafru.it/Amd) for your

board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find

and install these libraries from Adafruit's CircuitPython library bundle (https://adafru.it/uap). Our

CircuitPython starter guide has a great page on how to install the library bundle (https://adafru.it/ABU).

You can manually install the necessary libraries from the bundle:

adafruit_esp32spi

adafruit_requests.mpy

adafruit_bus_device

Before continuing make sure your board's lib folder or root filesystem has the adafruit_esp32spi,

adafruit_requests.mpy, and adafruit_bus_device files and folders copied over.

Next make sure you are set up to connect to the serial console (https://adafru.it/Bec)

CircuitPython Usage

Copy the following code to your code.py file on your microcontroller:

import board import busio from digitalio import DigitalInOut

from adafruit_esp32spi import adafruit_esp32spi import adafruit_requests as requests

print("ESP32 SPI hardware test")

esp32_cs = DigitalInOut(board.D10) esp32_ready = DigitalInOut(board.D9) esp32_reset = DigitalInOut(board.D7)

spi = busio.SPI(board.SCK, board.MOSI, board.MISO) esp = adafruit_esp32spi.ESP_SPIcontrol(spi, esp32_cs, esp32_ready, esp32_reset)

if esp.status == adafruit_esp32spi.WL_IDLE_STATUS: print("ESP32 found and in idle mode") print("Firmware vers.", esp.firmware_version) print("MAC addr:", [hex(i) for i in esp.MAC_address])

for ap in esp.scan_networks(): print("\t%s\t\tRSSI: %d" % (str(ap['ssid'], 'utf-8'), ap['rssi']))

print("Done!")

Connect to the serial console (https://adafru.it/BlO) to see the output. It should look something like the

following:

Make sure you see the same output! If you don't, check your wiring. Note that we've changed the pinout

in the code example above to reflect the CircuitPython Microcontroller Pinout at the top of this page.

Once you've succeeded, continue onto the next page!

 If you can read the Firmware and MAC address but fails on scanning SSIDs, check your power

supply, you may be running out of juice to the ESP32 and it's resetting

Internet Connect!

Once you have CircuitPython setup and libraries installed we can get your board connected to the

Internet.

To get connected, you will need to start by creating a

secrets file

.

What's a secrets file?

We expect people to share tons of projects as they build CircuitPython WiFi widgets. What we want to

avoid is people accidentally sharing their passwords or secret tokens and API keys. So, we designed all

our examples to use a secrets.py file, that is in your CIRCUITPY drive, to hold secret/private/custom data.

That way you can share your main project without worrying about accidentally sharing private stuff.

Your secrets.py file should look like this:

# This file is where you keep secret settings, passwords, and tokens! # If you put them in the code you risk committing that info or sharing it

secrets = { 'ssid' : 'home ssid', 'password' : 'my password', 'timezone' : "America/New_York", # http://worldtimeapi.org/timezones 'github_token' : 'fawfj23rakjnfawiefa', 'hackaday_token' : 'h4xx0rs3kret', }

Inside is a python dictionary named secrets with a line for each entry. Each entry has an entry name (say

'ssid' ) and then a colon to separate it from the entry key 'home ssid' and finally a comma ,

At a minimum you'll need the ssid and password for your local WiFi setup. As you make projects you may

need more tokens and keys, just add them one line at a time. See for example other tokens such as one

for accessing github or the hackaday API. Other non-secret data like your timezone can also go here, just

cause its called secrets doesn't mean you can't have general customization data in there!

For the correct time zone string, look at http://worldtimeapi.org/timezones (https://adafru.it/EcP) and

remember that if your city is not listed, look for a city in the same time zone, for example Boston, New

York, Philadelphia, Washington DC, and Miami are all on the same time as New York.

Of course, don't share your secrets.py - keep that out of GitHub, Discord or other project-sharing sites.

Connect to WiFi

OK now you have your secrets setup - you can connect to the Internet using the ESP32SPI and the

Requests modules.

First make sure you are running the latest version of Adafruit CircuitPython (https://adafru.it/Amd) for your

board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find

and install these libraries from Adafruit's CircuitPython library bundle (https://adafru.it/zdx). Our

introduction guide has a great page on how to install the library bundle (https://adafru.it/ABU) for both

express and non-express boards.

Adafruit ESP32 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual