这是MicroPython最新开发分支的文档，可能涉及发布版本中不可用的功能。

如果您正在查找特定版本的文档，请使用左侧的下拉菜单并选择所需版本。

ESP32的快速参考¶

Espressif ESP32开发委员会（图片来源：Adafruit）。

以下是基于ESP32的板的快速参考。如果这是您第一次使用此板，了解微控制器的概况可能会很有用：

安装MicroPython¶

请参阅教程的相应部分：ESP32上的MicroPython入门它还包括一个故障排除小节。

通用板控制¶

MicroPython REPL位于UART0（GPIO1=TX，GPIO3=RX）上，波特率115200。制表符完成有助于了解对象的方法。粘贴模式（ctrl-E）用于将一大块Python代码粘贴到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 Fahrenheit
esp32.ULP()             # access to the Ultra-Low-Power Co-processor

请注意，ESP32中的温度传感器通常读数高于环境温度，因为IC在运行时会变热。这种影响可以通过在从睡眠中醒来后立即读取温度传感器来最小化。

网络¶

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('ssid', 'key') # 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(ssid='ESP-AP') # set the SSID of the access point
ap.config(max_clients=10) # set how many clients can connect to the network
ap.active(True)         # activate the interface

连接到本地WiFi网络的一个有用功能是：

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

一旦建立了网络， socket 模块就可以像往常一样创建和使用TCP/UDP套接字，而urequests模块则可以方便地进行HTTP请求。

在呼叫 wlan.connect()后，设备默认情况下将永远重试连接，即使验证失败或AP不在范围内。 wlan.status() 将在此状态下返回 network.STAT_CONNECTING，直到连接成功或接口被禁用。这可以通过调用 wlan.config(reconnects=n)来更改，其中n是所需的重新连接尝试次数（0表示它不会重试，-1将恢复尝试永久重新连接的默认行为）。

延迟和计时¶

使用 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

计时器¶

ESP32端口有四个硬件计时器。使用计时器ID从0到3（含）的machine.Timer 类：

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))

周期以毫秒为单位。

此端口当前不支持虚拟计时器。

引脚和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
p6 = Pin(6, Pin.OUT, drive=Pin.DRIVE_3) # set maximum drive strength

可用引脚范围如下（包括）：0-19、21-23、25-27、32-39。这些引脚对应于ESP32芯片的实际GPIO引脚编号。注意，许多终端用户板使用自己的特殊引脚编号（标记为D0、D1、…）。有关电路板逻辑引脚和物理芯片引脚之间的映射，请参阅电路板文档。

支持四种驱动强度，使用Pin()构造函数或 Pin.init()方法的drive关键字参数，具有不同的对应最大安全源/汇电流和近似内部驱动器电阻：

Pin.DRIVE_0: 5mA / 130 ohm

Pin.DRIVE_1: 10mA / 60 ohm

Pin.DRIVE_2: 20mA / 30 ohm（如果未配置，则为默认强度）

Pin.DRIVE_3: 40mA / 15 ohm

Pin()和 Pin.init() 的 hold=关键字参数将启用ESP32“pad hold”功能。当设置为 True时，管脚配置（方向、牵引电阻和输出值）将保持不变，不会进行任何进一步的更改（包括更改输出电平）。设置 hold=False 将立即应用任何未完成的引脚配置更改并释放引脚。在引脚已固定时使用hold=True 将应用任何配置更改，然后立即重新应用固定。

笔记：

引脚1和3分别为REPL UART TX和RX
引脚6、7、8、11、16和17用于连接嵌入式闪存，不建议用于其他用途
引脚34-39仅为输入，也没有内部上拉电阻器
请参阅Deep-sleep mode 模式，了解有关睡眠期间引脚行为的讨论

有一个更高级的抽象 machine.Signal可以用来反转一个引脚。用于使用on() 或 value(1)照明有源低LED。

UART（串行总线）¶

参阅 machine.UART.

from machine import UART

uart1 = UART(1, baudrate=9600, tx=33, rx=32)
uart1.write('hello')  # write 5 bytes
uart1.read(5)         # read up to 5 bytes

ESP32有三个硬件UART：UART0、UART1和UART2。它们各自分配了默认GPIO，但根据您的ESP32变体和板，这些引脚可能会与嵌入式闪存、板载PSRAM或外设发生冲突。

