ESP32 快速参考

ESP32 board

Espressif (乐鑫) ESP32 开发板 (图像归属:Adafruit)。

Below is a quick reference for ESP32-based boards. If it is your first time working with this board it may be useful to get an overview of the microcontroller:

安装 MicroPython

See the corresponding section of tutorial: 在 ESP32 上快速入门 MicroPython . It also includes a troubleshooting subsection.

一般板控制

The MicroPython REPL is on UART0 (GPIO1=TX, GPIO3=RX) at baudrate 115200. Tab-completion is useful to find out what methods an object has. Paste mode (ctrl-E) is useful to paste a large slab of Python code into the REPL.

machine 模块:

import machine
machine.freq()          # get the current frequency of the CPU
machine.freq(240000000) # set the CPU frequency to 240 MHz
											

esp 模块:

import esp
esp.osdebug(None)       # turn off vendor O/S debugging messages
esp.osdebug(0)          # redirect vendor O/S debugging messages to UART(0)
# low level methods to interact with flash storage
esp.flash_size()
esp.flash_user_start()
esp.flash_erase(sector_no)
esp.flash_write(byte_offset, buffer)
esp.flash_read(byte_offset, buffer)
											

esp32 模块:

import esp32
esp32.hall_sensor()     # read the internal hall sensor
esp32.raw_temperature() # read the internal temperature of the MCU, in Farenheit
esp32.ULP()             # access to the Ultra-Low-Power Co-processor
											

Note that the temperature sensor in the ESP32 will typically read higher than ambient due to the IC getting warm while it runs. This effect can be minimised by reading the temperature sensor immediately after waking up from sleep.

网络

network 模块:

import network
wlan = network.WLAN(network.STA_IF) # create station interface
wlan.active(True)       # activate the interface
wlan.scan()             # scan for access points
wlan.isconnected()      # check if the station is connected to an AP
wlan.connect('essid', 'password') # connect to an AP
wlan.config('mac')      # get the interface's MAC address
wlan.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
ap = network.WLAN(network.AP_IF) # create access-point interface
ap.config(essid='ESP-AP') # set the ESSID of the access point
ap.config(max_clients=10) # set how many clients can connect to the network
ap.active(True)         # activate the interface
											

A useful function for connecting to your local WiFi network is:

def do_connect():
    import network
    wlan = network.WLAN(network.STA_IF)
    wlan.active(True)
    if not wlan.isconnected():
        print('connecting to network...')
        wlan.connect('essid', 'password')
        while not wlan.isconnected():
            pass
    print('network config:', wlan.ifconfig())
											

Once the network is established the socket module can be used to create and use TCP/UDP sockets as usual, and the urequests module for convenient HTTP requests.

延迟和计时

使用 time 模块:

import time
time.sleep(1)           # sleep for 1 second
time.sleep_ms(500)      # sleep for 500 milliseconds
time.sleep_us(10)       # sleep for 10 microseconds
start = time.ticks_ms() # get millisecond counter
delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference
											

计时器

The ESP32 port has four hardware timers. Use the machine.Timer class with a timer ID from 0 to 3 (inclusive):

from machine import Timer
tim0 = Timer(0)
tim0.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(0))
tim1 = Timer(1)
tim1.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(1))
											

The period is in milliseconds.

Virtual timers are not currently supported on this port.

引脚和 GPIO

使用 machine.Pin 类:

