micropython/docs/esp32/quickref.rst

+.. _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/index.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 Fahrenheit
+    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
+----------
+
+WLAN
+^^^^
+
+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('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
+
+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('ssid', 'key')
+            while not wlan.isconnected():
+                pass
+        print('network config:', wlan.ifconfig())
+
+Once the network is established the :mod:`socket <socket>` module can be used
+to create and use TCP/UDP sockets as usual, and the ``urequests`` module for
+convenient HTTP requests.
+
+After a call to ``wlan.connect()``, the device will by default retry to connect
+**forever**, even when the authentication failed or no AP is in range.
+``wlan.status()`` will return ``network.STAT_CONNECTING`` in this state until a
+connection succeeds or the interface gets disabled.  This can be changed by
+calling ``wlan.config(reconnects=n)``, where n are the number of desired reconnect
+attempts (0 means it won't retry, -1 will restore the default behaviour of trying
+to reconnect forever).
+
+LAN
+^^^
+
+To use the wired interfaces one has to specify the pins and mode ::
+
+    import network
+
+    lan = network.LAN(mdc=PIN_MDC, ...)   # Set the pin and mode configuration
+    lan.active(True)                      # activate the interface
+    lan.ifconfig()                        # get the interface's IP/netmask/gw/DNS addresses
+
+
+The keyword arguments for the constructor defining the PHY type and interface are:
+
+- mdc=pin-object    # set the mdc and mdio pins.
+- mdio=pin-object
+- power=pin-object  # set the pin which switches the power of the PHY device.
+- phy_type=<type>   # Select the PHY device type. Supported devices are PHY_LAN8710,
+  PHY_LAN8720, PH_IP101, PHY_RTL8201, PHY_DP83848 and PHY_KSZ8041
+- phy_addr=number   # The address number of the PHY device.
+- ref_clk_mode=mode # Defines, whether the ref_clk at the ESP32 is an input
+  or output. Suitable values are Pin.IN and Pin.OUT.
+- ref_clk=pin-object  # defines the Pin used for ref_clk.
+
+The options ref_clk_mode and ref_clk require at least esp-idf version 4.4. For
+earlier esp-idf versions, these parameters must be defined by kconfig board options.
+
+These are working configurations for LAN interfaces of popular boards::
+
+    # Olimex ESP32-GATEWAY: power controlled by Pin(5)
+    # Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
+                      phy_type=network.PHY_LAN8720, phy_addr=0)
+
+    # or with dynamic ref_clk pin configuration
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5), 
+                      phy_type=network.PHY_LAN8720, phy_addr=0,
+                      ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
+
+    # Wireless-Tag's WT32-ETH01
+
+    lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
+                      phy_type=network.PHY_LAN8720, phy_addr=1, power=None)
+
+    # Espressif ESP32-Ethernet-Kit_A_V1.2
+
+    lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
+                      phy_type=network.PHY_IP101, phy_addr=1)
+
+A suitable definition of the PHY interface in a sdkconfig.board file is::
+
+    CONFIG_ETH_PHY_INTERFACE_RMII=y
+    CONFIG_ETH_RMII_CLK_OUTPUT=y
+    CONFIG_ETH_RMII_CLK_OUT_GPIO=17
+    CONFIG_LWIP_LOCAL_HOSTNAME="ESP32_POE"
+
+The value assigned to CONFIG_ETH_RMII_CLK_OUT_GPIO may vary depending on the
+board's wiring.
+
+Delay and timing
+----------------
+
+Use the :mod:`time <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
+------
+
+The ESP32 port has four hardware timers. Use the :ref:`machine.Timer <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.
+
+.. _Pins_and_GPIO:
+
+Pins and GPIO
+-------------
+
+Use the :ref:`machine.Pin <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
+    p6 = Pin(6, Pin.OUT, drive=Pin.DRIVE_3) # set maximum drive strength
+
+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.
+
+Four drive strengths are supported, using the ``drive`` keyword argument to the
+``Pin()`` constructor or ``Pin.init()`` method, with different corresponding
+safe maximum source/sink currents and approximate internal driver resistances:
+
+ - ``Pin.DRIVE_0``: 5mA / 130 ohm
+ - ``Pin.DRIVE_1``: 10mA / 60 ohm
+ - ``Pin.DRIVE_2``: 20mA / 30 ohm (default strength if not configured)
+ - ``Pin.DRIVE_3``: 40mA / 15 ohm
+
+The ``hold=`` keyword argument to ``Pin()`` and ``Pin.init()`` will enable the
+ESP32 "pad hold" feature. When set to ``True``, the pin configuration
+(direction, pull resistors and output value) will be held and any further
+changes (including changing the output level) will not be applied. Setting
+``hold=False`` will immediately apply any outstanding pin configuration changes
+and release the pin. Using ``hold=True`` while a pin is already held will apply
+any configuration changes and then immediately reapply the hold.
+
+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
+
+* See :ref:`Deep_sleep_Mode` for a discussion of pin behaviour during sleep
+
+There's a higher-level abstraction :ref:`machine.Signal <machine.Signal>`
+which can be used to invert a pin. Useful for illuminating active-low LEDs
+using ``on()`` or ``value(1)``.
+
+UART (serial bus)
+-----------------
+
+See :ref:`machine.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
+
+The ESP32 has three hardware UARTs: UART0, UART1 and UART2.
+They each have default GPIO assigned to them, however depending on your
+ESP32 variant and board, these pins may conflict with embedded flash,
+onboard PSRAM or peripherals.
+
+Any GPIO can be used for hardware UARTs using the GPIO matrix, except for
+input-only pins 34-39 that can be used as ``rx``. To avoid conflicts simply
+provide ``tx`` and ``rx`` pins when constructing. The default pins listed
+below.
+
+=====  =====  =====  =====
+\      UART0  UART1  UART2
+=====  =====  =====  =====
+tx     1      10     17
+rx     3      9      16
+=====  =====  =====  =====
+
+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 <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/ledc.html>`_
+for more details.
+
+Use the :ref:`machine.PWM <machine.PWM>` class::
+
+    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 chips have different hardware peripherals:
+
+=====================================================  ========  ========  ========
+Hardware specification                                    ESP32  ESP32-S2  ESP32-C3
+-----------------------------------------------------  --------  --------  --------
+Number of groups (speed modes)                                2         1         1
+Number of timers per group                                    4         4         4
+Number of channels per group                                  8         8         6
+-----------------------------------------------------  --------  --------  --------
+Different PWM frequencies (groups * timers)                   8         4         4
+Total PWM channels (Pins, duties) (groups * channels)        16         8         6
+=====================================================  ========  ========  ========
+
+A maximum number of PWM channels (Pins) are available on the ESP32 - 16 channels,
+but only 8 different PWM frequencies are available, the remaining 8 channels must
+have the same frequency.  On the other hand, 16 independent PWM duty cycles are
+possible at the same frequency.
+
+See more examples in the :ref:`esp32_pwm` tutorial.
+
+ADC (analog to digital conversion)
+----------------------------------
+
+On the ESP32, ADC functionality is available on pins 32-39 (ADC block 1) and
+pins 0, 2, 4, 12-15 and 25-27 (ADC block 2).
+
+Use the :ref:`machine.ADC <machine.ADC>` class::
+
+    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 block 2 is also used by WiFi and so attempting to read analog values from
+block 2 pins when WiFi is active will raise an exception.
+
+The internal ADC reference voltage is typically 1.1V, but varies slightly from
+package to package. The ADC is less linear close to the reference voltage
+(particularly at higher attenuations) and has a minimum measurement voltage
+around 100mV, voltages at or below this will read as 0. To read voltages
+accurately, it is recommended to use the ``read_uv()`` method (see below).
+
+ESP32-specific ADC class method reference:
+
+.. class:: ADC(pin, *, atten)
+
+    Return the ADC object for the specified pin. ESP32 does not support
+    different timings for ADC sampling and so the ``sample_ns`` keyword argument
+    is not supported.
+
+    To read voltages above the reference voltage, apply input attenuation with
+    the ``atten`` keyword argument. Valid values (and approximate linear
+    measurement ranges) are:
+
+      - ``ADC.ATTN_0DB``: No attenuation (100mV - 950mV)
+      - ``ADC.ATTN_2_5DB``: 2.5dB attenuation (100mV - 1250mV)
+      - ``ADC.ATTN_6DB``: 6dB attenuation (150mV - 1750mV)
+      - ``ADC.ATTN_11DB``: 11dB attenuation (150mV - 2450mV)
+
+.. Warning::
+   Note that the absolute maximum voltage rating for input pins is 3.6V. Going
+   near to this boundary risks damage to the IC!
+
+.. method:: ADC.read_uv()
+
+    This method uses the known characteristics of the ADC and per-package eFuse
+    values - set during manufacture - to return a calibrated input voltage
+    (before attenuation) in microvolts. The returned value has only millivolt
+    resolution (i.e., will always be a multiple of 1000 microvolts).
+
+    The calibration is only valid across the linear range of the ADC. In
+    particular, an input tied to ground will read as a value above 0 microvolts.
+    Within the linear range, however, more accurate and consistent results will
+    be obtained than using `read_u16()` and scaling the result with a constant.
+
+The ESP32 port also supports the :ref:`machine.ADC <machine.ADCBlock>` API:
+
+.. class:: ADCBlock(id, *, bits)
+
+    Return the ADC block object with the given ``id`` (1 or 2) and initialize
+    it to the specified resolution (9 to 12-bits depending on the ESP32 series)
+    or the highest supported resolution if not specified.
+
+.. method:: ADCBlock.connect(pin)
+            ADCBlock.connect(channel)
+            ADCBlock.connect(channel, pin)
+
+    Return the ``ADC`` object for the specified ADC pin or channel number.
+    Arbitrary connection of ADC channels to GPIO is not supported and so
+    specifying a pin that is not connected to this block, or specifying a
+    mismatched channel and pin, will raise an exception.
+
+Legacy methods:
+
+.. method:: ADC.read()
+
+    This method returns the raw ADC value ranged according to the resolution of
+    the block, e.g., 0-4095 for 12-bit resolution.
+
+.. method:: ADC.atten(atten)
+
+    Equivalent to ``ADC.init(atten=atten)``.
+
+.. method:: ADC.width(bits)
+
+    Equivalent to ``ADC.block().init(bits=bits)``.
+
+For compatibility, the ``ADC`` object also provides constants matching the
+supported ADC resolutions:
+
+  - ``ADC.WIDTH_9BIT`` = 9
+  - ``ADC.WIDTH_10BIT`` = 10
+  - ``ADC.WIDTH_11BIT`` = 11
+  - ``ADC.WIDTH_12BIT`` = 12
+
+
+Software SPI bus
+----------------
+
+Software SPI (using bit-banging) works on all pins, and is accessed via the
+:ref:`machine.SoftSPI <machine.SoftSPI>` class::
+
+    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
+
+.. 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 transmission
+rates (up to 80Mhz). These may be used on any IO pins that support the
+required direction and are otherwise unused (see :ref:`Pins_and_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 :ref:`machine.SPI <machine.SPI>` class and
+has the same methods as software SPI above::
+
+    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))
+
+Software I2C bus
+----------------
+
+Software I2C (using bit-banging) works on all output-capable pins, and is
+accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
+
+    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
+
+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 <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)
+
+I2S bus
+-------
+
+See :ref:`machine.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
+
+The I2S class is currently available as a Technical Preview.  During the preview period, feedback from
+users is encouraged.  Based on this feedback, the I2S class API and implementation may be changed.
+
+ESP32 has two I2S buses with id=0 and id=1
+
+Real time clock (RTC)
+---------------------
+
+See :ref:`machine.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 (Watchdog timer)
+--------------------
+
+See :ref:`machine.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()
+
+.. _Deep_sleep_mode:
+
+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
+
+Some ESP32 pins (0, 2, 4, 12-15, 25-27, 32-39) are connected to the RTC during
+deep-sleep and can be used to wake the device with the ``wake_on_`` functions in
+the :mod:`esp32` module. The output-capable RTC pins (all except 34-39) will
+also retain their pull-up or pull-down resistor configuration when entering
+deep-sleep.
+
+If the pull resistors are not actively required during deep-sleep and are likely
+to cause current leakage (for example a pull-up resistor is connected to ground
+through a switch), then they should be disabled to save power before entering
+deep-sleep mode::
+
+    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)
+
+Output-configured RTC pins will also retain their output direction and level in
+deep-sleep if pad hold is enabled with the ``hold=True`` argument to
+``Pin.init()``.
+
+Non-RTC GPIO pins will be disconnected by default on entering deep-sleep.
+Configuration of non-RTC pins - including output level - can be retained by
+enabling pad hold on the pin and enabling GPIO pad hold during deep-sleep::
+
+    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)
+
+The pin configuration - including the pad hold - will be retained on wake from
+sleep. See :ref:`Pins_and_GPIO` above for a further discussion of pad holding.
+
+SD card
+-------
+
+See :ref:`machine.SDCard <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
+---
+
+The RMT is ESP32-specific and allows generation of accurate digital pulses with
+12.5ns resolution.  See :ref:`esp32.RMT <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), 0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
+
+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 and APA106 driver
+--------------------------
+
+Use the ``neopixel`` and ``apa106`` modules::
+
+    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
+
+
+The APA106 driver extends NeoPixel, but internally uses a different colour order::
+
+    from apa106 import APA106
+    ap = APA106(pin, 8)
+    r, g, b = ap[0]
+
+.. 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.
+
+For low-level driving of a NeoPixel see `machine.bitstream`.
+This low-level driver uses an RMT channel by default.  To configure this see
+`RMT.bitstream_channel`.
+
+APA102 (DotStar) uses a different driver as it has an additional clock pin.
+
+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.lightsleep()        # put the MCU to sleep until a touchpad is touched
+
+For more details on touchpads refer to `Espressif Touch Sensor
+<https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/touch_pad.html>`_.
+
+
+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.

micropython/docs/esp32/tutorial/index.rst

+.. _esp32_tutorial:
+
+MicroPython tutorial for ESP32
+==============================
+
+This tutorial is intended to get you started using MicroPython on the ESP32
+system-on-a-chip.  If it is your first time it is recommended to follow the
+tutorial through in the order below.  Otherwise the sections are mostly self
+contained, so feel free to skip to those that interest you.
+
+The tutorial does not assume that you know Python, but it also does not attempt
+to explain any of the details of the Python language.  Instead it provides you
+with commands that are ready to run, and hopes that you will gain a bit of
+Python knowledge along the way.  To learn more about Python itself please refer
+to `<https://www.python.org>`__.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   pwm.rst
+   peripheral_access.rst

