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

+.. _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 <https://docs.espressif.com/projects/esp-idf/en/latest/index.html>`_
+for details.

docs/esp32/tutorial/intro.rst

+.. _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 <https://micropython.org/download#esp32>`_.
+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: `<https://github.com/espressif/esptool/>`__, 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.

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

docs/library/esp.rst

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

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

docs/templates/topindex.html

@@ -53,6 +53,10 @@
         <a class="biglink" href="{{ pathto("esp8266/quickref") }}">Quick reference for the ESP8266</a><br/>
         <span class="linkdescr">pinout for ESP8266-based boards, snippets of useful code, and a tutorial</span>
       </p>
+      <p class="biglink">
+        <a class="biglink" href="{{ pathto("esp32/quickref") }}">Quick reference for the ESP32</a><br/>
+        <span class="linkdescr">pinout for ESP32-based boards, snippets of useful code, and a tutorial</span>
+      </p>
       <p class="biglink">
         <a class="biglink" href="{{ pathto("wipy/quickref") }}">Quick reference for the WiPy/CC3200</a><br/>
         <span class="linkdescr">pinout for the WiPy/CC3200, snippets of useful code, and a tutorial</span>