from machine import Pin
p0 = Pin(0, Pin.OUT)    # create output pin on GPIO0
p0.on()                 # set pin to "on" (high) level
p0.off()                # set pin to "off" (low) level
p0.value(1)             # set pin to on/high
p2 = Pin(2, Pin.IN)     # create input pin on GPIO2
print(p2.value())       # get value, 0 or 1
p4 = Pin(4, Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
p5 = Pin(5, Pin.OUT, value=1) # set pin high on creation
											

Available Pins are from the following ranges (inclusive): 0-19, 21-23, 25-27, 32-39. These correspond to the actual GPIO pin numbers of ESP32 chip. Note that many end-user boards use their own adhoc pin numbering (marked e.g. D0, D1, …). For mapping between board logical pins and physical chip pins consult your board documentation.

注意事项:

  • Pins 1 and 3 are REPL UART TX and RX respectively

  • Pins 6, 7, 8, 11, 16, and 17 are used for connecting the embedded flash, and are not recommended for other uses

  • Pins 34-39 are input only, and also do not have internal pull-up resistors

  • The pull value of some pins can be set to Pin.PULL_HOLD to reduce power consumption during deepsleep.

PWM (脉冲宽度调制)

PWM can be enabled on all output-enabled pins. The base frequency can range from 1Hz to 40MHz but there is a tradeoff; as the base frequency increases the duty resolution decreases 。见 LED Control for more details. Currently the duty cycle has to be in the range of 0-1023.

使用 machine.PWM 类:

from machine import Pin, PWM
pwm0 = PWM(Pin(0))      # create PWM object from a pin
pwm0.freq()             # get current frequency
pwm0.freq(1000)         # set frequency
pwm0.duty()             # get current duty cycle
pwm0.duty(200)          # set duty cycle
pwm0.deinit()           # turn off PWM on the pin
pwm2 = PWM(Pin(2), freq=20000, duty=512) # create and configure in one go
											

ADC (模拟到数字转换)

On the ESP32 ADC functionality is available on Pins 32-39. Note that, when using the default configuration, input voltages on the ADC pin must be between 0.0v and 1.0v (anything above 1.0v will just read as 4095). Attenuation must be applied in order to increase this usable voltage range.

使用 machine.ADC 类:

from machine import ADC
adc = ADC(Pin(32))          # create ADC object on ADC pin
adc.read()                  # read value, 0-4095 across voltage range 0.0v - 1.0v
adc.atten(ADC.ATTN_11DB)    # set 11dB input attenuation (voltage range roughly 0.0v - 3.6v)
adc.width(ADC.WIDTH_9BIT)   # set 9 bit return values (returned range 0-511)
adc.read()                  # read value using the newly configured attenuation and width
											

ESP32 specific ADC class method reference:

ADC. atten ( attenuation )

This method allows for the setting of the amount of attenuation on the input of the ADC. This allows for a wider possible input voltage range, at the cost of accuracy (the same number of bits now represents a wider range). The possible attenuation options are:

  • ADC.ATTN_0DB : 0dB attenuation, gives a maximum input voltage of 1.00v - this is the default configuration

  • ADC.ATTN_2_5DB : 2.5dB attenuation, gives a maximum input voltage of approximately 1.34v

  • ADC.ATTN_6DB : 6dB attenuation, gives a maximum input voltage of approximately 2.00v

  • ADC.ATTN_11DB : 11dB attenuation, gives a maximum input voltage of approximately 3.6v

警告

Despite 11dB attenuation allowing for up to a 3.6v range, note that the absolute maximum voltage rating for the input pins is 3.6v, and so going near this boundary may be damaging to the IC!

ADC. width ( width )

This method allows for the setting of the number of bits to be utilised and returned during ADC reads. Possible width options are:

  • ADC.WIDTH_9BIT :9 位数据

  • ADC.WIDTH_10BIT :10 位数据

  • ADC.WIDTH_11BIT :11 位数据

  • ADC.WIDTH_12BIT :12 位数据 - 这是默认配置

软件 SPI 总线

Software SPI (using bit-banging) works on all pins, and is accessed via the machine.SoftSPI 类:

from machine import Pin, SoftSPI
# construct a SoftSPI bus on the given pins
# polarity is the idle state of SCK
# phase=0 means sample on the first edge of SCK, phase=1 means the second
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
spi.init(baudrate=200000) # set the baudrate
spi.read(10)            # read 10 bytes on MISO
spi.read(10, 0xff)      # read 10 bytes while outputting 0xff on MOSI
buf = bytearray(50)     # create a buffer
spi.readinto(buf)       # read into the given buffer (reads 50 bytes in this case)
spi.readinto(buf, 0xff) # read into the given buffer and output 0xff on MOSI
spi.write(b'12345')     # write 5 bytes on MOSI
buf = bytearray(4)      # create a buffer
spi.write_readinto(b'1234', buf) # write to MOSI and read from MISO into the buffer
spi.write_readinto(buf, buf) # write buf to MOSI and read MISO back into buf
											

警告

目前 all of sck , mosi and miso must be specified when initialising Software SPI.

硬件 SPI 总线

There are two hardware SPI channels that allow faster transmission rates (up to 80Mhz). These may be used on any IO pins that support the required direction and are otherwise unused (see 引脚和 GPIO ) but if they are not configured to their default pins then they need to pass through an extra layer of GPIO multiplexing, which can impact their reliability at high speeds. Hardware SPI channels are limited to 40MHz when used on pins other than the default ones listed below.

HSPI (id=1)

VSPI (id=2)

sck

14

18

mosi

13

23

miso

12

19

Hardware SPI is accessed via the machine.SPI class and has the same methods as software SPI above:

from machine import Pin, SPI
hspi = SPI(1, 10000000, sck=Pin(14), mosi=Pin(13), miso=Pin(12))
vspi = SPI(2, baudrate=80000000, polarity=0, phase=0, bits=8, firstbit=0, sck=Pin(18), mosi=Pin(23), miso=Pin(19))
											

软件 I2C 总线

Software I2C (using bit-banging) works on all output-capable pins, and is accessed via the machine.SoftI2C 类:

from machine import Pin, SoftI2C
i2c = SoftI2C(scl=Pin(5), sda=Pin(4), freq=100000)
i2c.scan()              # scan for devices
i2c.readfrom(0x3a, 4)   # read 4 bytes from device with address 0x3a
i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
buf = bytearray(10)     # create a buffer with 10 bytes
i2c.writeto(0x3a, buf)  # write the given buffer to the slave
											

硬件 I2C 总线

There are two hardware I2C peripherals with identifiers 0 and 1. Any available output-capable pins can be used for SCL and SDA but the defaults are given below.

I2C(0)

I2C(1)

scl

18

25

sda

19

26

The driver is accessed via the machine.I2C class and has the same methods as software I2C above:

from machine import Pin, I2C
i2c = I2C(0)
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
											

RTC (实时时钟)

machine.RTC

from machine import RTC
rtc = RTC()
rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time
rtc.datetime() # get date and time
											

深度休眠模式

The following code can be used to sleep, wake and check the reset cause:

import machine
# check if the device woke from a deep sleep
if machine.reset_cause() == machine.DEEPSLEEP_RESET:
    print('woke from a deep sleep')
# put the device to sleep for 10 seconds
machine.deepsleep(10000)
											

注意事项:

  • 调用 deepsleep() without an argument will put the device to sleep indefinitely

  • A software reset does not change the reset cause

  • There may be some leakage current flowing through enabled internal pullups. To further reduce power consumption it is possible to disable the internal pullups:

    p1 = Pin(4, Pin.IN, Pin.PULL_HOLD)
    													

    After leaving deepsleep it may be necessary to un-hold the pin explicitly (e.g. if it is an output pin) via:

    p1 = Pin(4, Pin.OUT, None)
    													

RMT (远程控制)

The RMT is ESP32-specific and allows generation of accurate digital pulses with 12.5ns resolution. See esp32.RMT for details. Usage is:

import esp32
from machine import Pin
r = esp32.RMT(0, pin=Pin(18), clock_div=8)
r   # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8)
# The channel resolution is 100ns (1/(source_freq/clock_div)).
r.write_pulses((1, 20, 2, 40), start=0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
											

OneWire 驱动程序

The OneWire driver is implemented in software and works on all pins:

from machine import Pin
import onewire
ow = onewire.OneWire(Pin(12)) # create a OneWire bus on GPIO12
ow.scan()               # return a list of devices on the bus
ow.reset()              # reset the bus
ow.readbyte()           # read a byte
ow.writebyte(0x12)      # write a byte on the bus
ow.write('123')         # write bytes on the bus
ow.select_rom(b'12345678') # select a specific device by its ROM code
											

There is a specific driver for DS18S20 and DS18B20 devices:

import time, ds18x20
ds = ds18x20.DS18X20(ow)
roms = ds.scan()
ds.convert_temp()
time.sleep_ms(750)
for rom in roms:
    print(ds.read_temp(rom))
											

Be sure to put a 4.7k pull-up resistor on the data line. Note that the convert_temp() method must be called each time you want to sample the temperature.

NeoPixel 驱动程序

使用 neopixel 模块:

from machine import Pin
from neopixel import NeoPixel
pin = Pin(0, Pin.OUT)   # set GPIO0 to output to drive NeoPixels
np = NeoPixel(pin, 8)   # create NeoPixel driver on GPIO0 for 8 pixels
np[0] = (255, 255, 255) # set the first pixel to white
np.write()              # write data to all pixels
r, g, b = np[0]         # get first pixel colour
											

用于 NeoPixel 的低级驱动:

import esp
esp.neopixel_write(pin, grb_buf, is800khz)
											

警告

默认情况下 NeoPixel is configured to control the more popular 800kHz units. It is possible to use alternative timing to control other (typically 400kHz) devices by passing timing=0 when constructing the NeoPixel 对象。

电容触摸

使用 TouchPad 类在 machine 模块:

from machine import TouchPad, Pin
t = TouchPad(Pin(14))
t.read()              # Returns a smaller number when touched
											

TouchPad.read returns a value relative to the capacitive variation. Small numbers (typically in the tens ) are common when a pin is touched, larger numbers (above one thousand ) when no touch is present. However the values are relative and can vary depending on the board and surrounding composition so some calibration may be required.

There are ten capacitive touch-enabled pins that can be used on the ESP32: 0, 2, 4, 12, 13 14, 15, 27, 32, 33. Trying to assign to any other pins will result in a ValueError .

注意,TouchPad 可用于从睡眠唤醒 ESP32:

import machine
from machine import TouchPad, Pin
import esp32
t = TouchPad(Pin(14))
t.config(500)               # configure the threshold at which the pin is considered touched
esp32.wake_on_touch(True)
machine.lightsleep()        # put the MCU to sleep until a touchpad is touched
											

有关 TouchPad 的更多细节,参考 Espressif (乐鑫) 触控传感器 .

DHT 驱动程序

DHT 驱动程序在软件中实现并工作于所有引脚:

import dht
import machine
d = dht.DHT11(machine.Pin(4))
d.measure()
d.temperature() # eg. 23 (°C)
d.humidity()    # eg. 41 (% RH)
d = dht.DHT22(machine.Pin(4))
d.measure()
d.temperature() # eg. 23.6 (°C)
d.humidity()    # eg. 41.3 (% RH)
											

WebREPL (Web 浏览器交互提示)

WebREPL (REPL over WebSockets, accessible via a web browser) is an experimental feature available in ESP32 port. Download web client from https://github.com/micropython/webrepl (hosted version available at http://micropython.org/webrepl ), and configure it by executing:

import webrepl_setup
											

and following on-screen instructions. After reboot, it will be available for connection. If you disabled automatic start-up on boot, you may run configured daemon on demand using:

import webrepl
webrepl.start()
# or, start with a specific password
webrepl.start(password='mypass')
											

The WebREPL daemon listens on all active interfaces, which can be STA or AP. This allows you to connect to the ESP32 via a router (the STA interface) or directly when connected to its access point.

In addition to terminal/command prompt access, WebREPL also has provision for file transfer (both upload and download). The web client has buttons for the corresponding functions, or you can use the command-line client webrepl_cli.py from the repository above.

See the MicroPython forum for other community-supported alternatives to transfer files to an ESP32 board.