任何GPIO都可以用于使用GPIO矩阵的硬件UART，除了可以用作 rx的仅输入引脚34-39。为了避免冲突，只需在构建时提供tx 和 rx 引脚即可。下面列出的默认管脚。

	UART0	UART1	UART2
tx	1	10	17
rx	3	9	16

PWM （脉宽调制）¶

可以在所有输出启用引脚上启用PWM。基本频率可以在1Hz到40MHz的范围内，但存在折衷；随着基频增加，占空比分辨率降低。有关详细信息，请参见 LED Control。

使用 machine.PWM 类：

from machine import Pin, PWM

pwm0 = PWM(Pin(0))         # create PWM object from a pin
freq = pwm0.freq()         # get current frequency (default 5kHz)
pwm0.freq(1000)            # set PWM frequency from 1Hz to 40MHz

duty = pwm0.duty()         # get current duty cycle, range 0-1023 (default 512, 50%)
pwm0.duty(256)             # set duty cycle from 0 to 1023 as a ratio duty/1023, (now 25%)

duty_u16 = pwm0.duty_u16() # get current duty cycle, range 0-65535
pwm0.duty_u16(2**16*3//4)  # set duty cycle from 0 to 65535 as a ratio duty_u16/65535, (now 75%)

duty_ns = pwm0.duty_ns()   # get current pulse width in ns
pwm0.duty_ns(250_000)      # set pulse width in nanoseconds from 0 to 1_000_000_000/freq, (now 25%)

pwm0.deinit()              # turn off PWM on the pin

pwm2 = PWM(Pin(2), freq=20000, duty=512)  # create and configure in one go
print(pwm2)                               # view PWM settings

ESP芯片具有不同的硬件外设：

硬件规格	ESP32	ESP32-S2	ESP32-C3
组数（速度模式）	2	1	1
每组计时器数量	4	4	4
每组通道数	8	8	6
不同的PWM频率（组*计时器）	8	4	4
总PWM通道（引脚、占空比）（组*通道）	16	8	6

ESP32-16通道上最多可提供PWM通道（引脚），但只有8个不同的PWM频率可用，其余8个通道必须具有相同的频率。另一方面，在相同频率下，16个独立的PWM占空比是可能的。

请参见 Pulse Width Modulation教程中的更多示例。

ADC （模数转换）¶

在ESP32上，ADC功能在引脚32-39（ADC块1）和引脚0、2、4、12-15和25-27（ADC块2）上可用。

使用 machine.ADC 类：

from machine import ADC

adc = ADC(pin)        # create an ADC object acting on a pin
val = adc.read_u16()  # read a raw analog value in the range 0-65535
val = adc.read_uv()   # read an analog value in microvolts

ADC块2也被WiFi使用，因此当WiFi激活时，尝试从块2引脚读取模拟值将引发异常。

内部ADC参考电压通常为1.1V，但每个封装略有不同。ADC在接近参考电压（尤其是在较高衰减时）时线性较小，最小测量电压约为100mV，电压等于或低于此值将读取为0。为了准确读取电压，建议使用read_uv() 方法（见下文）。

ESP32特定ADC类方法参考：

class ADC(pin, *, atten)¶

返回指定引脚的ADC对象。ESP32不支持ADC采样的不同定时，因此不支持sample_ns关键字参数。

要读取高于参考电压的电压，请使用atten 关键字参数应用输入衰减。有效值（和近似线性测量范围）为：

ADC.ATTN_0DB: 无衰减（100mV-950mV）)

ADC.ATTN_2_5DB: 2.5dB衰减（100mV-1250mV）

ADC.ATTN_6DB: 6dB衰减（150mV-1750mV）

ADC.ATTN_11DB: 11dB衰减（150mV-2450mV）

警告

请注意，输入引脚的绝对最大额定电压为3.6V。接近此边界可能会损坏IC！

ADC.read_uv()¶

该方法使用ADC的已知特性和每个封装的eFuse值（在制造过程中设置），以微伏为单位返回校准的输入电压（衰减前）。返回的值只有毫伏分辨率（即，总是1000微伏的倍数）。

校准仅在ADC的线性范围内有效。特别是，与接地连接的输入将读取为0微伏以上的值。然而，在线性范围内，将获得比使用 read_u16()和用常数缩放结果更准确和一致的结果。