micropython/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.

micropython/docs/esp32/tutorial/peripheral_access.rst

+Accessing peripherals directly via registers
+============================================
+
+The ESP32's peripherals can be controlled via direct register reads and writes.
+This requires reading the datasheet to know what registers to use and what
+values to write to them.  The following example shows how to turn on and change
+the prescaler of the MCPWM0 peripheral.
+
+.. code-block:: python3
+
+    from micropython import const
+    from machine import mem32
+
+    # Define the register addresses that will be used.
+    DR_REG_DPORT_BASE = const(0x3FF00000)
+    DPORT_PERIP_CLK_EN_REG = const(DR_REG_DPORT_BASE + 0x0C0)
+    DPORT_PERIP_RST_EN_REG = const(DR_REG_DPORT_BASE + 0x0C4)
+    DPORT_PWM0_CLK_EN = const(1 << 17)
+    MCPWM0 = const(0x3FF5E000)
+    MCPWM1 = const(0x3FF6C000)
+
+    # Enable CLK and disable RST.
+    print(hex(mem32[DPORT_PERIP_CLK_EN_REG] & 0xffffffff))
+    print(hex(mem32[DPORT_PERIP_RST_EN_REG] & 0xffffffff))
+    mem32[DPORT_PERIP_CLK_EN_REG] |= DPORT_PWM0_CLK_EN
+    mem32[DPORT_PERIP_RST_EN_REG] &= ~DPORT_PWM0_CLK_EN
+    print(hex(mem32[DPORT_PERIP_CLK_EN_REG] & 0xffffffff))
+    print(hex(mem32[DPORT_PERIP_RST_EN_REG] & 0xffffffff))
+
+    # Change the MCPWM0 prescaler.
+    print(hex(mem32[MCPWM0])) # read PWM_CLK_CFG_REG (reset value = 0)
+    mem32[MCPWM0] = 0x55      # change PWM_CLK_PRESCALE
+    print(hex(mem32[MCPWM0])) # read PWM_CLK_CFG_REG
+
+Note that before a peripheral can be used its clock must be enabled and it must
+be taken out of reset.  In the above example the following registers are used
+for this:
+
+- ``DPORT_PERI_CLK_EN_REG``: used to enable a peripheral clock
+
+- ``DPORT_PERI_RST_EN_REG``: used to reset (or take out of reset) a peripheral
+
+The MCPWM0 peripheral is in bit position 17 of the above two registers, hence
+the value of ``DPORT_PWM0_CLK_EN``.

