From 69e72954ad4757f8e3faccef6333cb33842ce052 Mon Sep 17 00:00:00 2001 From: Matt Trentini Date: Tue, 22 Jan 2019 08:06:17 +1100 Subject: [PATCH] docs: Add initial docs for esp32 port, including quick-ref and general. With contributions from Oliver Robson (@HowManyOliversAreThere), Sean Lanigan (@seanlano) and @rprr. --- docs/esp32/general.rst | 63 +++++ docs/esp32/img/esp32.jpg | Bin 0 -> 86457 bytes docs/esp32/quickref.rst | 478 ++++++++++++++++++++++++++++++++++ docs/esp32/tutorial/intro.rst | 139 ++++++++++ docs/index.rst | 1 + docs/library/esp.rst | 26 +- docs/library/index.rst | 6 +- docs/templates/topindex.html | 4 + 8 files changed, 710 insertions(+), 7 deletions(-) create mode 100644 docs/esp32/general.rst create mode 100644 docs/esp32/img/esp32.jpg create mode 100644 docs/esp32/quickref.rst create mode 100644 docs/esp32/tutorial/intro.rst diff --git a/docs/esp32/general.rst b/docs/esp32/general.rst new file mode 100644 index 0000000000..51918d4e18 --- /dev/null +++ b/docs/esp32/general.rst @@ -0,0 +1,63 @@ +.. _esp32_general: + +General information about the ESP32 port +======================================== + +The ESP32 is a popular WiFi and Bluetooth enabled System-on-Chip (SoC) by +Espressif Systems. + +Multitude of boards +------------------- + +There is a multitude of modules and boards from different sources which carry +the ESP32 chip. MicroPython tries to provide a generic port which would run on +as many boards/modules as possible, but there may be limitations. Espressif +development boards are taken as reference for the port (for example, testing is +performed on them). For any board you are using please make sure you have a +datasheet, schematics and other reference materials so you can look up any +board-specific functions. + +To make a generic ESP32 port and support as many boards as possible the +following design and implementation decision were made: + +* GPIO pin numbering is based on ESP32 chip numbering. Please have the manual/pin + diagram of your board at hand to find correspondence between your board pins and + actual ESP32 pins. +* All pins are supported by MicroPython but not all are usable on any given board. + For example pins that are connected to external SPI flash should not be used, + and a board may only expose a certain selection of pins. + + +Technical specifications and SoC datasheets +------------------------------------------- + +The datasheets and other reference material for ESP32 chip are available +from the vendor site: https://www.espressif.com/en/support/download/documents?keys=esp32 . +They are the primary reference for the chip technical specifications, capabilities, +operating modes, internal functioning, etc. + +For your convenience, some of technical specifications are provided below: + +* Architecture: Xtensa Dual-Core 32-bit LX6 +* CPU frequency: up to 240MHz +* Total RAM available: 528KB (part of it reserved for system) +* BootROM: 448KB +* Internal FlashROM: none +* External FlashROM: code and data, via SPI Flash; usual size 4MB +* GPIO: 34 (GPIOs are multiplexed with other functions, including + external FlashROM, UART, etc.) +* UART: 3 RX/TX UART (no hardware handshaking), one TX-only UART +* SPI: 4 SPI interfaces (one used for FlashROM) +* I2C: 2 I2C (bitbang implementation available on any pins) +* I2S: 2 +* ADC: 12-bit SAR ADC up to 18 channels +* DAC: 2 8-bit DACs +* Programming: using BootROM bootloader from UART - due to external FlashROM + and always-available BootROM bootloader, the ESP32 is not brickable + +For more information see the ESP32 datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf + +MicroPython is implemented on top of the ESP-IDF, Espressif's development +framework for the ESP32. This is a FreeRTOS based system. See the +`ESP-IDF Programming Guide `_ +for details. diff --git a/docs/esp32/img/esp32.jpg b/docs/esp32/img/esp32.jpg new file mode 100644 index 0000000000000000000000000000000000000000..a96ddcbe6a39a74bded948698db956998f9d6c5e GIT binary patch literal 86457 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 z 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 literal 0 HcmV?d00001 diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst new file mode 100644 index 0000000000..81b2a53b39 --- /dev/null +++ b/docs/esp32/quickref.rst @@ -0,0 +1,478 @@ +.. _esp32_quickref: + +Quick reference for the ESP32 +============================= + +.. image:: img/esp32.jpg + :alt: ESP32 board + :width: 640px + +The Espressif ESP32 Development Board (image attribution: 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: + +.. toctree:: + :maxdepth: 1 + + general.rst + tutorial/intro.rst + +Installing MicroPython +---------------------- + +See the corresponding section of tutorial: :ref:`esp32_intro`. It also includes +a troubleshooting subsection. + +General board control +--------------------- + +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. + +The :mod:`machine` module:: + + import machine + + machine.freq() # get the current frequency of the CPU + machine.freq(240000000) # set the CPU frequency to 240 MHz + +The :mod:`esp` module:: + + 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) + +The :mod:`esp32` module:: + + 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. + +Networking +---------- + +The :mod:`network` module:: + + 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 adddress + 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.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 :mod:`socket ` module can be used +to create and use TCP/UDP sockets as usual, and the ``urequests`` module for +convenient HTTP requests. + +Delay and timing +---------------- + +Use the :mod:`time ` module:: + + 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 + +Timers +------ + +Virtual (RTOS-based) timers are supported. Use the :ref:`machine.Timer ` class +with timer ID of -1:: + + from machine import Timer + + tim = Timer(-1) + tim.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(1)) + tim.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(2)) + +The period is in milliseconds. + +Pins and GPIO +------------- + +Use the :ref:`machine.Pin ` class:: + + 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. + +Notes: + +* 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 + +PWM (pulse width modulation) +---------------------------- + +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*. See +`LED Control `_ +for more details. + +Use the ``machine.PWM`` class:: + + 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 (analog to digital conversion) +---------------------------------- + +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. + +Use the :ref:`machine.ADC ` class:: + + 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 attentuation (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: + +.. method:: 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 + +.. Warning:: + 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! + +.. method:: 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 bit data + - ``ADC.WIDTH_10BIT``: 10 bit data + - ``ADC.WIDTH_11BIT``: 11 bit data + - ``ADC.WIDTH_12BIT``: 12 bit data - this is the default configuration + +Software SPI bus +---------------- + +There are two SPI drivers. One is implemented in software (bit-banging) +and works on all pins, and is accessed via the :ref:`machine.SPI ` +class:: + + from machine import Pin, SPI + + # construct an SPI 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 = SPI(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 outputing 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 + +.. Warning:: + Currently *all* of ``sck``, ``mosi`` and ``miso`` *must* be specified when + initialising Software SPI. + +Hardware SPI bus +---------------- + +There are two hardware SPI channels that allow faster (up to 80Mhz) +transmission rates, but are only supported on a subset of pins. + +===== =========== ============ +\ HSPI (id=1) VSPI (id=2) +===== =========== ============ +sck 14 18 +mosi 13 23 +miso 12 19 +===== =========== ============ + +Hardware SPI 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 bus +------- + +The I2C driver is implemented in software and works on all pins, +and is accessed via the :ref:`machine.I2C ` class:: + + from machine import Pin, I2C + + # construct an I2C bus + i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000) + + i2c.readfrom(0x3a, 4) # read 4 bytes from slave device with address 0x3a + i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a + + buf = bytearray(10) # create a buffer with 10 bytes + i2c.writeto(0x3a, buf) # write the given buffer to the slave + +Real time clock (RTC) +--------------------- + +See :ref:`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 + +Deep-sleep mode +--------------- + +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) + +Notes: + +* Calling ``deepsleep()`` without an argument will put the device to sleep + indefinitely +* A software reset does not change the reset cause + +OneWire driver +-------------- + +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 driver +--------------- + +Use the ``neopixel`` module:: + + 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 + +For low-level driving of a NeoPixel:: + + import esp + esp.neopixel_write(pin, grb_buf, is800khz) + +.. Warning:: + By default ``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`` object. + + +Capacitive Touch +---------------- + +Use the ``TouchPad`` class in the ``machine`` module:: + + 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``. + +Note that TouchPads can be used to wake an ESP32 from sleep:: + + 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.sleep() # put the MCU to sleep until a touchpad is touched + +For more details on touchpads refer to `Espressif Touch Sensor +`_. + + +DHT driver +---------- + +The DHT driver is implemented in software and works on all pins:: + + 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 browser interactive prompt) +---------------------------------------- + +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. diff --git a/docs/esp32/tutorial/intro.rst b/docs/esp32/tutorial/intro.rst new file mode 100644 index 0000000000..4c56738347 --- /dev/null +++ b/docs/esp32/tutorial/intro.rst @@ -0,0 +1,139 @@ +.. _esp32_intro: + +Getting started with MicroPython on the ESP32 +============================================= + +Using MicroPython is a great way to get the most of your ESP32 board. And +vice versa, the ESP32 chip is a great platform for using MicroPython. This +tutorial will guide you through setting up MicroPython, getting a prompt, using +WebREPL, connecting to the network and communicating with the Internet, using +the hardware peripherals, and controlling some external components. + +Let's get started! + +Requirements +------------ + +The first thing you need is a board with an ESP32 chip. The MicroPython +software supports the ESP32 chip itself and any board should work. The main +characteristic of a board is how the GPIO pins are connected to the outside +world, and whether it includes a built-in USB-serial convertor to make the +UART available to your PC. + +Names of pins will be given in this tutorial using the chip names (eg GPIO2) +and it should be straightforward to find which pin this corresponds to on your +particular board. + +Powering the board +------------------ + +If your board has a USB connector on it then most likely it is powered through +this when connected to your PC. Otherwise you will need to power it directly. +Please refer to the documentation for your board for further details. + +Getting the firmware +-------------------- + +The first thing you need to do is download the most recent MicroPython firmware +.bin file to load onto your ESP32 device. You can download it from the +`MicroPython downloads page `_. +From here, you have 3 main choices: + +* Stable firmware builds +* Daily firmware builds +* Daily firmware builds with SPIRAM support + +If you are just starting with MicroPython, the best bet is to go for the Stable +firmware builds. If you are an advanced, experienced MicroPython ESP32 user +who would like to follow development closely and help with testing new +features, there are daily builds. If your board has SPIRAM support you can +use either the standard firmware or the firmware with SPIRAM support, and in +the latter case you will have access to more RAM for Python objects. + +Deploying the firmware +---------------------- + +Once you have the MicroPython firmware you need to load it onto your ESP32 device. +There are two main steps to do this: first you need to put your device in +bootloader mode, and second you need to copy across the firmware. The exact +procedure for these steps is highly dependent on the particular board and you will +need to refer to its documentation for details. + +Fortunately, most boards have a USB connector, a USB-serial convertor, and the DTR +and RTS pins wired in a special way then deploying the firmware should be easy as +all steps can be done automatically. Boards that have such features +include the Adafruit Feather HUZZAH32, M5Stack, Wemos LOLIN32, and TinyPICO +boards, along with the Espressif DevKitC, PICO-KIT, WROVER-KIT dev-kits. + +For best results it is recommended to first erase the entire flash of your +device before putting on new MicroPython firmware. + +Currently we only support esptool.py to copy across the firmware. You can find +this tool here: ``__, or install it +using pip:: + + pip install esptool + +Versions starting with 1.3 support both Python 2.7 and Python 3.4 (or newer). +An older version (at least 1.2.1 is needed) works fine but will require Python +2.7. + +Using esptool.py you can erase the flash with the command:: + + esptool.py --port /dev/ttyUSB0 erase_flash + +And then deploy the new firmware using:: + + esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z 0x1000 esp32-20180511-v1.9.4.bin + +Notes: + +* You might need to change the "port" setting to something else relevant for your + PC +* You may need to reduce the baudrate if you get errors when flashing + (eg down to 115200 by adding ``--baud 115200`` into the command) +* For some boards with a particular FlashROM configuration you may need to + change the flash mode (eg by adding ``-fm dio`` into the command) +* The filename of the firmware should match the file that you have + +If the above commands run without error then MicroPython should be installed on +your board! + +Serial prompt +------------- + +Once you have the firmware on the device you can access the REPL (Python prompt) +over UART0 (GPIO1=TX, GPIO3=RX), which might be connected to a USB-serial +convertor, depending on your board. The baudrate is 115200. + +From here you can now follow the ESP8266 tutorial, because these two Espressif chips +are very similar when it comes to using MicroPython on them. The ESP8266 tutorial +is found at :ref:`esp8266_tutorial` (but skip the Introduction section). + +Troubleshooting installation problems +------------------------------------- + +If you experience problems during flashing or with running firmware immediately +after it, here are troubleshooting recommendations: + +* Be aware of and try to exclude hardware problems. There are 2 common + problems: bad power source quality, and worn-out/defective FlashROM. + Speaking of power source, not just raw amperage is important, but also low + ripple and noise/EMI in general. The most reliable and convenient power + source is a USB port. + +* The flashing instructions above use flashing speed of 460800 baud, which is + good compromise between speed and stability. However, depending on your + module/board, USB-UART convertor, cables, host OS, etc., the above baud + rate may be too high and lead to errors. Try a more common 115200 baud + rate instead in such cases. + +* To catch incorrect flash content (e.g. from a defective sector on a chip), + add ``--verify`` switch to the commands above. + +* If you still experience problems with flashing the firmware please + refer to esptool.py project page, https://github.com/espressif/esptool + for additional documentation and a bug tracker where you can report problems. + +* If you are able to flash the firmware but the ``--verify`` option returns + errors even after multiple retries the you may have a defective FlashROM chip. diff --git a/docs/index.rst b/docs/index.rst index af5ffb885a..235185b6c2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,4 +9,5 @@ MicroPython documentation and references license.rst pyboard/quickref.rst esp8266/quickref.rst + esp32/quickref.rst wipy/quickref.rst diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 121a80d42e..867182be99 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -1,10 +1,12 @@ -:mod:`esp` --- functions related to the ESP8266 -=============================================== +:mod:`esp` --- functions related to the ESP8266 and ESP32 +========================================================= .. module:: esp - :synopsis: functions related to the ESP8266 + :synopsis: functions related to the ESP8266 and ESP32 -The ``esp`` module contains specific functions related to the ESP8266 module. +The ``esp`` module contains specific functions related to both the ESP8266 and +ESP32 modules. Some functions are only available on one or the other of these +ports. Functions @@ -12,6 +14,8 @@ Functions .. function:: sleep_type([sleep_type]) + **Note**: ESP8266 only + Get or set the sleep type. If the *sleep_type* parameter is provided, sets the sleep type to its @@ -29,6 +33,8 @@ Functions .. function:: deepsleep(time=0) + **Note**: ESP8266 only - use `machine.deepsleep()` on ESP32 + Enter deep sleep. The whole module powers down, except for the RTC clock circuit, which can @@ -38,8 +44,18 @@ Functions .. function:: flash_id() + **Note**: ESP8266 only + Read the device ID of the flash memory. +.. function:: flash_size() + + Read the total size of the flash memory. + +.. function:: flash_user_start() + + Read the memory offset at which the user flash space begins. + .. function:: flash_read(byte_offset, length_or_buffer) .. function:: flash_write(byte_offset, bytes) @@ -48,6 +64,8 @@ Functions .. function:: set_native_code_location(start, length) + **Note**: ESP8266 only + Set the location that native code will be placed for execution after it is compiled. Native code is emitted when the ``@micropython.native``, ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied diff --git a/docs/library/index.rst b/docs/library/index.rst index e37f1d6256..290192fa08 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -139,10 +139,10 @@ The following libraries and classes are specific to the WiPy. machine.TimerWiPy.rst -Libraries specific to the ESP8266 ---------------------------------- +Libraries specific to the ESP8266 and ESP32 +------------------------------------------- -The following libraries are specific to the ESP8266. +The following libraries are specific to the ESP8266 and ESP32. .. toctree:: :maxdepth: 2 diff --git a/docs/templates/topindex.html b/docs/templates/topindex.html index 675fae29fa..08bf4c73e7 100644 --- a/docs/templates/topindex.html +++ b/docs/templates/topindex.html @@ -53,6 +53,10 @@ Quick reference for the ESP8266
pinout for ESP8266-based boards, snippets of useful code, and a tutorial

+