ESP32 快速參考手冊
.. only:: not latex
.. image:: http://www.01studio.org/micropython/picture/pyWiFi-ESP32_pinout.png
:alt: pyWiFi-ESP32 pinout
:width: 700px
.. only:: latex
.. image:: http://www.01studio.org/micropython/picture/pyWiFi-ESP32_pinout.png
:alt: pyWiFi-ESP32 pinout
ESP32開發闆 (圖檔來源: 01Studio).
以下内容是ESP32開發闆的快速入門内容。如果這是你第一次使用ESP32開發闆，那麼建議你先閱讀以下兩個章節熟悉一下：
.. toctree::
:maxdepth: 1
general.rst
tutorial/intro.rst
安裝MicroPython
請參考教程的相應部分: :ref:`esp32_intro`. 它還包括故障排除小節。
通用控制
MicroPython 的序列槽互動調試（REPL）在 UART0 (GPIO1=TX, GPIO3=RX)，波特率為：115200。
Tab按鍵補全功能對于找到每個對象的使用方法非常有用。 粘貼模式 (ctrl-E) 對需要複制比較多
的python代碼到REPL是非常有用。
import machine
machine.freq() # 擷取CPU目前工作頻率
machine.freq(240000000) # 設定CPU的工作頻率為 240 MHz
The :mod:`esp` module:
import esp
esp.osdebug(None) # 關閉原廠 O/S 調試資訊
esp.osdebug(0) # 将原廠 O/S 調試資訊重定向到 UART(0) 輸出
# 與flash互動的低級方法
esp.flash_size()
esp.flash_user_start()
esp.flash_erase(sector_no)
esp.flash_write(byte_offset, buffer)
esp.flash_read(byte_offset, buffer)
import esp32
esp32.hall_sensor() # 讀取内部霍爾傳感器
esp32.raw_temperature() # 讀取内部溫度傳感器，在MCU上, 機關：華氏度F
esp32.ULP() # 使用超低功耗協處理器（ULP）
請注意ESP32内部溫度讀取數值會比實際要高，因為晶片工作時候回發熱。
從睡眠狀态喚醒後立即讀取溫度傳感器可以最大限度地減少這種影響。
Networking
import network
wlan = network.WLAN(network.STA_IF) # 建立 station 接口
wlan.active(True) # 激活接口
wlan.scan() # 掃描允許通路的SSID
wlan.isconnected() # 檢查建立的station是否連已經接到AP
wlan.connect('essid', 'password') # 連接配接到指定ESSID網絡
wlan.config('mac') # 擷取接口的MAC位址
wlan.ifconfig() # 擷取接口的 IP/netmask(子網路遮罩)/gw(網關)/DNS 位址
ap = network.WLAN(network.AP_IF) # 創捷一個AP熱點接口
ap.config(essid='ESP-AP') # 激活接口
ap.config(max_clients=10) # 設定熱點允許連接配接數量
ap.active(True) # 設定AP的ESSID名稱
連接配接到本地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('essid', 'password')
while not wlan.isconnected():
pass
print('network config:', wlan.ifconfig())
一旦網絡建立成功，你就可以通過 :mod:`socket ` 子產品建立和使用 TCP/UDP sockets 通訊,
以及通過 ``urequests``子產品非常友善地發送 HTTP 請求。
延時和時間
import time
time.sleep(1) # 睡眠1秒
time.sleep_ms(500) # 睡眠500毫秒
time.sleep_us(10) # 睡眠10微妙
start = time.ticks_ms() # 擷取毫秒計時器開始值
delta = time.ticks_diff(time.ticks_ms(), start) # 計算從開始到目前時間的內插補點
定時器
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))
該周期的機關為毫秒(ms)
Virtual timers are not currently supported on this port.
引腳和GPIO口
from machine import Pin
p0 = Pin(0, Pin.OUT) # 建立對象p0，對應GPIO0口輸出
p0.on() # 設定引腳為 "on" (1)高電平
p0.off() # 設定引腳為 "off" (0)低電平
p0.value(1) # 設定引腳為 "on" (1)高電平
p2 = Pin(2, Pin.IN) # 建立對象p2，對應GPIO2口輸入
print(p2.value()) # 擷取引腳輸入值, 0（低電平） 或者 1（高電平）
p4 = Pin(4, Pin.IN, Pin.PULL_UP) # 打開内部上拉電阻
p5 = Pin(5, Pin.OUT, value=1) # 初始化時候設定引腳的值為 1（高電平）
可以使用引腳排列如下 (包括首尾): 0-19, 21-23, 25-27, 32-39.分别對應ESP32晶片的實際
引腳編号。 請注意，使用者使用自己其它的開發闆有特定的引腳命名方式（例如：DO, D1, ...）。
由于MicroPython緻力于支援 不同的開發闆和子產品，是以我們采用最原始簡單具且有共同特征的引
腳命名方式。如果你使用自己的開發闆，請參考其原理圖。
注意:
引腳1和3分别是序列槽互動（REPL）的TX和RX。
引腳6, 7, 8, 11, 16, 和 17 are 連接配接到子產品的Flash，不建議做其它用途。
引腳 34-39 隻允許輸入, 沒有内部上拉電阻。
部分引腳的pull值可以設定為 Pin.PULL_HOLD 以降低深度睡眠時候的功耗。
PWM (脈寬調制)
PWM 能在所有可輸出引腳上實作。基頻的範圍可以從 1Hz 到 40MHz 但需要權衡: 随着基頻的
增加 占空分辨率 下降. 詳情請參閱：
LED Control
.
現在占空比範圍為 0-1023
Use the machine.PWM class:
from machine import Pin, PWM
pwm0 = PWM(Pin(0)) # 從1個引腳中建立PWM對象
pwm0.freq() # 擷取目前頻率
pwm0.freq(1000) # 設定頻率
pwm0.duty() # 擷取目前占空比
pwm0.duty(200) # 設定占空比
pwm0.deinit() # 關閉引腳的 PWM
pwm2 = PWM(Pin(2), freq=20000, duty=512) # 在同一語句下建立和配置 PWM
ADC (模數轉換)
ADC功能在ESP32引腳32-39上可用。請注意，使用預設配置時，ADC引腳上的輸入電壓必須
介于0.0v和1.0v之間（任何高于1.0v的值都将讀為4095）。如果需要增加測量範圍，需要配置
衰減器。
from machine import ADC
adc = ADC(Pin(32)) # 在ADC引腳上建立ADC對象
adc.read() # 讀取測量值, 0-4095 表示電壓從 0.0v - 1.0v
adc.atten(ADC.ATTN_11DB) # 設定 11dB 衰減輸入 (測量電壓大緻從 0.0v - 3.6v)
adc.width(ADC.WIDTH_9BIT) # 設定 9位 精度輸出 (傳回值 0-511)
adc.read() # 擷取重新配置後的測量值
ESP32 特定的 ADC 類使用方法說明:
.. method:: ADC.atten(attenuation)
該方法允許設定ADC輸入的衰減量，以擷取更大的電壓測量範圍，但是以精度為代價的。
（配置後相同的位數表示更寬的範圍）。衰減選項如下:
- ``ADC.ATTN_0DB``: 0dB 衰減, 最大輸入電壓為 1.00v - 這是預設配置
- ``ADC.ATTN_2_5DB``: 2.5dB 衰減, 最大輸入電壓約為 1.34v
- ``ADC.ATTN_6DB``: 6dB 衰減, 最大輸入電壓約為 2.00v
- ``ADC.ATTN_11DB``: 11dB 衰減, 最大輸入電壓約為3v
Warning
盡管通過配置11dB衰減可以讓測量電壓到達3.6v,但由于ESP32晶片的最大允許輸入電壓是3.6V,
是以輸入接近3.6V的電壓可能會導緻IC燒壞！
.. method:: ADC.width(width)
該方法允許設定ADC輸入的位數精度。 選項如下:
- ``ADC.WIDTH_9BIT``: 9 bit data
- ``ADC.WIDTH_10BIT``: 10 bit data
- ``ADC.WIDTH_11BIT``: 11 bit data
- ``ADC.WIDTH_12BIT``: 12 bit data - 這是預設配置
軟體SPI總線
EPS32内部有兩個SPI驅動。其中1個是通過軟體實作 (bit-banging)，并允許配置到所有引腳，
通過 :ref:`machine.SoftSPI ` 類子產品配置:
from machine import Pin, SoftSPI
# 在給定的引腳上建立SoftSPI總線
# （極性）polarity是指 SCK 空閑時候的狀态
# （相位）phase=0 表示SCK在第1個邊沿開始取樣，phase=1 表示在第2個邊沿開始。
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4))
spi.init(baudrate=200000) # 設定頻率
spi.read(10) # 在MISO引腳讀取10位元組資料
spi.read(10, 0xff) # 在MISO引腳讀取10位元組資料同時在MOSI輸出0xff
buf = bytearray(50) # 建立緩沖區
spi.readinto(buf) # 讀取資料并存放在緩沖區 (這裡讀取50個位元組)
spi.readinto(buf, 0xff) # 讀取資料并存放在緩沖區，同時在MOSI輸出0xff
spi.write(b'12345') # 在MOSI引腳上寫5位元組資料
buf = bytearray(4) # 建立緩沖區
spi.write_readinto(b'1234', buf) # 在MOSI引腳上寫資料并将MISO讀取資料存放到緩沖區
spi.write_readinto(buf, buf) # 在MOSI引腳上寫緩沖區的資料并将MISO讀取資料存放到緩沖區
Warning
目前在建立軟體SPI對象時，sck, mosi 和 miso 所有 的引腳 必須 定義。
硬體SPI總線
有兩個硬體SPI通道允許更高速率傳輸（到達80MHz）。 也可以配置成任意引腳，但相關引腳要
符合輸入輸出的方向性，這可以參閱(see :ref:`Pins_and_GPIO`)内容。通過自定義引腳而非
預設引腳，會降低傳輸速度，上限為40MHz。以下是硬體SPI總線預設引腳：
HSPI (id=1)
VSPI (id=2)
sck
14
18
mosi
13
23
miso
12
19
Hardware SPI is accessed via the :ref:`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))
SoftI2C總線
I2C總線分軟體和硬體對象，硬體可以定義0和1，通過配置可以在任意引腳上實作改功能，
詳情請看:ref:machine.SoftI2C 類子產品:
from machine import Pin, SoftI2C
# 建構1個I2C對象
i2c = SoftI2C(scl=Pin(5), sda=Pin(4), freq=100000)
# 建構一個硬體 I2C 總線
i2c = I2C(0)
i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
i2c.scan() # 掃描從裝置
i2c.readfrom(0x3a, 4) # 從位址為0x3a的從機裝置讀取4位元組資料
i2c.writeto(0x3a, '12') # 向位址為0x3a的從機裝置寫入資料"12"
buf = bytearray(10) # 建立1個10位元組緩沖區
i2c.writeto(0x3a, buf) # 寫入緩沖區資料到從機
Hardware I2C bus
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 :ref:`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)
from machine import RTC
rtc = RTC()
rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # 設定時間（年，月，日，星期，時，分，秒，微秒）
# 其中星期使用0-6表示星期一至星期日。
rtc.datetime() # 擷取目前日期和時間
深度睡眠模式
下面代碼可以用來睡眠、喚醒和檢測複位喚醒:
import machine
# 檢測裝置是否從深度睡眠中喚醒
if machine.reset_cause() == machine.DEEPSLEEP_RESET:
print('woke from a deep sleep')
# 使裝置進入深度睡眠，時間10秒。
machine.deepsleep(10000)
注意事項:
調用深度睡眠函數 deepsleep() 如果不提供參數（時間）的話可能會讓裝置無限期休眠。
軟體複位不能觸發複位事件（reset cause）。
可能會出現一些洩漏電流流經内部上下拉電阻，為了進一步降低功耗，可以關閉GPIO的上下拉電阻:
p1 = Pin(4, Pin.IN, Pin.PULL_HOLD)
退出深度睡眠後，有必要恢複GPIO原來的狀态 (例如：原來是輸出引腳)
p1 = Pin(4, Pin.OUT, None)
RMT
The RMT is ESP32-specific and allows generation of accurate digital pulses with
12.5ns resolution. See :ref:`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）
單總線驅動允許通過軟體在各個引腳上實作:
from machine import Pin
import onewire
ow = onewire.OneWire(Pin(12)) # 在引腳 GPIO12 建立單總線對象ow
ow.scan() # 掃描裝置,傳回裝置編号清單
ow.reset() # 複位總線
ow.readbyte() # 讀取1位元組
ow.writebyte(0x12) # 寫入1個位元組（0x12）
ow.write('123') # 寫入多個位元組('123')
ow.select_rom(b'12345678') # 根據ROM編号選擇總線上的指定裝置
下面是一個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 彩燈驅動
Use the neopixel module:
from machine import Pin
from neopixel import NeoPixel
pin = Pin(0, Pin.OUT) # 設定引腳GPIO0來驅動 NeoPixels
np = NeoPixel(pin, 8) # 在GPIO0上建立一個 NeoPixel對象，包含8個燈珠
np[0] = (255, 255, 255) # 設定第一個燈珠顯示資料為白色
np.write() # 寫入資料
r, g, b = np[0] # 擷取第一個燈珠的顔色
低級别的 NeoPixel 驅動:
import esp
esp.neopixel_write(pin, grb_buf, is800khz)
.. 警告::
預設情況下， ``NeoPixel`` 被配置成控制更常用的 *800kHz*單元裝置。使用者可以通過使用替代的定時器
來說控制其他頻率的裝置 (通常是 400kHz)。 可以通過使用定時器 ``timing=0`` 當建構``NeoPixel`` 對象的時候。
電容觸摸
Use the TouchPad class in the machine module:
from machine import TouchPad, Pin
t = TouchPad(Pin(14))
t.read() # 當觸摸的時候傳回一個很小的數字。
TouchPad.read 傳回一個跟電容相關的變量數值。 當被觸摸時候，這個數值很小 (通常是 十位)，
而當電容按鍵沒有被觸摸時候，傳回一個很大的數字 (大于*1000*)。 然而，這些值是 相對的，它可能會
随外部環境變化，是以你可能需要做一些校準。
ESP32有10個電容觸摸輸入IO口: 0, 2, 4, 12, 13,14, 15, 27, 32, 33。嘗試其它GPIO會傳回``ValueError``。
TouchPads可以喚醒睡眠中的ESP32:
import machine
from machine import TouchPad, Pin
import esp32
t = TouchPad(Pin(14))
t.config(500) # 配置觸摸引腳的門檻值
esp32.wake_on_touch(True)
machine.lightsleep() # MCU進入睡眠狀态，直到touchpad被觸摸
有關 touchpads 更多資料請參考以下連結： 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, 可以通過浏覽器使用) 是ESP8266端口實驗的功能。
可以從 https://github.com/micropython/webrepl 下載下傳并打開html檔案運作。
(線上托管版可以通過通路 http://micropython.org/webrepl)直接使用, 通過執行
以下指令進行配置:
import webrepl_setup
按照螢幕的提示操作。重新開機後，允許使用WebREPL。如果你禁用了開機自動啟動WebREPL,
可以通過以下指令使用:
import webrepl
webrepl.start()
# 也可在在開始時候設定一個密碼
webrepl.start(password='mypass')
這個 WebREPL 通過連接配接到ESP32的AP使用,如果你的路由器配網絡配置正确，這個功能
也可以通過STA方式使用，那意味着你可以同時上網和調試ESP32。(如果遇到不可行的
特殊情況， 請先使用ESP32 AP方式)。
除了終端/指令符的通路方式, WebREPL同時允許傳輸檔案 (包含上傳和下載下傳)。Web用戶端有相應的
功能按鈕，也可以通過 ``webrepl_cli.py``子產品上存儲的指令行進行操作。
有關将檔案傳輸到ESP32其他支援的替代方法，請參閱MicroPython論壇。