micropython/docs/esp32/tutorial/pwm.rst

+.. _esp32_pwm:
+
+Pulse Width Modulation
+======================
+
+Pulse width modulation (PWM) is a way to get an artificial analog output on a
+digital pin.  It achieves this by rapidly toggling the pin from low to high.
+There are two parameters associated with this: the frequency of the toggling,
+and the duty cycle.  The duty cycle is defined to be how long the pin is high
+compared with the length of a single period (low plus high time).  Maximum
+duty cycle is when the pin is high all of the time, and minimum is when it is
+low all of the time.
+
+* More comprehensive example with all 16 PWM channels and 8 timers::
+
+    from machine import Pin, PWM
+    try:
+        f = 100  # Hz
+        d = 1024 // 16  # 6.25%
+        pins = (15, 2, 4, 16, 18, 19, 22, 23, 25, 26, 27, 14 , 12, 13, 32, 33)
+        pwms = []
+        for i, pin in enumerate(pins):
+            pwms.append(PWM(Pin(pin), freq=f * (i // 2 + 1), duty= 1023 if i==15 else d * (i + 1)))
+            print(pwms[i])
+    finally:
+        for pwm in pwms:
+            try:
+                pwm.deinit()
+            except:
+                pass
+
+  Output is::
+
+    PWM(Pin(15), freq=100, duty=64, resolution=10, mode=0, channel=0, timer=0)
+    PWM(Pin(2), freq=100, duty=128, resolution=10, mode=0, channel=1, timer=0)
+    PWM(Pin(4), freq=200, duty=192, resolution=10, mode=0, channel=2, timer=1)
+    PWM(Pin(16), freq=200, duty=256, resolution=10, mode=0, channel=3, timer=1)
+    PWM(Pin(18), freq=300, duty=320, resolution=10, mode=0, channel=4, timer=2)
+    PWM(Pin(19), freq=300, duty=384, resolution=10, mode=0, channel=5, timer=2)
+    PWM(Pin(22), freq=400, duty=448, resolution=10, mode=0, channel=6, timer=3)
+    PWM(Pin(23), freq=400, duty=512, resolution=10, mode=0, channel=7, timer=3)
+    PWM(Pin(25), freq=500, duty=576, resolution=10, mode=1, channel=0, timer=0)
+    PWM(Pin(26), freq=500, duty=640, resolution=10, mode=1, channel=1, timer=0)
+    PWM(Pin(27), freq=600, duty=704, resolution=10, mode=1, channel=2, timer=1)
+    PWM(Pin(14), freq=600, duty=768, resolution=10, mode=1, channel=3, timer=1)
+    PWM(Pin(12), freq=700, duty=832, resolution=10, mode=1, channel=4, timer=2)
+    PWM(Pin(13), freq=700, duty=896, resolution=10, mode=1, channel=5, timer=2)
+    PWM(Pin(32), freq=800, duty=960, resolution=10, mode=1, channel=6, timer=3)
+    PWM(Pin(33), freq=800, duty=1023, resolution=10, mode=1, channel=7, timer=3)
+
+* Example of a smooth frequency change::
+
+    from utime import sleep
+    from machine import Pin, PWM
+
+    F_MIN = 500
+    F_MAX = 1000
+
+    f = F_MIN
+    delta_f = 1
+
+    p = PWM(Pin(5), f)
+    print(p)
+
+    while True:
+        p.freq(f)
+
+        sleep(10 / F_MIN)
+
+        f += delta_f
+        if f >= F_MAX or f <= F_MIN:
+            delta_f = -delta_f
+
+  See PWM wave at Pin(5) with an oscilloscope.
+
+* Example of a smooth duty change::
+
+    from utime import sleep
+    from machine import Pin, PWM
+
+    DUTY_MAX = 2**16 - 1
+
+    duty_u16 = 0
+    delta_d = 16
+
+    p = PWM(Pin(5), 1000, duty_u16=duty_u16)
+    print(p)
+
+    while True:
+        p.duty_u16(duty_u16)
+
+        sleep(1 / 1000)
+
+        duty_u16 += delta_d
+        if duty_u16 >= DUTY_MAX:
+            duty_u16 = DUTY_MAX
+            delta_d = -delta_d
+        elif duty_u16 <= 0:
+            duty_u16 = 0
+            delta_d = -delta_d
+
+  See PWM wave at Pin(5) with an oscilloscope.
+
+Note: the Pin.OUT mode does not need to be specified.  The channel is initialized
+to PWM mode internally once for each Pin that is passed to the PWM constructor.
+
+The following code is wrong::
+
+    pwm = PWM(Pin(5, Pin.OUT), freq=1000, duty=512)  # Pin(5) in PWM mode here
+    pwm = PWM(Pin(5, Pin.OUT), freq=500, duty=256)  # Pin(5) in OUT mode here, PWM is off
+
+Use this code instead::
+
+    pwm = PWM(Pin(5), freq=1000, duty=512)
+    pwm.init(freq=500, duty=256)

micropython/docs/esp8266/general.rst

+.. _esp8266_general:
+
+General information about the ESP8266 port
+==========================================
+
+ESP8266 is a popular WiFi-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 ESP8266 chip. MicroPython tries to provide a generic port which would run on
+as many boards/modules as possible, but there may be limitations. Adafruit
+Feather HUZZAH board is taken as a reference board for the port (for example,
+testing is performed on it). If you have another board, please make sure you
+have a datasheet, schematics and other reference materials for your board
+handy to look up various aspects of your board functioning.
+
+To make a generic ESP8266 port and support as many boards as possible,
+the following design and implementation decision were made:
+
+* GPIO pin numbering is based on ESP8266 chip numbering, not some "logical"
+  numbering of a particular board. Please have the manual/pin diagram of your board
+  at hand to find correspondence between your board pins and actual ESP8266 pins.
+  We also encourage users of various boards to share this mapping via MicroPython
+  forum, with the idea to collect community-maintained reference materials
+  eventually.
+* All pins which make sense to support, are supported by MicroPython
+  (for example, pins which are used to connect SPI flash
+  are not exposed, as they're unlikely useful for anything else, and
+  operating on them will lead to board lock-up). However, any particular
+  board may expose only subset of pins. Consult your board reference manual.
+* Some boards may lack external pins/internal connectivity to support
+  ESP8266 deepsleep mode.
+
+
+Technical specifications and SoC datasheets
+-------------------------------------------
+
+The datasheets and other reference material for ESP8266 chip are available
+from the vendor site: http://bbs.espressif.com/viewtopic.php?f=67&t=225 .
+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 lx106
+* CPU frequency: 80MHz overclockable to 160MHz
+* Total RAM available: 96KB (part of it reserved for system)
+* BootROM: 64KB
+* Internal FlashROM: None
+* External FlashROM: code and data, via SPI Flash. Normal sizes 512KB-4MB.
+* GPIO: 16 + 1 (GPIOs are multiplexed with other functions, including
+  external FlashROM, UART, deep sleep wake-up, etc.)
+* UART: One RX/TX UART (no hardware handshaking), one TX-only UART.
+* SPI: 2 SPI interfaces (one used for FlashROM).
+* I2C: No native external I2C (bitbang implementation available on any pins).
+* I2S: 1.
+* Programming: using BootROM bootloader from UART. Due to external FlashROM
+  and always-available BootROM bootloader, ESP8266 is not brickable.
+
+
+Scarcity of runtime resources
+-----------------------------
+
+ESP8266 has very modest resources (first of all, RAM memory). So, please
+avoid allocating too big container objects (lists, dictionaries) and
+buffers. There is also no full-fledged OS to keep track of resources
+and automatically clean them up, so that's the task of a user/user
+application: please be sure to close open files, sockets, etc. as soon
+as possible after use.
+
+
+Boot process
+------------
+
+On boot, MicroPython EPS8266 port executes ``_boot.py`` script from internal
+frozen modules. It mounts filesystem in FlashROM, or if it's not available,
+performs first-time setup of the module and creates the filesystem. This
+part of the boot process is considered fixed, and not available for customization
+for end users (even if you build from source, please refrain from changes to
+it; customization of early boot process is available only to advanced users
+and developers, who can diagnose themselves any issues arising from
+modifying the standard process).
+
+Once the filesystem is mounted, ``boot.py`` is executed from it. The standard
+version of this file is created during first-time module set up and has
+commands to start a WebREPL daemon (disabled by default, configurable
+with ``webrepl_setup`` module), etc. This
+file is customizable by end users (for example, you may want to set some
+parameters or add other services which should be run on
+a module start-up). But keep in mind that incorrect modifications to boot.py
+may still lead to boot loops or lock ups, requiring to reflash a module
+from scratch. (In particular, it's recommended that you use either
+``webrepl_setup`` module or manual editing to configure WebREPL, but not
+both).
+
+As a final step of boot procedure, ``main.py`` is executed from filesystem,
+if exists. This file is a hook to start up a user application each time
+on boot (instead of going to REPL). For small test applications, you may
+name them directly as ``main.py``, and upload to module, but instead it's
+recommended to keep your application(s) in separate files, and have just
+the following in ``main.py``::
+
+    import my_app
+    my_app.main()
+
+This will allow to keep the structure of your application clear, as well as
+allow to install multiple applications on a board, and switch among them.
+
+
+Known Issues
+------------
+
+Real-time clock
+~~~~~~~~~~~~~~~
+
+RTC in ESP8266 has very bad accuracy, drift may be seconds per minute. As
+a workaround, to measure short enough intervals you can use
+``time.time()``, etc. functions, and for wall clock time, synchronize from
+the net using included ``ntptime.py`` module.
+
+Due to limitations of the ESP8266 chip the internal real-time clock (RTC)
+will overflow every 7:45h.  If a long-term working RTC time is required then
+``time()`` or ``localtime()`` must be called at least once within 7 hours.
+MicroPython will then handle the overflow.
+
+Simultaneous operation of STA_IF and AP_IF
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Simultaneous operation of STA_IF and AP_IF interfaces is supported.
+
+However, due to restrictions of the hardware, there may be performance
+issues in the AP_IF, if the STA_IF is not connected and searching.
+An application should manage these interfaces and for example
+deactivate the STA_IF in environments where only the AP_IF is used.
+
+Sockets and WiFi buffers overflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Socket instances remain active until they are explicitly closed. This has two
+consequences. Firstly they occupy RAM, so an application which opens sockets
+without closing them may eventually run out of memory. Secondly not properly
+closed socket can cause the low-level part of the vendor WiFi stack to emit
+``Lmac`` errors. This occurs if data comes in for a socket and is not
+processed in a timely manner. This can overflow the WiFi stack input queue
+and lead to a deadlock. The only recovery is by a hard reset.
+
+The above may also happen after an application terminates and quits to the REPL
+for any reason including an exception. Subsequent arrival of data provokes the
+failure with the above error message repeatedly issued. So, sockets should be
+closed in any case, regardless whether an application terminates successfully
+or by an exception, for example using try/finally::
+
+    sock = socket(...)
+    try:
+        # Use sock
+    finally:
+        sock.close()
+
+
+SSL/TLS limitations
+~~~~~~~~~~~~~~~~~~~
+
+ESP8266 uses `axTLS <http://axtls.sourceforge.net/>`_ library, which is one
+of the smallest TLS libraries with compatible licensing. However, it
+also has some known issues/limitations:
+
+1. No support for Diffie-Hellman (DH) key exchange and Elliptic-curve
+   cryptography (ECC). This means it can't work with sites which require
+   the use of these features (it works ok with the typical sites that use
+   RSA certificates).
+2. Half-duplex communication nature. axTLS uses a single buffer for both
+   sending and receiving, which leads to considerable memory saving and
+   works well with protocols like HTTP. But there may be problems with
+   protocols which don't follow classic request-response model.
+
+Besides axTLS's own limitations, the configuration used for MicroPython is
+highly optimized for code size, which leads to additional limitations
+(these may be lifted in the future):
+
+3. Optimized RSA algorithms are not enabled, which may lead to slow
+   SSL handshakes.
+4. Session Reuse is not enabled, which means every connection must undergo
+   the full, expensive SSL handshake.
+
+Besides axTLS specific limitations described above, there's another generic
+limitation with usage of TLS on the low-memory devices:
+
+5. The TLS standard specifies the maximum length of the TLS record (unit
+   of TLS communication, the entire record must be buffered before it can
+   be processed) as 16KB. That's almost half of the available ESP8266 memory,
+   and inside a more or less advanced application would be hard to allocate
+   due to memory fragmentation issues. As a compromise, a smaller buffer is
+   used, with the idea that the most interesting usage for SSL would be
+   accessing various REST APIs, which usually require much smaller messages.
+   The buffers size is on the order of 5KB, and is adjusted from time to
+   time, taking as a reference being able to access https://google.com .
+   The smaller buffer however means that some sites can't be accessed using
+   it, and it's not possible to stream large amounts of data. axTLS does
+   have support for TLS's Max Fragment Size extension, but no HTTPS website
+   does, so use of the extension is really only effective for local
+   communication with other devices.
+
+There are also some not implemented features specifically in MicroPython's
+``ssl`` module based on axTLS:
+
+6. Certificates are not validated (this makes connections susceptible
+   to man-in-the-middle attacks).
+7. There is no support for client certificates (scheduled to be fixed in
+   1.9.4 release).

micropython/docs/esp8266/quickref.rst

+.. _esp8266_quickref:
+
+Quick reference for the ESP8266
+===============================
+
+.. image:: img/adafruit_products_pinoutstop.jpg
+    :alt: Adafruit Feather HUZZAH board
+    :width: 640px
+
+The Adafruit Feather HUZZAH board (image attribution: Adafruit).
+
+Below is a quick reference for ESP8266-based boards.  If it is your first time
+working with this board please consider reading the following sections first:
+
+.. toctree::
+   :maxdepth: 1
+
+   general.rst
+   tutorial/index.rst
+
+Installing MicroPython
+----------------------
+
+See the corresponding section of tutorial: :ref:`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(160000000) # set the CPU frequency to 160 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)
+
+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('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.active(True)         # activate the interface
+    ap.config(ssid='ESP-AP') # set the SSID of the access point
+
+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('ssid', 'key')
+            while not wlan.isconnected():
+                pass
+        print('network config:', wlan.ifconfig())
+
+Once the network is established the :mod:`socket <socket>` module can be used
+to create and use TCP/UDP sockets as usual.
+
+Delay and timing
+----------------
+
+Use the :mod:`time <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 <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 <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: 0, 1, 2, 3, 4, 5, 12, 13, 14, 15, 16, which correspond
+to the actual GPIO pin numbers of ESP8266 chip. Note that many end-user
+boards use their own adhoc pin numbering (marked e.g. D0, D1, ...). As
+MicroPython supports different boards and modules, physical pin numbering
+was chosen as the lowest common denominator. For mapping between board
+logical pins and physical chip pins, consult your board documentation.
+
+Note that Pin(1) and Pin(3) are REPL UART TX and RX respectively.
+Also note that Pin(16) is a special pin (used for wakeup from deepsleep
+mode) and may be not available for use with higher-level classes like
+``Neopixel``.
+
+There's a higher-level abstraction :ref:`machine.Signal <machine.Signal>`
+which can be used to invert a pin. Useful for illuminating active-low LEDs
+using ``on()`` or ``value(1)``.
+
+UART (serial bus)
+-----------------
+
+See :ref:`machine.UART <machine.UART>`. ::
+
+    from machine import UART
+    uart = UART(0, baudrate=9600)
+    uart.write('hello')
+    uart.read(5) # read up to 5 bytes
+
+Two UARTs are available. UART0 is on Pins 1 (TX) and 3 (RX). UART0 is
+bidirectional, and by default is used for the REPL. UART1 is on Pins 2
+(TX) and 8 (RX) however Pin 8 is used to connect the flash chip, so
+UART1 is TX only.
+
+When UART0 is attached to the REPL, all incoming chars on UART(0) go
+straight to stdin so uart.read() will always return None.  Use
+sys.stdin.read() if it's needed to read characters from the UART(0)
+while it's also used for the REPL (or detach, read, then reattach).
+When detached the UART(0) can be used for other purposes.
+
+If there are no objects in any of the dupterm slots when the REPL is
+started (on hard or soft reset) then UART(0) is automatically attached.
+Without this, the only way to recover a board without a REPL would be to
+completely erase and reflash (which would install the default boot.py which
+attaches the REPL).
+
+To detach the REPL from UART0, use::
+
+    import os
+    os.dupterm(None, 1)
+
+The REPL is attached by default. If you have detached it, to reattach
+it use::
+
+    import os, machine
+    uart = machine.UART(0, 115200)
+    os.dupterm(uart, 1)
+
+PWM (pulse width modulation)
+----------------------------
+
+PWM can be enabled on all pins except Pin(16).  There is a single frequency
+for all channels, with range between 1 and 1000 (measured in Hz).  The duty
+cycle is between 0 and 1023 inclusive.
+
+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=500, duty=512) # create and configure in one go
+
+ADC (analog to digital conversion)
+----------------------------------
+
+ADC is available on a dedicated pin.
+Note that input voltages on the ADC pin must be between 0v and 1.0v.
+
+Use the :ref:`machine.ADC <machine.ADC>` class::
+
+    from machine import ADC
+
+    adc = ADC(0)            # create ADC object on ADC pin
+    adc.read()              # read value, 0-1024
+
+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.SoftSPI <machine.SoftSPI>`
+class::
+
+    from machine import Pin, SoftSPI
+
+    # 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 = 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
+
+
+Hardware SPI bus
+----------------
+
+The hardware SPI is faster (up to 80Mhz), but only works on following pins:
+``MISO`` is GPIO12, ``MOSI`` is GPIO13, and ``SCK`` is GPIO14. It has the same
+methods as the bitbanging SPI class above, except for the pin parameters for the
+constructor and init (as those are fixed)::
+
+    from machine import Pin, SPI
+
+    hspi = SPI(1, baudrate=80000000, polarity=0, phase=0)
+
+(``SPI(0)`` is used for FlashROM and not available to users.)
+
+I2C bus
+-------
+
+The I2C driver is implemented in software and works on all pins,
+and is accessed via the :ref:`machine.I2C <machine.I2C>` class (which is an
+alias of :ref:`machine.SoftI2C <machine.SoftI2C>`)::
+
+    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 peripheral device with address 0x3a
+    i2c.writeto(0x3a, '12') # write '12' to peripheral device with address 0x3a
+
+    buf = bytearray(10)     # create a buffer with 10 bytes
+    i2c.writeto(0x3a, buf)  # write the given buffer to the peripheral
+
+Real time clock (RTC)
+---------------------
+
+See :ref:`machine.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
+
+    # synchronize with ntp
+    # need to be connected to wifi
+    import ntptime
+    ntptime.settime() # set the rtc datetime from the remote server
+    rtc.datetime()    # get the date and time in UTC
+
+.. note:: Not all methods are implemented: `RTC.now()`, `RTC.irq(handler=*) <RTC.irq>`
+          (using a custom handler), `RTC.init()` and `RTC.deinit()` are
+          currently not supported.
+
+WDT (Watchdog timer)
+--------------------
+
+See :ref:`machine.WDT <machine.WDT>`. ::
+
+    from machine import WDT
+
+    # enable the WDT
+    wdt = WDT()
+    wdt.feed()
+
+Deep-sleep mode
+---------------
+
+Connect GPIO16 to the reset pin (RST on HUZZAH).  Then the following code
+can be used to sleep, wake and check the reset cause::
+
+    import machine
+
+    # configure RTC.ALARM0 to be able to wake the device
+    rtc = machine.RTC()
+    rtc.irq(trigger=rtc.ALARM0, wake=machine.DEEPSLEEP)
+
+    # check if the device woke from a deep sleep
+    if machine.reset_cause() == machine.DEEPSLEEP_RESET:
+        print('woke from a deep sleep')
+
+    # set RTC.ALARM0 to fire after 10 seconds (waking the device)
+    rtc.alarm(rtc.ALARM0, 10000)
+
+    # put the device to sleep
+    machine.deepsleep()
+
+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
+
+.. 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.
+
+For low-level driving of a NeoPixel see `machine.bitstream`.
+
+APA102 driver
+-------------
+
+Use the ``apa102`` module::
+
+    from machine import Pin
+    from apa102 import APA102
+
+    clock = Pin(14, Pin.OUT)     # set GPIO14 to output to drive the clock
+    data = Pin(13, Pin.OUT)      # set GPIO13 to output to drive the data
+    apa = APA102(clock, data, 8) # create APA102 driver on the clock and the data pin for 8 pixels
+    apa[0] = (255, 255, 255, 31) # set the first pixel to white with a maximum brightness of 31
+    apa.write()                  # write data to all pixels
+    r, g, b, brightness = apa[0] # get first pixel colour
+
+For low-level driving of an APA102::
+
+    import esp
+    esp.apa102_write(clock_pin, data_pin, rgbi_buf)
+
+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)
+
+SSD1306 driver
+--------------
+
+Driver for SSD1306 monochrome OLED displays. See tutorial :ref:`ssd1306`. ::
+
+    from machine import Pin, I2C
+    import ssd1306
+
+    i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000)
+    display = ssd1306.SSD1306_I2C(128, 64, i2c)
+
+    display.text('Hello World', 0, 0, 1)
+    display.show()
+
+WebREPL (web browser interactive prompt)
+----------------------------------------
+
+WebREPL (REPL over WebSockets, accessible via a web browser) is an
+experimental feature available in ESP8266 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()
+
+The supported way to use WebREPL is by connecting to ESP8266 access point,
+but the daemon is also started on STA interface if it is active, so if your
+router is set up and works correctly, you may also use WebREPL while connected
+to your normal Internet access point (use the ESP8266 AP connection method
+if you face any issues).
+
+Besides terminal/command prompt access, WebREPL also has provision for file
+transfer (both upload and download). Web client has buttons for the
+corresponding functions, or you can use command-line client ``webrepl_cli.py``
+from the repository above.
+
+See the MicroPython forum for other community-supported alternatives
+to transfer files to ESP8266.