ESP32端口还支持machine.ADC API:

class ADCBlock(id, *, bits)¶: 返回具有给定id （1或2）的ADC块对象，并将其初始化为指定分辨率（9至12位，取决于ESP32系列）或最高支持分辨率（如果未指定）。

ADCBlock.connect(pin)¶
ADCBlock.connect(channel)
ADCBlock.connect(channel, pin): 返回指定ADC管脚或通道号的 ADC 对象。不支持将ADC通道任意连接到GPIO，因此指定未连接到此块的引脚或指定不匹配的通道和引脚将引发异常。

传统方法：

ADC.read()¶: 该方法返回根据块的分辨率范围的原始ADC值，例如，对于12位分辨率为0-4095。

ADC.atten(atten)¶: 相当于 ADC.init(atten=atten).

ADC.width(bits)¶: 相当于ADC.block().init(bits=bits).

为了兼容性， ADC对象还提供与支持的ADC分辨率匹配的常量：

ADC.WIDTH_9BIT = 9

ADC.WIDTH_10BIT = 10

ADC.WIDTH_11BIT = 11

ADC.WIDTH_12BIT = 12

软件SPI总线¶

软件SPI（使用位碰撞）在所有引脚上工作，并通过 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

警告

目前，在初始化软件SPI时，必须指定所有sck, mosi 和 miso must be specified when initialising Software SPI.

硬件SPI总线¶

有两个硬件SPI通道允许更快的传输速率（最高80Mhz）。这些引脚可用于支持所需方向且未使用的任何IO引脚（见引脚和GPIO），但如果它们未配置为默认引脚，则需要通过额外的GPIO复用层，这可能会影响它们在高速下的可靠性。当在以下列出的默认引脚以外的引脚上使用时，硬件SPI信道限制为40MHz。

	HSPI (id=1)	VSPI (id=2)
sck	14	18
mosi	13	23
miso	12	19

硬件SPI通过machine.SPI类访问，其方法与上述软件SPI相同：

from machine import Pin, SPI

hspi = SPI(1, 10000000)
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总线¶

软件I2C（使用位碰撞）适用于所有支持输出的引脚，并通过 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 peripheral

硬件I2C总线¶

有两个标识符为0和1的硬件I2C外设。任何可用的支持输出的引脚都可以用于SCL和SDA，但默认值如下所示。

	I2C(0)	I2C(1)
scl	18	25
sda	19	26

驱动程序通过 machine.I2C 类访问，其方法与上述软件I2C相同：

from machine import Pin, I2C

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

I2S总线¶

参阅 machine.I2S。

from machine import I2S, Pin

i2s = I2S(0, sck=Pin(13), ws=Pin(14), sd=Pin(34), mode=I2S.TX, bits=16, format=I2S.STEREO, rate=44100, ibuf=40000) # create I2S object
i2s.write(buf)             # write buffer of audio samples to I2S device

i2s = I2S(1, sck=Pin(33), ws=Pin(25), sd=Pin(32), mode=I2S.RX, bits=16, format=I2S.MONO, rate=22050, ibuf=40000) # create I2S object
i2s.readinto(buf)          # fill buffer with audio samples from I2S device

I2S类目前作为技术预览版提供。在预览期间，鼓励用户提供反馈。基于该反馈，可以改变I2S类API和实现。

ESP32有两条id=0和id=1的I2S总线

实时时钟（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

WDT（看门狗定时器）¶

参阅 machine.WDT。

from machine import WDT

# enable the WDT with a timeout of 5s (1s is the minimum)
wdt = WDT(timeout=5000)
wdt.feed()

深度睡眠模式¶

以下代码可用于休眠、唤醒和检查重置原因：

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() 将使设备无限期休眠
软件重置不会改变重置原因

一些ESP32引脚（0、2、4、12-15、25-27、32-39）在深度睡眠期间连接到RTC，可用于通过esp32模块中的wake_on_功能唤醒设备。当进入深度睡眠时，支持输出的RTC引脚（除34-39之外的所有引脚）也将保持其上拉或下拉电阻器配置。

如果在深度睡眠期间不主动需要上拉电阻器，并且可能导致电流泄漏（例如，上拉电阻器通过开关接地），则应在进入深度睡眠模式之前禁用它们以节省电力：

