diff options
Diffstat (limited to 'docs/esp8266/quickref.rst')
| -rw-r--r-- | docs/esp8266/quickref.rst | 375 |
1 files changed, 0 insertions, 375 deletions
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst deleted file mode 100644 index c510e4064..000000000 --- a/docs/esp8266/quickref.rst +++ /dev/null @@ -1,375 +0,0 @@ -.. _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). - -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('essid', 'password') # connect to an AP - wlan.config('mac') # get the interface's MAC adddress - wlan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses - - ap = network.WLAN(network.AP_IF) # create access-point interface - ap.active(True) # activate the interface - ap.config(essid='ESP-AP') # set the ESSID 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('essid', 'password') - while not wlan.isconnected(): - pass - print('network config:', wlan.ifconfig()) - -Once the network is established the :mod:`socket <usocket>` module can be used -to create and use TCP/UDP sockets as usual. - -Delay and timing ----------------- - -Use the :mod:`time <utime>` 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``. - -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.SPI <machine.SPI>` -class:: - - from machine import Pin, SPI - - # construct an SPI bus on the given pins - # polarity is the idle state of SCK - # phase=0 means sample on the first edge of SCK, phase=1 means the second - spi = SPI(-1, baudrate=100000, polarity=1, phase=0, sck=Pin(0), mosi=Pin(2), miso=Pin(4)) - - spi.init(baudrate=200000) # set the baudrate - - spi.read(10) # read 10 bytes on MISO - spi.read(10, 0xff) # read 10 bytes while outputing 0xff on MOSI - - buf = bytearray(50) # create a buffer - spi.readinto(buf) # read into the given buffer (reads 50 bytes in this case) - spi.readinto(buf, 0xff) # read into the given buffer and output 0xff on MOSI - - spi.write(b'12345') # write 5 bytes on MOSI - - buf = bytearray(4) # create a buffer - spi.write_readinto(b'1234', buf) # write to MOSI and read from MISO into the buffer - spi.write_readinto(buf, buf) # write buf to MOSI and read MISO back into buf - - -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:: - - from machine import Pin, I2C - - # construct an I2C bus - i2c = I2C(scl=Pin(5), sda=Pin(4), freq=100000) - - i2c.readfrom(0x3a, 4) # read 4 bytes from slave device with address 0x3a - i2c.writeto(0x3a, '12') # write '12' to slave device with address 0x3a - - buf = bytearray(10) # create a buffer with 10 bytes - i2c.writeto(0x3a, buf) # write the given buffer to the slave - -Real time clock (RTC) ---------------------- - -See :ref:`machine.RTC <machine.RTC>` :: - - from machine import RTC - - rtc = RTC() - rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time - rtc.datetime() # get date and time - -Deep-sleep mode ---------------- - -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 - -For low-level driving of a NeoPixel:: - - import esp - esp.neopixel_write(pin, grb_buf, is800khz) - -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) - -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. |