micropython/docs/esp8266/tutorial/adc.rst

+Analog to Digital Conversion
+============================
+
+The ESP8266 has a single pin (separate to the GPIO pins) which can be used to
+read analog voltages and convert them to a digital value.  You can construct
+such an ADC pin object using::
+
+    >>> import machine
+    >>> adc = machine.ADC(0)
+
+Then read its value with::
+
+    >>> adc.read()
+    58
+
+The values returned from the ``read()`` function are between 0 (for 0.0 volts)
+and 1024 (for 1.0 volts).  Please note that this input can only tolerate a
+maximum of 1.0 volts and you must use a voltage divider circuit to measure
+larger voltages.

micropython/docs/esp8266/tutorial/apa102.rst

+Controlling APA102 LEDs
+=======================
+
+APA102 LEDs, also known as DotStar LEDs, are individually addressable
+full-colour RGB LEDs, generally in a string formation. They differ from
+NeoPixels in that they require two pins to control - both a Clock and Data pin.
+They can operate at a much higher data and PWM frequencies than NeoPixels and
+are more suitable for persistence-of-vision effects.
+
+To create an APA102 object do the following::
+
+    >>> import machine, apa102
+    >>> strip = apa102.APA102(machine.Pin(5), machine.Pin(4), 60)
+
+This configures an 60 pixel APA102 strip with clock on GPIO5 and data on GPIO4.
+You can adjust the pin numbers and the number of pixels to suit your needs.
+
+The RGB colour data, as well as a brightness level, is sent to the APA102 in a
+certain order.  Usually this is ``(Red, Green, Blue, Brightness)``.
+If you are using one of the newer APA102C LEDs the green and blue are swapped,
+so the order is ``(Red, Blue, Green, Brightness)``.
+The APA102 has more of a square lens while the APA102C has more of a round one.
+If you are using a APA102C strip and would prefer to provide colours in RGB
+order instead of RBG, you can customise the tuple colour order like so::
+
+    >>> strip.ORDER = (0, 2, 1, 3)
+
+To set the colour of pixels use::
+
+    >>> strip[0] = (255, 255, 255, 31) # set to white, full brightness
+    >>> strip[1] = (255, 0, 0, 31) # set to red, full brightness
+    >>> strip[2] = (0, 255, 0, 15) # set to green, half brightness
+    >>> strip[3] = (0, 0, 255, 7)  # set to blue, quarter brightness
+
+Use the ``write()`` method to output the colours to the LEDs::
+
+    >>> strip.write()
+
+Demonstration::
+
+    import time
+    import machine, apa102
+
+    # 1M strip with 60 LEDs
+    strip = apa102.APA102(machine.Pin(5), machine.Pin(4), 60)
+
+    brightness = 1  # 0 is off, 1 is dim, 31 is max
+
+    # Helper for converting 0-255 offset to a colour tuple
+    def wheel(offset, brightness):
+        # The colours are a transition r - g - b - back to r
+        offset = 255 - offset
+        if offset < 85:
+            return (255 - offset * 3, 0, offset * 3, brightness)
+        if offset < 170:
+            offset -= 85
+            return (0, offset * 3, 255 - offset * 3, brightness)
+        offset -= 170
+        return (offset * 3, 255 - offset * 3, 0, brightness)
+
+    # Demo 1: RGB RGB RGB
+    red = 0xff0000
+    green = red >> 8
+    blue = red >> 16
+    for i in range(strip.n):
+        colour = red >> (i % 3) * 8
+        strip[i] = ((colour & red) >> 16, (colour & green) >> 8, (colour & blue), brightness)
+    strip.write()
+
+    # Demo 2: Show all colours of the rainbow
+    for i in range(strip.n):
+        strip[i] = wheel((i * 256 // strip.n) % 255, brightness)
+    strip.write()
+
+    # Demo 3: Fade all pixels together through rainbow colours, offset each pixel
+    for r in range(5):
+        for n in range(256):
+            for i in range(strip.n):
+                strip[i] = wheel(((i * 256 // strip.n) + n) & 255, brightness)
+            strip.write()
+        time.sleep_ms(25)
+
+    # Demo 4: Same colour, different brightness levels
+    for b in range(31,-1,-1):
+        strip[0] = (255, 153, 0, b)
+        strip.write()
+        time.sleep_ms(250)
+
+    # End: Turn off all the LEDs
+    strip.fill((0, 0, 0, 0))
+    strip.write()

micropython/docs/esp8266/tutorial/dht.rst

+Temperature and Humidity
+========================
+
+DHT (Digital Humidity & Temperature) sensors are low cost digital sensors with
+capacitive humidity sensors and thermistors to measure the surrounding air.
+They feature a chip that handles analog to digital conversion and provide a
+1-wire interface. Newer sensors additionally provide an I2C interface.
+
+The DHT11 (blue) and DHT22 (white) sensors provide the same 1-wire interface,
+however, the DHT22 requires a separate object as it has more complex
+calculation. DHT22 have 1 decimal place resolution for both humidity and
+temperature readings. DHT11 have whole number for both.
+
+A custom 1-wire protocol, which is different to Dallas 1-wire, is used to get
+the measurements from the sensor. The payload consists of a humidity value,
+a temperature value and a checksum.
+
+To use the 1-wire interface, construct the objects referring to their data pin::
+
+    >>> import dht
+    >>> import machine
+    >>> d = dht.DHT11(machine.Pin(4))
+
+    >>> import dht
+    >>> import machine
+    >>> d = dht.DHT22(machine.Pin(4))
+
+Then measure and read their values with::
+
+    >>> d.measure()
+    >>> d.temperature()
+    >>> d.humidity()
+
+Values returned from ``temperature()`` are in degrees Celsius and values
+returned from ``humidity()`` are a percentage of relative humidity.
+
+The DHT11 can be called no more than once per second and the DHT22 once every
+two seconds for most accurate results. Sensor accuracy will degrade over time.
+Each sensor supports a different operating range. Refer to the product
+datasheets for specifics.
+
+In 1-wire mode, only three of the four pins are used and in I2C mode, all four
+pins are used. Older sensors may still have 4 pins even though they do not
+support I2C. The 3rd pin is simply not connected.
+
+Pin configurations:
+
+Sensor without I2C in 1-wire mode (eg. DHT11, DHT22, AM2301, AM2302):
+
+    1=VDD, 2=Data, 3=NC, 4=GND
+
+Sensor with I2C in 1-wire mode (eg. DHT12, AM2320, AM2321, AM2322):
+
+    1=VDD, 2=Data, 3=GND, 4=GND
+
+Sensor with I2C in I2C mode (eg. DHT12, AM2320, AM2321, AM2322):
+
+    1=VDD, 2=SDA, 3=GND, 4=SCL
+
+You should use pull-up resistors for the Data, SDA and SCL pins.
+
+To make newer I2C sensors work in backwards compatible 1-wire mode, you must
+connect both pins 3 and 4 to GND. This disables the I2C interface.
+
+DHT22 sensors are now sold under the name AM2302 and are otherwise identical.

micropython/docs/esp8266/tutorial/filesystem.rst

+The internal filesystem
+=======================
+
+If your devices has 1Mbyte or more of storage then it will be set up (upon first
+boot) to contain a filesystem.  This filesystem uses the FAT format and is
+stored in the flash after the MicroPython firmware.
+
+Creating and reading files
+--------------------------
+
+MicroPython on the ESP8266 supports the standard way of accessing files in
+Python, using the built-in ``open()`` function.
+
+To create a file try::
+
+    >>> f = open('data.txt', 'w')
+    >>> f.write('some data')
+    9
+    >>> f.close()
+
+The "9" is the number of bytes that were written with the ``write()`` method.
+Then you can read back the contents of this new file using::
+
+    >>> f = open('data.txt')
+    >>> f.read()
+    'some data'
+    >>> f.close()
+
+Note that the default mode when opening a file is to open it in read-only mode,
+and as a text file.  Specify ``'wb'`` as the second argument to ``open()`` to
+open for writing in binary mode, and ``'rb'`` to open for reading in binary
+mode.
+
+Listing file and more
+---------------------
+
+The os module can be used for further control over the filesystem.  First
+import the module::
+
+    >>> import os
+
+Then try listing the contents of the filesystem::
+
+    >>> os.listdir()
+    ['boot.py', 'port_config.py', 'data.txt']
+
+You can make directories::
+
+    >>> os.mkdir('dir')
+
+And remove entries::
+
+    >>> os.remove('data.txt')
+
+Start up scripts
+----------------
+
+There are two files that are treated specially by the ESP8266 when it starts up:
+boot.py and main.py.  The boot.py script is executed first (if it exists) and
+then once it completes the main.py script is executed.  You can create these
+files yourself and populate them with the code that you want to run when the
+device starts up.
+
+Accessing the filesystem via WebREPL
+------------------------------------
+
+You can access the filesystem over WebREPL using the web client in a browser
+or via the command-line tool. Please refer to Quick Reference and Tutorial
+sections for more information about WebREPL.

micropython/docs/esp8266/tutorial/index.rst

+.. _esp8266_tutorial:
+
+MicroPython tutorial for ESP8266
+================================
+
+This tutorial is intended to get you started using MicroPython on the ESP8266
+system-on-a-chip.  If it is your first time it is recommended to follow the
+tutorial through in the order below.  Otherwise the sections are mostly self
+contained, so feel free to skip to those that interest you.
+
+The tutorial does not assume that you know Python, but it also does not attempt
+to explain any of the details of the Python language.  Instead it provides you
+with commands that are ready to run, and hopes that you will gain a bit of
+Python knowledge along the way.  To learn more about Python itself please refer
+to `<https://www.python.org>`__.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   repl.rst
+   filesystem.rst
+   network_basics.rst
+   network_tcp.rst
+   pins.rst
+   pwm.rst
+   adc.rst
+   powerctrl.rst
+   onewire.rst
+   neopixel.rst
+   apa102.rst
+   dht.rst
+   ssd1306.rst
+   nextsteps.rst

micropython/docs/esp8266/tutorial/intro.rst

+.. _intro:
+
+Getting started with MicroPython on the ESP8266
+===============================================
+
+Using MicroPython is a great way to get the most of your ESP8266 board.  And
+vice versa, the ESP8266 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 ESP8266 chip.  The MicroPython
+software supports the ESP8266 chip itself and any board should work.  The main
+characteristic of a board is how much flash it has, 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.
+
+The minimum requirement for flash size is 1Mbyte. There is also a special
+build for boards with 512KB, but it is highly limited comparing to the
+normal build: there is no support for filesystem, and thus features which
+depend on it won't work (WebREPL, mip, etc.). As such, 512KB build will
+be more interesting for users who build from source and fine-tune parameters
+for their particular application.
+
+Names of pins will be given in this tutorial using the chip names (eg GPIO0)
+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 ESP8266 device. You can download it from the
+`MicroPython downloads page <http://micropython.org/download#esp8266>`_.
+From here, you have 3 main choices
+
+* Stable firmware builds for 1024kb modules and above.
+* Daily firmware builds for 1024kb modules and above.
+* Daily firmware builds for 512kb modules.
+
+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 ESP8266 user
+who would like to follow development closely and help with testing new
+features, there are daily builds (note: you actually may need some
+development experience, e.g. being ready to follow git history to know
+what new changes and features were introduced).
+
+Support for 512kb modules is provided on a feature preview basis. For end
+users, it's recommended to use modules with flash of 1024kb or more. As
+such, only daily builds for 512kb modules are provided.
+
+Deploying the firmware
+----------------------
+
+Once you have the MicroPython firmware (compiled code), you need to load it onto
+your ESP8266 device.  There are two main steps to do this: first you
+need to put your device in boot-loader 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.
+
+If you have a board that has a USB connector, a USB-serial convertor, and has
+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 HUZZAH and NodeMCU boards.
+
+If you do not have such a board, you need keep GPIO0 pulled to ground and reset
+the device by pulling the reset pin to ground and releasing it again to enter
+programming mode.
+
+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.
+
+Any other flashing program should work, so feel free to try them out or refer
+to the documentation for your board to see its recommendations.
+
+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 --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20170108-v1.8.7.bin
+
+You might need to change the "port" setting to something else relevant for your
+PC.  You may also need to reduce the baudrate if you get errors when flashing
+(eg down to 115200).  The filename of the firmware should also match the file
+that you have.
+
+For some boards with a particular FlashROM configuration (e.g. some variants of
+a NodeMCU board) you may need to manually set a compatible
+`SPI Flash Mode <https://github.com/espressif/esptool/wiki/SPI-Flash-Modes>`_.
+You'd usually pick the fastest option that is compatible with your device, but
+the ``-fm dout`` option (the slowest option) should have the best compatibility::
+
+    esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dout 0 esp8266-20170108-v1.8.7.bin
+
+If the above commands run without error then MicroPython should be installed on
+your board!
+
+If you pulled GPIO0 manually to ground to enter programming mode, release it
+now and reset the device by again pulling the reset pin to ground for a short
+duration.
+
+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.  The next part of
+the tutorial will discuss the prompt in more detail.
+
+WiFi
+----
+
+After a fresh install and boot the device configures itself as a WiFi access
+point (AP) that you can connect to.  The ESSID is of the form MicroPython-xxxxxx
+where the x's are replaced with part of the MAC address of your device (so will
+be the same everytime, and most likely different for all ESP8266 chips).  The
+password for the WiFi is micropythoN (note the upper-case N).  Its IP address
+will be 192.168.4.1 once you connect to its network.  WiFi configuration will
+be discussed in more detail later in the tutorial.
+
+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. If you experience issues with self-made or wall-wart style power
+  supply, try USB power from a computer. Unearthed power supplies are also known
+  to cause problems as they source of increased EMI (electromagnetic interference)
+  - at the very least, and may lead to electrical devices breakdown. So, you are
+  advised to avoid using unearthed power connections when working with ESP8266
+  and other boards. In regard to FlashROM hardware problems, there are independent
+  (not related to MicroPython in any way) reports
+  `(e.g.) <http://internetofhomethings.com/homethings/?p=538>`_
+  that on some ESP8266 modules, FlashROM can be programmed as little as 20 times
+  before programming errors occur. This is *much* less than 100,000 programming
+  cycles cited for FlashROM chips of a type used with ESP8266 by reputable
+  vendors, which points to either production rejects, or second-hand worn-out
+  flash chips to be used on some (apparently cheap) modules/boards. You may want
+  to use your best judgement about source, price, documentation, warranty,
+  post-sales support for the modules/boards you purchase.
+
+* 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.
+
+* If lower baud rate didn't help, you may want to try older version of
+  esptool.py, which had a different programming algorithm::
+
+    pip install esptool==1.0.1
+
+  This version doesn't support ``--flash_size=detect`` option, so you will
+  need to specify FlashROM size explicitly (in megabits). It also requires
+  Python 2.7, so you may need to use ``pip2`` instead of ``pip`` in the
+  command above.
+
+* The ``--flash_size`` option in the commands above is mandatory. Omitting
+  it will lead to a corrupted firmware.
+
+* To catch incorrect flash content (e.g. from a defective sector on a chip),
+  add ``--verify`` switch to the commands above.
+
+* Additionally, you can check the firmware integrity from a MicroPython REPL
+  prompt (assuming you were able to flash it and ``--verify`` option doesn't
+  report errors)::
+
+    import esp
+    esp.check_fw()
+
+  If the last output value is True, the firmware is OK. Otherwise, it's
+  corrupted and need to be reflashed correctly.
+
+* If you experience any issues with another flashing application (not
+  esptool.py), try esptool.py, it is a generally accepted flashing
+  application in the ESP8266 community.
+
+* If you still experience problems with even flashing the firmware, please
+  refer to esptool.py project page, https://github.com/espressif/esptool
+  for additional documentation and bug tracker where you can report problems.
+
+* If you are able to flash firmware, but ``--verify`` option or
+  ``esp.check_fw()`` return errors even after multiple retries, you
+  may have a defective FlashROM chip, as explained above.

micropython/docs/esp8266/tutorial/neopixel.rst

+Controlling NeoPixels
+=====================
+
+NeoPixels, also known as WS2812 LEDs, are full-colour LEDs that are connected in
+serial, are individually addressable, and can have their red, green and blue
+components set between 0 and 255.  They require precise timing to control them
+and there is a special neopixel module to do just this.
+
+To create a NeoPixel object do the following::
+
+    >>> import machine, neopixel
+    >>> np = neopixel.NeoPixel(machine.Pin(4), 8)
+
+This configures a NeoPixel strip on GPIO4 with 8 pixels.  You can adjust the
+"4" (pin number) and the "8" (number of pixel) to suit your set up.
+
+To set the colour of pixels use::
+
+    >>> np[0] = (255, 0, 0) # set to red, full brightness
+    >>> np[1] = (0, 128, 0) # set to green, half brightness
+    >>> np[2] = (0, 0, 64)  # set to blue, quarter brightness
+
+For LEDs with more than 3 colours, such as RGBW pixels or RGBY pixels, the
+NeoPixel class takes a ``bpp`` parameter. To setup a NeoPixel object for an
+RGBW Pixel, do the following::
+
+    >>> import machine, neopixel
+    >>> np = neopixel.NeoPixel(machine.Pin(4), 8, bpp=4)
+
+In a 4-bpp mode, remember to use 4-tuples instead of 3-tuples to set the colour.
+For example to set the first three pixels use::
+
+    >>> np[0] = (255, 0, 0, 128) # Orange in an RGBY Setup
+    >>> np[1] = (0, 255, 0, 128) # Yellow-green in an RGBY Setup
+    >>> np[2] = (0, 0, 255, 128) # Green-blue in an RGBY Setup
+
+Then use the ``write()`` method to output the colours to the LEDs::
+
+    >>> np.write()
+
+The following demo function makes a fancy show on the LEDs::
+
+    import time
+
+    def demo(np):
+        n = np.n
+
+        # cycle
+        for i in range(4 * n):
+            for j in range(n):
+                np[j] = (0, 0, 0)
+            np[i % n] = (255, 255, 255)
+            np.write()
+            time.sleep_ms(25)
+
+        # bounce
+        for i in range(4 * n):
+            for j in range(n):
+                np[j] = (0, 0, 128)
+            if (i // n) % 2 == 0:
+                np[i % n] = (0, 0, 0)
+            else:
+                np[n - 1 - (i % n)] = (0, 0, 0)
+            np.write()
+            time.sleep_ms(60)
+
+        # fade in/out
+        for i in range(0, 4 * 256, 8):
+            for j in range(n):
+                if (i // 256) % 2 == 0:
+                    val = i & 0xff
+                else:
+                    val = 255 - (i & 0xff)
+                np[j] = (val, 0, 0)
+            np.write()
+
+        # clear
+        for i in range(n):
+            np[i] = (0, 0, 0)
+        np.write()
+
+Execute it using::
+
+    >>> demo(np)

micropython/docs/esp8266/tutorial/network_basics.rst

+Network basics
+==============
+
+The network module is used to configure the WiFi connection.  There are two WiFi
+interfaces, one for the station (when the ESP8266 connects to a router) and one
+for the access point (for other devices to connect to the ESP8266).  Create
+instances of these objects using::
+
+    >>> import network
+    >>> sta_if = network.WLAN(network.STA_IF)
+    >>> ap_if = network.WLAN(network.AP_IF)
+
+You can check if the interfaces are active by::
+
+    >>> sta_if.active()
+    False
+    >>> ap_if.active()
+    True
+
+You can also check the network settings of the interface by::
+
+    >>> ap_if.ifconfig()
+    ('192.168.4.1', '255.255.255.0', '192.168.4.1', '8.8.8.8')
+
+The returned values are: IP address, netmask, gateway, DNS.
+
+Configuration of the WiFi
+-------------------------
+
+Upon a fresh install the ESP8266 is configured in access point mode, so the
+AP_IF interface is active and the STA_IF interface is inactive.  You can
+configure the module to connect to your own network using the STA_IF interface.
+
+First activate the station interface::
+
+    >>> sta_if.active(True)
+
+Then connect to your WiFi network::
+
+    >>> sta_if.connect('<your SSID>', '<your key>')
+
+To check if the connection is established use::
+
+    >>> sta_if.isconnected()
+
+Once established you can check the IP address::
+
+    >>> sta_if.ifconfig()
+    ('192.168.0.2', '255.255.255.0', '192.168.0.1', '8.8.8.8')
+
+You can then disable the access-point interface if you no longer need it::
+
+    >>> ap_if.active(False)
+
+Here is a function you can run (or put in your boot.py file) to automatically
+connect to your WiFi network::
+
+    def do_connect():
+        import network
+        sta_if = network.WLAN(network.STA_IF)
+        if not sta_if.isconnected():
+            print('connecting to network...')
+            sta_if.active(True)
+            sta_if.connect('<ssid>', '<key>')
+            while not sta_if.isconnected():
+                pass
+        print('network config:', sta_if.ifconfig())
+
+Sockets
+-------
+
+Once the WiFi is set up the way to access the network is by using sockets.
+A socket represents an endpoint on a network device, and when two sockets are
+connected together communication can proceed.
+Internet protocols are built on top of sockets, such as email (SMTP), the web
+(HTTP), telnet, ssh, among many others.  Each of these protocols is assigned
+a specific port, which is just an integer.  Given an IP address and a port
+number you can connect to a remote device and start talking with it.
+
+The next part of the tutorial discusses how to use sockets to do some common
+and useful network tasks.

micropython/docs/esp8266/tutorial/network_tcp.rst

+Network - TCP sockets
+=====================
+
+The building block of most of the internet is the TCP socket.  These sockets
+provide a reliable stream of bytes between the connected network devices.
+This part of the tutorial will show how to use TCP sockets in a few different
+cases.
+
+Star Wars Asciimation
+---------------------
+
+The simplest thing to do is to download data from the internet.  In this case
+we will use the Star Wars Asciimation service provided by the blinkenlights.nl
+website.  It uses the telnet protocol on port 23 to stream data to anyone that
+connects.  It's very simple to use because it doesn't require you to
+authenticate (give a username or password), you can just start downloading data
+straight away.
+
+The first thing to do is make sure we have the socket module available::
+
+    >>> import socket
+
+Then get the IP address of the server::
+
+    >>> addr_info = socket.getaddrinfo("towel.blinkenlights.nl", 23)
+
+The ``getaddrinfo`` function actually returns a list of addresses, and each
+address has more information than we need.  We want to get just the first valid
+address, and then just the IP address and port of the server.  To do this use::
+
+    >>> addr = addr_info[0][-1]
+
+If you type ``addr_info`` and ``addr`` at the prompt you will see exactly what
+information they hold.
+
+Using the IP address we can make a socket and connect to the server::
+
+    >>> s = socket.socket()
+    >>> s.connect(addr)
+
+Now that we are connected we can download and display the data::
+
+    >>> while True:
+    ...     data = s.recv(500)
+    ...     print(str(data, 'utf8'), end='')
+    ...
+
+When this loop executes it should start showing the animation (use ctrl-C to
+interrupt it).
+
+You should also be able to run this same code on your PC using normal Python if
+you want to try it out there.
+
+HTTP GET request
+----------------
+
+The next example shows how to download a webpage.  HTTP uses port 80 and you
+first need to send a "GET" request before you can download anything.  As part
+of the request you need to specify the page to retrieve.
+
+Let's define a function that can download and print a URL::
+
+    def http_get(url):
+        import socket
+        _, _, host, path = url.split('/', 3)
+        addr = socket.getaddrinfo(host, 80)[0][-1]
+        s = socket.socket()
+        s.connect(addr)
+        s.send(bytes('GET /%s HTTP/1.0\r\nHost: %s\r\n\r\n' % (path, host), 'utf8'))
+        while True:
+            data = s.recv(100)
+            if data:
+                print(str(data, 'utf8'), end='')
+            else:
+                break
+        s.close()
+
+Then you can try::
+
+    >>> http_get('http://micropython.org/ks/test.html')
+
+This should retrieve the webpage and print the HTML to the console.
+
+Simple HTTP server
+------------------
+
+The following code creates an simple HTTP server which serves a single webpage
+that contains a table with the state of all the GPIO pins::
+
+    import machine
+    pins = [machine.Pin(i, machine.Pin.IN) for i in (0, 2, 4, 5, 12, 13, 14, 15)]
+
+    html = """<!DOCTYPE html>
+    <html>
+        <head> <title>ESP8266 Pins</title> </head>
+        <body> <h1>ESP8266 Pins</h1>
+            <table border="1"> <tr><th>Pin</th><th>Value</th></tr> %s </table>
+        </body>
+    </html>
+    """
+
+    import socket
+    addr = socket.getaddrinfo('0.0.0.0', 80)[0][-1]
+
+    s = socket.socket()
+    s.bind(addr)
+    s.listen(1)
+
+    print('listening on', addr)
+
+    while True:
+        cl, addr = s.accept()
+        print('client connected from', addr)
+        cl_file = cl.makefile('rwb', 0)
+        while True:
+            line = cl_file.readline()
+            if not line or line == b'\r\n':
+                break
+        rows = ['<tr><td>%s</td><td>%d</td></tr>' % (str(p), p.value()) for p in pins]
+        response = html % '\n'.join(rows)
+        cl.send('HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n')
+        cl.send(response)
+        cl.close()

micropython/docs/esp8266/tutorial/nextsteps.rst

+Next steps
+==========
+
+That brings us to the end of the tutorial!  Hopefully by now you have a good
+feel for the capabilities of MicroPython on the ESP8266 and understand how to
+control both the WiFi and IO aspects of the chip.
+
+There are many features that were not covered in this tutorial.  The best way
+to learn about them is to read the full documentation of the modules, and to
+experiment!
+
+Good luck creating your Internet of Things devices!

micropython/docs/esp8266/tutorial/onewire.rst

+Controlling 1-wire devices
+==========================
+
+The 1-wire bus is a serial bus that uses just a single wire for communication
+(in addition to wires for ground and power).  The DS18B20 temperature sensor
+is a very popular 1-wire device, and here we show how to use the onewire module
+to read from such a device.
+
+For the following code to work you need to have at least one DS18S20 or DS18B20 temperature
+sensor with its data line connected to GPIO12.  You must also power the sensors
+and connect a 4.7k Ohm resistor between the data pin and the power pin.  ::
+
+    import time
+    import machine
+    import onewire, ds18x20
+
+    # the device is on GPIO12
+    dat = machine.Pin(12)
+
+    # create the onewire object
+    ds = ds18x20.DS18X20(onewire.OneWire(dat))
+
+    # scan for devices on the bus
+    roms = ds.scan()
+    print('found devices:', roms)
+
+    # loop 10 times and print all temperatures
+    for i in range(10):
+        print('temperatures:', end=' ')
+        ds.convert_temp()
+        time.sleep_ms(750)
+        for rom in roms:
+            print(ds.read_temp(rom), end=' ')
+        print()
+
+Note that you must execute the ``convert_temp()`` function to initiate a
+temperature reading, then wait at least 750ms before reading the value.