from machine import Pin, deepsleep

# configure input RTC pin with pull-up on boot
pin = Pin(2, Pin.IN, Pin.PULL_UP)

# disable pull-up and put the device to sleep for 10 seconds
pin.init(pull=None)
machine.deepsleep(10000)

如果使用 hold=True参数 Pin.init()启用了pad hold，则输出配置的RTC引脚也将在深度睡眠中保持其输出方向和电平。

进入深度睡眠时，非RTC GPIO引脚将默认断开。非RTC引脚的配置（包括输出电平）可通过在引脚上启用焊盘保持并在深度睡眠期间启用GPIO焊盘保持来保持：

from machine import Pin, deepsleep
import esp32

opin = Pin(19, Pin.OUT, value=1, hold=True) # hold output level
ipin = Pin(21, Pin.IN, Pin.PULL_UP, hold=True) # hold pull-up

# enable pad hold in deep-sleep for non-RTC GPIO
esp32.gpio_deep_sleep_hold(True)

# put the device to sleep for 10 seconds
deepsleep(10000)

引脚配置（包括衬垫保持）将在从睡眠中醒来时保留。有关衬垫保持的进一步讨论，请参见上文引脚和GPIO 。

记忆卡¶

参阅 machine.SDCard。

import machine, os

# Slot 2 uses pins sck=18, cs=5, miso=19, mosi=23
sd = machine.SDCard(slot=2)
os.mount(sd, '/sd')  # mount

os.listdir('/sd')    # list directory contents

os.umount('/sd')     # eject

RMT¶

RMT是ESP32专用的，允许生成分辨率为12.5ns的精确数字脉冲。详见esp32.RMT 。用法为：

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), 0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns

OneWire驱动程序¶

OneWire驱动程序在软件中实现，适用于所有引脚：

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

DS18S20和DS18B20设备有一个特定的驱动程序：

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))

确保在数据线上放置4.7k上拉电阻器。请注意，每次要采样温度时都必须调用convert_temp()方法。

NeoPixel和APA106驱动程序¶

使用 neopixel 和 apa106模块：

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

APA106驱动程序扩展了NeoPixel，但内部使用不同的颜色顺序：

from apa106 import APA106
ap = APA106(pin, 8)
r, g, b = ap[0]

警告

默认情况下， NeoPixel配置为控制更流行的800kHz单元。在构造NeoPixel对象时，可以通过传递 timing=0来使用替代定时来控制其他（通常为400kHz）设备。

对于NeoPixel的低级别驱动，请参见 machine.bitstream。此低级别驱动默认使用RMT通道。要对此进行配置，请参见 RMT.bitstream_channel。

APA102（DotStar）使用不同的驱动程序，因为它有一个额外的时钟引脚。

电容式触摸¶

使用machine 模块中的TouchPad类：

from machine import TouchPad, Pin

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

TouchPad.read 返回与电容变化相关的值。当触针时，小数字（通常为十位数）很常见，当没有触针时则大数字（超过一千）。然而，这些值是相对的，可能会根据电路板和周围的组成而变化，因此可能需要进行一些校准。

ESP32上可以使用十个电容式触摸启用引脚：0、2、4、12、13、14、15、27、32、33。尝试分配给任何其他引脚将导致 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

有关触摸板的更多详细信息，请参阅 Espressif Touch Sensor。

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（通过WebSockets的REPL，可通过web浏览器访问）是ESP32端口中的一项实验功能。从https://github.com/micropython/webrepl下载web客户端（http://micropython.org/webrepl提供托管版本），并通过执行以下操作进行配置：

import webrepl_setup

并遵循屏幕上的说明。重新启动后，它将可用于连接。如果禁用启动时的自动启动，则可以使用以下命令按需运行配置的守护程序：

import webrepl
webrepl.start()

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

WebREPL守护进程侦听所有活动接口，这些接口可以是STA或AP。这允许您通过路由器（STA接口）或直接连接到其接入点时连接到ESP32。

除了终端/命令提示符访问，WebREPL还提供文件传输（上传和下载）。web客户端具有相应功能的按钮，或者您可以使用上面存储库中的命令行客户端 webrepl_cli.py。

有关将文件传输到ESP32板的其他社区支持的替代方案，请参见MicroPython论坛。