diff options
| author | Dan Halbert <halbert@halwitz.org> | 2018-02-27 22:03:52 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2018-02-27 22:03:52 -0500 |
| commit | 568c04e6afa8016062f685b2198c0209f62827f4 (patch) | |
| tree | d07b76119f715add462983b335797adf64b61249 /docs | |
| parent | 6a2379fd0bfe10017d8abc5c36ef1d470c0d9b27 (diff) | |
| parent | ea633117d01d94e8d56ed94344e4b3e46b4eef03 (diff) | |
Merge pull request #650 from tannewt/merge_2x3.0.0-alpha.2
Merge in commits from 2.x branch.
Diffstat (limited to 'docs')
159 files changed, 315 insertions, 13195 deletions
diff --git a/docs/c2rst.py b/docs/c2rst.py index 3018e62af..9ca8bc1bb 100644 --- a/docs/c2rst.py +++ b/docs/c2rst.py @@ -1,10 +1,18 @@ import sphinx.parsers -import docutils.parsers.rst as rst class CStrip(sphinx.parsers.Parser): - def __init(self): - self.rst_parser = rst.Parser() + def __init__(self): + self.rst_parser = sphinx.parsers.RSTParser() - def parse(self, inputstring, document): - print(inputstring) - self.rst_parser(stripped, document) + def parse(self, inputstring, document): + # This setting is missing starting with Sphinx 1.7.1 so we set it ourself. + document.settings.tab_width = 4 + stripped = [] + for line in inputstring.split("\n"): + line = line.strip() + if line == "//|": + stripped.append("") + elif line.startswith("//| "): + stripped.append(line[len("//| "):]) + stripped = "\r\n".join(stripped) + self.rst_parser.parse(stripped, document) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 3b25ccbf7..a1524eaa2 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -215,7 +215,7 @@ Renders as: Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Attributes are state on objects. (See `Getters/Setters` above for more discussion +Attributes are state on objects. (See `Getters/Setters`_ above for more discussion about when to use them.) They can be defined internally in a number of different ways. Each approach is enumerated below with an explanation of where the comment goes. @@ -400,10 +400,11 @@ For example, if you are writing a driver for an I2C device, then take in an I2C object instead of the pins themselves. This allows the calling code to provide any object with the appropriate methods such as an I2C expansion board. -Another example is to expect a `DigitalInOut` for a pin to toggle instead of a -`microcontroller.Pin` from `board`. Taking in the `~microcontroller.Pin` object -alone would limit the driver to pins on the actual microcontroller instead of pins -provided by another driver such as an IO expander. +Another example is to expect a :py:class:`~digitalio.DigitalInOut` for a pin to +toggle instead of a :py:class:`~microcontroller.Pin` from `board`. Taking in the +:py:class:`~microcontroller.Pin` object alone would limit the driver to pins on +the actual microcontroller instead of pins provided by another driver such as an +IO expander. Lots of small modules -------------------------------------------------------------------------------- @@ -441,7 +442,7 @@ Examples ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ustruct.pack -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use `ustruct.pack_into` instead of `ustruct.pack`. diff --git a/docs/differences/index_template.txt b/docs/differences/index_template.txt deleted file mode 100644 index eb8b3ba64..000000000 --- a/docs/differences/index_template.txt +++ /dev/null @@ -1,10 +0,0 @@ -.. _cpython_diffs: - -MicroPython differences from CPython -==================================== - -The operations listed in this section produce conflicting results in MicroPython when compared to standard Python. - -.. toctree:: - :maxdepth: 2 - diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst deleted file mode 100644 index 96a454532..000000000 --- a/docs/esp8266/general.rst +++ /dev/null @@ -1,187 +0,0 @@ -General information about the ESP8266 port -========================================== - -ESP8266 is a popular WiFi-enabled System-on-Chip (SoC) by Espressif Systems. - -Multitude of boards -------------------- - -There are 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 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, -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 -``utime.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. - -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 exeption, 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 the 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 force - the use of these features (it works ok with classic RSA certifactes). -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 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. Stored sessions are not supported (may allow faster repeated connections - to the same site in some circumstances). - -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 hower means that some sites can't be accessed using - it, and it's not possible to stream large amounts of data. diff --git a/docs/esp8266/img/adafruit_products_pinoutstop.jpg b/docs/esp8266/img/adafruit_products_pinoutstop.jpg Binary files differdeleted file mode 100644 index 655e27aee..000000000 --- a/docs/esp8266/img/adafruit_products_pinoutstop.jpg +++ /dev/null diff --git a/docs/esp8266/index.rst b/docs/esp8266/index.rst deleted file mode 100644 index 63cf65c61..000000000 --- a/docs/esp8266/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -ESP8266 -======================================== - -.. toctree:: - - quickref.rst - general.rst - tutorial/index.rst 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. diff --git a/docs/esp8266/tutorial/adc.rst b/docs/esp8266/tutorial/adc.rst deleted file mode 100644 index fa6fdaba7..000000000 --- a/docs/esp8266/tutorial/adc.rst +++ /dev/null @@ -1,19 +0,0 @@ -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. diff --git a/docs/esp8266/tutorial/dht.rst b/docs/esp8266/tutorial/dht.rst deleted file mode 100644 index 1602e8a33..000000000 --- a/docs/esp8266/tutorial/dht.rst +++ /dev/null @@ -1,65 +0,0 @@ -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. diff --git a/docs/esp8266/tutorial/filesystem.rst b/docs/esp8266/tutorial/filesystem.rst deleted file mode 100644 index 27b0d2608..000000000 --- a/docs/esp8266/tutorial/filesystem.rst +++ /dev/null @@ -1,69 +0,0 @@ -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. diff --git a/docs/esp8266/tutorial/index.rst b/docs/esp8266/tutorial/index.rst deleted file mode 100644 index 39b459260..000000000 --- a/docs/esp8266/tutorial/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _tutorial-index: - -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 - dht.rst - nextsteps.rst diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst deleted file mode 100644 index 711db3fce..000000000 --- a/docs/esp8266/tutorial/intro.rst +++ /dev/null @@ -1,202 +0,0 @@ -.. _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, upip, 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. - -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 use the following command to deploy -the firmware (note the ``-fm dio`` option):: - - esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dio 0 esp8266-20170108-v1.8.7.bin - -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. 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. diff --git a/docs/esp8266/tutorial/neopixel.rst b/docs/esp8266/tutorial/neopixel.rst deleted file mode 100644 index a1537526f..000000000 --- a/docs/esp8266/tutorial/neopixel.rst +++ /dev/null @@ -1,84 +0,0 @@ -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) diff --git a/docs/esp8266/tutorial/network_basics.rst b/docs/esp8266/tutorial/network_basics.rst deleted file mode 100644 index 95d8cba4f..000000000 --- a/docs/esp8266/tutorial/network_basics.rst +++ /dev/null @@ -1,81 +0,0 @@ -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 ESSID>', '<your password>') - -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('<essid>', '<password>') - 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. diff --git a/docs/esp8266/tutorial/network_tcp.rst b/docs/esp8266/tutorial/network_tcp.rst deleted file mode 100644 index 26a2f469c..000000000 --- a/docs/esp8266/tutorial/network_tcp.rst +++ /dev/null @@ -1,122 +0,0 @@ -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): - _, _, 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() - -Make sure that you import the socket module before running this function. 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(response) - cl.close() diff --git a/docs/esp8266/tutorial/nextsteps.rst b/docs/esp8266/tutorial/nextsteps.rst deleted file mode 100644 index 318bd7ddf..000000000 --- a/docs/esp8266/tutorial/nextsteps.rst +++ /dev/null @@ -1,12 +0,0 @@ -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! diff --git a/docs/esp8266/tutorial/onewire.rst b/docs/esp8266/tutorial/onewire.rst deleted file mode 100644 index c2cede9e3..000000000 --- a/docs/esp8266/tutorial/onewire.rst +++ /dev/null @@ -1,37 +0,0 @@ -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. diff --git a/docs/esp8266/tutorial/pins.rst b/docs/esp8266/tutorial/pins.rst deleted file mode 100644 index cd45c83cd..000000000 --- a/docs/esp8266/tutorial/pins.rst +++ /dev/null @@ -1,75 +0,0 @@ -GPIO Pins -========= - -The way to connect your board to the external world, and control other -components, is through the GPIO pins. Not all pins are available to use, -in most cases only pins 0, 2, 4, 5, 12, 13, 14, 15, and 16 can be used. - -The pins are available in the machine module, so make sure you import that -first. Then you can create a pin using:: - - >>> pin = machine.Pin(0) - -Here, the "0" is the pin that you want to access. Usually you want to -configure the pin to be input or output, and you do this when constructing -it. To make an input pin use:: - - >>> pin = machine.Pin(0, machine.Pin.IN, machine.Pin.PULL_UP) - -You can either use PULL_UP or None for the input pull-mode. If it's -not specified then it defaults to None, which is no pull resistor. -You can read the value on the pin using:: - - >>> pin.value() - 0 - -The pin on your board may return 0 or 1 here, depending on what it's connected -to. To make an output pin use:: - - >>> pin = machine.Pin(0, machine.Pin.OUT) - -Then set its value using:: - - >>> pin.value(0) - >>> pin.value(1) - -Or:: - - >>> pin.off() - >>> pin.on() - -External interrupts -------------------- - -All pins except number 16 can be configured to trigger a hard interrupt if their -input changes. You can set code (a callback function) to be executed on the -trigger. - -Let's first define a callback function, which must take a single argument, -being the pin that triggered the function. We will make the function just print -the pin:: - - >>> def callback(p): - ... print('pin change', p) - -Next we will create two pins and configure them as inputs:: - - >>> from machine import Pin - >>> p0 = Pin(0, Pin.IN) - >>> p2 = Pin(2, Pin.IN) - -An finally we need to tell the pins when to trigger, and the function to call -when they detect an event:: - - >>> p0.irq(trigger=Pin.IRQ_FALLING, handler=callback) - >>> p2.irq(trigger=Pin.IRQ_RISING | Pin.IRQ_FALLING, handler=callback) - -We set pin 0 to trigger only on a falling edge of the input (when it goes from -high to low), and set pin 2 to trigger on both a rising and falling edge. After -entering this code you can apply high and low voltages to pins 0 and 2 to see -the interrupt being executed. - -A hard interrupt will trigger as soon as the event occurs and will interrupt any -running code, including Python code. As such your callback functions are -limited in what they can do (they cannot allocate memory, for example) and -should be as short and simple as possible. diff --git a/docs/esp8266/tutorial/powerctrl.rst b/docs/esp8266/tutorial/powerctrl.rst deleted file mode 100644 index 3502624ab..000000000 --- a/docs/esp8266/tutorial/powerctrl.rst +++ /dev/null @@ -1,61 +0,0 @@ -Power control -============= - -The ESP8266 provides the ability to change the CPU frequency on the fly, and -enter a deep-sleep state. Both can be used to manage power consumption. - -Changing the CPU frequency --------------------------- - -The machine module has a function to get and set the CPU frequency. To get the -current frequency use:: - - >>> import machine - >>> machine.freq() - 80000000 - -By default the CPU runs at 80MHz. It can be change to 160MHz if you need more -processing power, at the expense of current consumption:: - - >>> machine.freq(160000000) - >>> machine.freq() - 160000000 - -You can change to the higher frequency just while your code does the heavy -processing and then change back when it's finished. - -Deep-sleep mode ---------------- - -The deep-sleep mode will shut down the ESP8266 and all its peripherals, -including the WiFi (but not including the real-time-clock, which is used to wake -the chip). This drastically reduces current consumption and is a good way to -make devices that can run for a while on a battery. - -To be able to use the deep-sleep feature you must connect GPIO16 to the reset -pin (RST on the Adafruit Feather HUZZAH board). Then the following code can be -used to sleep and wake the device:: - - import machine - - # configure RTC.ALARM0 to be able to wake the device - rtc = machine.RTC() - rtc.irq(trigger=rtc.ALARM0, wake=machine.DEEPSLEEP) - - # set RTC.ALARM0 to fire after 10 seconds (waking the device) - rtc.alarm(rtc.ALARM0, 10000) - - # put the device to sleep - machine.deepsleep() - -Note that when the chip wakes from a deep-sleep it is completely reset, -including all of the memory. The boot scripts will run as usual and you can -put code in them to check the reset cause to perhaps do something different if -the device just woke from a deep-sleep. For example, to print the reset cause -you can use:: - - if machine.reset_cause() == machine.DEEPSLEEP_RESET: - print('woke from a deep sleep') - else: - print('power on or hard reset') - diff --git a/docs/esp8266/tutorial/pwm.rst b/docs/esp8266/tutorial/pwm.rst deleted file mode 100644 index 17f8ede35..000000000 --- a/docs/esp8266/tutorial/pwm.rst +++ /dev/null @@ -1,87 +0,0 @@ -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. - -On the ESP8266 the pins 0, 2, 4, 5, 12, 13, 14 and 15 all support PWM. The -limitation is that they must all be at the same frequency, and the frequency -must be between 1Hz and 1kHz. - -To use PWM on a pin you must first create the pin object, for example:: - - >>> import machine - >>> p12 = machine.Pin(12) - -Then create the PWM object using:: - - >>> pwm12 = machine.PWM(p12) - -You can set the frequency and duty cycle using:: - - >>> pwm12.freq(500) - >>> pwm12.duty(512) - -Note that the duty cycle is between 0 (all off) and 1023 (all on), with 512 -being a 50% duty. If you print the PWM object then it will tell you its current -configuration:: - - >>> pwm12 - PWM(12, freq=500, duty=512) - -You can also call the ``freq()`` and ``duty()`` methods with no arguments to -get their current values. - -The pin will continue to be in PWM mode until you deinitialise it using:: - - >>> pwm12.deinit() - -Fading an LED -------------- - -Let's use the PWM feature to fade an LED. Assuming your board has an LED -connected to pin 2 (ESP-12 modules do) we can create an LED-PWM object using:: - - >>> led = machine.PWM(machine.Pin(2), freq=1000) - -Notice that we can set the frequency in the PWM constructor. - -For the next part we will use timing and some math, so import these modules:: - - >>> import time, math - -Then create a function to pulse the LED:: - - >>> def pulse(l, t): - ... for i in range(20): - ... l.duty(int(math.sin(i / 10 * math.pi) * 500 + 500)) - ... time.sleep(t/1000) - -You can try this function out using:: - - >>> pulse(led, 50) - -For a nice effect you can pulse many times in a row:: - - >>> for i in range(10): - ... pulse(led, 20) - -Remember you can use ctrl-C to interrupt the code. - -Control a hobby servo ---------------------- - -Hobby servo motors can be controlled using PWM. They require a frequency of -50Hz and then a duty between about 40 and 115, with 77 being the centre value. -If you connect a servo to the power and ground pins, and then the signal line -to pin 12 (other pins will work just as well), you can control the motor using:: - - >>> servo = machine.PWM(machine.Pin(12), freq=50) - >>> servo.duty(40) - >>> servo.duty(115) - >>> servo.duty(77) diff --git a/docs/esp8266/tutorial/repl.rst b/docs/esp8266/tutorial/repl.rst deleted file mode 100644 index ba64fcccb..000000000 --- a/docs/esp8266/tutorial/repl.rst +++ /dev/null @@ -1,212 +0,0 @@ -Getting a MicroPython REPL prompt -================================= - -REPL stands for Read Evaluate Print Loop, and is the name given to the -interactive MicroPython prompt that you can access on the ESP8266. Using the -REPL is by far the easiest way to test out your code and run commands. - -There are two ways to access the REPL: either via a wired connection through the -UART serial port, or via WiFi. - -REPL over the serial port -------------------------- - -The REPL is always available on the UART0 serial peripheral, which is connected -to the pins GPIO1 for TX and GPIO3 for RX. The baudrate of the REPL is 115200. -If your board has a USB-serial convertor on it then you should be able to access -the REPL directly from your PC. Otherwise you will need to have a way of -communicating with the UART. - -To access the prompt over USB-serial you need to use a terminal emulator program. -On Windows TeraTerm is a good choice, on Mac you can use the built-in screen -program, and Linux has picocom and minicom. Of course, there are many other -terminal programs that will work, so pick your favourite! - -For example, on Linux you can try running:: - - picocom /dev/ttyUSB0 -b115200 - -Once you have made the connection over the serial port you can test if it is -working by hitting enter a few times. You should see the Python REPL prompt, -indicated by ``>>>``. - -WebREPL - a prompt over WiFi ----------------------------- - -WebREPL allows you to use the Python prompt over WiFi, connecting through a -browser. The latest versions of Firefox and Chrome are supported. - -For your convenience, WebREPL client is hosted at -`<http://micropython.org/webrepl>`__ . Alternatively, you can install it -locally from the the GitHub repository -`<https://github.com/micropython/webrepl>`__ . - -Before connecting to WebREPL, you should set a password and enable it via -a normal serial connection. Initial versions of MicroPython for ESP8266 -came with WebREPL automatically enabled on the boot and with the -ability to set a password via WiFi on the first connection, but as WebREPL -was becoming more widely known and popular, the initial setup has switched -to a wired connection for improved security:: - - import webrepl_setup - -Follow the on-screen instructions and prompts. To make any changes active, -you will need to reboot your device. - -To use WebREPL connect your computer to the ESP8266's access point -(MicroPython-xxxxxx, see the previous section about this). If you have -already reconfigured your ESP8266 to connect to a router then you can -skip this part. - -Once you are on the same network as the ESP8266 you click the "Connect" button -(if you are connecting via a router then you may need to change the IP address, -by default the IP address is correct when connected to the ESP8266's access -point). If the connection succeeds then you should see a password prompt. - -Once you type the password configured at the setup step above, press Enter once -more and you should get a prompt looking like ``>>>``. You can now start -typing Python commands! - -Using the REPL --------------- - -Once you have a prompt you can start experimenting! Anything you type at the -prompt will be executed after you press the Enter key. MicroPython will run -the code that you enter and print the result (if there is one). If there is an -error with the text that you enter then an error message is printed. - -Try typing the following at the prompt:: - - >>> print('hello esp8266!') - hello esp8266! - -Note that you shouldn't type the ``>>>`` arrows, they are there to indicate that -you should type the text after it at the prompt. And then the line following is -what the device should respond with. In the end, once you have entered the text -``print("hello esp8266!")`` and pressed the Enter key, the output on your screen -should look exactly like it does above. - -If you already know some python you can now try some basic commands here. For -example:: - - >>> 1 + 2 - 3 - >>> 1 / 2 - 0.5 - >>> 12**34 - 4922235242952026704037113243122008064 - -If your board has an LED attached to GPIO2 (the ESP-12 modules do) then you can -turn it on and off using the following code:: - - >>> import machine - >>> pin = machine.Pin(2, machine.Pin.OUT) - >>> pin.on() - >>> pin.off() - -Note that ``on`` method of a Pin might turn the LED off and ``off`` might -turn it on (or vice versa), depending on how the LED is wired on your board. -To resolve this, machine.Signal class is provided. - -Line editing -~~~~~~~~~~~~ - -You can edit the current line that you are entering using the left and right -arrow keys to move the cursor, as well as the delete and backspace keys. Also, -pressing Home or ctrl-A moves the cursor to the start of the line, and pressing -End or ctrl-E moves to the end of the line. - -Input history -~~~~~~~~~~~~~ - -The REPL remembers a certain number of previous lines of text that you entered -(up to 8 on the ESP8266). To recall previous lines use the up and down arrow -keys. - -Tab completion -~~~~~~~~~~~~~~ - -Pressing the Tab key will do an auto-completion of the current word that you are -entering. This can be very useful to find out functions and methods that a -module or object has. Try it out by typing "ma" and then pressing Tab. It -should complete to "machine" (assuming you imported machine in the above -example). Then type "." and press Tab again to see a list of all the functions -that the machine module has. - -Line continuation and auto-indent -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Certain things that you type will need "continuing", that is, will need more -lines of text to make a proper Python statement. In this case the prompt will -change to ``...`` and the cursor will auto-indent the correct amount so you can -start typing the next line straight away. Try this by defining the following -function:: - - >>> def toggle(p): - ... p.value(not p.value()) - ... - ... - ... - >>> - -In the above, you needed to press the Enter key three times in a row to finish -the compound statement (that's the three lines with just dots on them). The -other way to finish a compound statement is to press backspace to get to the -start of the line, then press the Enter key. (If you did something wrong and -want to escape the continuation mode then press ctrl-C; all lines will be -ignored.) - -The function you just defined allows you to toggle a pin. The pin object you -created earlier should still exist (recreate it if it doesn't) and you can -toggle the LED using:: - - >>> toggle(pin) - -Let's now toggle the LED in a loop (if you don't have an LED then you can just -print some text instead of calling toggle, to see the effect):: - - >>> import time - >>> while True: - ... toggle(pin) - ... time.sleep_ms(500) - ... - ... - ... - >>> - -This will toggle the LED at 1Hz (half a second on, half a second off). To stop -the toggling press ctrl-C, which will raise a KeyboardInterrupt exception and -break out of the loop. - -The time module provides some useful functions for making delays and doing -timing. Use tab completion to find out what they are and play around with them! - -Paste mode -~~~~~~~~~~ - -Pressing ctrl-E will enter a special paste mode. This allows you to copy and -paste a chunk of text into the REPL. If you press ctrl-E you will see the -paste-mode prompt:: - - paste mode; Ctrl-C to cancel, Ctrl-D to finish - === - -You can then paste (or type) your text in. Note that none of the special keys -or commands work in paste mode (eg Tab or backspace), they are just accepted -as-is. Press ctrl-D to finish entering the text and execute it. - -Other control commands -~~~~~~~~~~~~~~~~~~~~~~ - -There are four other control commands: - -* Ctrl-A on a blank line will enter raw REPL mode. This is like a permanent - paste mode, except that characters are not echoed back. - -* Ctrl-B on a blank like goes to normal REPL mode. - -* Ctrl-C cancels any input, or interrupts the currently running code. - -* Ctrl-D on a blank line will do a soft reset. - -Note that ctrl-A and ctrl-D do not work with WebREPL. diff --git a/docs/esp8266_index.rst b/docs/esp8266_index.rst deleted file mode 100644 index 519acecda..000000000 --- a/docs/esp8266_index.rst +++ /dev/null @@ -1,12 +0,0 @@ -MicroPython documentation and references -======================================== - -.. toctree:: - - esp8266/quickref.rst - esp8266/general.rst - esp8266/tutorial/index.rst - library/index.rst - reference/index.rst - genrst/index.rst - license.rst diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 000000000..a85772fdc --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,54 @@ +Adafruit CircuitPython API Reference +==================================== + +Welcome to the API reference documentation for Adafruit CircuitPython. +This contains low-level API reference docs which may link out to separate +*"getting started"* guides. `Adafruit <https://adafruit.com>`_ has many +excellent tutorials available through the +`Adafruit Learning System <https://learn.adafruit.com/>`_. + +.. include:: ../README.rst + +.. _contents: + +Full Table of Contents +---------------------- + +.. toctree:: + :maxdepth: 3 + :caption: API and Usage + + ../shared-bindings/index.rst + supported_ports.rst + troubleshooting.rst + drivers.rst + +.. toctree:: + :maxdepth: 1 + :caption: Design and porting reference + + design_guide + porting + common_hal + +.. toctree:: + :maxdepth: 2 + :caption: MicroPython specific + + library/index.rst + +.. toctree:: + :maxdepth: 1 + :caption: About the project + + ../README + ../CONTRIBUTING + ../CODE_OF_CONDUCT + ../license.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/library/array.rst b/docs/library/array.rst index d096c6ec4..dfaef0ff6 100644 --- a/docs/library/array.rst +++ b/docs/library/array.rst @@ -1,10 +1,12 @@ :mod:`array` -- arrays of numeric data ====================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: array :synopsis: efficient arrays of numeric data -|see_cpython_module| :mod:`python:array`. +|see_cpython_module| :mod:`cpython:array`. Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``, ``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the diff --git a/docs/library/btree.rst b/docs/library/btree.rst index 8fac67e8d..303a936ad 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -1,6 +1,8 @@ :mod:`btree` -- simple BTree database ===================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: btree :synopsis: simple BTree database @@ -78,7 +80,7 @@ Functions .. function:: open(stream, \*, flags=0, pagesize=0, cachesize=0, minkeypage=0) - Open a database from a random-access `stream` (like an open file). All + Open a database from a random-access ``stream`` (like an open file). All other parameters are optional and keyword-only, and allow to tweak advanced parameters of the database operation (most users will not need them): diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst index 365248dc7..b45b6fe38 100644 --- a/docs/library/builtins.rst +++ b/docs/library/builtins.rst @@ -1,6 +1,12 @@ Builtin functions and exceptions ================================ +.. warning:: + + These builtins are inherited from MicroPython and may not work in CircuitPython + as documented or at all! If work differently from CPython, then their behavior + may change. + All builtin functions and exceptions are described here. They are also available via ``builtins`` module. @@ -21,7 +27,7 @@ Functions and types .. class:: bytes() - |see_cpython| `python:bytes`. + |see_cpython| `bytes`. .. function:: callable() @@ -176,7 +182,7 @@ Exceptions .. exception:: OSError - |see_cpython| `python:OSError`. MicroPython doesn't implement ``errno`` + |see_cpython| `OSError`. MicroPython doesn't implement ``errno`` attribute, instead use the standard way to access exception arguments: ``exc.args[0]``. @@ -188,11 +194,11 @@ Exceptions .. exception:: SystemExit - |see_cpython| `python:SystemExit`. + |see_cpython| :py:class:`python:SystemExit`. .. exception:: TypeError - |see_cpython| `python:TypeError`. + |see_cpython| :py:class:`python:TypeError`. .. exception:: ValueError diff --git a/docs/library/cmath.rst b/docs/library/cmath.rst deleted file mode 100644 index 59e4ec172..000000000 --- a/docs/library/cmath.rst +++ /dev/null @@ -1,63 +0,0 @@ -:mod:`cmath` -- mathematical functions for complex numbers -========================================================== - -.. module:: cmath - :synopsis: mathematical functions for complex numbers - -|see_cpython_module| :mod:`python:cmath`. - -The ``cmath`` module provides some basic mathematical functions for -working with complex numbers. - -Availability: not available on WiPy and ESP8266. Floating point support -required for this module. - -Functions ---------- - -.. function:: cos(z) - - Return the cosine of ``z``. - -.. function:: exp(z) - - Return the exponential of ``z``. - -.. function:: log(z) - - Return the natural logarithm of ``z``. The branch cut is along the negative real axis. - -.. function:: log10(z) - - Return the base-10 logarithm of ``z``. The branch cut is along the negative real axis. - -.. function:: phase(z) - - Returns the phase of the number ``z``, in the range (-pi, +pi]. - -.. function:: polar(z) - - Returns, as a tuple, the polar form of ``z``. - -.. function:: rect(r, phi) - - Returns the complex number with modulus ``r`` and phase ``phi``. - -.. function:: sin(z) - - Return the sine of ``z``. - -.. function:: sqrt(z) - - Return the square-root of ``z``. - -Constants ---------- - -.. data:: e - - base of the natural logarithm - -.. data:: pi - - the ratio of a circle's circumference to its diameter diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 121a80d42..125aaa890 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -1,6 +1,8 @@ :mod:`esp` --- functions related to the ESP8266 =============================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: esp :synopsis: functions related to the ESP8266 diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst index 74c9f8564..80961b872 100644 --- a/docs/library/framebuf.rst +++ b/docs/library/framebuf.rst @@ -1,6 +1,8 @@ :mod:`framebuf` --- Frame buffer manipulation ============================================= +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: framebuf :synopsis: Frame buffer manipulation diff --git a/docs/library/gc.rst b/docs/library/gc.rst index c823aed3e..01bd925e9 100644 --- a/docs/library/gc.rst +++ b/docs/library/gc.rst @@ -1,10 +1,12 @@ :mod:`gc` -- control the garbage collector ========================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: gc :synopsis: control the garbage collector -|see_cpython_module| :mod:`python:gc`. +|see_cpython_module| :mod:`cpython:gc`. Functions --------- diff --git a/docs/library/index.rst b/docs/library/index.rst index bf72c5ffa..647a25c8a 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -5,159 +5,34 @@ MicroPython libraries .. warning:: - Important summary of this section - - * MicroPython implements a subset of Python functionality for each module. - * To ease extensibility, MicroPython versions of standard Python modules - usually have ``u`` (micro) prefix. - * Any particular MicroPython variant or port may miss any feature/function - described in this general documentation, due to resource constraints. - - -This chapter describes modules (function and class libraries) which are built -into MicroPython and CircuitPython. There are a few categories of modules: - -* Modules which implement a subset of standard Python functionality and are not - intended to be extended by the user. -* Modules which implement a subset of Python functionality, with a provision - for extension by the user (via Python code). -* Modules which implement MicroPython extensions to the Python standard libraries. -* Modules specific to a particular port and thus not portable. - -Note about the availability of modules and their contents: This documentation -in general aspires to describe all modules and functions/classes which are -implemented in MicroPython. However, MicroPython is highly configurable, and -each port to a particular board/embedded system makes available only a subset -of MicroPython libraries. For officially supported ports, there is an effort -to either filter out non-applicable items, or mark individual descriptions -with "Availability:" clauses describing which ports provide a given feature. -With that in mind, please still be warned that some functions/classes -in a module (or even the entire module) described in this documentation may be -unavailable in a particular build of MicroPython on a particular board. The -best place to find general information of the availability/non-availability -of a particular feature is the "General Information" section which contains -information pertaining to a specific port. - -Beyond the built-in libraries described in this documentation, many more -modules from the Python standard library, as well as further MicroPython -extensions to it, can be found in `micropython-lib`. + These modules are inherited from MicroPython and may not work in CircuitPython + as documented or at all! If they do work, they may change at any time. + Python standard libraries and micro-libraries --------------------------------------------- -The following standard Python libraries have been "micro-ified" to fit in with -the philosophy of MicroPython. They provide the core functionality of that -module and are intended to be a drop-in replacement for the standard Python -library. Some modules below use a standard Python name, but prefixed with "u", -e.g. ``ujson`` instead of ``json``. This is to signify that such a module is -micro-library, i.e. implements only a subset of CPython module functionality. -By naming them differently, a user has a choice to write a Python-level module -to extend functionality for better compatibility with CPython (indeed, this is -what done by the `micropython-lib` project mentioned above). - -On some embedded platforms, where it may be cumbersome to add Python-level -wrapper modules to achieve naming compatibility with CPython, micro-modules -are available both by their u-name, and also by their non-u-name. The -non-u-name can be overridden by a file of that name in your package path. -For example, ``import json`` will first search for a file ``json.py`` or -directory ``json`` and load that package if it is found. If nothing is found, -it will fallback to loading the built-in ``ujson`` module. - -.. only:: port_unix - - .. toctree:: - :maxdepth: 1 - - builtins.rst - array.rst - cmath.rst - gc.rst - math.rst - sys.rst - ubinascii.rst - ucollections.rst - uerrno.rst - uhashlib.rst - uheapq.rst - uio.rst - ujson.rst - uos.rst - ure.rst - uselect.rst - usocket.rst - ustruct.rst - utime.rst - uzlib.rst - -.. only:: port_pyboard - - .. toctree:: - :maxdepth: 1 - - builtins.rst - array.rst - cmath.rst - gc.rst - math.rst - sys.rst - ubinascii.rst - ucollections.rst - uerrno.rst - uhashlib.rst - uheapq.rst - uio.rst - ujson.rst - uos.rst - ure.rst - uselect.rst - usocket.rst - ustruct.rst - utime.rst - uzlib.rst - -.. only:: port_wipy - - .. toctree:: - :maxdepth: 1 - - builtins.rst - array.rst - gc.rst - sys.rst - ubinascii.rst - ujson.rst - uos.rst - ure.rst - uselect.rst - usocket.rst - ussl.rst - utime.rst - -.. only:: port_esp8266 - - .. toctree:: - :maxdepth: 1 - - builtins.rst - array.rst - gc.rst - math.rst - sys.rst - ubinascii.rst - ucollections.rst - uerrno.rst - uhashlib.rst - uheapq.rst - uio.rst - ujson.rst - uos.rst - ure.rst - uselect.rst - usocket.rst - ussl.rst - ustruct.rst - utime.rst - uzlib.rst + +.. toctree:: + :maxdepth: 1 + + builtins.rst + array.rst + gc.rst + sys.rst + ubinascii.rst + ucollections.rst + uerrno.rst + uhashlib.rst + uheapq.rst + uio.rst + ujson.rst + ure.rst + uselect.rst + usocket.rst + ussl.rst + ustruct.rst + uzlib.rst MicroPython-specific libraries @@ -171,46 +46,16 @@ the following libraries. btree.rst framebuf.rst - machine.rst micropython.rst network.rst uctypes.rst +Libraries specific to the ESP8266 +--------------------------------- -.. only:: port_pyboard - - Libraries specific to the pyboard - --------------------------------- - - The following libraries are specific to the pyboard. - - .. toctree:: - :maxdepth: 2 - - pyb.rst - lcd160cr.rst - -.. only:: port_wipy +The following libraries are specific to the ESP8266. - Libraries specific to the WiPy - --------------------------------- - - The following libraries are specific to the WiPy. - - .. toctree:: - :maxdepth: 2 - - wipy.rst - - -.. only:: port_esp8266 - - Libraries specific to the ESP8266 - --------------------------------- - - The following libraries are specific to the ESP8266. - - .. toctree:: - :maxdepth: 2 +.. toctree:: + :maxdepth: 2 - esp.rst + esp.rst diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst deleted file mode 100644 index 567994640..000000000 --- a/docs/library/lcd160cr.rst +++ /dev/null @@ -1,394 +0,0 @@ -:mod:`lcd160cr` --- control of LCD160CR display -=============================================== - -.. module:: lcd160cr - :synopsis: control of LCD160CR display - -This module provides control of the MicroPython LCD160CR display. - -.. image:: http://micropython.org/resources/LCD160CRv10-persp.jpg - :alt: LCD160CRv1.0 picture - :width: 640px - -Further resources are available via the following links: - -* `LCD160CRv1.0 reference manual <http://micropython.org/resources/LCD160CRv10-refmanual.pdf>`_ (100KiB PDF) -* `LCD160CRv1.0 schematics <http://micropython.org/resources/LCD160CRv10-schematics.pdf>`_ (1.6MiB PDF) - -class LCD160CR --------------- - -The LCD160CR class provides an interface to the display. Create an -instance of this class and use its methods to draw to the LCD and get -the status of the touch panel. - -For example:: - - import lcd160cr - - lcd = lcd160cr.LCD160CR('X') - lcd.set_orient(lcd160cr.PORTRAIT) - lcd.set_pos(0, 0) - lcd.set_text_color(lcd.rgb(255, 0, 0), lcd.rgb(0, 0, 0)) - lcd.set_font(1) - lcd.write('Hello MicroPython!') - print('touch:', lcd.get_touch()) - -Constructors ------------- - -.. class:: LCD160CR(connect=None, \*, pwr=None, i2c=None, spi=None, i2c_addr=98) - - Construct an LCD160CR object. The parameters are: - - - *connect* is a string specifying the physical connection of the LCD - display to the board; valid values are "X", "Y", "XY", "YX". - Use "X" when the display is connected to a pyboard in the X-skin - position, and "Y" when connected in the Y-skin position. "XY" - and "YX" are used when the display is connected to the right or - left side of the pyboard, respectively. - - *pwr* is a Pin object connected to the LCD's power/enabled pin. - - *i2c* is an I2C object connected to the LCD's I2C interface. - - *spi* is an SPI object connected to the LCD's SPI interface. - - *i2c_addr* is the I2C address of the display. - - One must specify either a valid *connect* or all of *pwr*, *i2c* and *spi*. - If a valid *connect* is given then any of *pwr*, *i2c* or *spi* which are - not passed as parameters (i.e. they are ``None``) will be created based on the - value of *connect*. This allows to override the default interface to the - display if needed. - - The default values are: - - - "X" is for the X-skin and uses: - ``pwr=Pin("X4")``, ``i2c=I2C("X")``, ``spi=SPI("X")`` - - "Y" is for the Y-skin and uses: - ``pwr=Pin("Y4")``, ``i2c=I2C("Y")``, ``spi=SPI("Y")`` - - "XY" is for the right-side and uses: - ``pwr=Pin("X4")``, ``i2c=I2C("Y")``, ``spi=SPI("X")`` - - "YX" is for the left-side and uses: - ``pwr=Pin("Y4")``, ``i2c=I2C("X")``, ``spi=SPI("Y")`` - - See `this image <http://micropython.org/resources/LCD160CRv10-positions.jpg>`_ - for how the display can be connected to the pyboard. - -Static methods --------------- - -.. staticmethod:: LCD160CR.rgb(r, g, b) - - Return a 16-bit integer representing the given rgb color values. The - 16-bit value can be used to set the font color (see - :meth:`LCD160CR.set_text_color`) pen color (see :meth:`LCD160CR.set_pen`) - and draw individual pixels. - -.. staticmethod:: LCD160CR.clip_line(data, w, h): - - Clip the given line data. This is for internal use. - -Instance members ----------------- - -The following instance members are publicly accessible. - -.. data:: LCD160CR.w -.. data:: LCD160CR.h - - The width and height of the display, respectively, in pixels. These - members are updated when calling :meth:`LCD160CR.set_orient` and should - be considered read-only. - -Setup commands --------------- - -.. method:: LCD160CR.set_power(on) - - Turn the display on or off, depending on the given value of *on*: 0 or ``False`` - will turn the display off, and 1 or ``True`` will turn it on. - -.. method:: LCD160CR.set_orient(orient) - - Set the orientation of the display. The *orient* parameter can be one - of `PORTRAIT`, `LANDSCAPE`, `PORTRAIT_UPSIDEDOWN`, `LANDSCAPE_UPSIDEDOWN`. - -.. method:: LCD160CR.set_brightness(value) - - Set the brightness of the display, between 0 and 31. - -.. method:: LCD160CR.set_i2c_addr(addr) - - Set the I2C address of the display. The *addr* value must have the - lower 2 bits cleared. - -.. method:: LCD160CR.set_uart_baudrate(baudrate) - - Set the baudrate of the UART interface. - -.. method:: LCD160CR.set_startup_deco(value) - - Set the start-up decoration of the display. The *value* parameter can be a - logical or of `STARTUP_DECO_NONE`, `STARTUP_DECO_MLOGO`, `STARTUP_DECO_INFO`. - -.. method:: LCD160CR.save_to_flash() - - Save the following parameters to flash so they persist on restart and power up: - initial decoration, orientation, brightness, UART baud rate, I2C address. - -Pixel access methods --------------------- - -The following methods manipulate individual pixels on the display. - -.. method:: LCD160CR.set_pixel(x, y, c) - - Set the specified pixel to the given color. The color should be a 16-bit - integer and can be created by :meth:`LCD160CR.rgb`. - -.. method:: LCD160CR.get_pixel(x, y) - - Get the 16-bit value of the specified pixel. - -.. method:: LCD160CR.get_line(x, y, buf) - - Low-level method to get a line of pixels into the given buffer. - To read *n* pixels *buf* should be *2*n+1* bytes in length. The first byte - is a dummy byte and should be ignored, and subsequent bytes represent the - pixels in the line starting at coordinate *(x, y)*. - -.. method:: LCD160CR.screen_dump(buf, x=0, y=0, w=None, h=None) - - Dump the contents of the screen to the given buffer. The parameters *x* and *y* - specify the starting coordinate, and *w* and *h* the size of the region. If *w* - or *h* are ``None`` then they will take on their maximum values, set by the size - of the screen minus the given *x* and *y* values. *buf* should be large enough - to hold ``2*w*h`` bytes. If it's smaller then only the initial horizontal lines - will be stored. - -.. method:: LCD160CR.screen_load(buf) - - Load the entire screen from the given buffer. - -Drawing text ------------- - -To draw text one sets the position, color and font, and then uses -`write` to draw the text. - -.. method:: LCD160CR.set_pos(x, y) - - Set the position for text output using :meth:`LCD160CR.write`. The position - is the upper-left corner of the text. - -.. method:: LCD160CR.set_text_color(fg, bg) - - Set the foreground and background color of the text. - -.. method:: LCD160CR.set_font(font, scale=0, bold=0, trans=0, scroll=0) - - Set the font for the text. Subsequent calls to `write` will use the newly - configured font. The parameters are: - - - *font* is the font family to use, valid values are 0, 1, 2, 3. - - *scale* is a scaling value for each character pixel, where the pixels - are drawn as a square with side length equal to *scale + 1*. The value - can be between 0 and 63. - - *bold* controls the number of pixels to overdraw each character pixel, - making a bold effect. The lower 2 bits of *bold* are the number of - pixels to overdraw in the horizontal direction, and the next 2 bits are - for the vertical direction. For example, a *bold* value of 5 will - overdraw 1 pixel in both the horizontal and vertical directions. - - *trans* can be either 0 or 1 and if set to 1 the characters will be - drawn with a transparent background. - - *scroll* can be either 0 or 1 and if set to 1 the display will do a - soft scroll if the text moves to the next line. - -.. method:: LCD160CR.write(s) - - Write text to the display, using the current position, color and font. - As text is written the position is automatically incremented. The - display supports basic VT100 control codes such as newline and backspace. - -Drawing primitive shapes ------------------------- - -Primitive drawing commands use a foreground and background color set by the -`set_pen` method. - -.. method:: LCD160CR.set_pen(line, fill) - - Set the line and fill color for primitive shapes. - -.. method:: LCD160CR.erase() - - Erase the entire display to the pen fill color. - -.. method:: LCD160CR.dot(x, y) - - Draw a single pixel at the given location using the pen line color. - -.. method:: LCD160CR.rect(x, y, w, h) -.. method:: LCD160CR.rect_outline(x, y, w, h) -.. method:: LCD160CR.rect_interior(x, y, w, h) - - Draw a rectangle at the given location and size using the pen line - color for the outline, and the pen fill color for the interior. - The `rect` method draws the outline and interior, while the other methods - just draw one or the other. - -.. method:: LCD160CR.line(x1, y1, x2, y2) - - Draw a line between the given coordinates using the pen line color. - -.. method:: LCD160CR.dot_no_clip(x, y) -.. method:: LCD160CR.rect_no_clip(x, y, w, h) -.. method:: LCD160CR.rect_outline_no_clip(x, y, w, h) -.. method:: LCD160CR.rect_interior_no_clip(x, y, w, h) -.. method:: LCD160CR.line_no_clip(x1, y1, x2, y2) - - These methods are as above but don't do any clipping on the input - coordinates. They are faster than the clipping versions and can be - used when you know that the coordinates are within the display. - -.. method:: LCD160CR.poly_dot(data) - - Draw a sequence of dots using the pen line color. - The *data* should be a buffer of bytes, with each successive pair of - bytes corresponding to coordinate pairs (x, y). - -.. method:: LCD160CR.poly_line(data) - - Similar to :meth:`LCD160CR.poly_dot` but draws lines between the dots. - -Touch screen methods --------------------- - -.. method:: LCD160CR.touch_config(calib=False, save=False, irq=None) - - Configure the touch panel: - - - If *calib* is ``True`` then the call will trigger a touch calibration of - the resistive touch sensor. This requires the user to touch various - parts of the screen. - - If *save* is ``True`` then the touch parameters will be saved to NVRAM - to persist across reset/power up. - - If *irq* is ``True`` then the display will be configured to pull the IRQ - line low when a touch force is detected. If *irq* is ``False`` then this - feature is disabled. If *irq* is ``None`` (the default value) then no - change is made to this setting. - -.. method:: LCD160CR.is_touched() - - Returns a boolean: ``True`` if there is currently a touch force on the screen, - `False` otherwise. - -.. method:: LCD160CR.get_touch() - - Returns a 3-tuple of: *(active, x, y)*. If there is currently a touch force - on the screen then *active* is 1, otherwise it is 0. The *x* and *y* values - indicate the position of the current or most recent touch. - -Advanced commands ------------------ - -.. method:: LCD160CR.set_spi_win(x, y, w, h) - - Set the window that SPI data is written to. - -.. method:: LCD160CR.fast_spi(flush=True) - - Ready the display to accept RGB pixel data on the SPI bus, resetting the location - of the first byte to go to the top-left corner of the window set by - :meth:`LCD160CR.set_spi_win`. - The method returns an SPI object which can be used to write the pixel data. - - Pixels should be sent as 16-bit RGB values in the 5-6-5 format. The destination - counter will increase as data is sent, and data can be sent in arbitrary sized - chunks. Once the destination counter reaches the end of the window specified by - :meth:`LCD160CR.set_spi_win` it will wrap around to the top-left corner of that window. - -.. method:: LCD160CR.show_framebuf(buf) - - Show the given buffer on the display. *buf* should be an array of bytes containing - the 16-bit RGB values for the pixels, and they will be written to the area - specified by :meth:`LCD160CR.set_spi_win`, starting from the top-left corner. - - The `framebuf <framebuf.html>`_ module can be used to construct frame buffers - and provides drawing primitives. Using a frame buffer will improve - performance of animations when compared to drawing directly to the screen. - -.. method:: LCD160CR.set_scroll(on) - - Turn scrolling on or off. This controls globally whether any window regions will - scroll. - -.. method:: LCD160CR.set_scroll_win(win, x=-1, y=0, w=0, h=0, vec=0, pat=0, fill=0x07e0, color=0) - - Configure a window region for scrolling: - - - *win* is the window id to configure. There are 0..7 standard windows for - general purpose use. Window 8 is the text scroll window (the ticker). - - *x*, *y*, *w*, *h* specify the location of the window in the display. - - *vec* specifies the direction and speed of scroll: it is a 16-bit value - of the form ``0bF.ddSSSSSSSSSSSS``. *dd* is 0, 1, 2, 3 for +x, +y, -x, - -y scrolling. *F* sets the speed format, with 0 meaning that the window - is shifted *S % 256* pixel every frame, and 1 meaning that the window - is shifted 1 pixel every *S* frames. - - *pat* is a 16-bit pattern mask for the background. - - *fill* is the fill color. - - *color* is the extra color, either of the text or pattern foreground. - -.. method:: LCD160CR.set_scroll_win_param(win, param, value) - - Set a single parameter of a scrolling window region: - - - *win* is the window id, 0..8. - - *param* is the parameter number to configure, 0..7, and corresponds - to the parameters in the `set_scroll_win` method. - - *value* is the value to set. - -.. method:: LCD160CR.set_scroll_buf(s) - - Set the string for scrolling in window 8. The parameter *s* must be a string - with length 32 or less. - -.. method:: LCD160CR.jpeg(buf) - - Display a JPEG. *buf* should contain the entire JPEG data. JPEG data should - not include EXIF information. The following encodings are supported: Baseline - DCT, Huffman coding, 8 bits per sample, 3 color components, YCbCr4:2:2. - The origin of the JPEG is set by :meth:`LCD160CR.set_pos`. - -.. method:: LCD160CR.jpeg_start(total_len) -.. method:: LCD160CR.jpeg_data(buf) - - Display a JPEG with the data split across multiple buffers. There must be - a single call to `jpeg_start` to begin with, specifying the total number of - bytes in the JPEG. Then this number of bytes must be transferred to the - display using one or more calls to the `jpeg_data` command. - -.. method:: LCD160CR.feed_wdt() - - The first call to this method will start the display's internal watchdog - timer. Subsequent calls will feed the watchdog. The timeout is roughly 30 - seconds. - -.. method:: LCD160CR.reset() - - Reset the display. - -Constants ---------- - -.. data:: lcd160cr.PORTRAIT - lcd160cr.LANDSCAPE - lcd160cr.PORTRAIT_UPSIDEDOWN - lcd160cr.LANDSCAPE_UPSIDEDOWN - - Orientations of the display, used by :meth:`LCD160CR.set_orient`. - -.. data:: lcd160cr.STARTUP_DECO_NONE - lcd160cr.STARTUP_DECO_MLOGO - lcd160cr.STARTUP_DECO_INFO - - Types of start-up decoration, can be OR'ed together, used by - :meth:`LCD160CR.set_startup_deco`. diff --git a/docs/library/machine.ADC.rst b/docs/library/machine.ADC.rst deleted file mode 100644 index 4c7a04d74..000000000 --- a/docs/library/machine.ADC.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. currentmodule:: machine -.. _machine.ADC: - -class ADC -- analog to digital conversion -========================================= - -Usage:: - - import machine - - adc = machine.ADC() # create an ADC object - apin = adc.channel(pin='GP3') # create an analog pin on GP3 - val = apin() # read an analog value - -Constructors ------------- - -.. class:: ADC(id=0, \*, bits=12) - - Create an ADC object associated with the given pin. - This allows you to then read analog values on that pin. - For more info check the `pinout and alternate functions - table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ - - .. warning:: - - ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it - can withstand). When GP2, GP3, GP4 or GP5 are remapped to the - ADC block, 1.8 V is the maximum. If these pins are used in digital mode, - then the maximum allowed input is 3.6V. - -Methods -------- - -.. method:: ADC.channel(id, \*, pin) - - Create an analog pin. If only channel ID is given, the correct pin will - be selected. Alternatively, only the pin can be passed and the correct - channel will be selected. Examples:: - - # all of these are equivalent and enable ADC channel 1 on GP3 - apin = adc.channel(1) - apin = adc.channel(pin='GP3') - apin = adc.channel(id=1, pin='GP3') - -.. method:: ADC.init() - - Enable the ADC block. - -.. method:: ADC.deinit() - - Disable the ADC block. - -class ADCChannel --- read analog values from internal or external sources -========================================================================= - -ADC channels can be connected to internal points of the MCU or to GPIO pins. -ADC channels are created using the ADC.channel method. - -.. method:: adcchannel() - - Fast method to read the channel value. - -.. method:: adcchannel.value() - - Read the channel value. - -.. method:: adcchannel.init() - - Re-init (and effectively enable) the ADC channel. - -.. method:: adcchannel.deinit() - - Disable the ADC channel. diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst deleted file mode 100644 index a69c58999..000000000 --- a/docs/library/machine.I2C.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. currentmodule:: machine -.. _machine.I2C: - -class I2C -- a two-wire serial protocol -======================================= - -I2C is a two-wire protocol for communicating between devices. At the physical -level it consists of 2 wires: SCL and SDA, the clock and data lines respectively. - -I2C objects are created attached to a specific bus. They can be initialised -when created, or initialised later on. - -Printing the I2C object gives you information about its configuration. - -Example usage:: - - from machine import I2C - - i2c = I2C(freq=400000) # create I2C peripheral at frequency of 400kHz - # depending on the port, extra parameters may be required - # to select the peripheral and/or pins to use - - i2c.scan() # scan for slaves, returning a list of 7-bit addresses - - i2c.writeto(42, b'123') # write 3 bytes to slave with 7-bit address 42 - i2c.readfrom(42, 4) # read 4 bytes from slave with 7-bit address 42 - - i2c.readfrom_mem(42, 8, 3) # read 3 bytes from memory of slave 42, - # starting at memory-address 8 in the slave - i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42 - # starting at address 2 in the slave - -Constructors ------------- - -.. class:: I2C(id=-1, \*, scl, sda, freq=400000) - - Construct and return a new I2C object using the following parameters: - - - *id* identifies a particular I2C peripheral. The default - value of -1 selects a software implementation of I2C which can - work (in most cases) with arbitrary pins for SCL and SDA. - If *id* is -1 then *scl* and *sda* must be specified. Other - allowed values for *id* depend on the particular port/board, - and specifying *scl* and *sda* may or may not be required or - allowed in this case. - - *scl* should be a pin object specifying the pin to use for SCL. - - *sda* should be a pin object specifying the pin to use for SDA. - - *freq* should be an integer which sets the maximum frequency - for SCL. - -General Methods ---------------- - -.. method:: I2C.init(scl, sda, \*, freq=400000) - - Initialise the I2C bus with the given arguments: - - - *scl* is a pin object for the SCL line - - *sda* is a pin object for the SDA line - - *freq* is the SCL clock rate - -.. method:: I2C.deinit() - - Turn off the I2C bus. - - Availability: WiPy. - -.. method:: I2C.scan() - - Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of - those that respond. A device responds if it pulls the SDA line low after - its address (including a write bit) is sent on the bus. - -Primitive I2C operations ------------------------- - -The following methods implement the primitive I2C master bus operations and can -be combined to make any I2C transaction. They are provided if you need more -control over the bus, otherwise the standard methods (see below) can be used. - -.. method:: I2C.start() - - Generate a START condition on the bus (SDA transitions to low while SCL is high). - - Availability: ESP8266. - -.. method:: I2C.stop() - - Generate a STOP condition on the bus (SDA transitions to high while SCL is high). - - Availability: ESP8266. - -.. method:: I2C.readinto(buf, nack=True) - - Reads bytes from the bus and stores them into *buf*. The number of bytes - read is the length of *buf*. An ACK will be sent on the bus after - receiving all but the last byte. After the last byte is received, if *nack* - is true then a NACK will be sent, otherwise an ACK will be sent (and in this - case the slave assumes more bytes are going to be read in a later call). - - Availability: ESP8266. - -.. method:: I2C.write(buf) - - Write the bytes from *buf* to the bus. Checks that an ACK is received - after each byte and stops transmitting the remaining bytes if a NACK is - received. The function returns the number of ACKs that were received. - - Availability: ESP8266. - -Standard bus operations ------------------------ - -The following methods implement the standard I2C master read and write -operations that target a given slave device. - -.. method:: I2C.readfrom(addr, nbytes, stop=True) - - Read *nbytes* from the slave specified by *addr*. - If *stop* is true then a STOP condition is generated at the end of the transfer. - Returns a `bytes` object with the data read. - -.. method:: I2C.readfrom_into(addr, buf, stop=True) - - Read into *buf* from the slave specified by *addr*. - The number of bytes read will be the length of *buf*. - If *stop* is true then a STOP condition is generated at the end of the transfer. - - The method returns ``None``. - -.. method:: I2C.writeto(addr, buf, stop=True) - - Write the bytes from *buf* to the slave specified by *addr*. If a - NACK is received following the write of a byte from *buf* then the - remaining bytes are not sent. If *stop* is true then a STOP condition is - generated at the end of the transfer, even if a NACK is received. - The function returns the number of ACKs that were received. - -Memory operations ------------------ - -Some I2C devices act as a memory device (or set of registers) that can be read -from and written to. In this case there are two addresses associated with an -I2C transaction: the slave address and the memory address. The following -methods are convenience functions to communicate with such devices. - -.. method:: I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8) - - Read *nbytes* from the slave specified by *addr* starting from the memory - address specified by *memaddr*. - The argument *addrsize* specifies the address size in bits. - Returns a `bytes` object with the data read. - -.. method:: I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8) - - Read into *buf* from the slave specified by *addr* starting from the - memory address specified by *memaddr*. The number of bytes read is the - length of *buf*. - The argument *addrsize* specifies the address size in bits (on ESP8266 - this argument is not recognised and the address size is always 8 bits). - - The method returns ``None``. - -.. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8) - - Write *buf* to the slave specified by *addr* starting from the - memory address specified by *memaddr*. - The argument *addrsize* specifies the address size in bits (on ESP8266 - this argument is not recognised and the address size is always 8 bits). - - The method returns ``None``. diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst deleted file mode 100644 index 05ceb4ad3..000000000 --- a/docs/library/machine.Pin.rst +++ /dev/null @@ -1,248 +0,0 @@ -.. currentmodule:: machine -.. _machine.Pin: - -class Pin -- control I/O pins -============================= - -A pin object is used to control I/O pins (also known as GPIO - general-purpose -input/output). Pin objects are commonly associated with a physical pin that can -drive an output voltage and read input voltages. The pin class has methods to set the mode of -the pin (IN, OUT, etc) and methods to get and set the digital logic level. -For analog control of a pin, see the :class:`ADC` class. - -A pin object is constructed by using an identifier which unambiguously -specifies a certain I/O pin. The allowed forms of the identifier and the -physical pin that the identifier maps to are port-specific. Possibilities -for the identifier are an integer, a string or a tuple with port and pin -number. - -Usage Model:: - - from machine import Pin - - # create an output pin on pin #0 - p0 = Pin(0, Pin.OUT) - - # set the value low then high - p0.value(0) - p0.value(1) - - # create an input pin on pin #2, with a pull up resistor - p2 = Pin(2, Pin.IN, Pin.PULL_UP) - - # read and print the pin value - print(p2.value()) - - # reconfigure pin #0 in input mode - p0.mode(p0.IN) - - # configure an irq callback - p0.irq(lambda p:print(p)) - -Constructors ------------- - -.. class:: Pin(id, mode=-1, pull=-1, \*, value, drive, alt) - - Access the pin peripheral (GPIO pin) associated with the given ``id``. If - additional arguments are given in the constructor then they are used to initialise - the pin. Any settings that are not specified will remain in their previous state. - - The arguments are: - - - ``id`` is mandatory and can be an arbitrary object. Among possible value - types are: int (an internal Pin identifier), str (a Pin name), and tuple - (pair of [port, pin]). - - - ``mode`` specifies the pin mode, which can be one of: - - - ``Pin.IN`` - Pin is configured for input. If viewed as an output the pin - is in high-impedance state. - - - ``Pin.OUT`` - Pin is configured for (normal) output. - - - ``Pin.OPEN_DRAIN`` - Pin is configured for open-drain output. Open-drain - output works in the following way: if the output value is set to 0 the pin - is active at a low level; if the output value is 1 the pin is in a high-impedance - state. Not all ports implement this mode, or some might only on certain pins. - - - ``Pin.ALT`` - Pin is configured to perform an alternative function, which is - port specific. For a pin configured in such a way any other Pin methods - (except :meth:`Pin.init`) are not applicable (calling them will lead to undefined, - or a hardware-specific, result). Not all ports implement this mode. - - - ``Pin.ALT_OPEN_DRAIN`` - The Same as ``Pin.ALT``, but the pin is configured as - open-drain. Not all ports implement this mode. - - - ``pull`` specifies if the pin has a (weak) pull resistor attached, and can be - one of: - - - ``None`` - No pull up or down resistor. - - ``Pin.PULL_UP`` - Pull up resistor enabled. - - ``Pin.PULL_DOWN`` - Pull down resistor enabled. - - - ``value`` is valid only for Pin.OUT and Pin.OPEN_DRAIN modes and specifies initial - output pin value if given, otherwise the state of the pin peripheral remains - unchanged. - - - ``drive`` specifies the output power of the pin and can be one of: ``Pin.LOW_POWER``, - ``Pin.MED_POWER`` or ``Pin.HIGH_POWER``. The actual current driving capabilities - are port dependent. Not all ports implement this argument. - - - ``alt`` specifies an alternate function for the pin and the values it can take are - port dependent. This argument is valid only for ``Pin.ALT`` and ``Pin.ALT_OPEN_DRAIN`` - modes. It may be used when a pin supports more than one alternate function. If only - one pin alternate function is supported the this argument is not required. Not all - ports implement this argument. - - As specified above, the Pin class allows to set an alternate function for a particular - pin, but it does not specify any further operations on such a pin. Pins configured in - alternate-function mode are usually not used as GPIO but are instead driven by other - hardware peripherals. The only operation supported on such a pin is re-initialising, - by calling the constructor or :meth:`Pin.init` method. If a pin that is configured in - alternate-function mode is re-initialised with ``Pin.IN``, ``Pin.OUT``, or - ``Pin.OPEN_DRAIN``, the alternate function will be removed from the pin. - -Methods -------- - -.. method:: Pin.init(mode=-1, pull=-1, \*, value, drive, alt) - - Re-initialise the pin using the given parameters. Only those arguments that - are specified will be set. The rest of the pin peripheral state will remain - unchanged. See the constructor documentation for details of the arguments. - - Returns ``None``. - -.. method:: Pin.value([x]) - - This method allows to set and get the value of the pin, depending on whether - the argument ``x`` is supplied or not. - - If the argument is omitted then this method gets the digital logic level of - the pin, returning 0 or 1 corresponding to low and high voltage signals - respectively. The behaviour of this method depends on the mode of the pin: - - - ``Pin.IN`` - The method returns the actual input value currently present - on the pin. - - ``Pin.OUT`` - The behaviour and return value of the method is undefined. - - ``Pin.OPEN_DRAIN`` - If the pin is in state '0' then the behaviour and - return value of the method is undefined. Otherwise, if the pin is in - state '1', the method returns the actual input value currently present - on the pin. - - If the argument is supplied then this method sets the digital logic level of - the pin. The argument ``x`` can be anything that converts to a boolean. - If it converts to ``True``, the pin is set to state '1', otherwise it is set - to state '0'. The behaviour of this method depends on the mode of the pin: - - - ``Pin.IN`` - The value is stored in the output buffer for the pin. The - pin state does not change, it remains in the high-impedance state. The - stored value will become active on the pin as soon as it is changed to - ``Pin.OUT`` or ``Pin.OPEN_DRAIN`` mode. - - ``Pin.OUT`` - The output buffer is set to the given value immediately. - - ``Pin.OPEN_DRAIN`` - If the value is '0' the pin is set to a low voltage - state. Otherwise the pin is set to high-impedance state. - - When setting the value this method returns ``None``. - -.. method:: Pin.__call__([x]) - - Pin objects are callable. The call method provides a (fast) shortcut to set - and get the value of the pin. It is equivalent to Pin.value([x]). - See :meth:`Pin.value` for more details. - -.. method:: Pin.on() - - Set pin to "1" output level. - -.. method:: Pin.off() - - Set pin to "0" output level. - -.. method:: Pin.mode([mode]) - - Get or set the pin mode. - See the constructor documentation for details of the ``mode`` argument. - -.. method:: Pin.pull([pull]) - - Get or set the pin pull state. - See the constructor documentation for details of the ``pull`` argument. - -.. method:: Pin.drive([drive]) - - Get or set the pin drive strength. - See the constructor documentation for details of the ``drive`` argument. - - Not all ports implement this method. - - Availability: WiPy. - -.. method:: Pin.irq(handler=None, trigger=(Pin.IRQ_FALLING | Pin.IRQ_RISING), \*, priority=1, wake=None) - - Configure an interrupt handler to be called when the trigger source of the - pin is active. If the pin mode is ``Pin.IN`` then the trigger source is - the external value on the pin. If the pin mode is ``Pin.OUT`` then the - trigger source is the output buffer of the pin. Otherwise, if the pin mode - is ``Pin.OPEN_DRAIN`` then the trigger source is the output buffer for - state '0' and the external pin value for state '1'. - - The arguments are: - - - ``handler`` is an optional function to be called when the interrupt - triggers. - - - ``trigger`` configures the event which can generate an interrupt. - Possible values are: - - - ``Pin.IRQ_FALLING`` interrupt on falling edge. - - ``Pin.IRQ_RISING`` interrupt on rising edge. - - ``Pin.IRQ_LOW_LEVEL`` interrupt on low level. - - ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level. - - These values can be OR'ed together to trigger on multiple events. - - - ``priority`` sets the priority level of the interrupt. The values it - can take are port-specific, but higher values always represent higher - priorities. - - - ``wake`` selects the power mode in which this interrupt can wake up the - system. It can be ``machine.IDLE``, ``machine.SLEEP`` or ``machine.DEEPSLEEP``. - These values can also be OR'ed together to make a pin generate interrupts in - more than one power mode. - - This method returns a callback object. - -Constants ---------- - -The following constants are used to configure the pin objects. Note that -not all constants are available on all ports. - -.. data:: Pin.IN - Pin.OUT - Pin.OPEN_DRAIN - Pin.ALT - Pin.ALT_OPEN_DRAIN - - Selects the pin mode. - -.. data:: Pin.PULL_UP - Pin.PULL_DOWN - - Selects whether there is a pull up/down resistor. Use the value - ``None`` for no pull. - -.. data:: Pin.LOW_POWER - Pin.MED_POWER - Pin.HIGH_POWER - - Selects the pin drive strength. - -.. data:: Pin.IRQ_FALLING - Pin.IRQ_RISING - Pin.IRQ_LOW_LEVEL - Pin.IRQ_HIGH_LEVEL - - Selects the IRQ trigger type. diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst deleted file mode 100644 index 95fa2b4ce..000000000 --- a/docs/library/machine.RTC.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. currentmodule:: machine -.. _machine.RTC: - -class RTC -- real time clock -============================ - -The RTC is and independent clock that keeps track of the date -and time. - -Example usage:: - - rtc = machine.RTC() - rtc.init((2014, 5, 1, 4, 13, 0, 0, 0)) - print(rtc.now()) - - -Constructors ------------- - -.. class:: RTC(id=0, ...) - - Create an RTC object. See init for parameters of initialization. - -Methods -------- - -.. method:: RTC.init(datetime) - - Initialise the RTC. Datetime is a tuple of the form: - - ``(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])`` - -.. method:: RTC.now() - - Get get the current datetime tuple. - -.. method:: RTC.deinit() - - Resets the RTC to the time of January 1, 2015 and starts running it again. - -.. method:: RTC.alarm(id, time, \*, repeat=False) - - Set the RTC alarm. Time might be either a millisecond value to program the alarm to - current time + time_in_ms in the future, or a datetimetuple. If the time passed is in - milliseconds, repeat can be set to ``True`` to make the alarm periodic. - -.. method:: RTC.alarm_left(alarm_id=0) - - Get the number of milliseconds left before the alarm expires. - -.. method:: RTC.cancel(alarm_id=0) - - Cancel a running alarm. - -.. method:: RTC.irq(\*, trigger, handler=None, wake=machine.IDLE) - - Create an irq object triggered by a real time clock alarm. - - - ``trigger`` must be ``RTC.ALARM0`` - - ``handler`` is the function to be called when the callback is triggered. - - ``wake`` specifies the sleep mode from where this interrupt can wake - up the system. - -Constants ---------- - -.. data:: RTC.ALARM0 - - irq trigger source diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst deleted file mode 100644 index 608e95831..000000000 --- a/docs/library/machine.SD.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. currentmodule:: machine -.. _machine.SD: - -class SD -- secure digital memory card -====================================== - -The SD card class allows to configure and enable the memory card -module of the WiPy and automatically mount it as ``/sd`` as part -of the file system. There are several pin combinations that can be -used to wire the SD card socket to the WiPy and the pins used can -be specified in the constructor. Please check the `pinout and alternate functions -table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ for -more info regarding the pins which can be remapped to be used with a SD card. - -Example usage:: - - from machine import SD - import os - # clk cmd and dat0 pins must be passed along with - # their respective alternate functions - sd = machine.SD(pins=('GP10', 'GP11', 'GP15')) - os.mount(sd, '/sd') - # do normal file operations - -Constructors ------------- - -.. class:: SD(id,... ) - - Create a SD card object. See ``init()`` for parameters if initialization. - -Methods -------- - -.. method:: SD.init(id=0, pins=('GP10', 'GP11', 'GP15')) - - Enable the SD card. In order to initialize the card, give it a 3-tuple: - ``(clk_pin, cmd_pin, dat0_pin)``. - -.. method:: SD.deinit() - - Disable the SD card. diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst deleted file mode 100644 index 080f6fdfb..000000000 --- a/docs/library/machine.SPI.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. currentmodule:: machine -.. _machine.SPI: - -class SPI -- a Serial Peripheral Interface bus protocol (master side) -===================================================================== - -SPI is a synchronous serial protocol that is driven by a master. At the -physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices -can share the same bus. Each device should have a separate, 4th signal, -SS (Slave Select), to select a particular device on a bus with which -communication takes place. Management of an SS signal should happen in -user code (via machine.Pin class). - -Constructors ------------- - -.. class:: SPI(id, ...) - - Construct an SPI object on the given bus, ``id``. Values of ``id`` depend - on a particular port and its hardware. Values 0, 1, etc. are commonly used - to select hardware SPI block #0, #1, etc. Value -1 can be used for - bitbanging (software) implementation of SPI (if supported by a port). - - With no additional parameters, the SPI object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - -Methods -------- - -.. method:: SPI.init(baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, sck=None, mosi=None, miso=None, pins=(SCK, MOSI, MISO)) - - Initialise the SPI bus with the given parameters: - - - ``baudrate`` is the SCK clock rate. - - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. - - ``phase`` can be 0 or 1 to sample data on the first or second clock edge - respectively. - - ``bits`` is the width in bits of each transfer. Only 8 is guaranteed to be supported by all hardware. - - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. - - ``sck``, ``mosi``, ``miso`` are pins (machine.Pin) objects to use for bus signals. For most - hardware SPI blocks (as selected by ``id`` parameter to the constructor), pins are fixed - and cannot be changed. In some cases, hardware blocks allow 2-3 alternative pin sets for - a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver - (``id`` = -1). - - ``pins`` - WiPy port doesn't ``sck``, ``mosi``, ``miso`` arguments, and instead allows to - specify them as a tuple of ``pins`` parameter. - -.. method:: SPI.deinit() - - Turn off the SPI bus. - -.. method:: SPI.read(nbytes, write=0x00) - - Read a number of bytes specified by ``nbytes`` while continuously writing - the single byte given by ``write``. - Returns a ``bytes`` object with the data that was read. - -.. method:: SPI.readinto(buf, write=0x00) - - Read into the buffer specified by ``buf`` while continuously writing the - single byte given by ``write``. - Returns ``None``. - - Note: on WiPy this function returns the number of bytes read. - -.. method:: SPI.write(buf) - - Write the bytes contained in ``buf``. - Returns ``None``. - - Note: on WiPy this function returns the number of bytes written. - -.. method:: SPI.write_readinto(write_buf, read_buf) - - Write the bytes from ``write_buf`` while reading into ``read_buf``. The - buffers can be the same or different, but both buffers must have the - same length. - Returns ``None``. - - Note: on WiPy this function returns the number of bytes written. - -Constants ---------- - -.. data:: SPI.MASTER - - for initialising the SPI bus to master; this is only used for the WiPy - -.. data:: SPI.MSB - - set the first bit to be the most significant bit - -.. data:: SPI.LSB - - set the first bit to be the least significant bit diff --git a/docs/library/machine.Signal.rst b/docs/library/machine.Signal.rst deleted file mode 100644 index a1a29164b..000000000 --- a/docs/library/machine.Signal.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. currentmodule:: machine -.. _machine.Signal: - -class Signal -- control and sense external I/O devices -====================================================== - -The Signal class is a simple extension of the `Pin` class. Unlike Pin, which -can be only in "absolute" 0 and 1 states, a Signal can be in "asserted" -(on) or "deasserted" (off) states, while being inverted (active-low) or -not. In other words, it adds logical inversion support to Pin functionality. -While this may seem a simple addition, it is exactly what is needed to -support wide array of simple digital devices in a way portable across -different boards, which is one of the major MicroPython goals. Regardless -of whether different users have an active-high or active-low LED, a normally -open or normally closed relay - you can develop a single, nicely looking -application which works with each of them, and capture hardware -configuration differences in few lines in the config file of your app. - -Example:: - - from machine import Pin, Signal - - # Suppose you have an active-high LED on pin 0 - led1_pin = Pin(0, Pin.OUT) - # ... and active-low LED on pin 1 - led2_pin = Pin(1, Pin.OUT) - - # Now to light up both of them using Pin class, you'll need to set - # them to different values - led1_pin.value(1) - led2_pin.value(0) - - # Signal class allows to abstract away active-high/active-low - # difference - led1 = Signal(led1_pin, invert=False) - led2 = Signal(led2_pin, invert=True) - - # Now lighting up them looks the same - led1.value(1) - led2.value(1) - - # Even better: - led1.on() - led2.on() - -Following is the guide when Signal vs Pin should be used: - -* Use Signal: If you want to control a simple on/off (including software - PWM!) devices like LEDs, multi-segment indicators, relays, buzzers, or - read simple binary sensors, like normally open or normally closed buttons, - pulled high or low, Reed switches, moisture/flame detectors, etc. etc. - Summing up, if you have a real physical device/sensor requiring GPIO - access, you likely should use a Signal. - -* Use Pin: If you implement a higher-level protocol or bus to communicate - with more complex devices. - -The split between Pin and Signal come from the usecases above and the -architecture of MicroPython: Pin offers the lowest overhead, which may -be important when bit-banging protocols. But Signal adds additional -flexibility on top of Pin, at the cost of minor overhead (much smaller -than if you implemented active-high vs active-low device differences in -Python manually!). Also, Pin is a low-level object which needs to be -implemented for each support board, while Signal is a high-level object -which comes for free once Pin is implemented. - -If in doubt, give the Signal a try! Once again, it is offered to save -developers from the need to handle unexciting differences like active-low -vs active-high signals, and allow other users to share and enjoy your -application, instead of being frustrated by the fact that it doesn't -work for them simply because their LEDs or relays are wired in a slightly -different way. - -Constructors ------------- - -.. class:: Signal(pin_obj, invert=False) - Signal(pin_arguments..., \*, invert=False) - - Create a Signal object. There're two ways to create it: - - * By wrapping existing Pin object - universal method which works for - any board. - * By passing required Pin parameters directly to Signal constructor, - skipping the need to create intermediate Pin object. Available on - many, but not all boards. - - The arguments are: - - - ``pin_obj`` is existing Pin object. - - - ``pin_arguments`` are the same arguments as can be passed to Pin constructor. - - - ``invert`` - if True, the signal will be inverted (active low). - -Methods -------- - -.. method:: Signal.value([x]) - - This method allows to set and get the value of the signal, depending on whether - the argument ``x`` is supplied or not. - - If the argument is omitted then this method gets the signal level, 1 meaning - signal is asserted (active) and 0 - signal inactive. - - If the argument is supplied then this method sets the signal level. The - argument ``x`` can be anything that converts to a boolean. If it converts - to ``True``, the signal is active, otherwise it is inactive. - - Correspondence between signal being active and actual logic level on the - underlying pin depends on whether signal is inverted (active-low) or not. - For non-inverted signal, active status corresponds to logical 1, inactive - - to logical 0. For inverted/active-low signal, active status corresponds - to logical 0, while inactive - to logical 1. - -.. method:: Signal.on() - - Activate signal. - -.. method:: Signal.off() - - Deactivate signal. diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst deleted file mode 100644 index ef46f9dd7..000000000 --- a/docs/library/machine.Timer.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. currentmodule:: machine -.. _machine.Timer: - -class Timer -- control hardware timers -====================================== - -Hardware timers deal with timing of periods and events. Timers are perhaps -the most flexible and heterogeneous kind of hardware in MCUs and SoCs, -differently greatly from a model to a model. MicroPython's Timer class -defines a baseline operation of executing a callback with a given period -(or once after some delay), and allow specific boards to define more -non-standard behavior (which thus won't be portable to other boards). - -See discussion of :ref:`important constraints <machine_callbacks>` on -Timer callbacks. - -.. note:: - - Memory can't be allocated inside irq handlers (an interrupt) and so - exceptions raised within a handler don't give much information. See - :func:`micropython.alloc_emergency_exception_buf` for how to get around this - limitation. - -Constructors ------------- - -.. class:: Timer(id, ...) - - Construct a new timer object of the given id. Id of -1 constructs a - virtual timer (if supported by a board). - -Methods -------- - -.. only:: port_wipy - - .. method:: Timer.init(mode, \*, width=16) - - Initialise the timer. Example:: - - tim.init(Timer.PERIODIC) # periodic 16-bit timer - tim.init(Timer.ONE_SHOT, width=32) # one shot 32-bit timer - - Keyword arguments: - - - ``mode`` can be one of: - - - ``Timer.ONE_SHOT`` - The timer runs once until the configured - period of the channel expires. - - ``Timer.PERIODIC`` - The timer runs periodically at the configured - frequency of the channel. - - ``Timer.PWM`` - Output a PWM signal on a pin. - - - ``width`` must be either 16 or 32 (bits). For really low frequencies < 5Hz - (or large periods), 32-bit timers should be used. 32-bit mode is only available - for ``ONE_SHOT`` AND ``PERIODIC`` modes. - -.. method:: Timer.deinit() - - Deinitialises the timer. Stops the timer, and disables the timer peripheral. - -.. only:: port_wipy - - .. method:: Timer.channel(channel, \**, freq, period, polarity=Timer.POSITIVE, duty_cycle=0) - - If only a channel identifier passed, then a previously initialized channel - object is returned (or ``None`` if there is no previous channel). - - Otherwise, a TimerChannel object is initialized and returned. - - The operating mode is is the one configured to the Timer object that was used to - create the channel. - - - ``channel`` if the width of the timer is 16-bit, then must be either ``TIMER.A``, ``TIMER.B``. - If the width is 32-bit then it **must be** ``TIMER.A | TIMER.B``. - - Keyword only arguments: - - - ``freq`` sets the frequency in Hz. - - ``period`` sets the period in microseconds. - - .. note:: - - Either ``freq`` or ``period`` must be given, never both. - - - ``polarity`` this is applicable for ``PWM``, and defines the polarity of the duty cycle - - ``duty_cycle`` only applicable to ``PWM``. It's a percentage (0.00-100.00). Since the WiPy - doesn't support floating point numbers the duty cycle must be specified in the range 0-10000, - where 10000 would represent 100.00, 5050 represents 50.50, and so on. - - .. note:: - - When the channel is in PWM mode, the corresponding pin is assigned automatically, therefore - there's no need to assign the alternate function of the pin via the ``Pin`` class. The pins which - support PWM functionality are the following: - - - ``GP24`` on Timer 0 channel A. - - ``GP25`` on Timer 1 channel A. - - ``GP9`` on Timer 2 channel B. - - ``GP10`` on Timer 3 channel A. - - ``GP11`` on Timer 3 channel B. - -.. only:: port_wipy - - class TimerChannel --- setup a channel for a timer - ================================================== - - Timer channels are used to generate/capture a signal using a timer. - - TimerChannel objects are created using the Timer.channel() method. - - Methods - ------- - - .. method:: timerchannel.irq(\*, trigger, priority=1, handler=None) - - The behavior of this callback is heavily dependent on the operating - mode of the timer channel: - - - If mode is ``Timer.PERIODIC`` the callback is executed periodically - with the configured frequency or period. - - If mode is ``Timer.ONE_SHOT`` the callback is executed once when - the configured timer expires. - - If mode is ``Timer.PWM`` the callback is executed when reaching the duty - cycle value. - - The accepted params are: - - - ``priority`` level of the interrupt. Can take values in the range 1-7. - Higher values represent higher priorities. - - ``handler`` is an optional function to be called when the interrupt is triggered. - - ``trigger`` must be ``Timer.TIMEOUT`` when the operating mode is either ``Timer.PERIODIC`` or - ``Timer.ONE_SHOT``. In the case that mode is ``Timer.PWM`` then trigger must be equal to - ``Timer.MATCH``. - - Returns a callback object. - -.. only:: port_wipy - - .. method:: timerchannel.freq([value]) - - Get or set the timer channel frequency (in Hz). - - .. method:: timerchannel.period([value]) - - Get or set the timer channel period (in microseconds). - - .. method:: timerchannel.duty_cycle([value]) - - Get or set the duty cycle of the PWM signal. It's a percentage (0.00-100.00). Since the WiPy - doesn't support floating point numbers the duty cycle must be specified in the range 0-10000, - where 10000 would represent 100.00, 5050 represents 50.50, and so on. - -Constants ---------- - -.. data:: Timer.ONE_SHOT -.. data:: Timer.PERIODIC - - Timer operating mode. diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst deleted file mode 100644 index 983ef0a94..000000000 --- a/docs/library/machine.UART.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. currentmodule:: machine -.. _machine.UART: - -class UART -- duplex serial communication bus -============================================= - -UART implements the standard UART/USART duplex serial communications protocol. At -the physical level it consists of 2 lines: RX and TX. The unit of communication -is a character (not to be confused with a string character) which can be 8 or 9 -bits wide. - -UART objects can be created and initialised using:: - - from machine import UART - - uart = UART(1, 9600) # init with given baudrate - uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters - -Supported parameters differ on a board: - -Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With *parity=None*, -only 8 and 9 bits are supported. With parity enabled, only 7 and 8 bits -are supported. - -WiPy/CC3200: Bits can be 5, 6, 7, 8. Stop can be 1 or 2. - -A UART object acts like a stream object and reading and writing is done -using the standard stream methods:: - - uart.read(10) # read 10 characters, returns a bytes object - uart.read() # read all available characters - uart.readline() # read a line - uart.readinto(buf) # read and store into the given buffer - uart.write('abc') # write the 3 characters - -Constructors ------------- - -.. class:: UART(id, ...) - - Construct a UART object of the given id. - -Methods -------- - -.. only:: port_wipy - - .. method:: UART.init(baudrate=9600, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS)) - - Initialise the UART bus with the given parameters: - - - ``baudrate`` is the clock rate. - - ``bits`` is the number of bits per character, 7, 8 or 9. - - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd). - - ``stop`` is the number of stop bits, 1 or 2. - - ``pins`` is a 4 or 2 item list indicating the TX, RX, RTS and CTS pins (in that order). - Any of the pins can be None if one wants the UART to operate with limited functionality. - If the RTS pin is given the the RX pin must be given as well. The same applies to CTS. - When no pins are given, then the default set of TX and RX pins is taken, and hardware - flow control will be disabled. If pins=None, no pin assignment will be made. - -.. method:: UART.deinit() - - Turn off the UART bus. - -.. method:: UART.any() - - Returns an integer counting the number of characters that can be read without - blocking. It will return 0 if there are no characters available and a positive - number if there are characters. The method may return 1 even if there is more - than one character available for reading. - - For more sophisticated querying of available characters use select.poll:: - - poll = select.poll() - poll.register(uart, select.POLLIN) - poll.poll(timeout) - -.. method:: UART.read([nbytes]) - - Read characters. If ``nbytes`` is specified then read at most that many bytes, - otherwise read as much data as possible. - - Return value: a bytes object containing the bytes read in. Returns ``None`` - on timeout. - -.. method:: UART.readinto(buf[, nbytes]) - - Read bytes into the ``buf``. If ``nbytes`` is specified then read at most - that many bytes. Otherwise, read at most ``len(buf)`` bytes. - - Return value: number of bytes read and stored into ``buf`` or ``None`` on - timeout. - -.. method:: UART.readline() - - Read a line, ending in a newline character. - - Return value: the line read or ``None`` on timeout. - -.. method:: UART.write(buf) - - Write the buffer of bytes to the bus. - - Return value: number of bytes written or ``None`` on timeout. - -.. method:: UART.sendbreak() - - Send a break condition on the bus. This drives the bus low for a duration - longer than required for a normal transmission of a character. - -.. only:: port_wipy - - .. method:: UART.irq(trigger, priority=1, handler=None, wake=machine.IDLE) - - Create a callback to be triggered when data is received on the UART. - - - ``trigger`` can only be ``UART.RX_ANY`` - - ``priority`` level of the interrupt. Can take values in the range 1-7. - Higher values represent higher priorities. - - ``handler`` an optional function to be called when new characters arrive. - - ``wake`` can only be ``machine.IDLE``. - - .. note:: - - The handler will be called whenever any of the following two conditions are met: - - - 8 new characters have been received. - - At least 1 new character is waiting in the Rx buffer and the Rx line has been - silent for the duration of 1 complete frame. - - This means that when the handler function is called there will be between 1 to 8 - characters waiting. - - Returns an irq object. - - Constants - --------- - - .. data:: UART.RX_ANY - - IRQ trigger sources diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst deleted file mode 100644 index 5ca6dce45..000000000 --- a/docs/library/machine.WDT.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. currentmodule:: machine -.. _machine.WDT: - -class WDT -- watchdog timer -=========================== - -The WDT is used to restart the system when the application crashes and ends -up into a non recoverable state. Once started it cannot be stopped or -reconfigured in any way. After enabling, the application must "feed" the -watchdog periodically to prevent it from expiring and resetting the system. - -Example usage:: - - from machine import WDT - wdt = WDT(timeout=2000) # enable it with a timeout of 2s - wdt.feed() - -Availability of this class: pyboard, WiPy. - -Constructors ------------- - -.. class:: WDT(id=0, timeout=5000) - - Create a WDT object and start it. The timeout must be given in seconds and - the minimum value that is accepted is 1 second. Once it is running the timeout - cannot be changed and the WDT cannot be stopped either. - -Methods -------- - -.. method:: wdt.feed() - - Feed the WDT to prevent it from resetting the system. The application - should place this call in a sensible place ensuring that the WDT is - only fed after verifying that everything is functioning correctly. diff --git a/docs/library/machine.rst b/docs/library/machine.rst deleted file mode 100644 index 087f19cc6..000000000 --- a/docs/library/machine.rst +++ /dev/null @@ -1,170 +0,0 @@ -:mod:`machine` --- functions related to the hardware -==================================================== - -.. module:: machine - :synopsis: functions related to the hardware - -The ``machine`` module contains specific functions related to the hardware -on a particular board. Most functions in this module allow to achieve direct -and unrestricted access to and control of hardware blocks on a system -(like CPU, timers, buses, etc.). Used incorrectly, this can lead to -malfunction, lockups, crashes of your board, and in extreme cases, hardware -damage. - -.. _machine_callbacks: - -A note of callbacks used by functions and class methods of :mod:`machine` module: -all these callbacks should be considered as executing in an interrupt context. -This is true for both physical devices with IDs >= 0 and "virtual" devices -with negative IDs like -1 (these "virtual" devices are still thin shims on -top of real hardware and real hardware interrupts). See :ref:`isr_rules`. - -Reset related functions ------------------------ - -.. function:: reset() - - Resets the device in a manner similar to pushing the external RESET - button. - -.. function:: reset_cause() - - Get the reset cause. See :ref:`constants <machine_constants>` for the possible return values. - -Interrupt related functions ---------------------------- - -.. function:: disable_irq() - - Disable interrupt requests. - Returns the previous IRQ state which should be considered an opaque value. - This return value should be passed to the `enable_irq()` function to restore - interrupts to their original state, before `disable_irq()` was called. - -.. function:: enable_irq(state) - - Re-enable interrupt requests. - The *state* parameter should be the value that was returned from the most - recent call to the `disable_irq()` function. - -Power related functions ------------------------ - -.. function:: freq() - - Returns CPU frequency in hertz. - -.. function:: idle() - - Gates the clock to the CPU, useful to reduce power consumption at any time during - short or long periods. Peripherals continue working and execution resumes as soon - as any interrupt is triggered (on many ports this includes system timer - interrupt occurring at regular intervals on the order of millisecond). - -.. function:: sleep() - - Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from - the point where the sleep was requested. For wake up to actually happen, wake sources - should be configured first. - -.. function:: deepsleep() - - Stops the CPU and all peripherals (including networking interfaces, if any). Execution - is resumed from the main script, just as with a reset. The reset cause can be checked - to know that we are coming from `machine.DEEPSLEEP`. For wake up to actually happen, - wake sources should be configured first, like `Pin` change or `RTC` timeout. - -.. only:: port_wipy - - .. function:: wake_reason() - - Get the wake reason. See :ref:`constants <machine_constants>` for the possible return values. - -Miscellaneous functions ------------------------ - -.. only:: port_wipy - - .. function:: rng() - - Return a 24-bit software generated random number. - -.. function:: unique_id() - - Returns a byte string with a unique identifier of a board/SoC. It will vary - from a board/SoC instance to another, if underlying hardware allows. Length - varies by hardware (so use substring of a full value if you expect a short - ID). In some MicroPython ports, ID corresponds to the network MAC address. - -.. function:: time_pulse_us(pin, pulse_level, timeout_us=1000000) - - Time a pulse on the given *pin*, and return the duration of the pulse in - microseconds. The *pulse_level* argument should be 0 to time a low pulse - or 1 to time a high pulse. - - If the current input value of the pin is different to *pulse_level*, - the function first (*) waits until the pin input becomes equal to *pulse_level*, - then (**) times the duration that the pin is equal to *pulse_level*. - If the pin is already equal to *pulse_level* then timing starts straight away. - - The function will return -2 if there was timeout waiting for condition marked - (*) above, and -1 if there was timeout during the main measurement, marked (**) - above. The timeout is the same for both cases and given by *timeout_us* (which - is in microseconds). - -.. _machine_constants: - -Constants ---------- - -.. data:: machine.IDLE - machine.SLEEP - machine.DEEPSLEEP - - IRQ wake values. - -.. data:: machine.PWRON_RESET - machine.HARD_RESET - machine.WDT_RESET - machine.DEEPSLEEP_RESET - machine.SOFT_RESET - - Reset causes. - -.. data:: machine.WLAN_WAKE - machine.PIN_WAKE - machine.RTC_WAKE - - Wake-up reasons. - -Classes -------- - -.. only:: not port_wipy - - .. toctree:: - :maxdepth: 1 - - machine.Pin.rst - machine.Signal.rst - machine.UART.rst - machine.SPI.rst - machine.I2C.rst - machine.RTC.rst - machine.Timer.rst - machine.WDT.rst - -.. only:: port_wipy - - .. toctree:: - :maxdepth: 1 - - machine.Pin.rst - machine.UART.rst - machine.SPI.rst - machine.I2C.rst - machine.RTC.rst - machine.Timer.rst - machine.WDT.rst - machine.ADC.rst - machine.SD.rst diff --git a/docs/library/math.rst b/docs/library/math.rst deleted file mode 100644 index a6f13d48c..000000000 --- a/docs/library/math.rst +++ /dev/null @@ -1,185 +0,0 @@ -:mod:`math` -- mathematical functions -===================================== - -.. module:: math - :synopsis: mathematical functions - -|see_cpython_module| :mod:`python:math`. - -The ``math`` module provides some basic mathematical functions for -working with floating-point numbers. - -*Note:* On the pyboard, floating-point numbers have 32-bit precision. - -Availability: not available on WiPy. Floating point support required -for this module. - -Functions ---------- - -.. function:: acos(x) - - Return the inverse cosine of ``x``. - -.. function:: acosh(x) - - Return the inverse hyperbolic cosine of ``x``. - -.. function:: asin(x) - - Return the inverse sine of ``x``. - -.. function:: asinh(x) - - Return the inverse hyperbolic sine of ``x``. - -.. function:: atan(x) - - Return the inverse tangent of ``x``. - -.. function:: atan2(y, x) - - Return the principal value of the inverse tangent of ``y/x``. - -.. function:: atanh(x) - - Return the inverse hyperbolic tangent of ``x``. - -.. function:: ceil(x) - - Return an integer, being ``x`` rounded towards positive infinity. - -.. function:: copysign(x, y) - - Return ``x`` with the sign of ``y``. - -.. function:: cos(x) - - Return the cosine of ``x``. - -.. function:: cosh(x) - - Return the hyperbolic cosine of ``x``. - -.. function:: degrees(x) - - Return radians ``x`` converted to degrees. - -.. function:: erf(x) - - Return the error function of ``x``. - -.. function:: erfc(x) - - Return the complementary error function of ``x``. - -.. function:: exp(x) - - Return the exponential of ``x``. - -.. function:: expm1(x) - - Return ``exp(x) - 1``. - -.. function:: fabs(x) - - Return the absolute value of ``x``. - -.. function:: floor(x) - - Return an integer, being ``x`` rounded towards negative infinity. - -.. function:: fmod(x, y) - - Return the remainder of ``x/y``. - -.. function:: frexp(x) - - Decomposes a floating-point number into its mantissa and exponent. - The returned value is the tuple ``(m, e)`` such that ``x == m * 2**e`` - exactly. If ``x == 0`` then the function returns ``(0.0, 0)``, otherwise - the relation ``0.5 <= abs(m) < 1`` holds. - -.. function:: gamma(x) - - Return the gamma function of ``x``. - -.. function:: isfinite(x) - - Return ``True`` if ``x`` is finite. - -.. function:: isinf(x) - - Return ``True`` if ``x`` is infinite. - -.. function:: isnan(x) - - Return ``True`` if ``x`` is not-a-number - -.. function:: ldexp(x, exp) - - Return ``x * (2**exp)``. - -.. function:: lgamma(x) - - Return the natural logarithm of the gamma function of ``x``. - -.. function:: log(x) - - Return the natural logarithm of ``x``. - -.. function:: log10(x) - - Return the base-10 logarithm of ``x``. - -.. function:: log2(x) - - Return the base-2 logarithm of ``x``. - -.. function:: modf(x) - - Return a tuple of two floats, being the fractional and integral parts of - ``x``. Both return values have the same sign as ``x``. - -.. function:: pow(x, y) - - Returns ``x`` to the power of ``y``. - -.. function:: radians(x) - - Return degrees ``x`` converted to radians. - -.. function:: sin(x) - - Return the sine of ``x``. - -.. function:: sinh(x) - - Return the hyperbolic sine of ``x``. - -.. function:: sqrt(x) - - Return the square root of ``x``. - -.. function:: tan(x) - - Return the tangent of ``x``. - -.. function:: tanh(x) - - Return the hyperbolic tangent of ``x``. - -.. function:: trunc(x) - - Return an integer, being ``x`` rounded towards 0. - -Constants ---------- - -.. data:: e - - base of the natural logarithm - -.. data:: pi - - the ratio of a circle's circumference to its diameter diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index c13a7391b..59e1886fa 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -1,6 +1,8 @@ :mod:`micropython` -- access and control MicroPython internals ============================================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: micropython :synopsis: access and control MicroPython internals diff --git a/docs/library/network.rst b/docs/library/network.rst index 99a7c242c..60c9756db 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -2,6 +2,8 @@ :mod:`network` --- network configuration **************************************** +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: network :synopsis: network configuration @@ -39,7 +41,7 @@ Common network adapter interface ================================ This section describes an (implied) abstract base class for all network -interface classes implemented by `MicroPython ports <MicroPython port>` +interface classes implemented by ``MicroPython ports <MicroPython port>`` for different hardware. This means that MicroPython does not actually provide ``AbstractNIC`` class, but any actual NIC class, as described in the following sections, implements methods as described here. @@ -131,461 +133,145 @@ parameter should be `id`. # Extended status information also available this way print(sta.config('rssi')) -.. only:: port_pyboard - - class CC3K - ========== - - This class provides a driver for CC3000 WiFi modules. Example usage:: - - import network - nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3) - nic.connect('your-ssid', 'your-password') - while not nic.isconnected(): - pyb.delay(50) - print(nic.ifconfig()) - - # now use socket as usual - ... - - For this example to work the CC3000 module must have the following connections: - - - MOSI connected to Y8 - - MISO connected to Y7 - - CLK connected to Y6 - - CS connected to Y5 - - VBEN connected to Y4 - - IRQ connected to Y3 - - It is possible to use other SPI busses and other pins for CS, VBEN and IRQ. - - Constructors - ------------ - - .. class:: CC3K(spi, pin_cs, pin_en, pin_irq) - - Create a CC3K driver object, initialise the CC3000 module using the given SPI bus - and pins, and return the CC3K object. - - Arguments are: - - - *spi* is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the CC3000 is - connected to (the MOSI, MISO and CLK pins). - - *pin_cs* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin. - - *pin_en* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin. - - *pin_irq* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 IRQ pin. - - All of these objects will be initialised by the driver, so there is no need to - initialise them yourself. For example, you can use:: - - nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3) - - Methods - ------- - - .. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None) - - Connect to a WiFi access point using the given SSID, and other security - parameters. - - .. method:: cc3k.disconnect() - - Disconnect from the WiFi access point. - - .. method:: cc3k.isconnected() - - Returns True if connected to a WiFi access point and has a valid IP address, - False otherwise. - - .. method:: cc3k.ifconfig() - - Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server, - MAC address, SSID). - - .. method:: cc3k.patch_version() - - Return the version of the patch program (firmware) on the CC3000. - - .. method:: cc3k.patch_program('pgm') - - Upload the current firmware to the CC3000. You must pass 'pgm' as the first - argument in order for the upload to proceed. - - Constants - --------- - - .. data:: CC3K.WEP - .. data:: CC3K.WPA - .. data:: CC3K.WPA2 - - security type to use - - class WIZNET5K - ============== - - This class allows you to control WIZnet5x00 Ethernet adaptors based on - the W5200 and W5500 chipsets. The particular chipset that is supported - by the firmware is selected at compile-time via the MICROPY_PY_WIZNET5K - option. - - Example usage:: - - import network - nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) - print(nic.ifconfig()) - - # now use socket as usual - ... - - For this example to work the WIZnet5x00 module must have the following connections: - - - MOSI connected to X8 - - MISO connected to X7 - - SCLK connected to X6 - - nSS connected to X5 - - nRESET connected to X4 - - It is possible to use other SPI busses and other pins for nSS and nRESET. - - Constructors - ------------ - - .. class:: WIZNET5K(spi, pin_cs, pin_rst) - - Create a WIZNET5K driver object, initialise the WIZnet5x00 module using the given - SPI bus and pins, and return the WIZNET5K object. - - Arguments are: - - - *spi* is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the WIZnet5x00 is - connected to (the MOSI, MISO and SCLK pins). - - *pin_cs* is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nSS pin. - - *pin_rst* is a :ref:`Pin object <pyb.Pin>` which is connected to the WIZnet5x00 nRESET pin. - - All of these objects will be initialised by the driver, so there is no need to - initialise them yourself. For example, you can use:: - - nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) - - Methods - ------- - - .. method:: wiznet5k.isconnected() - - Returns ``True`` if the physical Ethernet link is connected and up. - Returns ``False`` otherwise. - - .. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)]) - - Get/set IP address, subnet mask, gateway and DNS. - - When called with no arguments, this method returns a 4-tuple with the above information. - - To set the above values, pass a 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - - .. method:: wiznet5k.regs() - - Dump the WIZnet5x00 registers. Useful for debugging. - .. _network.WLAN: -.. only:: port_esp8266 - - Functions - ========= - - .. function:: phy_mode([mode]) - - Get or set the PHY mode. - - If the *mode* parameter is provided, sets the mode to its value. If - the function is called without parameters, returns the current mode. - - The possible modes are defined as constants: - * ``MODE_11B`` -- IEEE 802.11b, - * ``MODE_11G`` -- IEEE 802.11g, - * ``MODE_11N`` -- IEEE 802.11n. - - class WLAN - ========== - - This class provides a driver for WiFi network processor in the ESP8266. Example usage:: - - import network - # enable station interface and connect to WiFi access point - nic = network.WLAN(network.STA_IF) - nic.active(True) - nic.connect('your-ssid', 'your-password') - # now use sockets as usual - - Constructors - ------------ - .. class:: WLAN(interface_id) - - Create a WLAN network interface object. Supported interfaces are - ``network.STA_IF`` (station aka client, connects to upstream WiFi access - points) and ``network.AP_IF`` (access point, allows other WiFi clients to - connect). Availability of the methods below depends on interface type. - For example, only STA interface may `connect()` to an access point. - - Methods - ------- - - .. method:: wlan.active([is_active]) - - Activate ("up") or deactivate ("down") network interface, if boolean - argument is passed. Otherwise, query current state if no argument is - provided. Most other methods require active interface. - - .. method:: wlan.connect(ssid=None, password=None, \*, bssid=None) - - Connect to the specified wireless network, using the specified password. - If *bssid* is given then the connection will be restricted to the - access-point with that MAC address (the *ssid* must also be specified - in this case). - - .. method:: wlan.disconnect() - - Disconnect from the currently connected wireless network. - - .. method:: wlan.scan() - - Scan for the available wireless networks. - - Scanning is only possible on STA interface. Returns list of tuples with - the information about WiFi access points: - - (ssid, bssid, channel, RSSI, authmode, hidden) - - *bssid* is hardware address of an access point, in binary form, returned as - bytes object. You can use `ubinascii.hexlify()` to convert it to ASCII form. - - There are five values for authmode: - - * 0 -- open - * 1 -- WEP - * 2 -- WPA-PSK - * 3 -- WPA2-PSK - * 4 -- WPA/WPA2-PSK - - and two for hidden: - - * 0 -- visible - * 1 -- hidden - - .. method:: wlan.status() - - Return the current status of the wireless connection. - - The possible statuses are defined as constants: - - * ``STAT_IDLE`` -- no connection and no activity, - * ``STAT_CONNECTING`` -- connecting in progress, - * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password, - * ``STAT_NO_AP_FOUND`` -- failed because no access point replied, - * ``STAT_CONNECT_FAIL`` -- failed due to other problems, - * ``STAT_GOT_IP`` -- connection successful. - - .. method:: wlan.isconnected() +Functions +========= - In case of STA mode, returns ``True`` if connected to a WiFi access - point and has a valid IP address. In AP mode returns ``True`` when a - station is connected. Returns ``False`` otherwise. +.. function:: phy_mode([mode]) - .. method:: wlan.ifconfig([(ip, subnet, gateway, dns)]) + Get or set the PHY mode. - Get/set IP-level network interface parameters: IP address, subnet mask, - gateway and DNS server. When called with no arguments, this method returns - a 4-tuple with the above information. To set the above values, pass a - 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - - .. method:: wlan.config('param') - .. method:: wlan.config(param=value, ...) - - Get or set general network interface parameters. These methods allow to work - with additional parameters beyond standard IP configuration (as dealt with by - `wlan.ifconfig()`). These include network-specific and hardware-specific - parameters. For setting parameters, keyword argument syntax should be used, - multiple parameters can be set at once. For querying, parameters name should - be quoted as a string, and only one parameter can be queries at time:: - - # Set WiFi access point name (formally known as ESSID) and WiFi channel - ap.config(essid='My AP', channel=11) - # Query params one by one - print(ap.config('essid')) - print(ap.config('channel')) - - Following are commonly supported parameters (availability of a specific parameter - depends on network technology type, driver, and `MicroPython port`). - - ============= =========== - Parameter Description - ============= =========== - mac MAC address (bytes) - essid WiFi access point name (string) - channel WiFi channel (integer) - hidden Whether ESSID is hidden (boolean) - authmode Authentication mode supported (enumeration, see module constants) - password Access password (string) - dhcp_hostname The DHCP hostname to use - ============= =========== + If the *mode* parameter is provided, sets the mode to its value. If + the function is called without parameters, returns the current mode. + The possible modes are defined as constants: + * ``MODE_11B`` -- IEEE 802.11b, + * ``MODE_11G`` -- IEEE 802.11g, + * ``MODE_11N`` -- IEEE 802.11n. +class WLAN +========== -.. only:: port_wipy +This class provides a driver for WiFi network processor in the ESP8266. Example usage:: - class WLAN - ========== - - This class provides a driver for the WiFi network processor in the WiPy. Example usage:: - - import network - import time - # setup as a station - wlan = network.WLAN(mode=WLAN.STA) - wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key')) - while not wlan.isconnected(): - time.sleep_ms(50) - print(wlan.ifconfig()) - - # now use socket as usual - ... - - Constructors - ------------ - - .. class:: WLAN(id=0, ...) - - Create a WLAN object, and optionally configure it. See `init()` for params of configuration. - - .. note:: - - The ``WLAN`` constructor is special in the sense that if no arguments besides the id are given, - it will return the already existing ``WLAN`` instance without re-configuring it. This is - because ``WLAN`` is a system feature of the WiPy. If the already existing instance is not - initialized it will do the same as the other constructors an will initialize it with default - values. - - Methods - ------- - - .. method:: wlan.init(mode, \*, ssid, auth, channel, antenna) - - Set or get the WiFi network processor configuration. - - Arguments are: - - - *mode* can be either ``WLAN.STA`` or ``WLAN.AP``. - - *ssid* is a string with the ssid name. Only needed when mode is ``WLAN.AP``. - - *auth* is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``, - ``WLAN.WPA`` or ``WLAN.WPA2``. The key is a string with the network password. - If ``sec`` is ``WLAN.WEP`` the key must be a string representing hexadecimal - values (e.g. 'ABC1DE45BF'). Only needed when mode is ``WLAN.AP``. - - *channel* a number in the range 1-11. Only needed when mode is ``WLAN.AP``. - - *antenna* selects between the internal and the external antenna. Can be either - ``WLAN.INT_ANT`` or ``WLAN.EXT_ANT``. - - For example, you can do:: - - # create and configure as an access point - wlan.init(mode=WLAN.AP, ssid='wipy-wlan', auth=(WLAN.WPA2,'www.wipy.io'), channel=7, antenna=WLAN.INT_ANT) - - or:: - - # configure as an station - wlan.init(mode=WLAN.STA) - - .. method:: wlan.connect(ssid, \*, auth=None, bssid=None, timeout=None) - - Connect to a WiFi access point using the given SSID, and other security - parameters. - - - *auth* is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``, - ``WLAN.WPA`` or ``WLAN.WPA2``. The key is a string with the network password. - If ``sec`` is ``WLAN.WEP`` the key must be a string representing hexadecimal - values (e.g. 'ABC1DE45BF'). - - *bssid* is the MAC address of the AP to connect to. Useful when there are several - APs with the same ssid. - - *timeout* is the maximum time in milliseconds to wait for the connection to succeed. - - .. method:: wlan.scan() - - Performs a network scan and returns a list of named tuples with (ssid, bssid, sec, channel, rssi). - Note that channel is always ``None`` since this info is not provided by the WiPy. + import network + # enable station interface and connect to WiFi access point + nic = network.WLAN(network.STA_IF) + nic.active(True) + nic.connect('your-ssid', 'your-password') + # now use sockets as usual - .. method:: wlan.disconnect() +Constructors +------------ +.. class:: WLAN(interface_id) - Disconnect from the WiFi access point. +Create a WLAN network interface object. Supported interfaces are +``network.STA_IF`` (station aka client, connects to upstream WiFi access +points) and ``network.AP_IF`` (access point, allows other WiFi clients to +connect). Availability of the methods below depends on interface type. +For example, only STA interface may `connect()` to an access point. - .. method:: wlan.isconnected() +Methods +------- - In case of STA mode, returns ``True`` if connected to a WiFi access point and has a valid IP address. - In AP mode returns ``True`` when a station is connected, ``False`` otherwise. +.. method:: wlan.active([is_active]) - .. method:: wlan.ifconfig(if_id=0, config=['dhcp' or configtuple]) + Activate ("up") or deactivate ("down") network interface, if boolean + argument is passed. Otherwise, query current state if no argument is + provided. Most other methods require active interface. - With no parameters given returns a 4-tuple of *(ip, subnet_mask, gateway, DNS_server)*. +.. method:: wlan.connect(ssid=None, password=None, \*, bssid=None) - if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params - are negotiated with the AP. + Connect to the specified wireless network, using the specified password. + If *bssid* is given then the connection will be restricted to the + access-point with that MAC address (the *ssid* must also be specified + in this case). - If the 4-tuple config is given then a static IP is configured. For instance:: +.. method:: wlan.disconnect() - wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + Disconnect from the currently connected wireless network. - .. method:: wlan.mode([mode]) +.. method:: wlan.scan() - Get or set the WLAN mode. + Scan for the available wireless networks. - .. method:: wlan.ssid([ssid]) + Scanning is only possible on STA interface. Returns list of tuples with + the information about WiFi access points: - Get or set the SSID when in AP mode. + (ssid, bssid, channel, RSSI, authmode, hidden) - .. method:: wlan.auth([auth]) + *bssid* is hardware address of an access point, in binary form, returned as + bytes object. You can use `ubinascii.hexlify()` to convert it to ASCII form. - Get or set the authentication type when in AP mode. + There are five values for authmode: - .. method:: wlan.channel([channel]) + * 0 -- open + * 1 -- WEP + * 2 -- WPA-PSK + * 3 -- WPA2-PSK + * 4 -- WPA/WPA2-PSK - Get or set the channel (only applicable in AP mode). + and two for hidden: - .. method:: wlan.antenna([antenna]) + * 0 -- visible + * 1 -- hidden - Get or set the antenna type (external or internal). +.. method:: wlan.status() - .. method:: wlan.mac([mac_addr]) + Return the current status of the wireless connection. - Get or set a 6-byte long bytes object with the MAC address. + The possible statuses are defined as constants: - .. method:: wlan.irq(\*, handler, wake) + * ``STAT_IDLE`` -- no connection and no activity, + * ``STAT_CONNECTING`` -- connecting in progress, + * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password, + * ``STAT_NO_AP_FOUND`` -- failed because no access point replied, + * ``STAT_CONNECT_FAIL`` -- failed due to other problems, + * ``STAT_GOT_IP`` -- connection successful. - Create a callback to be triggered when a WLAN event occurs during ``machine.SLEEP`` - mode. Events are triggered by socket activity or by WLAN connection/disconnection. +.. method:: wlan.isconnected() - - *handler* is the function that gets called when the IRQ is triggered. - - *wake* must be ``machine.SLEEP``. + In case of STA mode, returns ``True`` if connected to a WiFi access + point and has a valid IP address. In AP mode returns ``True`` when a + station is connected. Returns ``False`` otherwise. - Returns an IRQ object. +.. method:: wlan.ifconfig([(ip, subnet, gateway, dns)]) - Constants - --------- + Get/set IP-level network interface parameters: IP address, subnet mask, + gateway and DNS server. When called with no arguments, this method returns + a 4-tuple with the above information. To set the above values, pass a + 4-tuple with the required information. For example:: - .. data:: WLAN.STA - .. data:: WLAN.AP + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - selects the WLAN mode +.. method:: wlan.config('param') +.. method:: wlan.config(param=value, ...) - .. data:: WLAN.WEP - .. data:: WLAN.WPA - .. data:: WLAN.WPA2 + Get or set general network interface parameters. These methods allow to work + with additional parameters beyond standard IP configuration (as dealt with by + `wlan.ifconfig()`). These include network-specific and hardware-specific + parameters. For setting parameters, keyword argument syntax should be used, + multiple parameters can be set at once. For querying, parameters name should + be quoted as a string, and only one parameter can be queries at time:: - selects the network security + # Set WiFi access point name (formally known as ESSID) and WiFi channel + ap.config(essid='My AP', channel=11) + # Query params one by one + print(ap.config('essid')) + print(ap.config('channel')) - .. data:: WLAN.INT_ANT - .. data:: WLAN.EXT_ANT + Following are commonly supported parameters (availability of a specific parameter + depends on network technology type, driver, and ``MicroPython port``). - selects the antenna type + ============= =========== + Parameter Description + ============= =========== + mac MAC address (bytes) + essid WiFi access point name (string) + channel WiFi channel (integer) + hidden Whether ESSID is hidden (boolean) + authmode Authentication mode supported (enumeration, see module constants) + password Access password (string) + dhcp_hostname The DHCP hostname to use + ============= =========== diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst deleted file mode 100644 index 51021fdc1..000000000 --- a/docs/library/pyb.ADC.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.ADC: - -class ADC -- analog to digital conversion -========================================= - -.. only:: port_pyboard - - Usage:: - - import pyb - - adc = pyb.ADC(pin) # create an analog object from a pin - val = adc.read() # read an analog value - - adc = pyb.ADCAll(resolution) # create an ADCAll object - val = adc.read_channel(channel) # read the given channel - val = adc.read_core_temp() # read MCU temperature - val = adc.read_core_vbat() # read MCU VBAT - val = adc.read_core_vref() # read MCU VREF - - -Constructors ------------- - - -.. only:: port_pyboard - - .. class:: pyb.ADC(pin) - - Create an ADC object associated with the given pin. - This allows you to then read analog values on that pin. - -Methods -------- - -.. only:: port_pyboard - - .. method:: ADC.read() - - Read the value on the analog pin and return it. The returned value - will be between 0 and 4095. - - .. method:: ADC.read_timed(buf, timer) - - Read analog values into ``buf`` at a rate set by the ``timer`` object. - - ``buf`` can be bytearray or array.array for example. The ADC values have - 12-bit resolution and are stored directly into ``buf`` if its element size is - 16 bits or greater. If ``buf`` has only 8-bit elements (eg a bytearray) then - the sample resolution will be reduced to 8 bits. - - ``timer`` should be a Timer object, and a sample is read each time the timer - triggers. The timer must already be initialised and running at the desired - sampling frequency. - - To support previous behaviour of this function, ``timer`` can also be an - integer which specifies the frequency (in Hz) to sample at. In this case - Timer(6) will be automatically configured to run at the given frequency. - - Example using a Timer object (preferred way):: - - adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19 - tim = pyb.Timer(6, freq=10) # create a timer running at 10Hz - buf = bytearray(100) # creat a buffer to store the samples - adc.read_timed(buf, tim) # sample 100 values, taking 10s - - Example using an integer for the frequency:: - - adc = pyb.ADC(pyb.Pin.board.X19) # create an ADC on pin X19 - buf = bytearray(100) # create a buffer of 100 bytes - adc.read_timed(buf, 10) # read analog values into buf at 10Hz - # this will take 10 seconds to finish - for val in buf: # loop over all values - print(val) # print the value out - - This function does not allocate any memory. - -The ADCAll Object ------------------ - -.. only:: port_pyboard - - Instantiating this changes all ADC pins to analog inputs. The raw MCU temperature, - VREF and VBAT data can be accessed on ADC channels 16, 17 and 18 respectively. - Appropriate scaling will need to be applied. The temperature sensor on the chip - has poor absolute accuracy and is suitable only for detecting temperature changes. - - The ``ADCAll`` ``read_core_vbat()`` and ``read_core_vref()`` methods read - the backup battery voltage and the (1.21V nominal) reference voltage using the - 3.3V supply as a reference. Assuming the ``ADCAll`` object has been Instantiated with - ``adc = pyb.ADCAll(12)`` the 3.3V supply voltage may be calculated: - - ``v33 = 3.3 * 1.21 / adc.read_core_vref()`` - - If the 3.3V supply is correct the value of ``adc.read_core_vbat()`` will be - valid. If the supply voltage can drop below 3.3V, for example in in battery - powered systems with a discharging battery, the regulator will fail to preserve - the 3.3V supply resulting in an incorrect reading. To produce a value which will - remain valid under these circumstances use the following: - - ``vback = adc.read_core_vbat() * 1.21 / adc.read_core_vref()`` - - It is possible to access these values without incurring the side effects of ``ADCAll``:: - - def adcread(chan): # 16 temp 17 vbat 18 vref - assert chan >= 16 and chan <= 18, 'Invalid ADC channel' - start = pyb.millis() - timeout = 100 - stm.mem32[stm.RCC + stm.RCC_APB2ENR] |= 0x100 # enable ADC1 clock.0x4100 - stm.mem32[stm.ADC1 + stm.ADC_CR2] = 1 # Turn on ADC - stm.mem32[stm.ADC1 + stm.ADC_CR1] = 0 # 12 bit - if chan == 17: - stm.mem32[stm.ADC1 + stm.ADC_SMPR1] = 0x200000 # 15 cycles - stm.mem32[stm.ADC + 4] = 1 << 23 - elif chan == 18: - stm.mem32[stm.ADC1 + stm.ADC_SMPR1] = 0x1000000 - stm.mem32[stm.ADC + 4] = 0xc00000 - else: - stm.mem32[stm.ADC1 + stm.ADC_SMPR1] = 0x40000 - stm.mem32[stm.ADC + 4] = 1 << 23 - stm.mem32[stm.ADC1 + stm.ADC_SQR3] = chan - stm.mem32[stm.ADC1 + stm.ADC_CR2] = 1 | (1 << 30) | (1 << 10) # start conversion - while not stm.mem32[stm.ADC1 + stm.ADC_SR] & 2: # wait for EOC - if pyb.elapsed_millis(start) > timeout: - raise OSError('ADC timout') - data = stm.mem32[stm.ADC1 + stm.ADC_DR] # clear down EOC - stm.mem32[stm.ADC1 + stm.ADC_CR2] = 0 # Turn off ADC - return data - - def v33(): - return 4096 * 1.21 / adcread(17) - - def vbat(): - return 1.21 * 2 * adcread(18) / adcread(17) # 2:1 divider on Vbat channel - - def vref(): - return 3.3 * adcread(17) / 4096 - - def temperature(): - return 25 + 400 * (3.3 * adcread(16) / 4096 - 0.76) - -
\ No newline at end of file diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst deleted file mode 100644 index 9ade5c5c8..000000000 --- a/docs/library/pyb.Accel.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.Accel: - -class Accel -- accelerometer control -==================================== - -Accel is an object that controls the accelerometer. Example usage:: - - accel = pyb.Accel() - for i in range(10): - print(accel.x(), accel.y(), accel.z()) - -Raw values are between -32 and 31. - - -Constructors ------------- - -.. class:: pyb.Accel() - - Create and return an accelerometer object. - -Methods -------- - -.. method:: Accel.filtered_xyz() - - Get a 3-tuple of filtered x, y and z values. - - Implementation note: this method is currently implemented as taking the - sum of 4 samples, sampled from the 3 previous calls to this function along - with the sample from the current call. Returned values are therefore 4 - times the size of what they would be from the raw x(), y() and z() calls. - -.. method:: Accel.tilt() - - Get the tilt register. - -.. method:: Accel.x() - - Get the x-axis value. - -.. method:: Accel.y() - - Get the y-axis value. - -.. method:: Accel.z() - - Get the z-axis value. - -Hardware Note -------------- - -The accelerometer uses I2C bus 1 to communicate with the processor. Consequently -when readings are being taken pins X9 and X10 should be unused (other than for -I2C). Other devices using those pins, and which therefore cannot be used -concurrently, are UART 1 and Timer 4 channels 1 and 2. diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst deleted file mode 100644 index 232d04d96..000000000 --- a/docs/library/pyb.CAN.rst +++ /dev/null @@ -1,223 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.CAN: - -class CAN -- controller area network communication bus -====================================================== - -CAN implements the standard CAN communications protocol. At -the physical level it consists of 2 lines: RX and TX. Note that -to connect the pyboard to a CAN bus you must use a CAN transceiver -to convert the CAN logic signals from the pyboard to the correct -voltage levels on the bus. - -Example usage (works without anything connected):: - - from pyb import CAN - can = CAN(1, CAN.LOOPBACK) - can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126)) # set a filter to receive messages with id=123, 124, 125 and 126 - can.send('message!', 123) # send a message with id 123 - can.recv(0) # receive message on FIFO 0 - - -Constructors ------------- - -.. class:: pyb.CAN(bus, ...) - - Construct a CAN object on the given bus. ``bus`` can be 1-2, or 'YA' or 'YB'. - With no additional parameters, the CAN object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - - The physical pins of the CAN busses are: - - - ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)`` - - ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)`` - -Class Methods -------------- -.. classmethod:: CAN.initfilterbanks(nr) - - Reset and disable all filter banks and assign how many banks should be available for CAN(1). - - STM32F405 has 28 filter banks that are shared between the two available CAN bus controllers. - This function configures how many filter banks should be assigned to each. ``nr`` is the number of banks - that will be assigned to CAN(1), the rest of the 28 are assigned to CAN(2). - At boot, 14 banks are assigned to each controller. - -Methods -------- - -.. method:: CAN.init(mode, extframe=False, prescaler=100, \*, sjw=1, bs1=6, bs2=8) - - Initialise the CAN bus with the given parameters: - - - ``mode`` is one of: NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK - - if ``extframe`` is True then the bus uses extended identifiers in the frames - (29 bits); otherwise it uses standard 11 bit identifiers - - ``prescaler`` is used to set the duration of 1 time quanta; the time quanta - will be the input clock (PCLK1, see :meth:`pyb.freq()`) divided by the prescaler - - ``sjw`` is the resynchronisation jump width in units of the time quanta; - it can be 1, 2, 3, 4 - - ``bs1`` defines the location of the sample point in units of the time quanta; - it can be between 1 and 1024 inclusive - - ``bs2`` defines the location of the transmit point in units of the time quanta; - it can be between 1 and 16 inclusive - - The time quanta tq is the basic unit of time for the CAN bus. tq is the CAN - prescaler value divided by PCLK1 (the frequency of internal peripheral bus 1); - see :meth:`pyb.freq()` to determine PCLK1. - - A single bit is made up of the synchronisation segment, which is always 1 tq. - Then follows bit segment 1, then bit segment 2. The sample point is after bit - segment 1 finishes. The transmit point is after bit segment 2 finishes. - The baud rate will be 1/bittime, where the bittime is 1 + BS1 + BS2 multiplied - by the time quanta tq. - - For example, with PCLK1=42MHz, prescaler=100, sjw=1, bs1=6, bs2=8, the value of - tq is 2.38 microseconds. The bittime is 35.7 microseconds, and the baudrate - is 28kHz. - - See page 680 of the STM32F405 datasheet for more details. - -.. method:: CAN.deinit() - - Turn off the CAN bus. - -.. method:: CAN.setfilter(bank, mode, fifo, params, \*, rtr) - - Configure a filter bank: - - - ``bank`` is the filter bank that is to be configured. - - ``mode`` is the mode the filter should operate in. - - ``fifo`` is which fifo (0 or 1) a message should be stored in, if it is accepted by this filter. - - ``params`` is an array of values the defines the filter. The contents of the array depends on the ``mode`` argument. - - +-----------+---------------------------------------------------------+ - |``mode`` |contents of parameter array | - +===========+=========================================================+ - |CAN.LIST16 |Four 16 bit ids that will be accepted | - +-----------+---------------------------------------------------------+ - |CAN.LIST32 |Two 32 bit ids that will be accepted | - +-----------+---------------------------------------------------------+ - |CAN.MASK16 |Two 16 bit id/mask pairs. E.g. (1, 3, 4, 4) | - | | | The first pair, 1 and 3 will accept all ids | - | | | that have bit 0 = 1 and bit 1 = 0. | - | | | The second pair, 4 and 4, will accept all ids | - | | | that have bit 2 = 1. | - +-----------+---------------------------------------------------------+ - |CAN.MASK32 |As with CAN.MASK16 but with only one 32 bit id/mask pair.| - +-----------+---------------------------------------------------------+ - - - ``rtr`` is an array of booleans that states if a filter should accept a - remote transmission request message. If this argument is not given - then it defaults to False for all entries. The length of the array - depends on the ``mode`` argument. - - +-----------+----------------------+ - |``mode`` |length of rtr array | - +===========+======================+ - |CAN.LIST16 |4 | - +-----------+----------------------+ - |CAN.LIST32 |2 | - +-----------+----------------------+ - |CAN.MASK16 |2 | - +-----------+----------------------+ - |CAN.MASK32 |1 | - +-----------+----------------------+ - -.. method:: CAN.clearfilter(bank) - - Clear and disables a filter bank: - - - ``bank`` is the filter bank that is to be cleared. - -.. method:: CAN.any(fifo) - - Return ``True`` if any message waiting on the FIFO, else ``False``. - -.. method:: CAN.recv(fifo, \*, timeout=5000) - - Receive data on the bus: - - - ``fifo`` is an integer, which is the FIFO to receive on - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: A tuple containing four values. - - - The id of the message. - - A boolean that indicates if the message is an RTR message. - - The FMI (Filter Match Index) value. - - An array containing the data. - -.. method:: CAN.send(data, id, \*, timeout=0, rtr=False) - - Send a message on the bus: - - - ``data`` is the data to send (an integer to send, or a buffer object). - - ``id`` is the id of the message to be sent. - - ``timeout`` is the timeout in milliseconds to wait for the send. - - ``rtr`` is a boolean that specifies if the message shall be sent as - a remote transmission request. If ``rtr`` is True then only the length - of ``data`` is used to fill in the DLC slot of the frame; the actual - bytes in ``data`` are unused. - - If timeout is 0 the message is placed in a buffer in one of three hardware - buffers and the method returns immediately. If all three buffers are in use - an exception is thrown. If timeout is not 0, the method waits until the - message is transmitted. If the message can't be transmitted within the - specified time an exception is thrown. - - Return value: ``None``. - -.. method:: CAN.rxcallback(fifo, fun) - - Register a function to be called when a message is accepted into a empty fifo: - - - ``fifo`` is the receiving fifo. - - ``fun`` is the function to be called when the fifo becomes non empty. - - The callback function takes two arguments the first is the can object it self the second is - a integer that indicates the reason for the callback. - - +--------+------------------------------------------------+ - | Reason | | - +========+================================================+ - | 0 | A message has been accepted into a empty FIFO. | - +--------+------------------------------------------------+ - | 1 | The FIFO is full | - +--------+------------------------------------------------+ - | 2 | A message has been lost due to a full FIFO | - +--------+------------------------------------------------+ - - Example use of rxcallback:: - - def cb0(bus, reason): - print('cb0') - if reason == 0: - print('pending') - if reason == 1: - print('full') - if reason == 2: - print('overflow') - - can = CAN(1, CAN.LOOPBACK) - can.rxcallback(0, cb0) - -Constants ---------- - -.. data:: CAN.NORMAL -.. data:: CAN.LOOPBACK -.. data:: CAN.SILENT -.. data:: CAN.SILENT_LOOPBACK - - the mode of the CAN bus - -.. data:: CAN.LIST16 -.. data:: CAN.MASK16 -.. data:: CAN.LIST32 -.. data:: CAN.MASK32 - - the operation mode of a filter diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst deleted file mode 100644 index fd786b63b..000000000 --- a/docs/library/pyb.DAC.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.DAC: - -class DAC -- digital to analog conversion -========================================= - -The DAC is used to output analog values (a specific voltage) on pin X5 or pin X6. -The voltage will be between 0 and 3.3V. - -*This module will undergo changes to the API.* - -Example usage:: - - from pyb import DAC - - dac = DAC(1) # create DAC 1 on pin X5 - dac.write(128) # write a value to the DAC (makes X5 1.65V) - - dac = DAC(1, bits=12) # use 12 bit resolution - dac.write(4095) # output maximum value, 3.3V - -To output a continuous sine-wave:: - - import math - from pyb import DAC - - # create a buffer containing a sine-wave - buf = bytearray(100) - for i in range(len(buf)): - buf[i] = 128 + int(127 * math.sin(2 * math.pi * i / len(buf))) - - # output the sine-wave at 400Hz - dac = DAC(1) - dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR) - -To output a continuous sine-wave at 12-bit resolution:: - - import math - from array import array - from pyb import DAC - - # create a buffer containing a sine-wave, using half-word samples - buf = array('H', 2048 + int(2047 * math.sin(2 * math.pi * i / 128)) for i in range(128)) - - # output the sine-wave at 400Hz - dac = DAC(1, bits=12) - dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR) - -Constructors ------------- - -.. class:: pyb.DAC(port, bits=8) - - Construct a new DAC object. - - ``port`` can be a pin object, or an integer (1 or 2). - DAC(1) is on pin X5 and DAC(2) is on pin X6. - - ``bits`` is an integer specifying the resolution, and can be 8 or 12. - The maximum value for the write and write_timed methods will be - 2\*\*``bits``-1. - -Methods -------- - -.. method:: DAC.init(bits=8) - - Reinitialise the DAC. ``bits`` can be 8 or 12. - -.. method:: DAC.deinit() - - De-initialise the DAC making its pin available for other uses. - -.. method:: DAC.noise(freq) - - Generate a pseudo-random noise signal. A new random sample is written - to the DAC output at the given frequency. - -.. method:: DAC.triangle(freq) - - Generate a triangle wave. The value on the DAC output changes at - the given frequency, and the frequency of the repeating triangle wave - itself is 2048 times smaller. - -.. method:: DAC.write(value) - - Direct access to the DAC output. The minimum value is 0. The maximum - value is 2\*\*``bits``-1, where ``bits`` is set when creating the DAC - object or by using the ``init`` method. - -.. method:: DAC.write_timed(data, freq, \*, mode=DAC.NORMAL) - - Initiates a burst of RAM to DAC using a DMA transfer. - The input data is treated as an array of bytes in 8-bit mode, and - an array of unsigned half-words (array typecode 'H') in 12-bit mode. - - ``freq`` can be an integer specifying the frequency to write the DAC - samples at, using Timer(6). Or it can be an already-initialised - Timer object which is used to trigger the DAC sample. Valid timers - are 2, 4, 5, 6, 7 and 8. - - ``mode`` can be ``DAC.NORMAL`` or ``DAC.CIRCULAR``. - - Example using both DACs at the same time:: - - dac1 = DAC(1) - dac2 = DAC(2) - dac1.write_timed(buf1, pyb.Timer(6, freq=100), mode=DAC.CIRCULAR) - dac2.write_timed(buf2, pyb.Timer(7, freq=200), mode=DAC.CIRCULAR) diff --git a/docs/library/pyb.ExtInt.rst b/docs/library/pyb.ExtInt.rst deleted file mode 100644 index 814217cef..000000000 --- a/docs/library/pyb.ExtInt.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.ExtInt: - -class ExtInt -- configure I/O pins to interrupt on external events -================================================================== - -There are a total of 22 interrupt lines. 16 of these can come from GPIO pins -and the remaining 6 are from internal sources. - -For lines 0 through 15, a given line can map to the corresponding line from an -arbitrary port. So line 0 can map to Px0 where x is A, B, C, ... and -line 1 can map to Px1 where x is A, B, C, ... :: - - def callback(line): - print("line =", line) - -Note: ExtInt will automatically configure the gpio line as an input. :: - - extint = pyb.ExtInt(pin, pyb.ExtInt.IRQ_FALLING, pyb.Pin.PULL_UP, callback) - -Now every time a falling edge is seen on the X1 pin, the callback will be -called. Caution: mechanical pushbuttons have "bounce" and pushing or -releasing a switch will often generate multiple edges. -See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed -explanation, along with various techniques for debouncing. - -Trying to register 2 callbacks onto the same pin will throw an exception. - -If pin is passed as an integer, then it is assumed to map to one of the -internal interrupt sources, and must be in the range 16 through 22. - -All other pin objects go through the pin mapper to come up with one of the -gpio pins. :: - - extint = pyb.ExtInt(pin, mode, pull, callback) - -Valid modes are pyb.ExtInt.IRQ_RISING, pyb.ExtInt.IRQ_FALLING, -pyb.ExtInt.IRQ_RISING_FALLING, pyb.ExtInt.EVT_RISING, -pyb.ExtInt.EVT_FALLING, and pyb.ExtInt.EVT_RISING_FALLING. - -Only the IRQ_xxx modes have been tested. The EVT_xxx modes have -something to do with sleep mode and the WFE instruction. - -Valid pull values are pyb.Pin.PULL_UP, pyb.Pin.PULL_DOWN, pyb.Pin.PULL_NONE. - -There is also a C API, so that drivers which require EXTI interrupt lines -can also use this code. See extint.h for the available functions and -usrsw.h for an example of using this. - - -Constructors ------------- - -.. class:: pyb.ExtInt(pin, mode, pull, callback) - - Create an ExtInt object: - - - ``pin`` is the pin on which to enable the interrupt (can be a pin object or any valid pin name). - - ``mode`` can be one of: - - ``ExtInt.IRQ_RISING`` - trigger on a rising edge; - - ``ExtInt.IRQ_FALLING`` - trigger on a falling edge; - - ``ExtInt.IRQ_RISING_FALLING`` - trigger on a rising or falling edge. - - ``pull`` can be one of: - - ``pyb.Pin.PULL_NONE`` - no pull up or down resistors; - - ``pyb.Pin.PULL_UP`` - enable the pull-up resistor; - - ``pyb.Pin.PULL_DOWN`` - enable the pull-down resistor. - - ``callback`` is the function to call when the interrupt triggers. The - callback function must accept exactly 1 argument, which is the line that - triggered the interrupt. - - -Class methods -------------- - -.. classmethod:: ExtInt.regs() - - Dump the values of the EXTI registers. - - -Methods -------- - -.. method:: ExtInt.disable() - - Disable the interrupt associated with the ExtInt object. - This could be useful for debouncing. - -.. method:: ExtInt.enable() - - Enable a disabled interrupt. - -.. method:: ExtInt.line() - - Return the line number that the pin is mapped to. - -.. method:: ExtInt.swint() - - Trigger the callback from software. - - -Constants ---------- - -.. data:: ExtInt.IRQ_FALLING - - interrupt on a falling edge - -.. data:: ExtInt.IRQ_RISING - - interrupt on a rising edge - -.. data:: ExtInt.IRQ_RISING_FALLING - - interrupt on a rising or falling edge diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst deleted file mode 100644 index 740031890..000000000 --- a/docs/library/pyb.I2C.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.I2C: - -class I2C -- a two-wire serial protocol -======================================= - -I2C is a two-wire protocol for communicating between devices. At the physical -level it consists of 2 wires: SCL and SDA, the clock and data lines respectively. - -I2C objects are created attached to a specific bus. They can be initialised -when created, or initialised later on. - -.. only:: port_pyboard - - Example:: - - from pyb import I2C - - i2c = I2C(1) # create on bus 1 - i2c = I2C(1, I2C.MASTER) # create and init as a master - i2c.init(I2C.MASTER, baudrate=20000) # init as a master - i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address - i2c.deinit() # turn off the peripheral - -Printing the i2c object gives you information about its configuration. - -.. only:: port_pyboard - - The basic methods are send and recv:: - - i2c.send('abc') # send 3 bytes - i2c.send(0x42) # send a single byte, given by the number - data = i2c.recv(3) # receive 3 bytes - - To receive inplace, first create a bytearray:: - - data = bytearray(3) # create a buffer - i2c.recv(data) # receive 3 bytes, writing them into data - - You can specify a timeout (in ms):: - - i2c.send(b'123', timeout=2000) # timeout after 2 seconds - - A master must specify the recipient's address:: - - i2c.init(I2C.MASTER) - i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42 - i2c.send(b'456', addr=0x42) # keyword for address - - Master also has other methods:: - - i2c.is_ready(0x42) # check if slave 0x42 is ready - i2c.scan() # scan for slaves on the bus, returning - # a list of valid addresses - i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42, - # starting at address 2 in the slave - i2c.mem_write('abc', 0x42, 2, timeout=1000) # write 'abc' (3 bytes) to memory of slave 0x42 - # starting at address 2 in the slave, timeout after 1 second - -Constructors ------------- - -.. only:: port_pyboard - - .. class:: pyb.I2C(bus, ...) - - Construct an I2C object on the given bus. ``bus`` can be 1 or 2, 'X' or - 'Y'. With no additional parameters, the I2C object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - - The physical pins of the I2C busses on Pyboards V1.0 and V1.1 are: - - - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)`` - - ``I2C(2)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PB10, PB11)`` - - On the Pyboard Lite: - - - ``I2C(1)`` is on the X position: ``(SCL, SDA) = (X9, X10) = (PB6, PB7)`` - - ``I2C(3)`` is on the Y position: ``(SCL, SDA) = (Y9, Y10) = (PA8, PB8)`` - - Calling the constructor with 'X' or 'Y' enables portability between Pyboard - types. - -Methods -------- - -.. method:: I2C.deinit() - - Turn off the I2C bus. - -.. only:: port_pyboard - - .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False, dma=False) - - Initialise the I2C bus with the given parameters: - - - ``mode`` must be either ``I2C.MASTER`` or ``I2C.SLAVE`` - - ``addr`` is the 7-bit address (only sensible for a slave) - - ``baudrate`` is the SCL clock rate (only sensible for a master) - - ``gencall`` is whether to support general call mode - - ``dma`` is whether to allow the use of DMA for the I2C transfers (note - that DMA transfers have more precise timing but currently do not handle bus - errors properly) - - .. method:: I2C.is_ready(addr) - - Check if an I2C device responds to the given address. Only valid when in master mode. - - .. method:: I2C.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8) - - Read from the memory of an I2C device: - - - ``data`` can be an integer (number of bytes to read) or a buffer to read into - - ``addr`` is the I2C device address - - ``memaddr`` is the memory location within the I2C device - - ``timeout`` is the timeout in milliseconds to wait for the read - - ``addr_size`` selects width of memaddr: 8 or 16 bits - - Returns the read data. - This is only valid in master mode. - - .. method:: I2C.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8) - - Write to the memory of an I2C device: - - - ``data`` can be an integer or a buffer to write from - - ``addr`` is the I2C device address - - ``memaddr`` is the memory location within the I2C device - - ``timeout`` is the timeout in milliseconds to wait for the write - - ``addr_size`` selects width of memaddr: 8 or 16 bits - - Returns ``None``. - This is only valid in master mode. - - .. method:: I2C.recv(recv, addr=0x00, \*, timeout=5000) - - Receive data on the bus: - - - ``recv`` can be an integer, which is the number of bytes to receive, - or a mutable buffer, which will be filled with received bytes - - ``addr`` is the address to receive from (only required in master mode) - - ``timeout`` is the timeout in milliseconds to wait for the receive - - Return value: if ``recv`` is an integer then a new buffer of the bytes received, - otherwise the same buffer that was passed in to ``recv``. - - .. method:: I2C.send(send, addr=0x00, \*, timeout=5000) - - Send data on the bus: - - - ``send`` is the data to send (an integer to send, or a buffer object) - - ``addr`` is the address to send to (only required in master mode) - - ``timeout`` is the timeout in milliseconds to wait for the send - - Return value: ``None``. - -.. method:: I2C.scan() - - Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond. - Only valid when in master mode. - -Constants ---------- - -.. data:: I2C.MASTER - - for initialising the bus to master mode - -.. only:: port_pyboard - - .. data:: I2C.SLAVE - - for initialising the bus to slave mode diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst deleted file mode 100644 index 5ab127edc..000000000 --- a/docs/library/pyb.LCD.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.LCD: - -class LCD -- LCD control for the LCD touch-sensor pyskin -======================================================== - -The LCD class is used to control the LCD on the LCD touch-sensor pyskin, -LCD32MKv1.0. The LCD is a 128x32 pixel monochrome screen, part NHD-C12832A1Z. - -The pyskin must be connected in either the X or Y positions, and then -an LCD object is made using:: - - lcd = pyb.LCD('X') # if pyskin is in the X position - lcd = pyb.LCD('Y') # if pyskin is in the Y position - -Then you can use:: - - lcd.light(True) # turn the backlight on - lcd.write('Hello world!\n') # print text to the screen - -This driver implements a double buffer for setting/getting pixels. -For example, to make a bouncing dot, try:: - - x = y = 0 - dx = dy = 1 - while True: - # update the dot's position - x += dx - y += dy - - # make the dot bounce of the edges of the screen - if x <= 0 or x >= 127: dx = -dx - if y <= 0 or y >= 31: dy = -dy - - lcd.fill(0) # clear the buffer - lcd.pixel(x, y, 1) # draw the dot - lcd.show() # show the buffer - pyb.delay(50) # pause for 50ms - - -Constructors ------------- - -.. class:: pyb.LCD(skin_position) - - Construct an LCD object in the given skin position. ``skin_position`` can be 'X' or 'Y', and - should match the position where the LCD pyskin is plugged in. - - -Methods -------- - -.. method:: LCD.command(instr_data, buf) - - Send an arbitrary command to the LCD. Pass 0 for ``instr_data`` to send an - instruction, otherwise pass 1 to send data. ``buf`` is a buffer with the - instructions/data to send. - -.. method:: LCD.contrast(value) - - Set the contrast of the LCD. Valid values are between 0 and 47. - -.. method:: LCD.fill(colour) - - Fill the screen with the given colour (0 or 1 for white or black). - - This method writes to the hidden buffer. Use ``show()`` to show the buffer. - -.. method:: LCD.get(x, y) - - Get the pixel at the position ``(x, y)``. Returns 0 or 1. - - This method reads from the visible buffer. - -.. method:: LCD.light(value) - - Turn the backlight on/off. True or 1 turns it on, False or 0 turns it off. - -.. method:: LCD.pixel(x, y, colour) - - Set the pixel at ``(x, y)`` to the given colour (0 or 1). - - This method writes to the hidden buffer. Use ``show()`` to show the buffer. - -.. method:: LCD.show() - - Show the hidden buffer on the screen. - -.. method:: LCD.text(str, x, y, colour) - - Draw the given text to the position ``(x, y)`` using the given colour (0 or 1). - - This method writes to the hidden buffer. Use ``show()`` to show the buffer. - -.. method:: LCD.write(str) - - Write the string ``str`` to the screen. It will appear immediately. diff --git a/docs/library/pyb.LED.rst b/docs/library/pyb.LED.rst deleted file mode 100644 index 1ab73a69c..000000000 --- a/docs/library/pyb.LED.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.LED: - -class LED -- LED object -======================= - -The LED object controls an individual LED (Light Emitting Diode). - - -Constructors ------------- - -.. class:: pyb.LED(id) - - Create an LED object associated with the given LED: - - - ``id`` is the LED number, 1-4. - - -Methods -------- - -.. method:: LED.intensity([value]) - - Get or set the LED intensity. Intensity ranges between 0 (off) and 255 (full on). - If no argument is given, return the LED intensity. - If an argument is given, set the LED intensity and return ``None``. - - *Note:* Only LED(3) and LED(4) can have a smoothly varying intensity, and - they use timer PWM to implement it. LED(3) uses Timer(2) and LED(4) uses - Timer(3). These timers are only configured for PWM if the intensity of the - relevant LED is set to a value between 1 and 254. Otherwise the timers are - free for general purpose use. - -.. method:: LED.off() - - Turn the LED off. - -.. method:: LED.on() - - Turn the LED on, to maximum intensity. - -.. method:: LED.toggle() - - Toggle the LED between on (maximum intensity) and off. If the LED is at - non-zero intensity then it is considered "on" and toggle will turn it off. diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst deleted file mode 100644 index b766c5280..000000000 --- a/docs/library/pyb.Pin.rst +++ /dev/null @@ -1,280 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.Pin: - -class Pin -- control I/O pins -============================= - -A pin is the basic object to control I/O pins. It has methods to set -the mode of the pin (input, output, etc) and methods to get and set the -digital logic level. For analog control of a pin, see the ADC class. - -Usage Model: - -.. only:: port_pyboard - - All Board Pins are predefined as pyb.Pin.board.Name:: - - x1_pin = pyb.Pin.board.X1 - - g = pyb.Pin(pyb.Pin.board.X1, pyb.Pin.IN) - - CPU pins which correspond to the board pins are available - as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter - followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and - ``pyb.Pin.cpu.A0`` are the same pin. - - You can also use strings:: - - g = pyb.Pin('X1', pyb.Pin.OUT_PP) - - Users can add their own names:: - - MyMapperDict = { 'LeftMotorDir' : pyb.Pin.cpu.C12 } - pyb.Pin.dict(MyMapperDict) - g = pyb.Pin("LeftMotorDir", pyb.Pin.OUT_OD) - - and can query mappings:: - - pin = pyb.Pin("LeftMotorDir") - - Users can also add their own mapping function:: - - def MyMapper(pin_name): - if pin_name == "LeftMotorDir": - return pyb.Pin.cpu.A0 - - pyb.Pin.mapper(MyMapper) - - So, if you were to call: ``pyb.Pin("LeftMotorDir", pyb.Pin.OUT_PP)`` - then ``"LeftMotorDir"`` is passed directly to the mapper function. - - To summarise, the following order determines how things get mapped into - an ordinal pin number: - - 1. Directly specify a pin object - 2. User supplied mapping function - 3. User supplied mapping (object must be usable as a dictionary key) - 4. Supply a string which matches a board pin - 5. Supply a string which matches a CPU port/pin - - You can set ``pyb.Pin.debug(True)`` to get some debug information about - how a particular object gets mapped to a pin. - - When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled, - that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND - respectively (except pin Y5 which has 11k Ohm resistors). - - Now every time a falling edge is seen on the gpio pin, the callback will be - executed. Caution: mechanical push buttons have "bounce" and pushing or - releasing a switch will often generate multiple edges. - See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed - explanation, along with various techniques for debouncing. - - All pin objects go through the pin mapper to come up with one of the - gpio pins. - -Constructors ------------- - -.. class:: pyb.Pin(id, ...) - - Create a new Pin object associated with the id. If additional arguments are given, - they are used to initialise the pin. See :meth:`pin.init`. - -.. only:: port_pyboard - - Class methods - ------------- - - .. classmethod:: Pin.debug([state]) - - Get or set the debugging state (``True`` or ``False`` for on or off). - - .. classmethod:: Pin.dict([dict]) - - Get or set the pin mapper dictionary. - - .. classmethod:: Pin.mapper([fun]) - - Get or set the pin mapper function. - - -Methods -------- - -.. only:: port_pyboard - - .. method:: Pin.init(mode, pull=Pin.PULL_NONE, af=-1) - - Initialise the pin: - - - ``mode`` can be one of: - - - ``Pin.IN`` - configure the pin for input; - - ``Pin.OUT_PP`` - configure the pin for output, with push-pull control; - - ``Pin.OUT_OD`` - configure the pin for output, with open-drain control; - - ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull; - - ``Pin.AF_OD`` - configure the pin for alternate function, open-drain; - - ``Pin.ANALOG`` - configure the pin for analog. - - - ``pull`` can be one of: - - - ``Pin.PULL_NONE`` - no pull up or down resistors; - - ``Pin.PULL_UP`` - enable the pull-up resistor; - - ``Pin.PULL_DOWN`` - enable the pull-down resistor. - - - when mode is ``Pin.AF_PP`` or ``Pin.AF_OD``, then af can be the index or name - of one of the alternate functions associated with a pin. - - Returns: ``None``. - -.. method:: Pin.value([value]) - - Get or set the digital logic level of the pin: - - - With no argument, return 0 or 1 depending on the logic level of the pin. - - With ``value`` given, set the logic level of the pin. ``value`` can be - anything that converts to a boolean. If it converts to ``True``, the pin - is set high, otherwise it is set low. - -.. only:: port_pyboard - - .. method:: Pin.__str__() - - Return a string describing the pin object. - - .. method:: Pin.af() - - Returns the currently configured alternate-function of the pin. The - integer returned will match one of the allowed constants for the af - argument to the init function. - - .. method:: Pin.af_list() - - Returns an array of alternate functions available for this pin. - - .. method:: Pin.gpio() - - Returns the base address of the GPIO block associated with this pin. - - .. method:: Pin.mode() - - Returns the currently configured mode of the pin. The integer returned - will match one of the allowed constants for the mode argument to the init - function. - - .. method:: Pin.name() - - Get the pin name. - - .. method:: Pin.names() - - Returns the cpu and board names for this pin. - - .. method:: Pin.pin() - - Get the pin number. - - .. method:: Pin.port() - - Get the pin port. - -.. method:: Pin.pull() - - Returns the currently configured pull of the pin. The integer returned - will match one of the allowed constants for the pull argument to the init - function. - -Constants ---------- - -.. only:: port_pyboard - - .. data:: Pin.AF_OD - - initialise the pin to alternate-function mode with an open-drain drive - - .. data:: Pin.AF_PP - - initialise the pin to alternate-function mode with a push-pull drive - - .. data:: Pin.ANALOG - - initialise the pin to analog mode - - .. data:: Pin.IN - - initialise the pin to input mode - - .. data:: Pin.OUT_OD - - initialise the pin to output mode with an open-drain drive - - .. data:: Pin.OUT_PP - - initialise the pin to output mode with a push-pull drive - - .. data:: Pin.PULL_DOWN - - enable the pull-down resistor on the pin - - .. data:: Pin.PULL_NONE - - don't enable any pull up or down resistors on the pin - - .. data:: Pin.PULL_UP - - enable the pull-up resistor on the pin - -.. only:: port_pyboard - - class PinAF -- Pin Alternate Functions - ====================================== - - A Pin represents a physical pin on the microprocessor. Each pin - can have a variety of functions (GPIO, I2C SDA, etc). Each PinAF - object represents a particular function for a pin. - - Usage Model:: - - x3 = pyb.Pin.board.X3 - x3_af = x3.af_list() - - x3_af will now contain an array of PinAF objects which are available on - pin X3. - - For the pyboard, x3_af would contain: - [Pin.AF1_TIM2, Pin.AF2_TIM5, Pin.AF3_TIM9, Pin.AF7_USART2] - - Normally, each peripheral would configure the af automatically, but sometimes - the same function is available on multiple pins, and having more control - is desired. - - To configure X3 to expose TIM2_CH3, you could use:: - - pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=pyb.Pin.AF1_TIM2) - - or:: - - pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, af=1) - - Methods - ------- - - .. method:: pinaf.__str__() - - Return a string describing the alternate function. - - .. method:: pinaf.index() - - Return the alternate function index. - - .. method:: pinaf.name() - - Return the name of the alternate function. - - .. method:: pinaf.reg() - - Return the base register associated with the peripheral assigned to this - alternate function. For example, if the alternate function were TIM2_CH3 - this would return stm.TIM2 diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst deleted file mode 100644 index 262855452..000000000 --- a/docs/library/pyb.RTC.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.RTC: - -class RTC -- real time clock -============================ - -The RTC is and independent clock that keeps track of the date -and time. - -Example usage:: - - rtc = pyb.RTC() - rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0)) - print(rtc.datetime()) - - -Constructors ------------- - -.. class:: pyb.RTC() - - Create an RTC object. - - -Methods -------- - -.. method:: RTC.datetime([datetimetuple]) - - Get or set the date and time of the RTC. - - With no arguments, this method returns an 8-tuple with the current - date and time. With 1 argument (being an 8-tuple) it sets the date - and time. - - .. only:: port_pyboard - - The 8-tuple has the following format: - - (year, month, day, weekday, hours, minutes, seconds, subseconds) - - ``weekday`` is 1-7 for Monday through Sunday. - - ``subseconds`` counts down from 255 to 0 - -.. only:: port_pyboard - - .. method:: RTC.wakeup(timeout, callback=None) - - Set the RTC wakeup timer to trigger repeatedly at every ``timeout`` - milliseconds. This trigger can wake the pyboard from both the sleep - states: :meth:`pyb.stop` and :meth:`pyb.standby`. - - If ``timeout`` is ``None`` then the wakeup timer is disabled. - - If ``callback`` is given then it is executed at every trigger of the - wakeup timer. ``callback`` must take exactly one argument. - - .. method:: RTC.info() - - Get information about the startup time and reset source. - - - The lower 0xffff are the number of milliseconds the RTC took to - start up. - - Bit 0x10000 is set if a power-on reset occurred. - - Bit 0x20000 is set if an external reset occurred - - .. method:: RTC.calibration(cal) - - Get or set RTC calibration. - - With no arguments, ``calibration()`` returns the current calibration - value, which is an integer in the range [-511 : 512]. With one - argument it sets the RTC calibration. - - The RTC Smooth Calibration mechanism adjusts the RTC clock rate by - adding or subtracting the given number of ticks from the 32768 Hz - clock over a 32 second period (corresponding to 2^20 clock ticks.) - Each tick added will speed up the clock by 1 part in 2^20, or 0.954 - ppm; likewise the RTC clock it slowed by negative values. The - usable calibration range is: - (-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm - diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst deleted file mode 100644 index fd110be19..000000000 --- a/docs/library/pyb.SPI.rst +++ /dev/null @@ -1,132 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.SPI: - -class SPI -- a master-driven serial protocol -============================================ - -SPI is a serial protocol that is driven by a master. At the physical level -there are 3 lines: SCK, MOSI, MISO. - -.. only:: port_pyboard - - See usage model of I2C; SPI is very similar. Main difference is - parameters to init the SPI bus:: - - from pyb import SPI - spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7) - - Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be - 0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1 - to sample data on the first or second clock edge respectively. Crc can be - None for no CRC, or a polynomial specifier. - - Additional methods for SPI:: - - data = spi.send_recv(b'1234') # send 4 bytes and receive 4 bytes - buf = bytearray(4) - spi.send_recv(b'1234', buf) # send 4 bytes and receive 4 into buf - spi.send_recv(buf, buf) # send/recv 4 bytes from/to buf - -Constructors ------------- - -.. only:: port_pyboard - - .. class:: pyb.SPI(bus, ...) - - Construct an SPI object on the given bus. ``bus`` can be 1 or 2, or - 'X' or 'Y'. With no additional parameters, the SPI object is created but - not initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - - The physical pins of the SPI busses are: - - - ``SPI(1)`` is on the X position: ``(NSS, SCK, MISO, MOSI) = (X5, X6, X7, X8) = (PA4, PA5, PA6, PA7)`` - - ``SPI(2)`` is on the Y position: ``(NSS, SCK, MISO, MOSI) = (Y5, Y6, Y7, Y8) = (PB12, PB13, PB14, PB15)`` - - At the moment, the NSS pin is not used by the SPI driver and is free - for other use. - -Methods -------- - -.. method:: SPI.deinit() - - Turn off the SPI bus. - -.. only:: port_pyboard - - .. method:: SPI.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) - - Initialise the SPI bus with the given parameters: - - - ``mode`` must be either ``SPI.MASTER`` or ``SPI.SLAVE``. - - ``baudrate`` is the SCK clock rate (only sensible for a master). - - ``prescaler`` is the prescaler to use to derive SCK from the APB bus frequency; - use of ``prescaler`` overrides ``baudrate``. - - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. - - ``phase`` can be 0 or 1 to sample data on the first or second clock edge - respectively. - - ``bits`` can be 8 or 16, and is the number of bits in each transferred word. - - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. - - ``crc`` can be None for no CRC, or a polynomial specifier. - - Note that the SPI clock frequency will not always be the requested baudrate. - The hardware only supports baudrates that are the APB bus frequency - (see :meth:`pyb.freq`) divided by a prescaler, which can be 2, 4, 8, 16, 32, - 64, 128 or 256. SPI(1) is on AHB2, and SPI(2) is on AHB1. For precise - control over the SPI clock frequency, specify ``prescaler`` instead of - ``baudrate``. - - Printing the SPI object will show you the computed baudrate and the chosen - prescaler. - -.. only:: port_pyboard - - .. method:: SPI.recv(recv, \*, timeout=5000) - - Receive data on the bus: - - - ``recv`` can be an integer, which is the number of bytes to receive, - or a mutable buffer, which will be filled with received bytes. - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: if ``recv`` is an integer then a new buffer of the bytes received, - otherwise the same buffer that was passed in to ``recv``. - - .. method:: SPI.send(send, \*, timeout=5000) - - Send data on the bus: - - - ``send`` is the data to send (an integer to send, or a buffer object). - - ``timeout`` is the timeout in milliseconds to wait for the send. - - Return value: ``None``. - - .. method:: SPI.send_recv(send, recv=None, \*, timeout=5000) - - Send and receive data on the bus at the same time: - - - ``send`` is the data to send (an integer to send, or a buffer object). - - ``recv`` is a mutable buffer which will be filled with received bytes. - It can be the same as ``send``, or omitted. If omitted, a new buffer will - be created. - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: the buffer with the received bytes. - -Constants ---------- - -.. only:: port_pyboard - - .. data:: SPI.MASTER - .. data:: SPI.SLAVE - - for initialising the SPI bus to master or slave mode - - .. data:: SPI.LSB - .. data:: SPI.MSB - - set the first bit to be the least or most significant bit diff --git a/docs/library/pyb.Servo.rst b/docs/library/pyb.Servo.rst deleted file mode 100644 index b3ce71d11..000000000 --- a/docs/library/pyb.Servo.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.Servo: - -class Servo -- 3-wire hobby servo driver -======================================== - -Servo objects control standard hobby servo motors with 3-wires (ground, power, -signal). There are 4 positions on the pyboard where these motors can be plugged -in: pins X1 through X4 are the signal pins, and next to them are 4 sets of power -and ground pins. - -Example usage:: - - import pyb - - s1 = pyb.Servo(1) # create a servo object on position X1 - s2 = pyb.Servo(2) # create a servo object on position X2 - - s1.angle(45) # move servo 1 to 45 degrees - s2.angle(0) # move servo 2 to 0 degrees - - # move servo1 and servo2 synchronously, taking 1500ms - s1.angle(-60, 1500) - s2.angle(30, 1500) - -.. note:: The Servo objects use Timer(5) to produce the PWM output. You can - use Timer(5) for Servo control, or your own purposes, but not both at the - same time. - -Constructors ------------- - -.. class:: pyb.Servo(id) - - Create a servo object. ``id`` is 1-4, and corresponds to pins X1 through X4. - - -Methods -------- - -.. method:: Servo.angle([angle, time=0]) - - If no arguments are given, this function returns the current angle. - - If arguments are given, this function sets the angle of the servo: - - - ``angle`` is the angle to move to in degrees. - - ``time`` is the number of milliseconds to take to get to the specified - angle. If omitted, then the servo moves as quickly as possible to its - new position. - -.. method:: Servo.speed([speed, time=0]) - - If no arguments are given, this function returns the current speed. - - If arguments are given, this function sets the speed of the servo: - - - ``speed`` is the speed to change to, between -100 and 100. - - ``time`` is the number of milliseconds to take to get to the specified - speed. If omitted, then the servo accelerates as quickly as possible. - -.. method:: Servo.pulse_width([value]) - - If no arguments are given, this function returns the current raw pulse-width - value. - - If an argument is given, this function sets the raw pulse-width value. - -.. method:: Servo.calibration([pulse_min, pulse_max, pulse_centre, [pulse_angle_90, pulse_speed_100]]) - - If no arguments are given, this function returns the current calibration - data, as a 5-tuple. - - If arguments are given, this function sets the timing calibration: - - - ``pulse_min`` is the minimum allowed pulse width. - - ``pulse_max`` is the maximum allowed pulse width. - - ``pulse_centre`` is the pulse width corresponding to the centre/zero position. - - ``pulse_angle_90`` is the pulse width corresponding to 90 degrees. - - ``pulse_speed_100`` is the pulse width corresponding to a speed of 100. diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst deleted file mode 100644 index e5ab6bd84..000000000 --- a/docs/library/pyb.Switch.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.Switch: - -class Switch -- switch object -============================= - -A Switch object is used to control a push-button switch. - -Usage:: - - sw = pyb.Switch() # create a switch object - sw.value() # get state (True if pressed, False otherwise) - sw() # shorthand notation to get the switch state - sw.callback(f) # register a callback to be called when the - # switch is pressed down - sw.callback(None) # remove the callback - -Example:: - - pyb.Switch().callback(lambda: pyb.LED(1).toggle()) - - -Constructors ------------- - -.. class:: pyb.Switch() - - Create and return a switch object. - - -Methods -------- - -.. method:: Switch.__call__() - - Call switch object directly to get its state: ``True`` if pressed down, - ``False`` otherwise. - -.. method:: Switch.value() - - Get the switch state. Returns `True` if pressed down, otherwise `False`. - -.. method:: Switch.callback(fun) - - Register the given function to be called when the switch is pressed down. - If ``fun`` is ``None``, then it disables the callback. diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst deleted file mode 100644 index 052bce2ef..000000000 --- a/docs/library/pyb.Timer.rst +++ /dev/null @@ -1,286 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.Timer: - -class Timer -- control internal timers -====================================== - -.. only:: port_pyboard - - Timers can be used for a great variety of tasks. At the moment, only - the simplest case is implemented: that of calling a function periodically. - - Each timer consists of a counter that counts up at a certain rate. The rate - at which it counts is the peripheral clock frequency (in Hz) divided by the - timer prescaler. When the counter reaches the timer period it triggers an - event, and the counter resets back to zero. By using the callback method, - the timer event can call a Python function. - - Example usage to toggle an LED at a fixed frequency:: - - tim = pyb.Timer(4) # create a timer object using timer 4 - tim.init(freq=2) # trigger at 2Hz - tim.callback(lambda t:pyb.LED(1).toggle()) - - Example using named function for the callback:: - - def tick(timer): # we will receive the timer object when being called - print(timer.counter()) # show current timer's counter value - tim = pyb.Timer(4, freq=1) # create a timer object using timer 4 - trigger at 1Hz - tim.callback(tick) # set the callback to our tick function - - Further examples:: - - tim = pyb.Timer(4, freq=100) # freq in Hz - tim = pyb.Timer(4, prescaler=0, period=99) - tim.counter() # get counter (can also set) - tim.prescaler(2) # set prescaler (can also get) - tim.period(199) # set period (can also get) - tim.callback(lambda t: ...) # set callback for update interrupt (t=tim instance) - tim.callback(None) # clear callback - - *Note:* Timer(2) and Timer(3) are used for PWM to set the intensity of LED(3) - and LED(4) respectively. But these timers are only configured for PWM if - the intensity of the relevant LED is set to a value between 1 and 254. If - the intensity feature of the LEDs is not used then these timers are free for - general purpose use. Similarly, Timer(5) controls the servo driver, and - Timer(6) is used for timed ADC/DAC reading/writing. It is recommended to - use the other timers in your programs. - -*Note:* Memory can't be allocated during a callback (an interrupt) and so -exceptions raised within a callback don't give much information. See -:func:`micropython.alloc_emergency_exception_buf` for how to get around this -limitation. - - -Constructors ------------- - -.. class:: pyb.Timer(id, ...) - - .. only:: port_pyboard - - Construct a new timer object of the given id. If additional - arguments are given, then the timer is initialised by ``init(...)``. - ``id`` can be 1 to 14. - -Methods -------- - -.. only:: port_pyboard - - .. method:: Timer.init(\*, freq, prescaler, period) - - Initialise the timer. Initialisation must be either by frequency (in Hz) - or by prescaler and period:: - - tim.init(freq=100) # set the timer to trigger at 100Hz - tim.init(prescaler=83, period=999) # set the prescaler and period directly - - Keyword arguments: - - - ``freq`` --- specifies the periodic frequency of the timer. You might also - view this as the frequency with which the timer goes through one complete cycle. - - - ``prescaler`` [0-0xffff] - specifies the value to be loaded into the - timer's Prescaler Register (PSC). The timer clock source is divided by - (``prescaler + 1``) to arrive at the timer clock. Timers 2-7 and 12-14 - have a clock source of 84 MHz (pyb.freq()[2] \* 2), and Timers 1, and 8-11 - have a clock source of 168 MHz (pyb.freq()[3] \* 2). - - - ``period`` [0-0xffff] for timers 1, 3, 4, and 6-15. [0-0x3fffffff] for timers 2 & 5. - Specifies the value to be loaded into the timer's AutoReload - Register (ARR). This determines the period of the timer (i.e. when the - counter cycles). The timer counter will roll-over after ``period + 1`` - timer clock cycles. - - - ``mode`` can be one of: - - - ``Timer.UP`` - configures the timer to count from 0 to ARR (default) - - ``Timer.DOWN`` - configures the timer to count from ARR down to 0. - - ``Timer.CENTER`` - configures the timer to count from 0 to ARR and - then back down to 0. - - - ``div`` can be one of 1, 2, or 4. Divides the timer clock to determine - the sampling clock used by the digital filters. - - - ``callback`` - as per Timer.callback() - - - ``deadtime`` - specifies the amount of "dead" or inactive time between - transitions on complimentary channels (both channels will be inactive) - for this time). ``deadtime`` may be an integer between 0 and 1008, with - the following restrictions: 0-128 in steps of 1. 128-256 in steps of - 2, 256-512 in steps of 8, and 512-1008 in steps of 16. ``deadtime`` - measures ticks of ``source_freq`` divided by ``div`` clock ticks. - ``deadtime`` is only available on timers 1 and 8. - - You must either specify freq or both of period and prescaler. - -.. method:: Timer.deinit() - - Deinitialises the timer. - - .. only:: port_pyboard - - Disables the callback (and the associated irq). - - Disables any channel callbacks (and the associated irq). - Stops the timer, and disables the timer peripheral. - -.. only:: port_pyboard - - .. method:: Timer.callback(fun) - - Set the function to be called when the timer triggers. - ``fun`` is passed 1 argument, the timer object. - If ``fun`` is ``None`` then the callback will be disabled. - -.. only:: port_pyboard - - .. method:: Timer.channel(channel, mode, ...) - - If only a channel number is passed, then a previously initialized channel - object is returned (or ``None`` if there is no previous channel). - - Otherwise, a TimerChannel object is initialized and returned. - - Each channel can be configured to perform pwm, output compare, or - input capture. All channels share the same underlying timer, which means - that they share the same timer clock. - - Keyword arguments: - - - ``mode`` can be one of: - - - ``Timer.PWM`` --- configure the timer in PWM mode (active high). - - ``Timer.PWM_INVERTED`` --- configure the timer in PWM mode (active low). - - ``Timer.OC_TIMING`` --- indicates that no pin is driven. - - ``Timer.OC_ACTIVE`` --- the pin will be made active when a compare match occurs (active is determined by polarity) - - ``Timer.OC_INACTIVE`` --- the pin will be made inactive when a compare match occurs. - - ``Timer.OC_TOGGLE`` --- the pin will be toggled when an compare match occurs. - - ``Timer.OC_FORCED_ACTIVE`` --- the pin is forced active (compare match is ignored). - - ``Timer.OC_FORCED_INACTIVE`` --- the pin is forced inactive (compare match is ignored). - - ``Timer.IC`` --- configure the timer in Input Capture mode. - - ``Timer.ENC_A`` --- configure the timer in Encoder mode. The counter only changes when CH1 changes. - - ``Timer.ENC_B`` --- configure the timer in Encoder mode. The counter only changes when CH2 changes. - - ``Timer.ENC_AB`` --- configure the timer in Encoder mode. The counter changes when CH1 or CH2 changes. - - - ``callback`` - as per TimerChannel.callback() - - - ``pin`` None (the default) or a Pin object. If specified (and not None) - this will cause the alternate function of the the indicated pin - to be configured for this timer channel. An error will be raised if - the pin doesn't support any alternate functions for this timer channel. - - Keyword arguments for Timer.PWM modes: - - - ``pulse_width`` - determines the initial pulse width value to use. - - ``pulse_width_percent`` - determines the initial pulse width percentage to use. - - Keyword arguments for Timer.OC modes: - - - ``compare`` - determines the initial value of the compare register. - - - ``polarity`` can be one of: - - - ``Timer.HIGH`` - output is active high - - ``Timer.LOW`` - output is active low - - Optional keyword arguments for Timer.IC modes: - - - ``polarity`` can be one of: - - - ``Timer.RISING`` - captures on rising edge. - - ``Timer.FALLING`` - captures on falling edge. - - ``Timer.BOTH`` - captures on both edges. - - Note that capture only works on the primary channel, and not on the - complimentary channels. - - Notes for Timer.ENC modes: - - - Requires 2 pins, so one or both pins will need to be configured to use - the appropriate timer AF using the Pin API. - - Read the encoder value using the timer.counter() method. - - Only works on CH1 and CH2 (and not on CH1N or CH2N) - - The channel number is ignored when setting the encoder mode. - - PWM Example:: - - timer = pyb.Timer(2, freq=1000) - ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000) - ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000) - -.. only:: port_pyboard - - .. method:: Timer.counter([value]) - - Get or set the timer counter. - -.. only:: port_pyboard - - .. method:: Timer.freq([value]) - - Get or set the frequency for the timer (changes prescaler and period if set). - -.. only:: port_pyboard - - .. method:: Timer.period([value]) - - Get or set the period of the timer. - - .. method:: Timer.prescaler([value]) - - Get or set the prescaler for the timer. - - .. method:: Timer.source_freq() - - Get the frequency of the source of the timer. - -class TimerChannel --- setup a channel for a timer -================================================== - -Timer channels are used to generate/capture a signal using a timer. - -TimerChannel objects are created using the Timer.channel() method. - -Methods -------- - -.. only:: port_pyboard - - .. method:: timerchannel.callback(fun) - - Set the function to be called when the timer channel triggers. - ``fun`` is passed 1 argument, the timer object. - If ``fun`` is ``None`` then the callback will be disabled. - -.. only:: port_pyboard - - .. method:: timerchannel.capture([value]) - - Get or set the capture value associated with a channel. - capture, compare, and pulse_width are all aliases for the same function. - capture is the logical name to use when the channel is in input capture mode. - - .. method:: timerchannel.compare([value]) - - Get or set the compare value associated with a channel. - capture, compare, and pulse_width are all aliases for the same function. - compare is the logical name to use when the channel is in output compare mode. - - .. method:: timerchannel.pulse_width([value]) - - Get or set the pulse width value associated with a channel. - capture, compare, and pulse_width are all aliases for the same function. - pulse_width is the logical name to use when the channel is in PWM mode. - - In edge aligned mode, a pulse_width of ``period + 1`` corresponds to a duty cycle of 100% - In center aligned mode, a pulse width of ``period`` corresponds to a duty cycle of 100% - - .. method:: timerchannel.pulse_width_percent([value]) - - Get or set the pulse width percentage associated with a channel. The value - is a number between 0 and 100 and sets the percentage of the timer period - for which the pulse is active. The value can be an integer or - floating-point number for more accuracy. For example, a value of 25 gives - a duty cycle of 25%. diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst deleted file mode 100644 index 76f347ffa..000000000 --- a/docs/library/pyb.UART.rst +++ /dev/null @@ -1,245 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.UART: - -class UART -- duplex serial communication bus -============================================= - -UART implements the standard UART/USART duplex serial communications protocol. At -the physical level it consists of 2 lines: RX and TX. The unit of communication -is a character (not to be confused with a string character) which can be 8 or 9 -bits wide. - -UART objects can be created and initialised using:: - - from pyb import UART - - uart = UART(1, 9600) # init with given baudrate - uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters - -.. only:: port_pyboard - - Bits can be 7, 8 or 9. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2. - - *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, - only 7 and 8 bits are supported. - -A UART object acts like a stream object and reading and writing is done -using the standard stream methods:: - - uart.read(10) # read 10 characters, returns a bytes object - uart.read() # read all available characters - uart.readline() # read a line - uart.readinto(buf) # read and store into the given buffer - uart.write('abc') # write the 3 characters - -.. only:: port_pyboard - - Individual characters can be read/written using:: - - uart.readchar() # read 1 character and returns it as an integer - uart.writechar(42) # write 1 character - - To check if there is anything to be read, use:: - - uart.any() # returns the number of characters waiting - - - *Note:* The stream functions ``read``, ``write``, etc. are new in MicroPython v1.3.4. - Earlier versions use ``uart.send`` and ``uart.recv``. - -Constructors ------------- - -.. only:: port_pyboard - - .. class:: pyb.UART(bus, ...) - - Construct a UART object on the given bus. ``bus`` can be 1-6, or 'XA', 'XB', 'YA', or 'YB'. - With no additional parameters, the UART object is created but not - initialised (it has the settings from the last initialisation of - the bus, if any). If extra arguments are given, the bus is initialised. - See ``init`` for parameters of initialisation. - - The physical pins of the UART busses are: - - - ``UART(4)`` is on ``XA``: ``(TX, RX) = (X1, X2) = (PA0, PA1)`` - - ``UART(1)`` is on ``XB``: ``(TX, RX) = (X9, X10) = (PB6, PB7)`` - - ``UART(6)`` is on ``YA``: ``(TX, RX) = (Y1, Y2) = (PC6, PC7)`` - - ``UART(3)`` is on ``YB``: ``(TX, RX) = (Y9, Y10) = (PB10, PB11)`` - - ``UART(2)`` is on: ``(TX, RX) = (X3, X4) = (PA2, PA3)`` - - The Pyboard Lite supports UART(1), UART(2) and UART(6) only. Pins are as above except: - - - ``UART(2)`` is on: ``(TX, RX) = (X1, X2) = (PA2, PA3)`` - -Methods -------- - -.. only:: port_pyboard - - .. method:: UART.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64) - - Initialise the UART bus with the given parameters: - - - ``baudrate`` is the clock rate. - - ``bits`` is the number of bits per character, 7, 8 or 9. - - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd). - - ``stop`` is the number of stop bits, 1 or 2. - - ``flow`` sets the flow control type. Can be 0, ``UART.RTS``, ``UART.CTS`` - or ``UART.RTS | UART.CTS``. - - ``timeout`` is the timeout in milliseconds to wait for writing/reading the first character. - - ``timeout_char`` is the timeout in milliseconds to wait between characters while writing or reading. - - ``read_buf_len`` is the character length of the read buffer (0 to disable). - - This method will raise an exception if the baudrate could not be set within - 5% of the desired value. The minimum baudrate is dictated by the frequency - of the bus that the UART is on; UART(1) and UART(6) are APB2, the rest are on - APB1. The default bus frequencies give a minimum baudrate of 1300 for - UART(1) and UART(6) and 650 for the others. Use :func:`pyb.freq <pyb.freq>` - to reduce the bus frequencies to get lower baudrates. - - *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, - only 7 and 8 bits are supported. - -.. method:: UART.deinit() - - Turn off the UART bus. - -.. only:: port_pyboard - - .. method:: UART.any() - - Returns the number of bytes waiting (may be 0). - -.. method:: UART.read([nbytes]) - - Read characters. If ``nbytes`` is specified then read at most that many bytes. - If ``nbytes`` are available in the buffer, returns immediately, otherwise returns - when sufficient characters arrive or the timeout elapses. - - If ``nbytes`` is not given then the method reads as much data as possible. It - returns after the timeout has elapsed. - - .. only:: port_pyboard - - *Note:* for 9 bit characters each character takes two bytes, ``nbytes`` must - be even, and the number of characters is ``nbytes/2``. - - Return value: a bytes object containing the bytes read in. Returns ``None`` - on timeout. - -.. method:: UART.readchar() - - Receive a single character on the bus. - - Return value: The character read, as an integer. Returns -1 on timeout. - -.. method:: UART.readinto(buf[, nbytes]) - - Read bytes into the ``buf``. If ``nbytes`` is specified then read at most - that many bytes. Otherwise, read at most ``len(buf)`` bytes. - - Return value: number of bytes read and stored into ``buf`` or ``None`` on - timeout. - -.. method:: UART.readline() - - Read a line, ending in a newline character. If such a line exists, return is - immediate. If the timeout elapses, all available data is returned regardless - of whether a newline exists. - - Return value: the line read or ``None`` on timeout if no data is available. - -.. method:: UART.write(buf) - - .. only:: port_pyboard - - Write the buffer of bytes to the bus. If characters are 7 or 8 bits wide - then each byte is one character. If characters are 9 bits wide then two - bytes are used for each character (little endian), and ``buf`` must contain - an even number of bytes. - - Return value: number of bytes written. If a timeout occurs and no bytes - were written returns ``None``. - -.. only:: port_pyboard - - .. method:: UART.writechar(char) - - Write a single character on the bus. ``char`` is an integer to write. - Return value: ``None``. See note below if CTS flow control is used. - -.. method:: UART.sendbreak() - - Send a break condition on the bus. This drives the bus low for a duration - of 13 bits. - Return value: ``None``. - -Constants ---------- - -.. only:: port_pyboard - - .. data:: UART.RTS - .. data:: UART.CTS - - to select the flow control type. - -Flow Control ------------- - -.. only:: port_pyboard - - On Pyboards V1 and V1.1 ``UART(2)`` and ``UART(3)`` support RTS/CTS hardware flow control - using the following pins: - - - ``UART(2)`` is on: ``(TX, RX, nRTS, nCTS) = (X3, X4, X2, X1) = (PA2, PA3, PA1, PA0)`` - - ``UART(3)`` is on :``(TX, RX, nRTS, nCTS) = (Y9, Y10, Y7, Y6) = (PB10, PB11, PB14, PB13)`` - - On the Pyboard Lite only ``UART(2)`` supports flow control on these pins: - - ``(TX, RX, nRTS, nCTS) = (X1, X2, X4, X3) = (PA2, PA3, PA1, PA0)`` - - In the following paragraphs the term "target" refers to the device connected to - the UART. - - When the UART's ``init()`` method is called with ``flow`` set to one or both of - ``UART.RTS`` and ``UART.CTS`` the relevant flow control pins are configured. - ``nRTS`` is an active low output, ``nCTS`` is an active low input with pullup - enabled. To achieve flow control the Pyboard's ``nCTS`` signal should be connected - to the target's ``nRTS`` and the Pyboard's ``nRTS`` to the target's ``nCTS``. - - CTS: target controls Pyboard transmitter - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - If CTS flow control is enabled the write behaviour is as follows: - - If the Pyboard's ``UART.write(buf)`` method is called, transmission will stall for - any periods when ``nCTS`` is ``False``. This will result in a timeout if the entire - buffer was not transmitted in the timeout period. The method returns the number of - bytes written, enabling the user to write the remainder of the data if required. In - the event of a timeout, a character will remain in the UART pending ``nCTS``. The - number of bytes composing this character will be included in the return value. - - If ``UART.writechar()`` is called when ``nCTS`` is ``False`` the method will time - out unless the target asserts ``nCTS`` in time. If it times out ``OSError 116`` - will be raised. The character will be transmitted as soon as the target asserts ``nCTS``. - - RTS: Pyboard controls target's transmitter - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - If RTS flow control is enabled, behaviour is as follows: - - If buffered input is used (``read_buf_len`` > 0), incoming characters are buffered. - If the buffer becomes full, the next character to arrive will cause ``nRTS`` to go - ``False``: the target should cease transmission. ``nRTS`` will go ``True`` when - characters are read from the buffer. - - Note that the ``any()`` method returns the number of bytes in the buffer. Assume a - buffer length of ``N`` bytes. If the buffer becomes full, and another character arrives, - ``nRTS`` will be set False, and ``any()`` will return the count ``N``. When - characters are read the additional character will be placed in the buffer and will - be included in the result of a subsequent ``any()`` call. - - If buffered input is not used (``read_buf_len`` == 0) the arrival of a character will - cause ``nRTS`` to go ``False`` until the character is read. diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst deleted file mode 100644 index 702704435..000000000 --- a/docs/library/pyb.USB_HID.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.USB_HID: - -class USB_HID -- USB Human Interface Device (HID) -================================================= - -The USB_HID class allows creation of an object representing the USB -Human Interface Device (HID) interface. It can be used to emulate -a peripheral such as a mouse or keyboard. - -Before you can use this class, you need to use :meth:`pyb.usb_mode()` to set the USB mode to include the HID interface. - -Constructors ------------- - -.. class:: pyb.USB_HID() - - Create a new USB_HID object. - - -Methods -------- - -.. method:: USB_HID.recv(data, \*, timeout=5000) - - Receive data on the bus: - - - ``data`` can be an integer, which is the number of bytes to receive, - or a mutable buffer, which will be filled with received bytes. - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: if ``data`` is an integer then a new buffer of the bytes received, - otherwise the number of bytes read into ``data`` is returned. - -.. method:: USB_HID.send(data) - - Send data over the USB HID interface: - - - ``data`` is the data to send (a tuple/list of integers, or a - bytearray). diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst deleted file mode 100644 index 80cc40cdd..000000000 --- a/docs/library/pyb.USB_VCP.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. currentmodule:: pyb -.. _pyb.USB_VCP: - -class USB_VCP -- USB virtual comm port -====================================== - -The USB_VCP class allows creation of an object representing the USB -virtual comm port. It can be used to read and write data over USB to -the connected host. - - -Constructors ------------- - -.. class:: pyb.USB_VCP() - - Create a new USB_VCP object. - - -Methods -------- - -.. method:: USB_VCP.setinterrupt(chr) - - Set the character which interrupts running Python code. This is set - to 3 (CTRL-C) by default, and when a CTRL-C character is received over - the USB VCP port, a KeyboardInterrupt exception is raised. - - Set to -1 to disable this interrupt feature. This is useful when you - want to send raw bytes over the USB VCP port. - -.. method:: USB_VCP.isconnected() - - Return ``True`` if USB is connected as a serial device, else ``False``. - -.. method:: USB_VCP.any() - - Return ``True`` if any characters waiting, else ``False``. - -.. method:: USB_VCP.close() - - This method does nothing. It exists so the USB_VCP object can act as - a file. - -.. method:: USB_VCP.read([nbytes]) - - Read at most ``nbytes`` from the serial device and return them as a - bytes object. If ``nbytes`` is not specified then the method reads - all available bytes from the serial device. - USB_VCP stream implicitly works in non-blocking mode, - so if no pending data available, this method will return immediately - with ``None`` value. - -.. method:: USB_VCP.readinto(buf, [maxlen]) - - Read bytes from the serial device and store them into ``buf``, which - should be a buffer-like object. At most ``len(buf)`` bytes are read. - If ``maxlen`` is given and then at most ``min(maxlen, len(buf))`` bytes - are read. - - Returns the number of bytes read and stored into ``buf`` or ``None`` - if no pending data available. - -.. method:: USB_VCP.readline() - - Read a whole line from the serial device. - - Returns a bytes object containing the data, including the trailing - newline character or ``None`` if no pending data available. - -.. method:: USB_VCP.readlines() - - Read as much data as possible from the serial device, breaking it into - lines. - - Returns a list of bytes objects, each object being one of the lines. - Each line will include the newline character. - -.. method:: USB_VCP.write(buf) - - Write the bytes from ``buf`` to the serial device. - - Returns the number of bytes written. - -.. method:: USB_VCP.recv(data, \*, timeout=5000) - - Receive data on the bus: - - - ``data`` can be an integer, which is the number of bytes to receive, - or a mutable buffer, which will be filled with received bytes. - - ``timeout`` is the timeout in milliseconds to wait for the receive. - - Return value: if ``data`` is an integer then a new buffer of the bytes received, - otherwise the number of bytes read into ``data`` is returned. - -.. method:: USB_VCP.send(data, \*, timeout=5000) - - Send data over the USB VCP: - - - ``data`` is the data to send (an integer to send, or a buffer object). - - ``timeout`` is the timeout in milliseconds to wait for the send. - - Return value: number of bytes sent. diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst deleted file mode 100644 index 799160145..000000000 --- a/docs/library/pyb.rst +++ /dev/null @@ -1,321 +0,0 @@ -:mod:`pyb` --- functions related to the board -============================================= - -.. module:: pyb - :synopsis: functions related to the board - -The ``pyb`` module contains specific functions related to the board. - -Time related functions ----------------------- - -.. function:: delay(ms) - - Delay for the given number of milliseconds. - -.. function:: udelay(us) - - Delay for the given number of microseconds. - -.. function:: millis() - - Returns the number of milliseconds since the board was last reset. - - The result is always a MicroPython smallint (31-bit signed number), so - after 2^30 milliseconds (about 12.4 days) this will start to return - negative numbers. - - Note that if :meth:`pyb.stop()` is issued the hardware counter supporting this - function will pause for the duration of the "sleeping" state. This - will affect the outcome of :meth:`pyb.elapsed_millis()`. - -.. function:: micros() - - Returns the number of microseconds since the board was last reset. - - The result is always a MicroPython smallint (31-bit signed number), so - after 2^30 microseconds (about 17.8 minutes) this will start to return - negative numbers. - - Note that if :meth:`pyb.stop()` is issued the hardware counter supporting this - function will pause for the duration of the "sleeping" state. This - will affect the outcome of :meth:`pyb.elapsed_micros()`. - -.. function:: elapsed_millis(start) - - Returns the number of milliseconds which have elapsed since ``start``. - - This function takes care of counter wrap, and always returns a positive - number. This means it can be used to measure periods up to about 12.4 days. - - Example:: - - start = pyb.millis() - while pyb.elapsed_millis(start) < 1000: - # Perform some operation - -.. function:: elapsed_micros(start) - - Returns the number of microseconds which have elapsed since ``start``. - - This function takes care of counter wrap, and always returns a positive - number. This means it can be used to measure periods up to about 17.8 minutes. - - Example:: - - start = pyb.micros() - while pyb.elapsed_micros(start) < 1000: - # Perform some operation - pass - -Reset related functions ------------------------ - -.. function:: hard_reset() - - Resets the pyboard in a manner similar to pushing the external RESET - button. - -.. function:: bootloader() - - Activate the bootloader without BOOT\* pins. - -.. function:: fault_debug(value) - - Enable or disable hard-fault debugging. A hard-fault is when there is a fatal - error in the underlying system, like an invalid memory access. - - If the *value* argument is ``False`` then the board will automatically reset if - there is a hard fault. - - If *value* is ``True`` then, when the board has a hard fault, it will print the - registers and the stack trace, and then cycle the LEDs indefinitely. - - The default value is disabled, i.e. to automatically reset. - -Interrupt related functions ---------------------------- - -.. function:: disable_irq() - - Disable interrupt requests. - Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs - respectively. This return value can be passed to enable_irq to restore - the IRQ to its original state. - -.. function:: enable_irq(state=True) - - Enable interrupt requests. - If ``state`` is ``True`` (the default value) then IRQs are enabled. - If ``state`` is ``False`` then IRQs are disabled. The most common use of - this function is to pass it the value returned by ``disable_irq`` to - exit a critical section. - -Power related functions ------------------------ - -.. only:: port_pyboard - - .. function:: freq([sysclk[, hclk[, pclk1[, pclk2]]]]) - - If given no arguments, returns a tuple of clock frequencies: - (sysclk, hclk, pclk1, pclk2). - These correspond to: - - - sysclk: frequency of the CPU - - hclk: frequency of the AHB bus, core memory and DMA - - pclk1: frequency of the APB1 bus - - pclk2: frequency of the APB2 bus - - If given any arguments then the function sets the frequency of the CPU, - and the busses if additional arguments are given. Frequencies are given in - Hz. Eg freq(120000000) sets sysclk (the CPU frequency) to 120MHz. Note that - not all values are supported and the largest supported frequency not greater - than the given value will be selected. - - Supported sysclk frequencies are (in MHz): 8, 16, 24, 30, 32, 36, 40, 42, 48, - 54, 56, 60, 64, 72, 84, 96, 108, 120, 144, 168. - - The maximum frequency of hclk is 168MHz, of pclk1 is 42MHz, and of pclk2 is - 84MHz. Be sure not to set frequencies above these values. - - The hclk, pclk1 and pclk2 frequencies are derived from the sysclk frequency - using a prescaler (divider). Supported prescalers for hclk are: 1, 2, 4, 8, - 16, 64, 128, 256, 512. Supported prescalers for pclk1 and pclk2 are: 1, 2, - 4, 8. A prescaler will be chosen to best match the requested frequency. - - A sysclk frequency of - 8MHz uses the HSE (external crystal) directly and 16MHz uses the HSI - (internal oscillator) directly. The higher frequencies use the HSE to - drive the PLL (phase locked loop), and then use the output of the PLL. - - Note that if you change the frequency while the USB is enabled then - the USB may become unreliable. It is best to change the frequency - in boot.py, before the USB peripheral is started. Also note that sysclk - frequencies below 36MHz do not allow the USB to function correctly. - - .. function:: wfi() - - Wait for an internal or external interrupt. - - This executes a ``wfi`` instruction which reduces power consumption - of the MCU until any interrupt occurs (be it internal or external), - at which point execution continues. Note that the system-tick interrupt - occurs once every millisecond (1000Hz) so this function will block for - at most 1ms. - - .. function:: stop() - - Put the pyboard in a "sleeping" state. - - This reduces power consumption to less than 500 uA. To wake from this - sleep state requires an external interrupt or a real-time-clock event. - Upon waking execution continues where it left off. - - See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. - - .. function:: standby() - - Put the pyboard into a "deep sleep" state. - - This reduces power consumption to less than 50 uA. To wake from this - sleep state requires a real-time-clock event, or an external interrupt - on X1 (PA0=WKUP) or X18 (PC13=TAMP1). - Upon waking the system undergoes a hard reset. - - See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event. - -Miscellaneous functions ------------------------ - -.. only:: port_pyboard - - .. function:: have_cdc() - - Return True if USB is connected as a serial device, False otherwise. - - .. note:: This function is deprecated. Use pyb.USB_VCP().isconnected() instead. - - .. function:: hid((buttons, x, y, z)) - - Takes a 4-tuple (or list) and sends it to the USB host (the PC) to - signal a HID mouse-motion event. - - .. note:: This function is deprecated. Use :meth:`pyb.USB_HID.send()` instead. - - .. function:: info([dump_alloc_table]) - - Print out lots of information about the board. - -.. function:: main(filename) - - Set the filename of the main script to run after boot.py is finished. If - this function is not called then the default file main.py will be executed. - - It only makes sense to call this function from within boot.py. - -.. only:: port_pyboard - - .. function:: mount(device, mountpoint, \*, readonly=False, mkfs=False) - - Mount a block device and make it available as part of the filesystem. - ``device`` must be an object that provides the block protocol: - - - ``readblocks(self, blocknum, buf)`` - - ``writeblocks(self, blocknum, buf)`` (optional) - - ``count(self)`` - - ``sync(self)`` (optional) - - ``readblocks`` and ``writeblocks`` should copy data between ``buf`` and - the block device, starting from block number ``blocknum`` on the device. - ``buf`` will be a bytearray with length a multiple of 512. If - ``writeblocks`` is not defined then the device is mounted read-only. - The return value of these two functions is ignored. - - ``count`` should return the number of blocks available on the device. - ``sync``, if implemented, should sync the data on the device. - - The parameter ``mountpoint`` is the location in the root of the filesystem - to mount the device. It must begin with a forward-slash. - - If ``readonly`` is ``True``, then the device is mounted read-only, - otherwise it is mounted read-write. - - If ``mkfs`` is ``True``, then a new filesystem is created if one does not - already exist. - - To unmount a device, pass ``None`` as the device and the mount location - as ``mountpoint``. - -.. function:: repl_uart(uart) - - Get or set the UART object where the REPL is repeated on. - -.. only:: port_pyboard - - .. function:: rng() - - Return a 30-bit hardware generated random number. - -.. function:: sync() - - Sync all file systems. - -.. only:: port_pyboard - - .. function:: unique_id() - - Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU. - -.. function:: usb_mode([modestr], vid=0xf055, pid=0x9801, hid=pyb.hid_mouse) - - If called with no arguments, return the current USB mode as a string. - - If called with ``modestr`` provided, attempts to set USB mode. - This can only be done when called from ``boot.py`` before - :meth:`pyb.main()` has been called. The following values of - ``modestr`` are understood: - - - ``None``: disables USB - - ``'VCP'``: enable with VCP (Virtual COM Port) interface - - ``'VCP+MSC'``: enable with VCP and MSC (mass storage device class) - - ``'VCP+HID'``: enable with VCP and HID (human interface device) - - For backwards compatibility, ``'CDC'`` is understood to mean - ``'VCP'`` (and similarly for ``'CDC+MSC'`` and ``'CDC+HID'``). - - The ``vid`` and ``pid`` parameters allow you to specify the VID - (vendor id) and PID (product id). - - If enabling HID mode, you may also specify the HID details by - passing the ``hid`` keyword parameter. It takes a tuple of - (subclass, protocol, max packet length, polling interval, report - descriptor). By default it will set appropriate values for a USB - mouse. There is also a ``pyb.hid_keyboard`` constant, which is an - appropriate tuple for a USB keyboard. - -Classes -------- - -.. only:: port_pyboard - - .. toctree:: - :maxdepth: 1 - - pyb.Accel.rst - pyb.ADC.rst - pyb.CAN.rst - pyb.DAC.rst - pyb.ExtInt.rst - pyb.I2C.rst - pyb.LCD.rst - pyb.LED.rst - pyb.Pin.rst - pyb.RTC.rst - pyb.Servo.rst - pyb.SPI.rst - pyb.Switch.rst - pyb.Timer.rst - pyb.UART.rst - pyb.USB_HID.rst - pyb.USB_VCP.rst diff --git a/docs/library/sys.rst b/docs/library/sys.rst index d49577306..de2ec2dcd 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -1,10 +1,12 @@ :mod:`sys` -- system specific functions ======================================= +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: sys :synopsis: system specific functions -|see_cpython_module| :mod:`python:sys`. +|see_cpython_module| :mod:`cpython:sys`. Functions --------- @@ -27,8 +29,7 @@ Functions ``traceback`` module in CPython. Unlike ``traceback.print_exception()``, this function takes just exception value instead of exception type, exception value, and traceback object; *file* argument should be - positional; further arguments are not supported. CPython-compatible - ``traceback`` module can be found in `micropython-lib`. + positional; further arguments are not supported. Constants --------- diff --git a/docs/library/ubinascii.rst b/docs/library/ubinascii.rst index 192d34514..edf4a9fdf 100644 --- a/docs/library/ubinascii.rst +++ b/docs/library/ubinascii.rst @@ -1,10 +1,12 @@ :mod:`ubinascii` -- binary/ASCII conversions ============================================ +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: ubinascii :synopsis: binary/ASCII conversions -|see_cpython_module| :mod:`python:binascii`. +|see_cpython_module| :mod:`cpython:binascii`. This module implements conversions between binary data and various encodings of it in ASCII form (in both directions). diff --git a/docs/library/ucollections.rst b/docs/library/ucollections.rst index 96de67acc..396ba3c87 100644 --- a/docs/library/ucollections.rst +++ b/docs/library/ucollections.rst @@ -1,10 +1,12 @@ :mod:`ucollections` -- collection and container types ===================================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: ucollections :synopsis: collection and container types -|see_cpython_module| :mod:`python:collections`. +|see_cpython_module| :mod:`cpython:collections`. This module implements advanced collection and container types to hold/accumulate various objects. diff --git a/docs/library/uctypes.rst b/docs/library/uctypes.rst index 2a9c4dd5c..55de9a0a2 100644 --- a/docs/library/uctypes.rst +++ b/docs/library/uctypes.rst @@ -1,6 +1,8 @@ :mod:`uctypes` -- access binary data in a structured way ======================================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uctypes :synopsis: access binary data in a structured way @@ -13,7 +15,7 @@ sub-fields. .. seealso:: - Module :mod:`ustruct` + Module :mod:`struct` Standard Python way to access binary data structures (doesn't scale well to large and complex structures). diff --git a/docs/library/uerrno.rst b/docs/library/uerrno.rst index 0cdcc8448..72f71f0aa 100644 --- a/docs/library/uerrno.rst +++ b/docs/library/uerrno.rst @@ -1,13 +1,14 @@ :mod:`uerrno` -- system error codes =================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uerrno :synopsis: system error codes -|see_cpython_module| :mod:`python:errno`. +|see_cpython_module| :mod:`cpython:errno`. This module provides access to symbolic error codes for `OSError` exception. -A particular inventory of codes depends on `MicroPython port`. Constants --------- @@ -15,12 +16,11 @@ Constants .. data:: EEXIST, EAGAIN, etc. Error codes, based on ANSI C/POSIX standard. All error codes start with - "E". As mentioned above, inventory of the codes depends on - `MicroPython port`. Errors are usually accessible as ``exc.args[0]`` - where `exc` is an instance of `OSError`. Usage example:: + "E". Errors are usually accessible as ``exc.args[0]`` + where ``exc`` is an instance of `OSError`. Usage example:: try: - uos.mkdir("my_dir") + os.mkdir("my_dir") except OSError as exc: if exc.args[0] == uerrno.EEXIST: print("Directory already exists") diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index 50ed658cc..0f20413f7 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -1,10 +1,12 @@ :mod:`uhashlib` -- hashing algorithms ===================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uhashlib :synopsis: hashing algorithms -|see_cpython_module| :mod:`python:hashlib`. +|see_cpython_module| :mod:`cpython:hashlib`. This module implements binary data hashing algorithms. The exact inventory of available algorithms depends on a board. Among the algorithms which may diff --git a/docs/library/uheapq.rst b/docs/library/uheapq.rst index f822f1e7f..67da5f738 100644 --- a/docs/library/uheapq.rst +++ b/docs/library/uheapq.rst @@ -1,10 +1,12 @@ :mod:`uheapq` -- heap queue algorithm ===================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uheapq :synopsis: heap queue algorithm -|see_cpython_module| :mod:`python:heapq`. +|see_cpython_module| :mod:`cpython:heapq`. This module implements the heap queue algorithm. diff --git a/docs/library/uio.rst b/docs/library/uio.rst index 7042a9e37..5ae8b9ecb 100644 --- a/docs/library/uio.rst +++ b/docs/library/uio.rst @@ -1,10 +1,12 @@ :mod:`uio` -- input/output streams ================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uio :synopsis: input/output streams -|see_cpython_module| :mod:`python:io`. +|see_cpython_module| :mod:`cpython:io`. This module contains additional types of stream (file-like) objects and helper functions. @@ -81,7 +83,7 @@ Functions Open a file. Builtin ``open()`` function is aliased to this function. All ports (which provide access to file system) are required to support - `mode` parameter, but support for other arguments vary by port. + ``mode`` parameter, but support for other arguments vary by port. Classes ------- diff --git a/docs/library/ujson.rst b/docs/library/ujson.rst index 0932d0ab5..080ee2d03 100644 --- a/docs/library/ujson.rst +++ b/docs/library/ujson.rst @@ -1,10 +1,12 @@ :mod:`ujson` -- JSON encoding and decoding ========================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: ujson :synopsis: JSON encoding and decoding -|see_cpython_module| :mod:`python:json`. +|see_cpython_module| :mod:`cpython:json`. This modules allows to convert between Python objects and the JSON data format. diff --git a/docs/library/uos.rst b/docs/library/uos.rst deleted file mode 100644 index 43bf69cc0..000000000 --- a/docs/library/uos.rst +++ /dev/null @@ -1,110 +0,0 @@ -:mod:`uos` -- basic "operating system" services -=============================================== - -.. module:: uos - :synopsis: basic "operating system" services - -|see_cpython_module| :mod:`python:os`. - -The ``uos`` module contains functions for filesystem access and ``urandom`` -function. - -Functions ---------- - -.. function:: chdir(path) - - Change current directory. - -.. function:: getcwd() - - Get the current directory. - -.. function:: ilistdir([dir]) - - This function returns an iterator which then yields 3-tuples corresponding to - the entries in the directory that it is listing. With no argument it lists the - current directory, otherwise it lists the directory given by *dir*. - - The 3-tuples have the form *(name, type, inode)*: - - - *name* is a string (or bytes if *dir* is a bytes object) and is the name of - the entry; - - *type* is an integer that specifies the type of the entry, with 0x4000 for - directories and 0x8000 for regular files; - - *inode* is an integer corresponding to the inode of the file, and may be 0 - for filesystems that don't have such a notion. - -.. function:: listdir([dir]) - - With no argument, list the current directory. Otherwise list the given directory. - -.. function:: mkdir(path) - - Create a new directory. - -.. function:: remove(path) - - Remove a file. - -.. function:: rmdir(path) - - Remove a directory. - -.. function:: rename(old_path, new_path) - - Rename a file. - -.. function:: stat(path) - - Get the status of a file or directory. - -.. function:: statvfs(path) - - Get the status of a fileystem. - - Returns a tuple with the filesystem information in the following order: - - * ``f_bsize`` -- file system block size - * ``f_frsize`` -- fragment size - * ``f_blocks`` -- size of fs in f_frsize units - * ``f_bfree`` -- number of free blocks - * ``f_bavail`` -- number of free blocks for unpriviliged users - * ``f_files`` -- number of inodes - * ``f_ffree`` -- number of free inodes - * ``f_favail`` -- number of free inodes for unpriviliged users - * ``f_flag`` -- mount flags - * ``f_namemax`` -- maximum filename length - - Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail`` - and the ``f_flags`` parameter may return ``0`` as they can be unavailable - in a port-specific implementation. - -.. function:: sync() - - Sync all filesystems. - -.. function:: urandom(n) - - Return a bytes object with n random bytes. Whenever possible, it is - generated by the hardware random number generator. - -.. function:: dupterm(stream_object, index=0) - - Duplicate or switch the MicroPython terminal (the REPL) on the given stream-like - object. The *stream_object* argument must implement the ``readinto()`` and - ``write()`` methods. The stream should be in non-blocking mode and - ``readinto()`` should return ``None`` if there is no data available for reading. - - After calling this function all terminal output is repeated on this stream, - and any input that is available on the stream is passed on to the terminal input. - - The *index* parameter should be a non-negative integer and specifies which - duplication slot is set. A given port may implement more than one slot (slot 0 - will always be available) and in that case terminal input and output is - duplicated on all the slots that are set. - - If ``None`` is passed as the *stream_object* then duplication is cancelled on - the slot given by *index*. - - The function returns the previous stream-like object in the given slot. diff --git a/docs/library/ure.rst b/docs/library/ure.rst index ebae1db5f..c6457de9a 100644 --- a/docs/library/ure.rst +++ b/docs/library/ure.rst @@ -1,10 +1,12 @@ :mod:`ure` -- simple regular expressions ======================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: ure :synopsis: regular expressions -|see_cpython_module| :mod:`python:re`. +|see_cpython_module| :mod:`cpython:re`. This module implements regular expression operations. Regular expression syntax supported is a subset of CPython ``re`` module (and actually is diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index beffce69a..685f5b318 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -1,10 +1,12 @@ :mod:`uselect` -- wait for events on a set of streams ======================================================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uselect :synopsis: wait for events on a set of streams -|see_cpython_module| :mod:`python:select`. +|see_cpython_module| :mod:`cpython:select`. This module provides functions to efficiently wait for events on multiple streams (select streams which are ready for operations). @@ -69,7 +71,7 @@ Methods .. method:: poll.ipoll(timeout=-1, flags=0) Like :meth:`poll.poll`, but instead returns an iterator which yields - `callee-owned tuples`. This function provides efficient, allocation-free + ``callee-owned tuples``. This function provides efficient, allocation-free way to poll on streams. If *flags* is 1, one-shot behavior for events is employed: streams for diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index fab05b652..b07ba4413 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -2,10 +2,12 @@ :mod:`usocket` -- socket module ******************************* +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: usocket :synopsis: socket module -|see_cpython_module| :mod:`python:socket`. +|see_cpython_module| :mod:`cpython:socket`. This module provides access to the BSD socket interface. @@ -36,11 +38,7 @@ power) and portable way to work with addresses. However, ``socket`` module (note the difference with native MicroPython ``usocket`` module described here) provides CPython-compatible way to specify -addresses using tuples, as described below. Note that depending on a -`MicroPython port`, ``socket`` module can be builtin or need to be -installed from `micropython-lib` (as in the case of `MicroPython Unix port`), -and some ports still accept only numeric addresses in the tuple format, -and require to use `getaddrinfo` function to resolve domain names. +addresses using tuples, as described below. Summing up: @@ -60,8 +58,7 @@ Tuple address format for ``socket`` module: and *port* is an integer port number in the range 1-65535. *flowinfo* must be 0. *scopeid* is the interface scope identifier for link-local addresses. Note the domain names are not accepted as *ipv6_address*, - they should be resolved first using `usocket.getaddrinfo()`. Availability - of IPv6 support depends on a `MicroPython port`. + they should be resolved first using `usocket.getaddrinfo()`. Functions --------- @@ -81,8 +78,8 @@ Functions .. function:: getaddrinfo(host, port) - Translate the host/port argument into a sequence of 5-tuples that contain all the - necessary arguments for creating a socket connected to that service. The list of + Translate the host/port argument into a sequence of 5-tuples that contain all the + necessary arguments for creating a socket connected to that service. The list of 5-tuples has following structure:: (family, type, proto, canonname, sockaddr) @@ -99,7 +96,7 @@ Functions of error in this function. MicroPython doesn't have ``socket.gaierror`` and raises OSError directly. Note that error numbers of `getaddrinfo()` form a separate namespace and may not match error numbers from - `uerrno` module. To distinguish `getaddrinfo()` errors, they are + :py:mod:`uerrno` module. To distinguish `getaddrinfo()` errors, they are represented by negative numbers, whereas standard system errors are positive numbers (error numbers are accessible using ``e.args[0]`` property from an exception object). The use of negative values is a provisional @@ -127,7 +124,7 @@ Constants .. data:: AF_INET AF_INET6 - Address family types. Availability depends on a particular `MicroPython port`. + Address family types. Availability depends on a particular ``MicroPython port``. .. data:: SOCK_STREAM SOCK_DGRAM @@ -137,7 +134,7 @@ Constants .. data:: IPPROTO_UDP IPPROTO_TCP - IP protocol numbers. Availability depends on a particular `MicroPython port`. + IP protocol numbers. Availability depends on a particular ``MicroPython port``. Note that you don't need to specify these in a call to `usocket.socket()`, because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants @@ -146,12 +143,12 @@ Constants .. data:: usocket.SOL_* Socket option levels (an argument to `setsockopt()`). The exact - inventory depends on a `MicroPython port`. + inventory depends on a ``MicroPython port``. .. data:: usocket.SO_* Socket options (an argument to `setsockopt()`). The exact - inventory depends on a `MicroPython port`. + inventory depends on a ``MicroPython port``. Constants specific to WiPy: @@ -171,7 +168,7 @@ Methods on the socket object will fail. The remote end will receive EOF indication if supported by protocol. - Sockets are automatically closed when they are garbage-collected, but it is recommended + Sockets are automatically closed when they are garbage-collected, but it is recommended to `close()` them explicitly as soon you finished working with them. .. method:: socket.bind(address) @@ -245,7 +242,7 @@ Methods completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode. - Not every `MicroPython port` supports this method. A more portable and + Not every ``MicroPython port`` supports this method. A more portable and generic solution is to use `uselect.poll` object. This allows to wait on multiple objects at the same time (and not just on sockets, but on generic stream objects which support polling). Example:: diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index 3ec609f67..34db3151d 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -1,10 +1,12 @@ :mod:`ussl` -- SSL/TLS module ============================= +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: ussl :synopsis: TLS/SSL wrapper for socket objects -|see_cpython_module| :mod:`python:ssl`. +|see_cpython_module| :mod:`cpython:ssl`. This module provides access to Transport Layer Security (previously and widely known as “Secure Sockets Layer”) encryption and peer authentication @@ -18,13 +20,13 @@ Functions Takes a stream *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in an SSL context. Returned object has the usual stream interface methods like - `read()`, `write()`, etc. In MicroPython, the returned object does not expose - socket interface and methods like `recv()`, `send()`. In particular, a + ``read()``, ``write()``, etc. In MicroPython, the returned object does not expose + socket interface and methods like ``recv()``, ``send()``. In particular, a server-side SSL socket should be created from a normal socket returned from `accept()` on a non-SSL listening server socket. Depending on the underlying module implementation in a particular - `MicroPython port`, some or all keyword arguments above may be not supported. + ``MicroPython port``, some or all keyword arguments above may be not supported. .. warning:: diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst index 81915d0a8..c378a94bb 100644 --- a/docs/library/ustruct.rst +++ b/docs/library/ustruct.rst @@ -1,10 +1,12 @@ :mod:`ustruct` -- pack and unpack primitive data types ====================================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: ustruct :synopsis: pack and unpack primitive data types -|see_cpython_module| :mod:`python:struct`. +|see_cpython_module| :mod:`cpython:struct`. Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``. diff --git a/docs/library/utime.rst b/docs/library/utime.rst deleted file mode 100644 index a39f5ee73..000000000 --- a/docs/library/utime.rst +++ /dev/null @@ -1,229 +0,0 @@ -:mod:`utime` -- time related functions -====================================== - -.. module:: utime - :synopsis: time related functions - -|see_cpython_module| :mod:`python:time`. - -The ``utime`` module provides functions for getting the current time and date, -measuring time intervals, and for delays. - -**Time Epoch**: Unix port uses standard for POSIX systems epoch of -1970-01-01 00:00:00 UTC. However, embedded ports use epoch of -2000-01-01 00:00:00 UTC. - -**Maintaining actual calendar date/time**: This requires a -Real Time Clock (RTC). On systems with underlying OS (including some -RTOS), an RTC may be implicit. Setting and maintaining actual calendar -time is responsibility of OS/RTOS and is done outside of MicroPython, -it just uses OS API to query date/time. On baremetal ports however -system time depends on ``machine.RTC()`` object. The current calendar time -may be set using ``machine.RTC().datetime(tuple)`` function, and maintained -by following means: - -* By a backup battery (which may be an additional, optional component for - a particular board). -* Using networked time protocol (requires setup by a port/user). -* Set manually by a user on each power-up (many boards then maintain - RTC time across hard resets, though some may require setting it again - in such case). - -If actual calendar time is not maintained with a system/MicroPython RTC, -functions below which require reference to current absolute time may -behave not as expected. - -Functions ---------- - -.. function:: localtime([secs]) - - Convert a time expressed in seconds since the Epoch (see above) into an 8-tuple which - contains: (year, month, mday, hour, minute, second, weekday, yearday) - If secs is not provided or None, then the current time from the RTC is used. - - * year includes the century (for example 2014). - * month is 1-12 - * mday is 1-31 - * hour is 0-23 - * minute is 0-59 - * second is 0-59 - * weekday is 0-6 for Mon-Sun - * yearday is 1-366 - -.. function:: mktime() - - This is inverse function of localtime. It's argument is a full 8-tuple - which expresses a time as per localtime. It returns an integer which is - the number of seconds since Jan 1, 2000. - -.. function:: sleep(seconds) - - Sleep for the given number of seconds. Some boards may accept *seconds* as a - floating-point number to sleep for a fractional number of seconds. Note that - other boards may not accept a floating-point argument, for compatibility with - them use `sleep_ms()` and `sleep_us()` functions. - -.. function:: sleep_ms(ms) - - Delay for given number of milliseconds, should be positive or 0. - -.. function:: sleep_us(us) - - Delay for given number of microseconds, should be positive or 0. - -.. function:: ticks_ms() - - Returns an increasing millisecond counter with an arbitrary reference point, that - wraps around after some value. - - The wrap-around value is not explicitly exposed, but we will - refer to it as *TICKS_MAX* to simplify discussion. Period of the values is - *TICKS_PERIOD = TICKS_MAX + 1*. *TICKS_PERIOD* is guaranteed to be a power of - two, but otherwise may differ from port to port. The same period value is used - for all of `ticks_ms()`, `ticks_us()`, `ticks_cpu()` functions (for - simplicity). Thus, these functions will return a value in range [*0* .. - *TICKS_MAX*], inclusive, total *TICKS_PERIOD* values. Note that only - non-negative values are used. For the most part, you should treat values returned - by these functions as opaque. The only operations available for them are - `ticks_diff()` and `ticks_add()` functions described below. - - Note: Performing standard mathematical operations (+, -) or relational - operators (<, <=, >, >=) directly on these value will lead to invalid - result. Performing mathematical operations and then passing their results - as arguments to `ticks_diff()` or `ticks_add()` will also lead to - invalid results from the latter functions. - -.. function:: ticks_us() - - Just like `ticks_ms()` above, but in microseconds. - -.. function:: ticks_cpu() - - Similar to `ticks_ms()` and `ticks_us()`, but with the highest possible resolution - in the system. This is usually CPU clocks, and that's why the function is named that - way. But it doesn't have to be a CPU clock, some other timing source available in a - system (e.g. high-resolution timer) can be used instead. The exact timing unit - (resolution) of this function is not specified on ``utime`` module level, but - documentation for a specific port may provide more specific information. This - function is intended for very fine benchmarking or very tight real-time loops. - Avoid using it in portable code. - - Availability: Not every port implements this function. - - -.. function:: ticks_add(ticks, delta) - - Offset ticks value by a given number, which can be either positive or negative. - Given a *ticks* value, this function allows to calculate ticks value *delta* - ticks before or after it, following modular-arithmetic definition of tick values - (see `ticks_ms()` above). *ticks* parameter must be a direct result of call - to `ticks_ms()`, `ticks_us()`, or `ticks_cpu()` functions (or from previous - call to `ticks_add()`). However, *delta* can be an arbitrary integer number - or numeric expression. `ticks_add()` is useful for calculating deadlines for - events/tasks. (Note: you must use `ticks_diff()` function to work with - deadlines.) - - Examples:: - - # Find out what ticks value there was 100ms ago - print(ticks_add(time.ticks_ms(), -100)) - - # Calculate deadline for operation and test for it - deadline = ticks_add(time.ticks_ms(), 200) - while ticks_diff(deadline, time.ticks_ms()) > 0: - do_a_little_of_something() - - # Find out TICKS_MAX used by this port - print(ticks_add(0, -1)) - - -.. function:: ticks_diff(ticks1, ticks2) - - Measure ticks difference between values returned from `ticks_ms()`, `ticks_us()`, - or `ticks_cpu()` functions, as a signed value which may wrap around. - - The argument order is the same as for subtraction - operator, ``ticks_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. - However, values returned by `ticks_ms()`, etc. functions may wrap around, so - directly using subtraction on them will produce incorrect result. That is why - `ticks_diff()` is needed, it implements modular (or more specifically, ring) - arithmetics to produce correct result even for wrap-around values (as long as they not - too distant inbetween, see below). The function returns **signed** value in the range - [*-TICKS_PERIOD/2* .. *TICKS_PERIOD/2-1*] (that's a typical range definition for - two's-complement signed binary integers). If the result is negative, it means that - *ticks1* occurred earlier in time than *ticks2*. Otherwise, it means that - *ticks1* occurred after *ticks2*. This holds **only** if *ticks1* and *ticks2* - are apart from each other for no more than *TICKS_PERIOD/2-1* ticks. If that does - not hold, incorrect result will be returned. Specifically, if two tick values are - apart for *TICKS_PERIOD/2-1* ticks, that value will be returned by the function. - However, if *TICKS_PERIOD/2* of real-time ticks has passed between them, the - function will return *-TICKS_PERIOD/2* instead, i.e. result value will wrap around - to the negative range of possible values. - - Informal rationale of the constraints above: Suppose you are locked in a room with no - means to monitor passing of time except a standard 12-notch clock. Then if you look at - dial-plate now, and don't look again for another 13 hours (e.g., if you fall for a - long sleep), then once you finally look again, it may seem to you that only 1 hour - has passed. To avoid this mistake, just look at the clock regularly. Your application - should do the same. "Too long sleep" metaphor also maps directly to application - behavior: don't let your application run any single task for too long. Run tasks - in steps, and do time-keeping inbetween. - - `ticks_diff()` is designed to accommodate various usage patterns, among them: - - * Polling with timeout. In this case, the order of events is known, and you will deal - only with positive results of `ticks_diff()`:: - - # Wait for GPIO pin to be asserted, but at most 500us - start = time.ticks_us() - while pin.value() == 0: - if time.ticks_diff(time.ticks_us(), start) > 500: - raise TimeoutError - - * Scheduling events. In this case, `ticks_diff()` result may be negative - if an event is overdue:: - - # This code snippet is not optimized - now = time.ticks_ms() - scheduled_time = task.scheduled_time() - if ticks_diff(now, scheduled_time) > 0: - print("Too early, let's nap") - sleep_ms(ticks_diff(now, scheduled_time)) - task.run() - elif ticks_diff(now, scheduled_time) == 0: - print("Right at time!") - task.run() - elif ticks_diff(now, scheduled_time) < 0: - print("Oops, running late, tell task to run faster!") - task.run(run_faster=true) - - Note: Do not pass `time()` values to `ticks_diff()`, you should use - normal mathematical operations on them. But note that `time()` may (and will) - also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem . - - -.. function:: time() - - Returns the number of seconds, as an integer, since the Epoch, assuming that - underlying RTC is set and maintained as described above. If an RTC is not set, this - function returns number of seconds since a port-specific reference point in time (for - embedded boards without a battery-backed RTC, usually since power up or reset). If you - want to develop portable MicroPython application, you should not rely on this function - to provide higher than second precision. If you need higher precision, use - `ticks_ms()` and `ticks_us()` functions, if you need calendar time, - `localtime()` without an argument is a better choice. - - .. admonition:: Difference to CPython - :class: attention - - In CPython, this function returns number of - seconds since Unix epoch, 1970-01-01 00:00 UTC, as a floating-point, - usually having microsecond precision. With MicroPython, only Unix port - uses the same Epoch, and if floating-point precision allows, - returns sub-second precision. Embedded hardware usually doesn't have - floating-point precision to represent both long time ranges and subsecond - precision, so they use integer value with second precision. Some embedded - hardware also lacks battery-powered RTC, so returns number of seconds - since last power-up or from other relative, hardware-specific point - (e.g. reset). diff --git a/docs/library/uzlib.rst b/docs/library/uzlib.rst index fb1746fe8..2a2d9668c 100644 --- a/docs/library/uzlib.rst +++ b/docs/library/uzlib.rst @@ -1,10 +1,12 @@ :mod:`uzlib` -- zlib decompression ================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: uzlib :synopsis: zlib decompression -|see_cpython_module| :mod:`python:zlib`. +|see_cpython_module| :mod:`cpython:zlib`. This module allows to decompress binary data compressed with `DEFLATE algorithm <https://en.wikipedia.org/wiki/DEFLATE>`_ diff --git a/docs/library/wipy.rst b/docs/library/wipy.rst deleted file mode 100644 index cdece7b82..000000000 --- a/docs/library/wipy.rst +++ /dev/null @@ -1,17 +0,0 @@ -************************************* -:mod:`wipy` -- WiPy specific features -************************************* - -.. module:: wipy - :synopsis: WiPy specific features - -The ``wipy`` module contains functions to control specific features of the -WiPy, such as the heartbeat LED. - -Functions ---------- - -.. function:: heartbeat([enable]) - - Get or set the state (enabled or disabled) of the heartbeat LED. Accepts and - returns boolean values (``True`` or ``False``). diff --git a/docs/porting.rst b/docs/porting.rst index f46160b7d..6bb514458 100644 --- a/docs/porting.rst +++ b/docs/porting.rst @@ -45,7 +45,7 @@ these resources are compatible with the MIT License of the rest of the code! Step 2: Init -------------- Once your build is setup, the next step should be to get your clocks going as -you expect from the supervisor. The supervisor calls `port_init` to allow for +you expect from the supervisor. The supervisor calls ``port_init`` to allow for initialization at the beginning of main. This function also has the ability to request a safe mode state which prevents the supervisor from running user code while still allowing access to the REPL and other resources. diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst deleted file mode 100644 index 97e9aabc0..000000000 --- a/docs/pyboard/general.rst +++ /dev/null @@ -1,80 +0,0 @@ -General information about the pyboard -===================================== - -.. contents:: - -Local filesystem and SD card ----------------------------- - -There is a small internal filesystem (a drive) on the pyboard, called ``/flash``, -which is stored within the microcontroller's flash memory. If a micro SD card -is inserted into the slot, it is available as ``/sd``. - -When the pyboard boots up, it needs to choose a filesystem to boot from. If -there is no SD card, then it uses the internal filesystem ``/flash`` as the boot -filesystem, otherwise, it uses the SD card ``/sd``. After the boot, the current -directory is set to one of the directories above. - -If needed, you can prevent the use of the SD card by creating an empty file -called ``/flash/SKIPSD``. If this file exists when the pyboard boots -up then the SD card will be skipped and the pyboard will always boot from the -internal filesystem (in this case the SD card won't be mounted but you can still -mount and use it later in your program using ``os.mount``). - -(Note that on older versions of the board, ``/flash`` is called ``0:/`` and ``/sd`` -is called ``1:/``). - -The boot filesystem is used for 2 things: it is the filesystem from which -the ``boot.py`` and ``main.py`` files are searched for, and it is the filesystem -which is made available on your PC over the USB cable. - -The filesystem will be available as a USB flash drive on your PC. You can -save files to the drive, and edit ``boot.py`` and ``main.py``. - -*Remember to eject (on Linux, unmount) the USB drive before you reset your -pyboard.* - -Boot modes ----------- - -If you power up normally, or press the reset button, the pyboard will boot -into standard mode: the ``boot.py`` file will be executed first, then the -USB will be configured, then ``main.py`` will run. - -You can override this boot sequence by holding down the user switch as -the board is booting up. Hold down user switch and press reset, and then -as you continue to hold the user switch, the LEDs will count in binary. -When the LEDs have reached the mode you want, let go of the user switch, -the LEDs for the selected mode will flash quickly, and the board will boot. - -The modes are: - -1. Green LED only, *standard boot*: run ``boot.py`` then ``main.py``. -2. Orange LED only, *safe boot*: don't run any scripts on boot-up. -3. Green and orange LED together, *filesystem reset*: resets the flash - filesystem to its factory state, then boots in safe mode. - -If your filesystem becomes corrupt, boot into mode 3 to fix it. -If resetting the filesystem while plugged into your compute doesn't work, -you can try doing the same procedure while the board is plugged into a USB -charger, or other USB power supply without data connection. - -Errors: flashing LEDs ---------------------- - -There are currently 2 kinds of errors that you might see: - -1. If the red and green LEDs flash alternatively, then a Python script - (eg ``main.py``) has an error. Use the REPL to debug it. -2. If all 4 LEDs cycle on and off slowly, then there was a hard fault. - This cannot be recovered from and you need to do a hard reset. - -Guide for using the pyboard with Windows ----------------------------------------- - -The following PDF guide gives information about using the pyboard with Windows, -including setting up the serial prompt and downloading new firmware using -DFU programming: -`PDF guide <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`__. - -.. include:: hardware/index.rst diff --git a/docs/pyboard/hardware/index.rst b/docs/pyboard/hardware/index.rst deleted file mode 100644 index 91fea24e7..000000000 --- a/docs/pyboard/hardware/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _hardware_index: - -The pyboard hardware --------------------- - -For the pyboard: - -* `PYBv1.0 schematics and layout <http://micropython.org/resources/PYBv10b.pdf>`_ (2.4MiB PDF) -* `PYBv1.0 metric dimensions <http://micropython.org/resources/PYBv10b-metric-dimensions.pdf>`_ (360KiB PDF) -* `PYBv1.0 imperial dimensions <http://micropython.org/resources/PYBv10b-imperial-dimensions.pdf>`_ (360KiB PDF) - -For the official skin modules: - -* `LCD32MKv1.0 schematics <http://micropython.org/resources/LCD32MKv10-schematics.pdf>`_ (194KiB PDF) -* `AMPv1.0 schematics <http://micropython.org/resources/AMPv10-schematics.pdf>`_ (209KiB PDF) -* LCD160CRv1.0: see :mod:`lcd160cr` - -Datasheets for the components on the pyboard --------------------------------------------- - -* The microcontroller: `STM32F405RGT6 <http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1577/LN1035/PF252144>`_ (link to manufacturer's site) -* The accelerometer: `Freescale MMA7660 <http://micropython.org/resources/datasheets/MMA7660FC.pdf>`_ (800kiB PDF) -* The LDO voltage regulator: `Microchip MCP1802 <http://micropython.org/resources/datasheets/MCP1802-22053C.pdf>`_ (400kiB PDF) - -Datasheets for other components -------------------------------- - -* The LCD display on the LCD touch-sensor skin: `Newhaven Display NHD-C12832A1Z-FSW-FBW-3V3 <http://micropython.org/resources/datasheets/NHD-C12832A1Z-FSW-FBW-3V3.pdf>`_ (460KiB PDF) -* The touch sensor chip on the LCD touch-sensor skin: `Freescale MPR121 <http://micropython.org/resources/datasheets/MPR121.pdf>`_ (280KiB PDF) -* The digital potentiometer on the audio skin: `Microchip MCP4541 <http://micropython.org/resources/datasheets/MCP4541-22107B.pdf>`_ (2.7MiB PDF) diff --git a/docs/pyboard/index.rst b/docs/pyboard/index.rst deleted file mode 100644 index c05e5d47f..000000000 --- a/docs/pyboard/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -PyBoard -======================================== - -.. toctree:: - - quickref.rst - general.rst - tutorial/index.rst - hardware/index.rst diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst deleted file mode 100644 index 48798aad3..000000000 --- a/docs/pyboard/quickref.rst +++ /dev/null @@ -1,217 +0,0 @@ -.. _quickref: - -Quick reference for the pyboard -=============================== - -The below pinout is for PYBv1.0. You can also view pinouts for -other versions of the pyboard: -`PYBv1.1 <http://micropython.org/resources/pybv11-pinout.jpg>`__ -or `PYBLITEv1.0-AC <http://micropython.org/resources/pyblitev10ac-pinout.jpg>`__ -or `PYBLITEv1.0 <http://micropython.org/resources/pyblitev10-pinout.jpg>`__. - -.. image:: http://micropython.org/resources/pybv10-pinout.jpg - :alt: PYBv1.0 pinout - :width: 700px - -General board control ---------------------- - -See :mod:`pyb`. :: - - import pyb - - pyb.repl_uart(pyb.UART(1, 9600)) # duplicate REPL on UART(1) - pyb.wfi() # pause CPU, waiting for interrupt - pyb.freq() # get CPU and bus frequencies - pyb.freq(60000000) # set CPU freq to 60MHz - pyb.stop() # stop CPU, waiting for external interrupt - -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 value of millisecond counter - delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference - -Internal LEDs -------------- - -See :ref:`pyb.LED <pyb.LED>`. :: - - from pyb import LED - - led = LED(1) # 1=red, 2=green, 3=yellow, 4=blue - led.toggle() - led.on() - led.off() - - # LEDs 3 and 4 support PWM intensity (0-255) - LED(4).intensity() # get intensity - LED(4).intensity(128) # set intensity to half - -Internal switch ---------------- - -See :ref:`pyb.Switch <pyb.Switch>`. :: - - from pyb import Switch - - sw = Switch() - sw.value() # returns True or False - sw.callback(lambda: pyb.LED(1).toggle()) - -Pins and GPIO -------------- - -See :ref:`pyb.Pin <pyb.Pin>`. :: - - from pyb import Pin - - p_out = Pin('X1', Pin.OUT_PP) - p_out.high() - p_out.low() - - p_in = Pin('X2', Pin.IN, Pin.PULL_UP) - p_in.value() # get value, 0 or 1 - -Servo control -------------- - -See :ref:`pyb.Servo <pyb.Servo>`. :: - - from pyb import Servo - - s1 = Servo(1) # servo on position 1 (X1, VIN, GND) - s1.angle(45) # move to 45 degrees - s1.angle(-60, 1500) # move to -60 degrees in 1500ms - s1.speed(50) # for continuous rotation servos - -External interrupts -------------------- - -See :ref:`pyb.ExtInt <pyb.ExtInt>`. :: - - from pyb import Pin, ExtInt - - callback = lambda e: print("intr") - ext = ExtInt(Pin('Y1'), ExtInt.IRQ_RISING, Pin.PULL_NONE, callback) - -Timers ------- - -See :ref:`pyb.Timer <pyb.Timer>`. :: - - from pyb import Timer - - tim = Timer(1, freq=1000) - tim.counter() # get counter value - tim.freq(0.5) # 0.5 Hz - tim.callback(lambda t: pyb.LED(1).toggle()) - -RTC (real time clock) ---------------------- - -See :ref:`pyb.RTC <pyb.RTC>` :: - - from pyb 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 - -PWM (pulse width modulation) ----------------------------- - -See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.Timer <pyb.Timer>`. :: - - from pyb import Pin, Timer - - p = Pin('X1') # X1 has TIM2, CH1 - tim = Timer(2, freq=1000) - ch = tim.channel(1, Timer.PWM, pin=p) - ch.pulse_width_percent(50) - -ADC (analog to digital conversion) ----------------------------------- - -See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.ADC <pyb.ADC>`. :: - - from pyb import Pin, ADC - - adc = ADC(Pin('X19')) - adc.read() # read value, 0-4095 - -DAC (digital to analog conversion) ----------------------------------- - -See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.DAC <pyb.DAC>`. :: - - from pyb import Pin, DAC - - dac = DAC(Pin('X5')) - dac.write(120) # output between 0 and 255 - -UART (serial bus) ------------------ - -See :ref:`pyb.UART <pyb.UART>`. :: - - from pyb import UART - - uart = UART(1, 9600) - uart.write('hello') - uart.read(5) # read up to 5 bytes - -SPI bus -------- - -See :ref:`pyb.SPI <pyb.SPI>`. :: - - from pyb import SPI - - spi = SPI(1, SPI.MASTER, baudrate=200000, polarity=1, phase=0) - spi.send('hello') - spi.recv(5) # receive 5 bytes on the bus - spi.send_recv('hello') # send and receive 5 bytes - -I2C bus -------- - -See :ref:`pyb.I2C <pyb.I2C>`. :: - - from pyb import I2C - - i2c = I2C(1, I2C.MASTER, baudrate=100000) - i2c.scan() # returns list of slave addresses - i2c.send('hello', 0x42) # send 5 bytes to slave with address 0x42 - i2c.recv(5, 0x42) # receive 5 bytes from slave - i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10 - i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10 - -CAN bus (controller area network) ---------------------------------- - -See :ref:`pyb.CAN <pyb.CAN>`. :: - - from pyb import CAN - - can = CAN(1, CAN.LOOPBACK) - can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126)) - can.send('message!', 123) # send a message with id 123 - can.recv(0) # receive message on FIFO 0 - -Internal accelerometer ----------------------- - -See :ref:`pyb.Accel <pyb.Accel>`. :: - - from pyb import Accel - - accel = Accel() - print(accel.x(), accel.y(), accel.z(), accel.tilt()) diff --git a/docs/pyboard/tutorial/accel.rst b/docs/pyboard/tutorial/accel.rst deleted file mode 100644 index 58170e74f..000000000 --- a/docs/pyboard/tutorial/accel.rst +++ /dev/null @@ -1,92 +0,0 @@ -The accelerometer -================= - -Here you will learn how to read the accelerometer and signal using LEDs states like tilt left and tilt right. - -Using the accelerometer ------------------------ - -The pyboard has an accelerometer (a tiny mass on a tiny spring) that can be used -to detect the angle of the board and motion. There is a different sensor for -each of the x, y, z directions. To get the value of the accelerometer, create a -pyb.Accel() object and then call the x() method. :: - - >>> accel = pyb.Accel() - >>> accel.x() - 7 - -This returns a signed integer with a value between around -30 and 30. Note that -the measurement is very noisy, this means that even if you keep the board -perfectly still there will be some variation in the number that you measure. -Because of this, you shouldn't use the exact value of the x() method but see if -it is in a certain range. - -We will start by using the accelerometer to turn on a light if it is not flat. :: - - accel = pyb.Accel() - light = pyb.LED(3) - SENSITIVITY = 3 - - while True: - x = accel.x() - if abs(x) > SENSITIVITY: - light.on() - else: - light.off() - - pyb.delay(100) - -We create Accel and LED objects, then get the value of the x direction of the -accelerometer. If the magnitude of x is bigger than a certain value ``SENSITIVITY``, -then the LED turns on, otherwise it turns off. The loop has a small ``pyb.delay()`` -otherwise the LED flashes annoyingly when the value of x is close to -``SENSITIVITY``. Try running this on the pyboard and tilt the board left and right -to make the LED turn on and off. - -**Exercise: Change the above script so that the blue LED gets brighter the more -you tilt the pyboard. HINT: You will need to rescale the values, intensity goes -from 0-255.** - -Making a spirit level ---------------------- - -The example above is only sensitive to the angle in the x direction but if we -use the ``y()`` value and more LEDs we can turn the pyboard into a spirit level. :: - - xlights = (pyb.LED(2), pyb.LED(3)) - ylights = (pyb.LED(1), pyb.LED(4)) - - accel = pyb.Accel() - SENSITIVITY = 3 - - while True: - x = accel.x() - if x > SENSITIVITY: - xlights[0].on() - xlights[1].off() - elif x < -SENSITIVITY: - xlights[1].on() - xlights[0].off() - else: - xlights[0].off() - xlights[1].off() - - y = accel.y() - if y > SENSITIVITY: - ylights[0].on() - ylights[1].off() - elif y < -SENSITIVITY: - ylights[1].on() - ylights[0].off() - else: - ylights[0].off() - ylights[1].off() - - pyb.delay(100) - -We start by creating a tuple of LED objects for the x and y directions. Tuples -are immutable objects in python which means they can't be modified once they are -created. We then proceed as before but turn on a different LED for positive and -negative x values. We then do the same for the y direction. This isn't -particularly sophisticated but it does the job. Run this on your pyboard and you -should see different LEDs turning on depending on how you tilt the board. diff --git a/docs/pyboard/tutorial/amp_skin.rst b/docs/pyboard/tutorial/amp_skin.rst deleted file mode 100644 index 697637f9d..000000000 --- a/docs/pyboard/tutorial/amp_skin.rst +++ /dev/null @@ -1,98 +0,0 @@ -The AMP audio skin -================== - -Soldering and using the AMP audio skin. - -.. image:: img/skin_amp_1.jpg - :alt: AMP skin - :width: 250px - -.. image:: img/skin_amp_2.jpg - :alt: AMP skin - :width: 250px - -The following video shows how to solder the headers, microphone and speaker onto the AMP skin. - -.. raw:: html - - <iframe style="margin-left:3em;" width="560" height="315" src="http://www.youtube.com/embed/fjB1DuZRveo?rel=0" frameborder="0" allowfullscreen></iframe> - -For circuit schematics and datasheets for the components on the skin see :ref:`hardware_index`. - -Example code ------------- - -The AMP skin has a speaker which is connected to ``DAC(1)`` via a small -power amplifier. The volume of the amplifier is controlled by a digital -potentiometer, which is an I2C device with address 46 on the ``IC2(1)`` bus. - -To set the volume, define the following function:: - - import pyb - def volume(val): - pyb.I2C(1, pyb.I2C.MASTER).mem_write(val, 46, 0) - -Then you can do:: - - >>> volume(0) # minimum volume - >>> volume(127) # maximum volume - -To play a sound, use the ``write_timed`` method of the ``DAC`` object. -For example:: - - import math - from pyb import DAC - - # create a buffer containing a sine-wave - buf = bytearray(100) - for i in range(len(buf)): - buf[i] = 128 + int(127 * math.sin(2 * math.pi * i / len(buf))) - - # output the sine-wave at 400Hz - dac = DAC(1) - dac.write_timed(buf, 400 * len(buf), mode=DAC.CIRCULAR) - -You can also play WAV files using the Python ``wave`` module. You can get -the wave module `here <http://micropython.org/resources/examples/wave.py>`__ and you will also need -the chunk module available `here <http://micropython.org/resources/examples/chunk.py>`__. Put these -on your pyboard (either on the flash or the SD card in the top-level directory). You will need an -8-bit WAV file to play, such as `this one <http://micropython.org/resources/examples/test.wav>`_, -or to convert any file you have with the command:: - - avconv -i original.wav -ar 22050 -codec pcm_u8 test.wav - -Then you can do:: - - >>> import wave - >>> from pyb import DAC - >>> dac = DAC(1) - >>> f = wave.open('test.wav') - >>> dac.write_timed(f.readframes(f.getnframes()), f.getframerate()) - -This should play the WAV file. Note that this will read the whole file into RAM -so it has to be small enough to fit in it. - -To play larger wave files you will have to use the micro-SD card to store it. -Also the file must be read and sent to the DAC in small chunks that will fit -the RAM limit of the microcontroller. Here is an example function that can -play 8-bit wave files with up to 16kHz sampling:: - - import wave - from pyb import DAC - from pyb import delay - dac = DAC(1) - - def play(filename): - f = wave.open(filename, 'r') - total_frames = f.getnframes() - framerate = f.getframerate() - - for position in range(0, total_frames, framerate): - f.setpos(position) - dac.write_timed(f.readframes(framerate), framerate) - delay(1000) - -This function reads one second worth of data and sends it to DAC. It then waits -one second and moves the file cursor to the new position to read the next second -of data in the next iteration of the for-loop. It plays one second of audio at -a time every one second. diff --git a/docs/pyboard/tutorial/assembler.rst b/docs/pyboard/tutorial/assembler.rst deleted file mode 100644 index 1fe2bc4b0..000000000 --- a/docs/pyboard/tutorial/assembler.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. _pyboard_tutorial_assembler: - -Inline assembler -================ - -Here you will learn how to write inline assembler in MicroPython. - -**Note**: this is an advanced tutorial, intended for those who already -know a bit about microcontrollers and assembly language. - -MicroPython includes an inline assembler. It allows you to write -assembly routines as a Python function, and you can call them as you would -a normal Python function. - -Returning a value ------------------ - -Inline assembler functions are denoted by a special function decorator. -Let's start with the simplest example:: - - @micropython.asm_thumb - def fun(): - movw(r0, 42) - -You can enter this in a script or at the REPL. This function takes no -arguments and returns the number 42. ``r0`` is a register, and the value -in this register when the function returns is the value that is returned. -MicroPython always interprets the ``r0`` as an integer, and converts it to an -integer object for the caller. - -If you run ``print(fun())`` you will see it print out 42. - -Accessing peripherals ---------------------- - -For something a bit more complicated, let's turn on an LED:: - - @micropython.asm_thumb - def led_on(): - movwt(r0, stm.GPIOA) - movw(r1, 1 << 13) - strh(r1, [r0, stm.GPIO_BSRRL]) - -This code uses a few new concepts: - - - ``stm`` is a module which provides a set of constants for easy - access to the registers of the pyboard's microcontroller. Try - running ``import stm`` and then ``help(stm)`` at the REPL. It will - give you a list of all the available constants. - - - ``stm.GPIOA`` is the address in memory of the GPIOA peripheral. - On the pyboard, the red LED is on port A, pin PA13. - - - ``movwt`` moves a 32-bit number into a register. It is a convenience - function that turns into 2 thumb instructions: ``movw`` followed by ``movt``. - The ``movt`` also shifts the immediate value right by 16 bits. - - - ``strh`` stores a half-word (16 bits). The instruction above stores - the lower 16-bits of ``r1`` into the memory location ``r0 + stm.GPIO_BSRRL``. - This has the effect of setting high all those pins on port A for which - the corresponding bit in ``r0`` is set. In our example above, the 13th - bit in ``r0`` is set, so PA13 is pulled high. This turns on the red LED. - -Accepting arguments -------------------- - -Inline assembler functions can accept up to 4 arguments. If they are -used, they must be named ``r0``, ``r1``, ``r2`` and ``r3`` to reflect the registers -and the calling conventions. - -Here is a function that adds its arguments:: - - @micropython.asm_thumb - def asm_add(r0, r1): - add(r0, r0, r1) - -This performs the computation ``r0 = r0 + r1``. Since the result is put -in ``r0``, that is what is returned. Try ``asm_add(1, 2)``, it should return -3. - -Loops ------ - -We can assign labels with ``label(my_label)``, and branch to them using -``b(my_label)``, or a conditional branch like ``bgt(my_label)``. - -The following example flashes the green LED. It flashes it ``r0`` times. :: - - @micropython.asm_thumb - def flash_led(r0): - # get the GPIOA address in r1 - movwt(r1, stm.GPIOA) - - # get the bit mask for PA14 (the pin LED #2 is on) - movw(r2, 1 << 14) - - b(loop_entry) - - label(loop1) - - # turn LED on - strh(r2, [r1, stm.GPIO_BSRRL]) - - # delay for a bit - movwt(r4, 5599900) - label(delay_on) - sub(r4, r4, 1) - cmp(r4, 0) - bgt(delay_on) - - # turn LED off - strh(r2, [r1, stm.GPIO_BSRRH]) - - # delay for a bit - movwt(r4, 5599900) - label(delay_off) - sub(r4, r4, 1) - cmp(r4, 0) - bgt(delay_off) - - # loop r0 times - sub(r0, r0, 1) - label(loop_entry) - cmp(r0, 0) - bgt(loop1) - -Further reading ---------------- - -For further information about supported instructions of the inline assembler, -see the :ref:`reference documentation <asm_thumb2_index>`. diff --git a/docs/pyboard/tutorial/debounce.rst b/docs/pyboard/tutorial/debounce.rst deleted file mode 100644 index f730e1d34..000000000 --- a/docs/pyboard/tutorial/debounce.rst +++ /dev/null @@ -1,37 +0,0 @@ -Debouncing a pin input -====================== - -A pin used as input from a switch or other mechanical device can have a lot -of noise on it, rapidly changing from low to high when the switch is first -pressed or released. This noise can be eliminated using a capacitor (a -debouncing circuit). It can also be eliminated using a simple function that -makes sure the value on the pin is stable. - -The following function does just this. It gets the current value of the given -pin, and then waits for the value to change. The new pin value must be stable -for a continuous 20ms for it to register the change. You can adjust this time -(to say 50ms) if you still have noise. :: - - import pyb - - def wait_pin_change(pin): - # wait for pin to change value - # it needs to be stable for a continuous 20ms - cur_value = pin.value() - active = 0 - while active < 20: - if pin.value() != cur_value: - active += 1 - else: - active = 0 - pyb.delay(1) - - -Use it something like this:: - - import pyb - - pin_x1 = pyb.Pin('X1', pyb.Pin.IN, pyb.Pin.PULL_DOWN) - while True: - wait_pin_change(pin_x1) - pyb.LED(4).toggle() diff --git a/docs/pyboard/tutorial/fading_led.rst b/docs/pyboard/tutorial/fading_led.rst deleted file mode 100644 index 0a4b5c503..000000000 --- a/docs/pyboard/tutorial/fading_led.rst +++ /dev/null @@ -1,89 +0,0 @@ -Fading LEDs -=========== - -In addition to turning LEDs on and off, it is also possible to control the brightness of an LED using `Pulse-Width Modulation (PWM) <http://en.wikipedia.org/wiki/Pulse-width_modulation>`_, a common technique for obtaining variable output from a digital pin. This allows us to fade an LED: - -.. image:: http://upload.wikimedia.org/wikipedia/commons/a/a9/Fade.gif - -Components ----------- - -You will need: - -- Standard 5 or 3 mm LED -- 100 Ohm resistor -- Wires -- `Breadboard <http://en.wikipedia.org/wiki/Breadboard>`_ (optional, but makes things easier) - -Connecting Things Up --------------------- - -For this tutorial, we will use the ``X1`` pin. Connect one end of the resistor to ``X1``, and the other end to the **anode** of the LED, which is the longer leg. Connect the **cathode** of the LED to ground. - -.. image:: img/fading_leds_breadboard_fritzing.png - -Code ----- -By examining the :ref:`quickref`, we see that ``X1`` is connected to channel 1 of timer 5 (``TIM5 CH1``). Therefore we will first create a ``Timer`` object for timer 5, then create a ``TimerChannel`` object for channel 1:: - - from pyb import Timer - from time import sleep - - # timer 5 will be created with a frequency of 100 Hz - tim = pyb.Timer(5, freq=100) - tchannel = tim.channel(1, Timer.PWM, pin=pyb.Pin.board.X1, pulse_width=0) - -Brightness of the LED in PWM is controlled by controlling the pulse-width, that is the amount of time the LED is on every cycle. With a timer frequency of 100 Hz, each cycle takes 0.01 second, or 10 ms. - -To achieve the fading effect shown at the beginning of this tutorial, we want to set the pulse-width to a small value, then slowly increase the pulse-width to brighten the LED, and start over when we reach some maximum brightness:: - - # maximum and minimum pulse-width, which corresponds to maximum - # and minimum brightness - max_width = 200000 - min_width = 20000 - - # how much to change the pulse-width by each step - wstep = 1500 - cur_width = min_width - - while True: - tchannel.pulse_width(cur_width) - - # this determines how often we change the pulse-width. It is - # analogous to frames-per-second - sleep(0.01) - - cur_width += wstep - - if cur_width > max_width: - cur_width = min_width - -Breathing Effect ----------------- - -If we want to have a breathing effect, where the LED fades from dim to bright then bright to dim, then we simply need to reverse the sign of ``wstep`` when we reach maximum brightness, and reverse it again at minimum brightness. To do this we modify the ``while`` loop to be:: - - while True: - tchannel.pulse_width(cur_width) - - sleep(0.01) - - cur_width += wstep - - if cur_width > max_width: - cur_width = max_width - wstep *= -1 - elif cur_width < min_width: - cur_width = min_width - wstep *= -1 - -Advanced Exercise ------------------ - -You may have noticed that the LED brightness seems to fade slowly, but increases quickly. This is because our eyes interprets brightness logarithmically (`Weber's Law <http://www.telescope-optics.net/eye_intensity_response.htm>`_ -), while the LED's brightness changes linearly, that is by the same amount each time. How do you solve this problem? (Hint: what is the opposite of the logarithmic function?) - -Addendum --------- - -We could have also used the digital-to-analog converter (DAC) to achieve the same effect. The PWM method has the advantage that it drives the LED with the same current each time, but for different lengths of time. This allows better control over the brightness, because LEDs do not necessarily exhibit a linear relationship between the driving current and brightness. diff --git a/docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png b/docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png Binary files differdeleted file mode 100644 index a8eec4eb6..000000000 --- a/docs/pyboard/tutorial/img/fading_leds_breadboard_fritzing.png +++ /dev/null diff --git a/docs/pyboard/tutorial/img/pyboard_servo.jpg b/docs/pyboard/tutorial/img/pyboard_servo.jpg Binary files differdeleted file mode 100644 index 0d64e46c4..000000000 --- a/docs/pyboard/tutorial/img/pyboard_servo.jpg +++ /dev/null diff --git a/docs/pyboard/tutorial/img/pyboard_usb_micro.jpg b/docs/pyboard/tutorial/img/pyboard_usb_micro.jpg Binary files differdeleted file mode 100644 index bc1c2b832..000000000 --- a/docs/pyboard/tutorial/img/pyboard_usb_micro.jpg +++ /dev/null diff --git a/docs/pyboard/tutorial/img/skin_amp_1.jpg b/docs/pyboard/tutorial/img/skin_amp_1.jpg Binary files differdeleted file mode 100644 index df4446008..000000000 --- a/docs/pyboard/tutorial/img/skin_amp_1.jpg +++ /dev/null diff --git a/docs/pyboard/tutorial/img/skin_amp_2.jpg b/docs/pyboard/tutorial/img/skin_amp_2.jpg Binary files differdeleted file mode 100644 index 7631b3b63..000000000 --- a/docs/pyboard/tutorial/img/skin_amp_2.jpg +++ /dev/null diff --git a/docs/pyboard/tutorial/img/skin_lcd_1.jpg b/docs/pyboard/tutorial/img/skin_lcd_1.jpg Binary files differdeleted file mode 100644 index 1dda73ffd..000000000 --- a/docs/pyboard/tutorial/img/skin_lcd_1.jpg +++ /dev/null diff --git a/docs/pyboard/tutorial/img/skin_lcd_2.jpg b/docs/pyboard/tutorial/img/skin_lcd_2.jpg Binary files differdeleted file mode 100644 index 6e3e1033e..000000000 --- a/docs/pyboard/tutorial/img/skin_lcd_2.jpg +++ /dev/null diff --git a/docs/pyboard/tutorial/index.rst b/docs/pyboard/tutorial/index.rst deleted file mode 100644 index 1dc155f14..000000000 --- a/docs/pyboard/tutorial/index.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _tutorial-index: - -MicroPython tutorial for the pyboard -==================================== - -This tutorial is intended to get you started with your pyboard. -All you need is a pyboard and a micro-USB cable to connect it to -your PC. If it is your first time, it is recommended to follow -the tutorial through in the order below. - -.. toctree:: - :maxdepth: 1 - :numbered: - - intro.rst - script.rst - repl.rst - leds.rst - switch.rst - accel.rst - reset.rst - usb_mouse.rst - timer.rst - assembler.rst - power_ctrl.rst - -Tutorials requiring extra components ------------------------------------- - -.. toctree:: - :maxdepth: 1 - :numbered: - - servo.rst - fading_led.rst - lcd_skin.rst - amp_skin.rst - lcd160cr_skin.rst - -Tips, tricks and useful things to know --------------------------------------- - -.. toctree:: - :maxdepth: 1 - :numbered: - - debounce.rst - pass_through.rst diff --git a/docs/pyboard/tutorial/intro.rst b/docs/pyboard/tutorial/intro.rst deleted file mode 100644 index 78343db59..000000000 --- a/docs/pyboard/tutorial/intro.rst +++ /dev/null @@ -1,54 +0,0 @@ -Introduction to the pyboard -=========================== - -To get the most out of your pyboard, there are a few basic things to -understand about how it works. - -Caring for your pyboard ------------------------ - -Because the pyboard does not have a housing it needs a bit of care: - - - Be gentle when plugging/unplugging the USB cable. Whilst the USB connector - is soldered through the board and is relatively strong, if it breaks off - it can be very difficult to fix. - - - Static electricity can shock the components on the pyboard and destroy them. - If you experience a lot of static electricity in your area (eg dry and cold - climates), take extra care not to shock the pyboard. If your pyboard came - in a black plastic box, then this box is the best way to store and carry the - pyboard as it is an anti-static box (it is made of a conductive plastic, with - conductive foam inside). - -As long as you take care of the hardware, you should be okay. It's almost -impossible to break the software on the pyboard, so feel free to play around -with writing code as much as you like. If the filesystem gets corrupt, see -below on how to reset it. In the worst case you might need to reflash the -MicroPython software, but that can be done over USB. - -Layout of the pyboard ---------------------- - -The micro USB connector is on the top right, the micro SD card slot on -the top left of the board. There are 4 LEDs between the SD slot and -USB connector. The colours are: red on the bottom, then green, orange, -and blue on the top. There are 2 switches: the right one is the reset -switch, the left is the user switch. - -Plugging in and powering on ---------------------------- - -The pyboard can be powered via USB. Connect it to your PC via a micro USB -cable. There is only one way that the cable will fit. Once connected, -the green LED on the board should flash quickly. - -Powering by an external power source ------------------------------------- - -The pyboard can be powered by a battery or other external power source. - -**Be sure to connect the positive lead of the power supply to VIN, and -ground to GND. There is no polarity protection on the pyboard so you -must be careful when connecting anything to VIN.** - -**The input voltage must be between 3.6V and 10V.** diff --git a/docs/pyboard/tutorial/lcd160cr_skin.rst b/docs/pyboard/tutorial/lcd160cr_skin.rst deleted file mode 100644 index fc9d63538..000000000 --- a/docs/pyboard/tutorial/lcd160cr_skin.rst +++ /dev/null @@ -1,134 +0,0 @@ -The LCD160CR skin -================= - -This tutorial shows how to get started using the LCD160CR skin. - -.. image:: http://micropython.org/resources/LCD160CRv10-positions.jpg - :alt: LCD160CRv1.0 picture - :width: 800px - -For detailed documentation of the driver for the display see the -:mod:`lcd160cr` module. - -Plugging in the display ------------------------ - -The display can be plugged directly into a pyboard (all pyboard versions -are supported). You plug the display onto the top of the pyboard either -in the X or Y positions. The display should cover half of the pyboard. -See the picture above for how to achieve this; the left half of the picture -shows the X position, and the right half shows the Y position. - -Getting the driver ------------------- - -You can control the display directly using a power/enable pin and an I2C -bus, but it is much more convenient to use the driver provided by the -:mod:`lcd160cr` module. This driver is included in recent version of the -pyboard firmware (see `here <http://micropython.org/download>`__). You -can also find the driver in the GitHub repository -`here <https://github.com/micropython/micropython/blob/master/drivers/display/lcd160cr.py>`__, and to use this version you will need to copy the file to your -board, into a directory that is searched by import (usually the lib/ -directory). - -Once you have the driver installed you need to import it to use it:: - - import lcd160cr - -Testing the display -------------------- - -There is a test program which you can use to test the features of the display, -and which also serves as a basis to start creating your own code that uses the -LCD. This test program is included in recent versions of the pyboard firmware -and is also available on GitHub -`here <https://github.com/micropython/micropython/blob/master/drivers/display/lcd160cr_test.py>`__. - -To run the test from the MicroPython prompt do:: - - >>> import lcd160cr_test - -It will then print some brief instructions. You will need to know which -position your display is connected to (X or Y) and then you can run (assuming -you have the display on position X):: - - >>> test_all('X') - -Drawing some graphics ---------------------- - -You must first create an LCD160CR object which will control the display. Do this -using:: - - >>> import lcd160cr - >>> lcd = lcd160cr.LCD160CR('X') - -This assumes your display is connected in the X position. If it's in the Y -position then use ``lcd = lcd160cr.LCD160CR('Y')`` instead. - -To erase the screen and draw a line, try:: - - >>> lcd.set_pen(lcd.rgb(255, 0, 0), lcd.rgb(64, 64, 128)) - >>> lcd.erase() - >>> lcd.line(10, 10, 50, 80) - -The next example draws random rectangles on the screen. You can copy-and-paste it -into the MicroPython prompt by first pressing "Ctrl-E" at the prompt, then "Ctrl-D" -once you have pasted the text. :: - - from random import randint - for i in range(1000): - fg = lcd.rgb(randint(128, 255), randint(128, 255), randint(128, 255)) - bg = lcd.rgb(randint(0, 128), randint(0, 128), randint(0, 128)) - lcd.set_pen(fg, bg) - lcd.rect(randint(0, lcd.w), randint(0, lcd.h), randint(10, 40), randint(10, 40)) - -Using the touch sensor ----------------------- - -The display includes a resistive touch sensor that can report the position (in -pixels) of a single force-based touch on the screen. To see if there is a touch -on the screen use:: - - >>> lcd.is_touched() - -This will return either ``False`` or ``True``. Run the above command while touching -the screen to see the result. - -To get the location of the touch you can use the method:: - - >>> lcd.get_touch() - -This will return a 3-tuple, with the first entry being 0 or 1 depending on whether -there is currently anything touching the screen (1 if there is), and the second and -third entries in the tuple being the x and y coordinates of the current (or most -recent) touch. - -Directing the MicroPython output to the display ------------------------------------------------ - -The display supports input from a UART and implements basic VT100 commands, which -means it can be used as a simple, general purpose terminal. Let's set up the -pyboard to redirect its output to the display. - -First you need to create a UART object:: - - >>> import pyb - >>> uart = pyb.UART('XA', 115200) - -This assumes your display is connected to position X. If it's on position Y then -use ``uart = pyb.UART('YA', 115200)`` instead. - -Now, connect the REPL output to this UART:: - - >>> pyb.repl_uart(uart) - -From now on anything you type at the MicroPython prompt, and any output you -receive, will appear on the display. - -No set-up commands are required for this mode to work and you can use the display -to monitor the output of any UART, not just from the pyboard. All that is needed -is for the display to have power, ground and the power/enable pin driven high. -Then any characters on the display's UART input will be printed to the screen. -You can adjust the UART baudrate from the default of 115200 using the -`set_uart_baudrate` method. diff --git a/docs/pyboard/tutorial/lcd_skin.rst b/docs/pyboard/tutorial/lcd_skin.rst deleted file mode 100644 index 288ac1bf0..000000000 --- a/docs/pyboard/tutorial/lcd_skin.rst +++ /dev/null @@ -1,86 +0,0 @@ -The LCD and touch-sensor skin -============================= - -Soldering and using the LCD and touch-sensor skin. - -.. image:: img/skin_lcd_1.jpg - :alt: pyboard with LCD skin - :width: 250px - -.. image:: img/skin_lcd_2.jpg - :alt: pyboard with LCD skin - :width: 250px - -The following video shows how to solder the headers onto the LCD skin. -At the end of the video, it shows you how to correctly connect the LCD skin to the pyboard. - -.. raw:: html - - <iframe style="margin-left:3em;" width="560" height="315" src="http://www.youtube.com/embed/PowCzdLYbFM?rel=0" frameborder="0" allowfullscreen></iframe> - -For circuit schematics and datasheets for the components on the skin see :ref:`hardware_index`. - -Using the LCD -------------- - -To get started using the LCD, try the following at the MicroPython prompt. -Make sure the LCD skin is attached to the pyboard as pictured at the top of this page. :: - - >>> import pyb - >>> lcd = pyb.LCD('X') - >>> lcd.light(True) - >>> lcd.write('Hello uPy!\n') - -You can make a simple animation using the code:: - - import pyb - lcd = pyb.LCD('X') - lcd.light(True) - for x in range(-80, 128): - lcd.fill(0) - lcd.text('Hello uPy!', x, 10, 1) - lcd.show() - pyb.delay(25) - -Using the touch sensor ----------------------- - -To read the touch-sensor data you need to use the I2C bus. The -MPR121 capacitive touch sensor has address 90. - -To get started, try:: - - >>> import pyb - >>> i2c = pyb.I2C(1, pyb.I2C.MASTER) - >>> i2c.mem_write(4, 90, 0x5e) - >>> touch = i2c.mem_read(1, 90, 0)[0] - -The first line above makes an I2C object, and the second line -enables the 4 touch sensors. The third line reads the touch -status and the ``touch`` variable holds the state of the 4 touch -buttons (A, B, X, Y). - -There is a simple driver `here <http://micropython.org/resources/examples/mpr121.py>`__ -which allows you to set the threshold and debounce parameters, and -easily read the touch status and electrode voltage levels. Copy -this script to your pyboard (either flash or SD card, in the top -directory or ``lib/`` directory) and then try:: - - >>> import pyb - >>> import mpr121 - >>> m = mpr121.MPR121(pyb.I2C(1, pyb.I2C.MASTER)) - >>> for i in range(100): - ... print(m.touch_status()) - ... pyb.delay(100) - ... - -This will continuously print out the touch status of all electrodes. -Try touching each one in turn. - -Note that if you put the LCD skin in the Y-position, then you need to -initialise the I2C bus using:: - - >>> m = mpr121.MPR121(pyb.I2C(2, pyb.I2C.MASTER)) - -There is also a demo which uses the LCD and the touch sensors together, -and can be found `here <http://micropython.org/resources/examples/lcddemo.py>`__. diff --git a/docs/pyboard/tutorial/leds.rst b/docs/pyboard/tutorial/leds.rst deleted file mode 100644 index 6b05f5db0..000000000 --- a/docs/pyboard/tutorial/leds.rst +++ /dev/null @@ -1,75 +0,0 @@ -Turning on LEDs and basic Python concepts -========================================= - -The easiest thing to do on the pyboard is to turn on the LEDs attached to the board. Connect the board, and log in as described in tutorial 1. We will start by turning and LED on in the interpreter, type the following :: - - >>> myled = pyb.LED(1) - >>> myled.on() - >>> myled.off() - -These commands turn the LED on and off. - -This is all very well but we would like this process to be automated. Open the file MAIN.PY on the pyboard in your favourite text editor. Write or paste the following lines into the file. If you are new to python, then make sure you get the indentation correct since this matters! :: - - led = pyb.LED(2) - while True: - led.toggle() - pyb.delay(1000) - -When you save, the red light on the pyboard should turn on for about a second. To run the script, do a soft reset (CTRL-D). The pyboard will then restart and you should see a green light continuously flashing on and off. Success, the first step on your path to building an army of evil robots! When you are bored of the annoying flashing light then press CTRL-C at your terminal to stop it running. - -So what does this code do? First we need some terminology. Python is an object-oriented language, almost everything in python is a *class* and when you create an instance of a class you get an *object*. Classes have *methods* associated to them. A method (also called a member function) is used to interact with or control the object. - -The first line of code creates an LED object which we have then called led. When we create the object, it takes a single parameter which must be between 1 and 4, corresponding to the 4 LEDs on the board. The pyb.LED class has three important member functions that we will use: on(), off() and toggle(). The other function that we use is pyb.delay() this simply waits for a given time in miliseconds. Once we have created the LED object, the statement while True: creates an infinite loop which toggles the led between on and off and waits for 1 second. - -**Exercise: Try changing the time between toggling the led and turning on a different LED.** - -**Exercise: Connect to the pyboard directly, create a pyb.LED object and turn it on using the on() method.** - -A Disco on your pyboard ------------------------ - -So far we have only used a single LED but the pyboard has 4 available. Let's start by creating an object for each LED so we can control each of them. We do that by creating a list of LEDS with a list comprehension. :: - - leds = [pyb.LED(i) for i in range(1,5)] - -If you call pyb.LED() with a number that isn't 1,2,3,4 you will get an error message. -Next we will set up an infinite loop that cycles through each of the LEDs turning them on and off. :: - - n = 0 - while True: - n = (n + 1) % 4 - leds[n].toggle() - pyb.delay(50) - -Here, n keeps track of the current LED and every time the loop is executed we cycle to the next n (the % sign is a modulus operator that keeps n between 0 and 3.) Then we access the nth LED and toggle it. If you run this you should see each of the LEDs turning on then all turning off again in sequence. - -One problem you might find is that if you stop the script and then start it again that the LEDs are stuck on from the previous run, ruining our carefully choreographed disco. We can fix this by turning all the LEDs off when we initialise the script and then using a try/finally block. When you press CTRL-C, MicroPython generates a VCPInterrupt exception. Exceptions normally mean something has gone wrong and you can use a try: command to "catch" an exception. In this case it is just the user interrupting the script, so we don't need to catch the error but just tell MicroPython what to do when we exit. The finally block does this, and we use it to make sure all the LEDs are off. The full code is:: - - leds = [pyb.LED(i) for i in range(1,5)] - for l in leds: - l.off() - - n = 0 - try: - while True: - n = (n + 1) % 4 - leds[n].toggle() - pyb.delay(50) - finally: - for l in leds: - l.off() - -The Special LEDs ----------------- - -The yellow and blue LEDs are special. As well as turning them on and off, you can control their intensity using the intensity() method. This takes a number between 0 and 255 that determines how bright it is. The following script makes the blue LED gradually brighter then turns it off again. :: - - led = pyb.LED(4) - intensity = 0 - while True: - intensity = (intensity + 1) % 255 - led.intensity(intensity) - pyb.delay(20) - -You can call intensity() on LEDs 1 and 2 but they can only be off or on. 0 sets them off and any other number up to 255 turns them on. diff --git a/docs/pyboard/tutorial/pass_through.rst b/docs/pyboard/tutorial/pass_through.rst deleted file mode 100644 index 012a90764..000000000 --- a/docs/pyboard/tutorial/pass_through.rst +++ /dev/null @@ -1,18 +0,0 @@ -Making a UART - USB pass through -================================ - -It's as simple as:: - - import pyb - import select - - def pass_through(usb, uart): - usb.setinterrupt(-1) - while True: - select.select([usb, uart], [], []) - if usb.any(): - uart.write(usb.read(256)) - if uart.any(): - usb.write(uart.read(256)) - - pass_through(pyb.USB_VCP(), pyb.UART(1, 9600, timeout=0)) diff --git a/docs/pyboard/tutorial/power_ctrl.rst b/docs/pyboard/tutorial/power_ctrl.rst deleted file mode 100644 index 877b7cd7e..000000000 --- a/docs/pyboard/tutorial/power_ctrl.rst +++ /dev/null @@ -1,13 +0,0 @@ -Power control -============= - -:meth:`pyb.wfi` is used to reduce power consumption while waiting for an -event such as an interrupt. You would use it in the following situation:: - - while True: - do_some_processing() - pyb.wfi() - -Control the frequency using :meth:`pyb.freq`:: - - pyb.freq(30000000) # set CPU frequency to 30MHz diff --git a/docs/pyboard/tutorial/repl.rst b/docs/pyboard/tutorial/repl.rst deleted file mode 100644 index 646ecbc23..000000000 --- a/docs/pyboard/tutorial/repl.rst +++ /dev/null @@ -1,110 +0,0 @@ -Getting a MicroPython REPL prompt -================================= - -REPL stands for Read Evaluate Print Loop, and is the name given to the -interactive MicroPython prompt that you can access on the pyboard. Using -the REPL is by far the easiest way to test out your code and run commands. -You can use the REPL in addition to writing scripts in ``main.py``. - -To use the REPL, you must connect to the serial USB device on the pyboard. -How you do this depends on your operating system. - -Windows -------- - -You need to install the pyboard driver to use the serial USB device. -The driver is on the pyboard's USB flash drive, and is called ``pybcdc.inf``. - -To install this driver you need to go to Device Manager -for your computer, find the pyboard in the list of devices (it should have -a warning sign next to it because it's not working yet), right click on -the pyboard device, select Properties, then Install Driver. You need to -then select the option to find the driver manually (don't use Windows auto update), -navigate to the pyboard's USB drive, and select that. It should then install. -After installing, go back to the Device Manager to find the installed pyboard, -and see which COM port it is (eg COM4). -More comprehensive instructions can be found in the -`Guide for pyboard on Windows (PDF) <http://micropython.org/resources/Micro-Python-Windows-setup.pdf>`_. -Please consult this guide if you are having problems installing the driver. - -You now need to run your terminal program. You can use HyperTerminal if you -have it installed, or download the free program PuTTY: -`putty.exe <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_. -Using your serial program you must connect to the COM port that you found in the -previous step. With PuTTY, click on "Session" in the left-hand panel, then click -the "Serial" radio button on the right, then enter you COM port (eg COM4) in the -"Serial Line" box. Finally, click the "Open" button. - -Mac OS X --------- - -Open a terminal and run:: - - screen /dev/tty.usbmodem* - -When you are finished and want to exit screen, type CTRL-A CTRL-\\. - -Linux ------ - -Open a terminal and run:: - - screen /dev/ttyACM0 - -You can also try ``picocom`` or ``minicom`` instead of screen. You may have to -use ``/dev/ttyACM1`` or a higher number for ``ttyACM``. And, you may need to give -yourself the correct permissions to access this devices (eg group ``uucp`` or ``dialout``, -or use sudo). - -Using the REPL prompt ---------------------- - -Now let's try running some MicroPython code directly on the pyboard. - -With your serial program open (PuTTY, screen, picocom, etc) you may see a blank -screen with a flashing cursor. Press Enter and you should be presented with a -MicroPython prompt, i.e. ``>>>``. Let's make sure it is working with the obligatory test:: - - >>> print("hello pyboard!") - hello pyboard! - -In the above, you should not type in the ``>>>`` characters. They are there to -indicate that you should type the text after it at the prompt. In the end, once -you have entered the text ``print("hello pyboard!")`` and pressed Enter, the output -on your screen should look like it does above. - -If you already know some python you can now try some basic commands here. - -If any of this is not working you can try either a hard reset or a soft reset; -see below. - -Go ahead and try typing in some other commands. For example:: - - >>> pyb.LED(1).on() - >>> pyb.LED(2).on() - >>> 1 + 2 - 3 - >>> 1 / 2 - 0.5 - >>> 20 * 'py' - 'pypypypypypypypypypypypypypypypypypypypy' - -Resetting the board -------------------- - -If something goes wrong, you can reset the board in two ways. The first is to press CTRL-D -at the MicroPython prompt, which performs a soft reset. You will see a message something like :: - - >>> - PYB: sync filesystems - PYB: soft reboot - Micro Python v1.0 on 2014-05-03; PYBv1.0 with STM32F405RG - Type "help()" for more information. - >>> - -If that isn't working you can perform a hard reset (turn-it-off-and-on-again) by pressing the RST -switch (the small black button closest to the micro-USB socket on the board). This will end your -session, disconnecting whatever program (PuTTY, screen, etc) that you used to connect to the pyboard. - -If you are going to do a hard-reset, it's recommended to first close your serial program and eject/unmount -the pyboard drive. diff --git a/docs/pyboard/tutorial/reset.rst b/docs/pyboard/tutorial/reset.rst deleted file mode 100644 index 0cd5ac21c..000000000 --- a/docs/pyboard/tutorial/reset.rst +++ /dev/null @@ -1,60 +0,0 @@ -Safe mode and factory reset -=========================== - -If something goes wrong with your pyboard, don't panic! It is almost -impossible for you to break the pyboard by programming the wrong thing. - -The first thing to try is to enter safe mode: this temporarily skips -execution of ``boot.py`` and ``main.py`` and gives default USB settings. - -If you have problems with the filesystem you can do a factory reset, -which restores the filesystem to its original state. - -Safe mode ---------- - -To enter safe mode, do the following steps: - -1. Connect the pyboard to USB so it powers up. -2. Hold down the USR switch. -3. While still holding down USR, press and release the RST switch. -4. The LEDs will then cycle green to orange to green+orange and back again. -5. Keep holding down USR until *only the orange LED is lit*, and then let - go of the USR switch. -6. The orange LED should flash quickly 4 times, and then turn off. -7. You are now in safe mode. - -In safe mode, the ``boot.py`` and ``main.py`` files are not executed, and so -the pyboard boots up with default settings. This means you now have access -to the filesystem (the USB drive should appear), and you can edit ``boot.py`` -and ``main.py`` to fix any problems. - -Entering safe mode is temporary, and does not make any changes to the -files on the pyboard. - -Factory reset the filesystem ----------------------------- - -If you pyboard's filesystem gets corrupted (for example, you forgot to -eject/unmount it), or you have some code in ``boot.py`` or ``main.py`` which -you can't escape from, then you can reset the filesystem. - -Resetting the filesystem deletes all files on the internal pyboard storage -(not the SD card), and restores the files ``boot.py``, ``main.py``, ``README.txt`` -and ``pybcdc.inf`` back to their original state. - -To do a factory reset of the filesystem you follow a similar procedure as -you did to enter safe mode, but release USR on green+orange: - -1. Connect the pyboard to USB so it powers up. -2. Hold down the USR switch. -3. While still holding down USR, press and release the RST switch. -4. The LEDs will then cycle green to orange to green+orange and back again. -5. Keep holding down USR until *both the green and orange LEDs are lit*, and - then let go of the USR switch. -6. The green and orange LEDs should flash quickly 4 times. -7. The red LED will turn on (so red, green and orange are now on). -8. The pyboard is now resetting the filesystem (this takes a few seconds). -9. The LEDs all turn off. -10. You now have a reset filesystem, and are in safe mode. -11. Press and release the RST switch to boot normally. diff --git a/docs/pyboard/tutorial/script.rst b/docs/pyboard/tutorial/script.rst deleted file mode 100644 index 75dd324e3..000000000 --- a/docs/pyboard/tutorial/script.rst +++ /dev/null @@ -1,105 +0,0 @@ -Running your first script -========================= - -Let's jump right in and get a Python script running on the pyboard. After -all, that's what it's all about! - -Connecting your pyboard ------------------------ - -Connect your pyboard to your PC (Windows, Mac or Linux) with a micro USB cable. -There is only one way that the cable will connect, so you can't get it wrong. - -.. image:: img/pyboard_usb_micro.jpg - -When the pyboard is connected to your PC it will power on and enter the start up -process (the boot process). The green LED should light up for half a second or -less, and when it turns off it means the boot process has completed. - -Opening the pyboard USB drive ------------------------------ - -Your PC should now recognise the pyboard. It depends on the type of PC you -have as to what happens next: - - - **Windows**: Your pyboard will appear as a removable USB flash drive. - Windows may automatically pop-up a window, or you may need to go there - using Explorer. - - Windows will also see that the pyboard has a serial device, and it will - try to automatically configure this device. If it does, cancel the process. - We will get the serial device working in the next tutorial. - - - **Mac**: Your pyboard will appear on the desktop as a removable disc. - It will probably be called "NONAME". Click on it to open the pyboard folder. - - - **Linux**: Your pyboard will appear as a removable medium. On Ubuntu - it will mount automatically and pop-up a window with the pyboard folder. - On other Linux distributions, the pyboard may be mounted automatically, - or you may need to do it manually. At a terminal command line, type ``lsblk`` - to see a list of connected drives, and then ``mount /dev/sdb1`` (replace ``sdb1`` - with the appropriate device). You may need to be root to do this. - -Okay, so you should now have the pyboard connected as a USB flash drive, and -a window (or command line) should be showing the files on the pyboard drive. - -The drive you are looking at is known as ``/flash`` by the pyboard, and should contain -the following 4 files: - -* `boot.py <http://micropython.org/resources/fresh-pyboard/boot.py>`_ -- this script is executed when the pyboard boots up. It sets - up various configuration options for the pyboard. - -* `main.py <http://micropython.org/resources/fresh-pyboard/main.py>`_ -- this is the main script that will contain your Python program. - It is executed after ``boot.py``. - -* `README.txt <http://micropython.org/resources/fresh-pyboard/README.txt>`_ -- this contains some very basic information about getting - started with the pyboard. - -* `pybcdc.inf <http://micropython.org/resources/fresh-pyboard/pybcdc.inf>`_ -- this is a Windows driver file to configure the serial USB - device. More about this in the next tutorial. - -Editing ``main.py`` -------------------- - -Now we are going to write our Python program, so open the ``main.py`` -file in a text editor. On Windows you can use notepad, or any other editor. -On Mac and Linux, use your favourite text editor. With the file open you will -see it contains 1 line:: - - # main.py -- put your code here! - -This line starts with a # character, which means that it is a *comment*. Such -lines will not do anything, and are there for you to write notes about your -program. - -Let's add 2 lines to this ``main.py`` file, to make it look like this:: - - # main.py -- put your code here! - import pyb - pyb.LED(4).on() - -The first line we wrote says that we want to use the ``pyb`` module. -This module contains all the functions and classes to control the features -of the pyboard. - -The second line that we wrote turns the blue LED on: it first gets the ``LED`` -class from the ``pyb`` module, creates LED number 4 (the blue LED), and then -turns it on. - -Resetting the pyboard ---------------------- - -To run this little script, you need to first save and close the ``main.py`` file, -and then eject (or unmount) the pyboard USB drive. Do this like you would a -normal USB flash drive. - -When the drive is safely ejected/unmounted you can get to the fun part: -press the RST switch on the pyboard to reset and run your script. The RST -switch is the small black button just below the USB connector on the board, -on the right edge. - -When you press RST the green LED will flash quickly, and then the blue -LED should turn on and stay on. - -Congratulations! You have written and run your very first MicroPython -program! diff --git a/docs/pyboard/tutorial/servo.rst b/docs/pyboard/tutorial/servo.rst deleted file mode 100644 index 83d1b0cc1..000000000 --- a/docs/pyboard/tutorial/servo.rst +++ /dev/null @@ -1,146 +0,0 @@ -Controlling hobby servo motors -============================== - -There are 4 dedicated connection points on the pyboard for connecting up -hobby servo motors (see eg -[Wikipedia](http://en.wikipedia.org/wiki/Servo_%28radio_control%29)). -These motors have 3 wires: ground, power and signal. On the pyboard you -can connect them in the bottom right corner, with the signal pin on the -far right. Pins X1, X2, X3 and X4 are the 4 dedicated servo signal pins. - -.. image:: img/pyboard_servo.jpg - -In this picture there are male-male double adaptors to connect the servos -to the header pins on the pyboard. - -The ground wire on a servo is usually the darkest coloured one, either -black or dark brown. The power wire will most likely be red. - -The power pin for the servos (labelled VIN) is connected directly to the -input power source of the pyboard. When powered via USB, VIN is powered -through a diode by the 5V USB power line. Connect to USB, the pyboard can -power at least 4 small to medium sized servo motors. - -If using a battery to power the pyboard and run servo motors, make sure it -is not greater than 6V, since this is the maximum voltage most servo motors -can take. (Some motors take only up to 4.8V, so check what type you are -using.) - -Creating a Servo object ------------------------ - -Plug in a servo to position 1 (the one with pin X1) and create a servo object -using:: - - >>> servo1 = pyb.Servo(1) - -To change the angle of the servo use the ``angle`` method:: - - >>> servo1.angle(45) - >>> servo1.angle(-60) - -The angle here is measured in degrees, and ranges from about -90 to +90, -depending on the motor. Calling ``angle`` without parameters will return -the current angle:: - - >>> servo1.angle() - -60 - -Note that for some angles, the returned angle is not exactly the same as -the angle you set, due to rounding errors in setting the pulse width. - -You can pass a second parameter to the ``angle`` method, which specifies how -long to take (in milliseconds) to reach the desired angle. For example, to -take 1 second (1000 milliseconds) to go from the current position to 50 degrees, -use :: - - >>> servo1.angle(50, 1000) - -This command will return straight away and the servo will continue to move -to the desired angle, and stop when it gets there. You can use this feature -as a speed control, or to synchronise 2 or more servo motors. If we have -another servo motor (``servo2 = pyb.Servo(2)``) then we can do :: - - >>> servo1.angle(-45, 2000); servo2.angle(60, 2000) - -This will move the servos together, making them both take 2 seconds to -reach their final angles. - -Note: the semicolon between the 2 expressions above is used so that they -are executed one after the other when you press enter at the REPL prompt. -In a script you don't need to do this, you can just write them one line -after the other. - -Continuous rotation servos --------------------------- - -So far we have been using standard servos that move to a specific angle -and stay at that angle. These servo motors are useful to create joints -of a robot, or things like pan-tilt mechanisms. Internally, the motor -has a variable resistor (potentiometer) which measures the current angle -and applies power to the motor proportional to how far it is from the -desired angle. The desired angle is set by the width of a high-pulse on -the servo signal wire. A pulse width of 1500 microsecond corresponds -to the centre position (0 degrees). The pulses are sent at 50 Hz, ie -50 pulses per second. - -You can also get **continuous rotation** servo motors which turn -continuously clockwise or counterclockwise. The direction and speed of -rotation is set by the pulse width on the signal wire. A pulse width -of 1500 microseconds corresponds to a stopped motor. A pulse width -smaller or larger than this means rotate one way or the other, at a -given speed. - -On the pyboard, the servo object for a continuous rotation motor is -the same as before. In fact, using ``angle`` you can set the speed. But -to make it easier to understand what is intended, there is another method -called ``speed`` which sets the speed:: - - >>> servo1.speed(30) - -``speed`` has the same functionality as ``angle``: you can get the speed, -set it, and set it with a time to reach the final speed. :: - - >>> servo1.speed() - 30 - >>> servo1.speed(-20) - >>> servo1.speed(0, 2000) - -The final command above will set the motor to stop, but take 2 seconds -to do it. This is essentially a control over the acceleration of the -continuous servo. - -A servo speed of 100 (or -100) is considered maximum speed, but actually -you can go a bit faster than that, depending on the particular motor. - -The only difference between the ``angle`` and ``speed`` methods (apart from -the name) is the way the input numbers (angle or speed) are converted to -a pulse width. - -Calibration ------------ - -The conversion from angle or speed to pulse width is done by the servo -object using its calibration values. To get the current calibration, -use :: - - >>> servo1.calibration() - (640, 2420, 1500, 2470, 2200) - -There are 5 numbers here, which have meaning: - -1. Minimum pulse width; the smallest pulse width that the servo accepts. -2. Maximum pulse width; the largest pulse width that the servo accepts. -3. Centre pulse width; the pulse width that puts the servo at 0 degrees - or 0 speed. -4. The pulse width corresponding to 90 degrees. This sets the conversion - in the method ``angle`` of angle to pulse width. -5. The pulse width corresponding to a speed of 100. This sets the conversion - in the method ``speed`` of speed to pulse width. - -You can recalibrate the servo (change its default values) by using:: - - >>> servo1.calibration(700, 2400, 1510, 2500, 2000) - -Of course, you would change the above values to suit your particular -servo motor. diff --git a/docs/pyboard/tutorial/switch.rst b/docs/pyboard/tutorial/switch.rst deleted file mode 100644 index 91683fba4..000000000 --- a/docs/pyboard/tutorial/switch.rst +++ /dev/null @@ -1,113 +0,0 @@ -The Switch, callbacks and interrupts -==================================== - -The pyboard has 2 small switches, labelled USR and RST. The RST switch -is a hard-reset switch, and if you press it then it restarts the pyboard -from scratch, equivalent to turning the power off then back on. - -The USR switch is for general use, and is controlled via a Switch object. -To make a switch object do:: - - >>> sw = pyb.Switch() - -Remember that you may need to type ``import pyb`` if you get an error that -the name ``pyb`` does not exist. - -With the switch object you can get its status:: - - >>> sw.value() - False - -This will print ``False`` if the switch is not held, or ``True`` if it is held. -Try holding the USR switch down while running the above command. - -There is also a shorthand notation to get the switch status, by "calling" the -switch object:: - - >>> sw() - False - -Switch callbacks ----------------- - -The switch is a very simple object, but it does have one advanced feature: -the ``sw.callback()`` function. The callback function sets up something to -run when the switch is pressed, and uses an interrupt. It's probably best -to start with an example before understanding how interrupts work. Try -running the following at the prompt:: - - >>> sw.callback(lambda:print('press!')) - -This tells the switch to print ``press!`` each time the switch is pressed -down. Go ahead and try it: press the USR switch and watch the output on -your PC. Note that this print will interrupt anything you are typing, and -is an example of an interrupt routine running asynchronously. - -As another example try:: - - >>> sw.callback(lambda:pyb.LED(1).toggle()) - -This will toggle the red LED each time the switch is pressed. And it will -even work while other code is running. - -To disable the switch callback, pass ``None`` to the callback function:: - - >>> sw.callback(None) - -You can pass any function (that takes zero arguments) to the switch callback. -Above we used the ``lambda`` feature of Python to create an anonymous function -on the fly. But we could equally do:: - - >>> def f(): - ... pyb.LED(1).toggle() - ... - >>> sw.callback(f) - -This creates a function called ``f`` and assigns it to the switch callback. -You can do things this way when your function is more complicated than a -``lambda`` will allow. - -Note that your callback functions must not allocate any memory (for example -they cannot create a tuple or list). Callback functions should be relatively -simple. If you need to make a list, make it beforehand and store it in a -global variable (or make it local and close over it). If you need to do -a long, complicated calculation, then use the callback to set a flag which -some other code then responds to. - -Technical details of interrupts -------------------------------- - -Let's step through the details of what is happening with the switch -callback. When you register a function with ``sw.callback()``, the switch -sets up an external interrupt trigger (falling edge) on the pin that the -switch is connected to. This means that the microcontroller will listen -on the pin for any changes, and the following will occur: - -1. When the switch is pressed a change occurs on the pin (the pin goes - from low to high), and the microcontroller registers this change. -2. The microcontroller finishes executing the current machine instruction, - stops execution, and saves its current state (pushes the registers on - the stack). This has the effect of pausing any code, for example your - running Python script. -3. The microcontroller starts executing the special interrupt handler - associated with the switch's external trigger. This interrupt handler - get the function that you registered with ``sw.callback()`` and executes - it. -4. Your callback function is executed until it finishes, returning control - to the switch interrupt handler. -5. The switch interrupt handler returns, and the microcontroller is - notified that the interrupt has been dealt with. -6. The microcontroller restores the state that it saved in step 2. -7. Execution continues of the code that was running at the beginning. Apart - from the pause, this code does not notice that it was interrupted. - -The above sequence of events gets a bit more complicated when multiple -interrupts occur at the same time. In that case, the interrupt with the -highest priority goes first, then the others in order of their priority. -The switch interrupt is set at the lowest priority. - -Further reading ---------------- - -For further information about using hardware interrupts see -:ref:`writing interrupt handlers <isr_rules>`. diff --git a/docs/pyboard/tutorial/timer.rst b/docs/pyboard/tutorial/timer.rst deleted file mode 100644 index aedaaa13c..000000000 --- a/docs/pyboard/tutorial/timer.rst +++ /dev/null @@ -1,114 +0,0 @@ -The Timers -========== - -The pyboard has 14 timers which each consist of an independent counter -running at a user-defined frequency. They can be set up to run a function -at specific intervals. -The 14 timers are numbered 1 through 14, but 3 is reserved -for internal use, and 5 and 6 are used for servo and ADC/DAC control. -Avoid using these timers if possible. - -Let's create a timer object:: - - >>> tim = pyb.Timer(4) - -Now let's see what we just created:: - - >>> tim - Timer(4) - -The pyboard is telling us that ``tim`` is attached to timer number 4, but -it's not yet initialised. So let's initialise it to trigger at 10 Hz -(that's 10 times per second):: - - >>> tim.init(freq=10) - -Now that it's initialised, we can see some information about the timer:: - - >>> tim - Timer(4, prescaler=624, period=13439, mode=UP, div=1) - -The information means that this timer is set to run at the peripheral -clock speed divided by 624+1, and it will count from 0 up to 13439, at which -point it triggers an interrupt, and then starts counting again from 0. These -numbers are set to make the timer trigger at 10 Hz: the source frequency -of the timer is 84MHz (found by running ``tim.source_freq()``) so we -get 84MHz / 625 / 13440 = 10Hz. - -Timer counter -------------- - -So what can we do with our timer? The most basic thing is to get the -current value of its counter:: - - >>> tim.counter() - 21504 - -This counter will continuously change, and counts up. - -Timer callbacks ---------------- - -The next thing we can do is register a callback function for the timer to -execute when it triggers (see the [switch tutorial](tut-switch) for an -introduction to callback functions):: - - >>> tim.callback(lambda t:pyb.LED(1).toggle()) - -This should start the red LED flashing right away. It will be flashing -at 5 Hz (2 toggle's are needed for 1 flash, so toggling at 10 Hz makes -it flash at 5 Hz). You can change the frequency by re-initialising the -timer:: - - >>> tim.init(freq=20) - -You can disable the callback by passing it the value ``None``:: - - >>> tim.callback(None) - -The function that you pass to callback must take 1 argument, which is -the timer object that triggered. This allows you to control the timer -from within the callback function. - -We can create 2 timers and run them independently:: - - >>> tim4 = pyb.Timer(4, freq=10) - >>> tim7 = pyb.Timer(7, freq=20) - >>> tim4.callback(lambda t: pyb.LED(1).toggle()) - >>> tim7.callback(lambda t: pyb.LED(2).toggle()) - -Because the callbacks are proper hardware interrupts, we can continue -to use the pyboard for other things while these timers are running. - -Making a microsecond counter ----------------------------- - -You can use a timer to create a microsecond counter, which might be -useful when you are doing something which requires accurate timing. -We will use timer 2 for this, since timer 2 has a 32-bit counter (so -does timer 5, but if you use timer 5 then you can't use the Servo -driver at the same time). - -We set up timer 2 as follows:: - - >>> micros = pyb.Timer(2, prescaler=83, period=0x3fffffff) - -The prescaler is set at 83, which makes this timer count at 1 MHz. -This is because the CPU clock, running at 168 MHz, is divided by -2 and then by prescaler+1, giving a frequency of 168 MHz/2/(83+1)=1 MHz -for timer 2. The period is set to a large number so that the timer -can count up to a large number before wrapping back around to zero. -In this case it will take about 17 minutes before it cycles back to -zero. - -To use this timer, it's best to first reset it to 0:: - - >>> micros.counter(0) - -and then perform your timing:: - - >>> start_micros = micros.counter() - - ... do some stuff ... - - >>> end_micros = micros.counter() diff --git a/docs/pyboard/tutorial/usb_mouse.rst b/docs/pyboard/tutorial/usb_mouse.rst deleted file mode 100644 index 6f8831edb..000000000 --- a/docs/pyboard/tutorial/usb_mouse.rst +++ /dev/null @@ -1,131 +0,0 @@ -Making the pyboard act as a USB mouse -===================================== - -The pyboard is a USB device, and can configured to act as a mouse instead -of the default USB flash drive. - -To do this we must first edit the ``boot.py`` file to change the USB -configuration. If you have not yet touched your ``boot.py`` file then it -will look something like this:: - - # boot.py -- run on boot-up - # can run arbitrary Python, but best to keep it minimal - - import pyb - #pyb.main('main.py') # main script to run after this one - #pyb.usb_mode('VCP+MSC') # act as a serial and a storage device - #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse - -To enable the mouse mode, uncomment the last line of the file, to -make it look like:: - - pyb.usb_mode('VCP+HID') # act as a serial device and a mouse - -If you already changed your ``boot.py`` file, then the minimum code it -needs to work is:: - - import pyb - pyb.usb_mode('VCP+HID') - -This tells the pyboard to configure itself as a VCP (Virtual COM Port, -ie serial port) and HID (human interface device, in our case a mouse) -USB device when it boots up. - -Eject/unmount the pyboard drive and reset it using the RST switch. -Your PC should now detect the pyboard as a mouse! - -Sending mouse events by hand ----------------------------- - -To get the py-mouse to do anything we need to send mouse events to the PC. -We will first do this manually using the REPL prompt. Connect to your -pyboard using your serial program and type the following:: - - >>> hid = pyb.USB_HID() - >>> hid.send((0, 10, 0, 0)) - -Your mouse should move 10 pixels to the right! In the command above you -are sending 4 pieces of information: button status, x, y and scroll. The -number 10 is telling the PC that the mouse moved 10 pixels in the x direction. - -Let's make the mouse oscillate left and right:: - - >>> import math - >>> def osc(n, d): - ... for i in range(n): - ... hid.send((0, int(20 * math.sin(i / 10)), 0, 0)) - ... pyb.delay(d) - ... - >>> osc(100, 50) - -The first argument to the function ``osc`` is the number of mouse events to send, -and the second argument is the delay (in milliseconds) between events. Try -playing around with different numbers. - -**Exercise: make the mouse go around in a circle.** - -Making a mouse with the accelerometer -------------------------------------- - -Now lets make the mouse move based on the angle of the pyboard, using the -accelerometer. The following code can be typed directly at the REPL prompt, -or put in the ``main.py`` file. Here, we'll put in in ``main.py`` because to do -that we will learn how to go into safe mode. - -At the moment the pyboard is acting as a serial USB device and an HID (a mouse). -So you cannot access the filesystem to edit your ``main.py`` file. - -You also can't edit your ``boot.py`` to get out of HID-mode and back to normal -mode with a USB drive... - -To get around this we need to go into *safe mode*. This was described in -the [safe mode tutorial](tut-reset), but we repeat the instructions here: - -1. Hold down the USR switch. -2. While still holding down USR, press and release the RST switch. -3. The LEDs will then cycle green to orange to green+orange and back again. -4. Keep holding down USR until *only the orange LED is lit*, and then let - go of the USR switch. -5. The orange LED should flash quickly 4 times, and then turn off. -6. You are now in safe mode. - -In safe mode, the ``boot.py`` and ``main.py`` files are not executed, and so -the pyboard boots up with default settings. This means you now have access -to the filesystem (the USB drive should appear), and you can edit ``main.py``. -(Leave ``boot.py`` as-is, because we still want to go back to HID-mode after -we finish editing ``main.py``.) - -In ``main.py`` put the following code:: - - import pyb - - switch = pyb.Switch() - accel = pyb.Accel() - hid = pyb.USB_HID() - - while not switch(): - hid.send((0, accel.x(), accel.y(), 0)) - pyb.delay(20) - -Save your file, eject/unmount your pyboard drive, and reset it using the RST -switch. It should now act as a mouse, and the angle of the board will move -the mouse around. Try it out, and see if you can make the mouse stand still! - -Press the USR switch to stop the mouse motion. - -You'll note that the y-axis is inverted. That's easy to fix: just put a -minus sign in front of the y-coordinate in the ``hid.send()`` line above. - -Restoring your pyboard to normal --------------------------------- - -If you leave your pyboard as-is, it'll behave as a mouse everytime you plug -it in. You probably want to change it back to normal. To do this you need -to first enter safe mode (see above), and then edit the ``boot.py`` file. -In the ``boot.py`` file, comment out (put a # in front of) the line with the -``VCP+HID`` setting, so it looks like:: - - #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse - -Save your file, eject/unmount the drive, and reset the pyboard. It is now -back to normal operating mode. diff --git a/docs/pyboard_index.rst b/docs/pyboard_index.rst deleted file mode 100644 index 2255a7560..000000000 --- a/docs/pyboard_index.rst +++ /dev/null @@ -1,12 +0,0 @@ -MicroPython documentation and references -======================================== - -.. toctree:: - - pyboard/quickref.rst - pyboard/general.rst - pyboard/tutorial/index.rst - library/index.rst - reference/index.rst - genrst/index.rst - license.rst diff --git a/docs/reference/asm_thumb2_arith.rst b/docs/reference/asm_thumb2_arith.rst deleted file mode 100644 index da4a68852..000000000 --- a/docs/reference/asm_thumb2_arith.rst +++ /dev/null @@ -1,50 +0,0 @@ -Arithmetic instructions -======================= - -Document conventions --------------------- - -Notation: ``Rd, Rm, Rn`` denote ARM registers R0-R7. ``immN`` denotes an immediate -value having a width of N bits e.g. ``imm8``, ``imm3``. ``carry`` denotes -the carry condition flag, ``not(carry)`` denotes its complement. In the case of instructions -with more than one register argument, it is permissible for some to be identical. For example -the following will add the contents of R0 to itself, placing the result in R0: - -* add(r0, r0, r0) - -Arithmetic instructions affect the condition flags except where stated. - -Addition --------- - -* add(Rdn, imm8) ``Rdn = Rdn + imm8`` -* add(Rd, Rn, imm3) ``Rd = Rn + imm3`` -* add(Rd, Rn, Rm) ``Rd = Rn +Rm`` -* adc(Rd, Rn) ``Rd = Rd + Rn + carry`` - -Subtraction ------------ - -* sub(Rdn, imm8) ``Rdn = Rdn - imm8`` -* sub(Rd, Rn, imm3) ``Rd = Rn - imm3`` -* sub(Rd, Rn, Rm) ``Rd = Rn - Rm`` -* sbc(Rd, Rn) ``Rd = Rd - Rn - not(carry)`` - -Negation --------- - -* neg(Rd, Rn) ``Rd = -Rn`` - -Multiplication and division ---------------------------- - -* mul(Rd, Rn) ``Rd = Rd * Rn`` - -This produces a 32 bit result with overflow lost. The result may be treated as -signed or unsigned according to the definition of the operands. - -* sdiv(Rd, Rn, Rm) ``Rd = Rn / Rm`` -* udiv(Rd, Rn, Rm) ``Rd = Rn / Rm`` - -These functions perform signed and unsigned division respectively. Condition flags -are not affected. diff --git a/docs/reference/asm_thumb2_compare.rst b/docs/reference/asm_thumb2_compare.rst deleted file mode 100644 index 521af69da..000000000 --- a/docs/reference/asm_thumb2_compare.rst +++ /dev/null @@ -1,90 +0,0 @@ -Comparison instructions -======================= - -These perform an arithmetic or logical instruction on two arguments, discarding the result -but setting the condition flags. Typically these are used to test data values without changing -them prior to executing a conditional branch. - -Document conventions --------------------- - -Notation: ``Rd, Rm, Rn`` denote ARM registers R0-R7. ``imm8`` denotes an immediate -value having a width of 8 bits. - -The Application Program Status Register (APSR) ----------------------------------------------- - -This contains four bits which are tested by the conditional branch instructions. Typically a -conditional branch will test multiple bits, for example ``bge(LABEL)``. The meaning of -condition codes can depend on whether the operands of an arithmetic instruction are viewed as -signed or unsigned integers. Thus ``bhi(LABEL)`` assumes unsigned numbers were processed while -``bgt(LABEL)`` assumes signed operands. - -APSR Bits ---------- - -* Z (zero) - -This is set if the result of an operation is zero or the operands of a comparison are equal. - -* N (negative) - -Set if the result is negative. - -* C (carry) - -An addition sets the carry flag when the result overflows out of the MSB, for example adding -0x80000000 and 0x80000000. By the nature of two's complement arithmetic this behaviour is reversed -on subtraction, with a borrow indicated by the carry bit being clear. Thus 0x10 - 0x01 is executed -as 0x10 + 0xffffffff which will set the carry bit. - -* V (overflow) - -The overflow flag is set if the result, viewed as a two's compliment number, has the "wrong" sign -in relation to the operands. For example adding 1 to 0x7fffffff will set the overflow bit because -the result (0x8000000), viewed as a two's complement integer, is negative. Note that in this instance -the carry bit is not set. - -Comparison instructions ------------------------ - -These set the APSR (Application Program Status Register) N (negative), Z (zero), C (carry) and V -(overflow) flags. - -* cmp(Rn, imm8) ``Rn - imm8`` -* cmp(Rn, Rm) ``Rn - Rm`` -* cmn(Rn, Rm) ``Rn + Rm`` -* tst(Rn, Rm) ``Rn & Rm`` - -Conditional execution ---------------------- - -The ``it`` and ``ite`` instructions provide a means of conditionally executing from one to four subsequent -instructions without the need for a label. - -* it(<condition>) If then - -Execute the next instruction if <condition> is true: - -:: - - cmp(r0, r1) - it(eq) - mov(r0, 100) # runs if r0 == r1 - # execution continues here - -* ite(<condition>) If then else - -If <condtion> is true, execute the next instruction, otherwise execute the -subsequent one. Thus: - -:: - - cmp(r0, r1) - ite(eq) - mov(r0, 100) # runs if r0 == r1 - mov(r0, 200) # runs if r0 != r1 - # execution continues here - -This may be extended to control the execution of upto four subsequent instructions: it[x[y[z]]] -where x,y,z=t/e; e.g. itt, itee, itete, ittte, itttt, iteee, etc. diff --git a/docs/reference/asm_thumb2_directives.rst b/docs/reference/asm_thumb2_directives.rst deleted file mode 100644 index 95acd7781..000000000 --- a/docs/reference/asm_thumb2_directives.rst +++ /dev/null @@ -1,36 +0,0 @@ -Assembler Directives -==================== - -Labels ------- - -* label(INNER1) - -This defines a label for use in a branch instruction. Thus elsewhere in the code a ``b(INNER1)`` -will cause execution to continue with the instruction after the label directive. - -Defining inline data --------------------- - -The following assembler directives facilitate embedding data in an assembler code block. - -* data(size, d0, d1 .. dn) - -The data directive creates n array of data values in memory. The first argument specifies the -size in bytes of the subsequent arguments. Hence the first statement below will cause the -assembler to put three bytes (with values 2, 3 and 4) into consecutive memory locations -while the second will cause it to emit two four byte words. - -:: - - data(1, 2, 3, 4) - data(4, 2, 100000) - -Data values longer than a single byte are stored in memory in little-endian format. - -* align(nBytes) - -Align the following instruction to an nBytes value. ARM Thumb-2 instructions must be two -byte aligned, hence it's advisable to issue ``align(2)`` after ``data`` directives and -prior to any subsequent code. This ensures that the code will run irrespective of the -size of the data array. diff --git a/docs/reference/asm_thumb2_float.rst b/docs/reference/asm_thumb2_float.rst deleted file mode 100644 index 4acb734ee..000000000 --- a/docs/reference/asm_thumb2_float.rst +++ /dev/null @@ -1,77 +0,0 @@ -Floating Point instructions -============================== - -These instructions support the use of the ARM floating point coprocessor -(on platforms such as the Pyboard which are equipped with one). The FPU -has 32 registers known as ``s0-s31`` each of which can hold a single -precision float. Data can be passed between the FPU registers and the -ARM core registers with the ``vmov`` instruction. - -Note that MicroPython doesn't support passing floats to -assembler functions, nor can you put a float into ``r0`` and expect a -reasonable result. There are two ways to overcome this. The first is to -use arrays, and the second is to pass and/or return integers and convert -to and from floats in code. - -Document conventions --------------------- - -Notation: ``Sd, Sm, Sn`` denote FPU registers, ``Rd, Rm, Rn`` denote ARM core -registers. The latter can be any ARM core register although registers -``R13-R15`` are unlikely to be appropriate in this context. - -Arithmetic ----------- - -* vadd(Sd, Sn, Sm) ``Sd = Sn + Sm`` -* vsub(Sd, Sn, Sm) ``Sd = Sn - Sm`` -* vneg(Sd, Sm) ``Sd = -Sm`` -* vmul(Sd, Sn, Sm) ``Sd = Sn * Sm`` -* vdiv(Sd, Sn, Sm) ``Sd = Sn / Sm`` -* vsqrt(Sd, Sm) ``Sd = sqrt(Sm)`` - -Registers may be identical: ``vmul(S0, S0, S0)`` will execute ``S0 = S0*S0`` - -Move between ARM core and FPU registers ---------------------------------------- - -* vmov(Sd, Rm) ``Sd = Rm`` -* vmov(Rd, Sm) ``Rd = Sm`` - -The FPU has a register known as FPSCR, similar to the ARM core's APSR, which stores condition -codes plus other data. The following instructions provide access to this. - -* vmrs(APSR\_nzcv, FPSCR) - -Move the floating-point N, Z, C, and V flags to the APSR N, Z, C, and V flags. - -This is done after an instruction such as an FPU -comparison to enable the condition codes to be tested by the assembler -code. The following is a more general form of the instruction. - -* vmrs(Rd, FPSCR) ``Rd = FPSCR`` - -Move between FPU register and memory ------------------------------------- - -* vldr(Sd, [Rn, offset]) ``Sd = [Rn + offset]`` -* vstr(Sd, [Rn, offset]) ``[Rn + offset] = Sd`` - -Where ``[Rn + offset]`` denotes the memory address obtained by adding Rn to the offset. This -is specified in bytes. Since each float value occupies a 32 bit word, when accessing arrays of -floats the offset must always be a multiple of four bytes. - -Data Comparison ---------------- - -* vcmp(Sd, Sm) - -Compare the values in Sd and Sm and set the FPU N, Z, -C, and V flags. This would normally be followed by ``vmrs(APSR_nzcv, FPSCR)`` -to enable the results to be tested. - -Convert between integer and float ---------------------------------- - -* vcvt\_f32\_s32(Sd, Sm) ``Sd = float(Sm)`` -* vcvt\_s32\_f32(Sd, Sm) ``Sd = int(Sm)`` diff --git a/docs/reference/asm_thumb2_hints_tips.rst b/docs/reference/asm_thumb2_hints_tips.rst deleted file mode 100644 index 062a3c844..000000000 --- a/docs/reference/asm_thumb2_hints_tips.rst +++ /dev/null @@ -1,244 +0,0 @@ -Hints and tips -============== - -The following are some examples of the use of the inline assembler and some -information on how to work around its limitations. In this document the term -"assembler function" refers to a function declared in Python with the -``@micropython.asm_thumb`` decorator, whereas "subroutine" refers to assembler -code called from within an assembler function. - -Code branches and subroutines ------------------------------ - -It is important to appreciate that labels are local to an assembler function. -There is currently no way for a subroutine defined in one function to be called -from another. - -To call a subroutine the instruction ``bl(LABEL)`` is issued. This transfers -control to the instruction following the ``label(LABEL)`` directive and stores -the return address in the link register (``lr`` or ``r14``). To return the -instruction ``bx(lr)`` is issued which causes execution to continue with -the instruction following the subroutine call. This mechanism implies that, if -a subroutine is to call another, it must save the link register prior to -the call and restore it before terminating. - -The following rather contrived example illustrates a function call. Note that -it's necessary at the start to branch around all subroutine calls: subroutines -end execution with ``bx(lr)`` while the outer function simply "drops off the end" -in the style of Python functions. - -:: - - @micropython.asm_thumb - def quad(r0): - b(START) - label(DOUBLE) - add(r0, r0, r0) - bx(lr) - label(START) - bl(DOUBLE) - bl(DOUBLE) - - print(quad(10)) - -The following code example demonstrates a nested (recursive) call: the classic -Fibonacci sequence. Here, prior to a recursive call, the link register is saved -along with other registers which the program logic requires to be preserved. - -:: - - @micropython.asm_thumb - def fib(r0): - b(START) - label(DOFIB) - push({r1, r2, lr}) - cmp(r0, 1) - ble(FIBDONE) - sub(r0, 1) - mov(r2, r0) # r2 = n -1 - bl(DOFIB) - mov(r1, r0) # r1 = fib(n -1) - sub(r0, r2, 1) - bl(DOFIB) # r0 = fib(n -2) - add(r0, r0, r1) - label(FIBDONE) - pop({r1, r2, lr}) - bx(lr) - label(START) - bl(DOFIB) - - for n in range(10): - print(fib(n)) - -Argument passing and return ---------------------------- - -The tutorial details the fact that assembler functions can support from zero to -three arguments, which must (if used) be named ``r0``, ``r1`` and ``r2``. When -the code executes the registers will be initialised to those values. - -The data types which can be passed in this way are integers and memory -addresses. With current firmware all possible 32 bit values may be passed and -returned. If the return value may have the most significant bit set a Python -type hint should be employed to enable MicroPython to determine whether the -value should be interpreted as a signed or unsigned integer: types are -``int`` or ``uint``. - -:: - - @micropython.asm_thumb - def uadd(r0, r1) -> uint: - add(r0, r0, r1) - -``hex(uadd(0x40000000,0x40000000))`` will return 0x80000000, demonstrating the -passing and return of integers where bits 30 and 31 differ. - -The limitations on the number of arguments and return values can be overcome by means -of the ``array`` module which enables any number of values of any type to be accessed. - -Multiple arguments -~~~~~~~~~~~~~~~~~~ - -If a Python array of integers is passed as an argument to an assembler -function, the function will receive the address of a contiguous set of integers. -Thus multiple arguments can be passed as elements of a single array. Similarly a -function can return multiple values by assigning them to array elements. -Assembler functions have no means of determining the length of an array: -this will need to be passed to the function. - -This use of arrays can be extended to enable more than three arrays to be used. -This is done using indirection: the ``uctypes`` module supports ``addressof()`` -which will return the address of an array passed as its argument. Thus you can -populate an integer array with the addresses of other arrays: - -:: - - from uctypes import addressof - @micropython.asm_thumb - def getindirect(r0): - ldr(r0, [r0, 0]) # Address of array loaded from passed array - ldr(r0, [r0, 4]) # Return element 1 of indirect array (24) - - def testindirect(): - a = array.array('i',[23, 24]) - b = array.array('i',[0,0]) - b[0] = addressof(a) - print(getindirect(b)) - -Non-integer data types -~~~~~~~~~~~~~~~~~~~~~~ - -These may be handled by means of arrays of the appropriate data type. For -example, single precision floating point data may be processed as follows. -This code example takes an array of floats and replaces its contents with -their squares. - -:: - - from array import array - - @micropython.asm_thumb - def square(r0, r1): - label(LOOP) - vldr(s0, [r0, 0]) - vmul(s0, s0, s0) - vstr(s0, [r0, 0]) - add(r0, 4) - sub(r1, 1) - bgt(LOOP) - - a = array('f', (x for x in range(10))) - square(a, len(a)) - print(a) - -The uctypes module supports the use of data structures beyond simple -arrays. It enables a Python data structure to be mapped onto a bytearray -instance which may then be passed to the assembler function. - -Named constants ---------------- - -Assembler code may be made more readable and maintainable by using named -constants rather than littering code with numbers. This may be achieved -thus: - -:: - - MYDATA = const(33) - - @micropython.asm_thumb - def foo(): - mov(r0, MYDATA) - -The const() construct causes MicroPython to replace the variable name -with its value at compile time. If constants are declared in an outer -Python scope they can be shared between multiple assembler functions and -with Python code. - -Assembler code as class methods -------------------------------- - -MicroPython passes the address of the object instance as the first argument -to class methods. This is normally of little use to an assembler function. -It can be avoided by declaring the function as a static method thus: - -:: - - class foo: - @staticmethod - @micropython.asm_thumb - def bar(r0): - add(r0, r0, r0) - -Use of unsupported instructions -------------------------------- - -These can be coded using the data statement as shown below. While -``push()`` and ``pop()`` are supported the example below illustrates the -principle. The necessary machine code may be found in the ARM v7-M -Architecture Reference Manual. Note that the first argument of data -calls such as - -:: - - data(2, 0xe92d, 0x0f00) # push r8,r9,r10,r11 - -indicates that each subsequent argument is a two byte quantity. - -Overcoming MicroPython's integer restriction --------------------------------------------- - -The Pyboard chip includes a CRC generator. Its use presents a problem in -MicroPython because the returned values cover the full gamut of 32 bit -quantities whereas small integers in MicroPython cannot have differing values -in bits 30 and 31. This limitation is overcome with the following code, which -uses assembler to put the result into an array and Python code to -coerce the result into an arbitrary precision unsigned integer. - -:: - - from array import array - import stm - - def enable_crc(): - stm.mem32[stm.RCC + stm.RCC_AHB1ENR] |= 0x1000 - - def reset_crc(): - stm.mem32[stm.CRC+stm.CRC_CR] = 1 - - @micropython.asm_thumb - def getval(r0, r1): - movwt(r3, stm.CRC + stm.CRC_DR) - str(r1, [r3, 0]) - ldr(r2, [r3, 0]) - str(r2, [r0, 0]) - - def getcrc(value): - a = array('i', [0]) - getval(a, value) - return a[0] & 0xffffffff # coerce to arbitrary precision - - enable_crc() - reset_crc() - for x in range(20): - print(hex(getcrc(0))) diff --git a/docs/reference/asm_thumb2_index.rst b/docs/reference/asm_thumb2_index.rst deleted file mode 100644 index f066e6ace..000000000 --- a/docs/reference/asm_thumb2_index.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _asm_thumb2_index: - -Inline Assembler for Thumb2 architectures -========================================= - -This document assumes some familiarity with assembly language programming and should be read after studying -the :ref:`tutorial <pyboard_tutorial_assembler>`. For a detailed description of the instruction set consult the -Architecture Reference Manual detailed below. -The inline assembler supports a subset of the ARM Thumb-2 instruction set described here. The syntax tries -to be as close as possible to that defined in the above ARM manual, converted to Python function calls. - -Instructions operate on 32 bit signed integer data except where stated otherwise. Most supported instructions -operate on registers ``R0-R7`` only: where ``R8-R15`` are supported this is stated. Registers ``R8-R12`` must be -restored to their initial value before return from a function. Registers ``R13-R15`` constitute the Link Register, -Stack Pointer and Program Counter respectively. - -Document conventions --------------------- - -Where possible the behaviour of each instruction is described in Python, for example - -* add(Rd, Rn, Rm) ``Rd = Rn + Rm`` - -This enables the effect of instructions to be demonstrated in Python. In certain case this is impossible -because Python doesn't support concepts such as indirection. The pseudocode employed in such cases is -described on the relevant page. - -Instruction Categories ----------------------- - -The following sections details the subset of the ARM Thumb-2 instruction set supported by MicroPython. - -.. toctree:: - :maxdepth: 1 - :numbered: - - asm_thumb2_mov.rst - asm_thumb2_ldr.rst - asm_thumb2_str.rst - asm_thumb2_logical_bit.rst - asm_thumb2_arith.rst - asm_thumb2_compare.rst - asm_thumb2_label_branch.rst - asm_thumb2_stack.rst - asm_thumb2_misc.rst - asm_thumb2_float.rst - asm_thumb2_directives.rst - -Usage examples --------------- - -These sections provide further code examples and hints on the use of the assembler. - -.. toctree:: - :maxdepth: 1 - :numbered: - - asm_thumb2_hints_tips.rst - -References ----------- - -- :ref:`Assembler Tutorial <pyboard_tutorial_assembler>` -- `Wiki hints and tips - <http://wiki.micropython.org/platforms/boards/pyboard/assembler>`__ -- `uPy Inline Assembler source-code, - emitinlinethumb.c <https://github.com/micropython/micropython/blob/master/py/emitinlinethumb.c>`__ -- `ARM Thumb2 Instruction Set Quick Reference - Card <http://infocenter.arm.com/help/topic/com.arm.doc.qrc0001l/QRC0001_UAL.pdf>`__ -- `RM0090 Reference - Manual <http://www.google.ae/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&sqi=2&ved=0CBoQFjAA&url=http%3A%2F%2Fwww.st.com%2Fst-web-ui%2Fstatic%2Factive%2Fen%2Fresource%2Ftechnical%2Fdocument%2Freference_manual%2FDM00031020.pdf&ei=G0rSU66xFeuW0QWYwoD4CQ&usg=AFQjCNFuW6TgzE4QpahO_U7g3f3wdwecAg&sig2=iET-R0y9on_Pbflzf9aYDw&bvm=bv.71778758,bs.1,d.bGQ>`__ -- ARM v7-M Architecture Reference Manual (Available on the - ARM site after a simple registration procedure. Also available on academic sites but beware of out of date versions.) diff --git a/docs/reference/asm_thumb2_label_branch.rst b/docs/reference/asm_thumb2_label_branch.rst deleted file mode 100644 index 8c85e55f0..000000000 --- a/docs/reference/asm_thumb2_label_branch.rst +++ /dev/null @@ -1,85 +0,0 @@ -Branch instructions -=================== - -These cause execution to jump to a target location usually specified by a label (see the ``label`` -assembler directive). Conditional branches and the ``it`` and ``ite`` instructions test -the Application Program Status Register (APSR) N (negative), Z (zero), C (carry) and V -(overflow) flags to determine whether the branch should be executed. - -Most of the exposed assembler instructions (including move operations) set the flags but -there are explicit comparison instructions to enable values to be tested. - -Further detail on the meaning of the condition flags is provided in the section -describing comparison functions. - -Document conventions --------------------- - -Notation: ``Rm`` denotes ARM registers R0-R15. ``LABEL`` denotes a label defined with the -``label()`` assembler directive. ``<condition>`` indicates one of the following condition -specifiers: - -* eq Equal to (result was zero) -* ne Not equal -* cs Carry set -* cc Carry clear -* mi Minus (negative) -* pl Plus (positive) -* vs Overflow set -* vc Overflow clear -* hi > (unsigned comparison) -* ls <= (unsigned comparison) -* ge >= (signed comparison) -* lt < (signed comparison) -* gt > (signed comparison) -* le <= (signed comparison) - -Branch to label ---------------- - -* b(LABEL) Unconditional branch -* beq(LABEL) branch if equal -* bne(LABEL) branch if not equal -* bge(LABEL) branch if greater than or equal -* bgt(LABEL) branch if greater than -* blt(LABEL) branch if less than (<) (signed) -* ble(LABEL) branch if less than or equal to (<=) (signed) -* bcs(LABEL) branch if carry flag is set -* bcc(LABEL) branch if carry flag is clear -* bmi(LABEL) branch if negative -* bpl(LABEL) branch if positive -* bvs(LABEL) branch if overflow flag set -* bvc(LABEL) branch if overflow flag is clear -* bhi(LABEL) branch if higher (unsigned) -* bls(LABEL) branch if lower or equal (unsigned) - -Long branches -------------- - -The code produced by the branch instructions listed above uses a fixed bit width to specify the -branch destination, which is PC relative. Consequently in long programs where the -branch instruction is remote from its destination the assembler will produce a "branch not in -range" error. This can be overcome with the "wide" variants such as - -* beq\_w(LABEL) long branch if equal - -Wide branches use 4 bytes to encode the instruction (compared with 2 bytes for standard branch instructions). - -Subroutines (functions) ------------------------ - -When entering a subroutine the processor stores the return address in register r14, also -known as the link register (lr). Return to the instruction after the subroutine call is -performed by updating the program counter (r15 or pc) from the link register, This -process is handled by the following instructions. - -* bl(LABEL) - -Transfer execution to the instruction after ``LABEL`` storing the return address in -the link register (r14). - -* bx(Rm) Branch to address specified by Rm. - -Typically ``bx(lr)`` is issued to return from a subroutine. For nested subroutines the -link register of outer scopes must be saved (usually on the stack) before performing -inner subroutine calls. diff --git a/docs/reference/asm_thumb2_ldr.rst b/docs/reference/asm_thumb2_ldr.rst deleted file mode 100644 index 16b772959..000000000 --- a/docs/reference/asm_thumb2_ldr.rst +++ /dev/null @@ -1,23 +0,0 @@ -Load register from memory -========================= - -Document conventions --------------------- - -Notation: ``Rt, Rn`` denote ARM registers R0-R7 except where stated. ``immN`` represents an immediate -value having a width of N bits hence ``imm5`` is constrained to the range 0-31. ``[Rn + immN]`` is the contents -of the memory address obtained by adding Rn and the offset ``immN``. Offsets are measured in -bytes. These instructions affect the condition flags. - -Register Load -------------- - -* ldr(Rt, [Rn, imm7]) ``Rt = [Rn + imm7]`` Load a 32 bit word -* ldrb(Rt, [Rn, imm5]) ``Rt = [Rn + imm5]`` Load a byte -* ldrh(Rt, [Rn, imm6]) ``Rt = [Rn + imm6]`` Load a 16 bit half word - -Where a byte or half word is loaded, it is zero-extended to 32 bits. - -The specified immediate offsets are measured in bytes. Hence in the case of ``ldr`` the 7 bit value -enables 32 bit word aligned values to be accessed with a maximum offset of 31 words. In the case of ``ldrh`` the -6 bit value enables 16 bit half-word aligned values to be accessed with a maximum offset of 31 half-words. diff --git a/docs/reference/asm_thumb2_logical_bit.rst b/docs/reference/asm_thumb2_logical_bit.rst deleted file mode 100644 index 8c51feaf4..000000000 --- a/docs/reference/asm_thumb2_logical_bit.rst +++ /dev/null @@ -1,53 +0,0 @@ -Logical & Bitwise instructions -============================== - -Document conventions --------------------- - -Notation: ``Rd, Rn`` denote ARM registers R0-R7 except in the case of the -special instructions where R0-R15 may be used. ``Rn<a-b>`` denotes an ARM register -whose contents must lie in range ``a <= contents <= b``. In the case of instructions -with two register arguments, it is permissible for them to be identical. For example -the following will zero R0 (Python ``R0 ^= R0``) regardless of its initial contents. - -* eor(r0, r0) - -These instructions affect the condition flags except where stated. - -Logical instructions --------------------- - -* and\_(Rd, Rn) ``Rd &= Rn`` -* orr(Rd, Rn) ``Rd |= Rn`` -* eor(Rd, Rn) ``Rd ^= Rn`` -* mvn(Rd, Rn) ``Rd = Rn ^ 0xffffffff`` i.e. Rd = 1's complement of Rn -* bic(Rd, Rn) ``Rd &= ~Rn`` bit clear Rd using mask in Rn - -Note the use of "and\_" instead of "and", because "and" is a reserved keyword in Python. - -Shift and rotation instructions -------------------------------- - -* lsl(Rd, Rn<0-31>) ``Rd <<= Rn`` -* lsr(Rd, Rn<1-32>) ``Rd = (Rd & 0xffffffff) >> Rn`` Logical shift right -* asr(Rd, Rn<1-32>) ``Rd >>= Rn`` arithmetic shift right -* ror(Rd, Rn<1-31>) ``Rd = rotate_right(Rd, Rn)`` Rd is rotated right Rn bits. - -A rotation by (for example) three bits works as follows. If Rd initially -contains bits ``b31 b30..b0`` after rotation it will contain ``b2 b1 b0 b31 b30..b3`` - -Special instructions --------------------- - -Condition codes are unaffected by these instructions. - -* clz(Rd, Rn) ``Rd = count_leading_zeros(Rn)`` - -count_leading_zeros(Rn) returns the number of binary zero bits before the first binary one bit in Rn. - -* rbit(Rd, Rn) ``Rd = bit_reverse(Rn)`` - -bit_reverse(Rn) returns the bit-reversed contents of Rn. If Rn contains bits ``b31 b30..b0`` Rd will be set -to ``b0 b1 b2..b31`` - -Trailing zeros may be counted by performing a bit reverse prior to executing clz. diff --git a/docs/reference/asm_thumb2_misc.rst b/docs/reference/asm_thumb2_misc.rst deleted file mode 100644 index ca3f878cc..000000000 --- a/docs/reference/asm_thumb2_misc.rst +++ /dev/null @@ -1,13 +0,0 @@ -Miscellaneous instructions -========================== - -* nop() ``pass`` no operation. -* wfi() Suspend execution in a low power state until an interrupt occurs. -* cpsid(flags) set the Priority Mask Register - disable interrupts. -* cpsie(flags) clear the Priority Mask Register - enable interrupts. -* mrs(Rd, special_reg) ``Rd = special_reg`` copy a special register to a general register. The special register - may be IPSR (Interrupt Status Register) or BASEPRI (Base Priority Register). The IPSR provides a means of determining - the exception number of an interrupt being processed. It contains zero if no interrupt is being processed. - -Currently the ``cpsie()`` and ``cpsid()`` functions are partially implemented. -They require but ignore the flags argument and serve as a means of enabling and disabling interrupts. diff --git a/docs/reference/asm_thumb2_mov.rst b/docs/reference/asm_thumb2_mov.rst deleted file mode 100644 index 900bf957b..000000000 --- a/docs/reference/asm_thumb2_mov.rst +++ /dev/null @@ -1,27 +0,0 @@ -Register move instructions -========================== - -Document conventions --------------------- - -Notation: ``Rd, Rn`` denote ARM registers R0-R15. ``immN`` denotes an immediate -value having a width of N bits. These instructions affect the condition flags. - -Register moves --------------- - -Where immediate values are used, these are zero-extended to 32 bits. Thus -``mov(R0, 0xff)`` will set R0 to 255. - -* mov(Rd, imm8) ``Rd = imm8`` -* mov(Rd, Rn) ``Rd = Rn`` -* movw(Rd, imm16) ``Rd = imm16`` -* movt(Rd, imm16) ``Rd = (Rd & 0xffff) | (imm16 << 16)`` - -movt writes an immediate value to the top halfword of the destination register. -It does not affect the contents of the bottom halfword. - -* movwt(Rd, imm32) ``Rd = imm32`` - -movwt is a pseudo-instruction: the MicroPython assembler emits a ``movw`` followed -by a ``movt`` to move a 32-bit value into Rd. diff --git a/docs/reference/asm_thumb2_stack.rst b/docs/reference/asm_thumb2_stack.rst deleted file mode 100644 index bffbab277..000000000 --- a/docs/reference/asm_thumb2_stack.rst +++ /dev/null @@ -1,20 +0,0 @@ -Stack push and pop -================== - -Document conventions --------------------- - -The ``push()`` and ``pop()`` instructions accept as their argument a register set containing -a subset, or possibly all, of the general-purpose registers R0-R12 and the link register (lr or R14). -As with any Python set the order in which the registers are specified is immaterial. Thus the -in the following example the pop() instruction would restore R1, R7 and R8 to their contents prior -to the push(): - -* push({r1, r8, r7}) Save three registers on the stack. -* pop({r7, r1, r8}) Restore them - -Stack operations ----------------- - -* push({regset}) Push a set of registers onto the stack -* pop({regset}) Restore a set of registers from the stack diff --git a/docs/reference/asm_thumb2_str.rst b/docs/reference/asm_thumb2_str.rst deleted file mode 100644 index 5a88b091b..000000000 --- a/docs/reference/asm_thumb2_str.rst +++ /dev/null @@ -1,21 +0,0 @@ -Store register to memory -======================== - -Document conventions --------------------- - -Notation: ``Rt, Rn`` denote ARM registers R0-R7 except where stated. ``immN`` represents an immediate -value having a width of N bits hence ``imm5`` is constrained to the range 0-31. ``[Rn + imm5]`` is the -contents of the memory address obtained by adding Rn and the offset ``imm5``. Offsets are measured in -bytes. These instructions do not affect the condition flags. - -Register Store --------------- - -* str(Rt, [Rn, imm7]) ``[Rn + imm7] = Rt`` Store a 32 bit word -* strb(Rt, [Rn, imm5]) ``[Rn + imm5] = Rt`` Store a byte (b0-b7) -* strh(Rt, [Rn, imm6]) ``[Rn + imm6] = Rt`` Store a 16 bit half word (b0-b15) - -The specified immediate offsets are measured in bytes. Hence in the case of ``str`` the 7 bit value -enables 32 bit word aligned values to be accessed with a maximum offset of 31 words. In the case of ``strh`` the -6 bit value enables 16 bit half-word aligned values to be accessed with a maximum offset of 31 half-words. diff --git a/docs/reference/constrained.rst b/docs/reference/constrained.rst deleted file mode 100644 index e7de459bc..000000000 --- a/docs/reference/constrained.rst +++ /dev/null @@ -1,456 +0,0 @@ -.. _constrained: - -MicroPython on Microcontrollers -=============================== - -MicroPython is designed to be capable of running on microcontrollers. These -have hardware limitations which may be unfamiliar to programmers more familiar -with conventional computers. In particular the amount of RAM and nonvolatile -"disk" (flash memory) storage is limited. This tutorial offers ways to make -the most of the limited resources. Because MicroPython runs on controllers -based on a variety of architectures, the methods presented are generic: in some -cases it will be necessary to obtain detailed information from platform specific -documentation. - -Flash Memory ------------- - -On the Pyboard the simple way to address the limited capacity is to fit a micro -SD card. In some cases this is impractical, either because the device does not -have an SD card slot or for reasons of cost or power consumption; hence the -on-chip flash must be used. The firmware including the MicroPython subsystem is -stored in the onboard flash. The remaining capacity is available for use. For -reasons connected with the physical architecture of the flash memory part of -this capacity may be inaccessible as a filesystem. In such cases this space may -be employed by incorporating user modules into a firmware build which is then -flashed to the device. - -There are two ways to achieve this: frozen modules and frozen bytecode. Frozen -modules store the Python source with the firmware. Frozen bytecode uses the -cross compiler to convert the source to bytecode which is then stored with the -firmware. In either case the module may be accessed with an import statement: - -.. code:: - - import mymodule - -The procedure for producing frozen modules and bytecode is platform dependent; -instructions for building the firmware can be found in the README files in the -relevant part of the source tree. - -In general terms the steps are as follows: - -* Clone the MicroPython `repository <https://github.com/micropython/micropython>`_. -* Acquire the (platform specific) toolchain to build the firmware. -* Build the cross compiler. -* Place the modules to be frozen in a specified directory (dependent on whether - the module is to be frozen as source or as bytecode). -* Build the firmware. A specific command may be required to build frozen - code of either type - see the platform documentation. -* Flash the firmware to the device. - -RAM ---- - -When reducing RAM usage there are two phases to consider: compilation and -execution. In addition to memory consumption, there is also an issue known as -heap fragmentation. In general terms it is best to minimise the repeated -creation and destruction of objects. The reason for this is covered in the -section covering the `heap`_. - -Compilation Phase -~~~~~~~~~~~~~~~~~ - -When a module is imported, MicroPython compiles the code to bytecode which is -then executed by the MicroPython virtual machine (VM). The bytecode is stored -in RAM. The compiler itself requires RAM, but this becomes available for use -when the compilation has completed. - -If a number of modules have already been imported the situation can arise where -there is insufficient RAM to run the compiler. In this case the import -statement will produce a memory exception. - -If a module instantiates global objects on import it will consume RAM at the -time of import, which is then unavailable for the compiler to use on subsequent -imports. In general it is best to avoid code which runs on import; a better -approach is to have initialisation code which is run by the application after -all modules have been imported. This maximises the RAM available to the -compiler. - -If RAM is still insufficient to compile all modules one solution is to -precompile modules. MicroPython has a cross compiler capable of compiling Python -modules to bytecode (see the README in the mpy-cross directory). The resulting -bytecode file has a .mpy extension; it may be copied to the filesystem and -imported in the usual way. Alternatively some or all modules may be implemented -as frozen bytecode: on most platforms this saves even more RAM as the bytecode -is run directly from flash rather than being stored in RAM. - -Execution Phase -~~~~~~~~~~~~~~~ - -There are a number of coding techniques for reducing RAM usage. - -**Constants** - -MicroPython provides a ``const`` keyword which may be used as follows: - -.. code:: - - from micropython import const - ROWS = const(33) - _COLS = const(0x10) - a = ROWS - b = _COLS - -In both instances where the constant is assigned to a variable the compiler -will avoid coding a lookup to the name of the constant by substituting its -literal value. This saves bytecode and hence RAM. However the ``ROWS`` value -will occupy at least two machine words, one each for the key and value in the -globals dictionary. The presence in the dictionary is necessary because another -module might import or use it. This RAM can be saved by prepending the name -with an underscore as in ``_COLS``: this symbol is not visible outside the -module so will not occupy RAM. - -The argument to ``const()`` may be anything which, at compile time, evaluates -to an integer e.g. ``0x100`` or ``1 << 8``. It can even include other const -symbols that have already been defined, e.g. ``1 << BIT``. - -**Constant data structures** - -Where there is a substantial volume of constant data and the platform supports -execution from Flash, RAM may be saved as follows. The data should be located in -Python modules and frozen as bytecode. The data must be defined as `bytes` -objects. The compiler 'knows' that `bytes` objects are immutable and ensures -that the objects remain in flash memory rather than being copied to RAM. The -`ustruct` module can assist in converting between `bytes` types and other -Python built-in types. - -When considering the implications of frozen bytecode, note that in Python -strings, floats, bytes, integers and complex numbers are immutable. Accordingly -these will be frozen into flash. Thus, in the line - -.. code:: - - mystring = "The quick brown fox" - -the actual string "The quick brown fox" will reside in flash. At runtime a -reference to the string is assigned to the *variable* ``mystring``. The reference -occupies a single machine word. In principle a long integer could be used to -store constant data: - -.. code:: - - bar = 0xDEADBEEF0000DEADBEEF - -As in the string example, at runtime a reference to the arbitrarily large -integer is assigned to the variable ``bar``. That reference occupies a -single machine word. - -It might be expected that tuples of integers could be employed for the purpose -of storing constant data with minimal RAM use. With the current compiler this -is ineffective (the code works, but RAM is not saved). - -.. code:: - - foo = (1, 2, 3, 4, 5, 6, 100000) - -At runtime the tuple will be located in RAM. This may be subject to future -improvement. - -**Needless object creation** - -There are a number of situations where objects may unwittingly be created and -destroyed. This can reduce the usability of RAM through fragmentation. The -following sections discuss instances of this. - -**String concatenation** - -Consider the following code fragments which aim to produce constant strings: - -.. code:: - - var = "foo" + "bar" - var1 = "foo" "bar" - var2 = """\ - foo\ - bar""" - -Each produces the same outcome, however the first needlessly creates two string -objects at runtime, allocates more RAM for concatenation before producing the -third. The others perform the concatenation at compile time which is more -efficient, reducing fragmentation. - -Where strings must be dynamically created before being fed to a stream such as -a file it will save RAM if this is done in a piecemeal fashion. Rather than -creating a large string object, create a substring and feed it to the stream -before dealing with the next. - -The best way to create dynamic strings is by means of the string `format` -method: - -.. code:: - - var = "Temperature {:5.2f} Pressure {:06d}\n".format(temp, press) - -**Buffers** - -When accessing devices such as instances of UART, I2C and SPI interfaces, using -pre-allocated buffers avoids the creation of needless objects. Consider these -two loops: - -.. code:: - - while True: - var = spi.read(100) - # process data - - buf = bytearray(100) - while True: - spi.readinto(buf) - # process data in buf - -The first creates a buffer on each pass whereas the second re-uses a pre-allocated -buffer; this is both faster and more efficient in terms of memory fragmentation. - -**Bytes are smaller than ints** - -On most platforms an integer consumes four bytes. Consider the two calls to the -function ``foo()``: - -.. code:: - - def foo(bar): - for x in bar: - print(x) - foo((1, 2, 0xff)) - foo(b'\1\2\xff') - -In the first call a tuple of integers is created in RAM. The second efficiently -creates a `bytes` object consuming the minimum amount of RAM. If the module -were frozen as bytecode, the `bytes` object would reside in flash. - -**Strings Versus Bytes** - -Python3 introduced Unicode support. This introduced a distinction between a -string and an array of bytes. MicroPython ensures that Unicode strings take no -additional space so long as all characters in the string are ASCII (i.e. have -a value < 126). If values in the full 8-bit range are required `bytes` and -`bytearray` objects can be used to ensure that no additional space will be -required. Note that most string methods (e.g. :meth:`str.strip()`) apply also to `bytes` -instances so the process of eliminating Unicode can be painless. - -.. code:: - - s = 'the quick brown fox' # A string instance - b = b'the quick brown fox' # A bytes instance - -Where it is necessary to convert between strings and bytes the :meth:`str.encode` -and the :meth:`bytes.decode` methods can be used. Note that both strings and bytes -are immutable. Any operation which takes as input such an object and produces -another implies at least one RAM allocation to produce the result. In the -second line below a new bytes object is allocated. This would also occur if ``foo`` -were a string. - -.. code:: - - foo = b' empty whitespace' - foo = foo.lstrip() - -**Runtime compiler execution** - -The Python funcitons `eval` and `exec` invoke the compiler at runtime, which -requires significant amounts of RAM. Note that the `pickle` library from -`micropython-lib` employs `exec`. It may be more RAM efficient to use the -`ujson` library for object serialisation. - -**Storing strings in flash** - -Python strings are immutable hence have the potential to be stored in read only -memory. The compiler can place in flash strings defined in Python code. As with -frozen modules it is necessary to have a copy of the source tree on the PC and -the toolchain to build the firmware. The procedure will work even if the -modules have not been fully debugged, so long as they can be imported and run. - -After importing the modules, execute: - -.. code:: - - micropython.qstr_info(1) - -Then copy and paste all the Q(xxx) lines into a text editor. Check for and -remove lines which are obviously invalid. Open the file qstrdefsport.h which -will be found in ports/stm32 (or the equivalent directory for the architecture in -use). Copy and paste the corrected lines at the end of the file. Save the file, -rebuild and flash the firmware. The outcome can be checked by importing the -modules and again issuing: - -.. code:: - - micropython.qstr_info(1) - -The Q(xxx) lines should be gone. - -.. _heap: - -The Heap --------- - -When a running program instantiates an object the necessary RAM is allocated -from a fixed size pool known as the heap. When the object goes out of scope (in -other words becomes inaccessible to code) the redundant object is known as -"garbage". A process known as "garbage collection" (GC) reclaims that memory, -returning it to the free heap. This process runs automatically, however it can -be invoked directly by issuing `gc.collect()`. - -The discourse on this is somewhat involved. For a 'quick fix' issue the -following periodically: - -.. code:: - - gc.collect() - gc.threshold(gc.mem_free() // 4 + gc.mem_alloc()) - -Fragmentation -~~~~~~~~~~~~~ - -Say a program creates an object ``foo``, then an object ``bar``. Subsequently -``foo`` goes out of scope but ``bar`` remains. The RAM used by ``foo`` will be -reclaimed by GC. However if ``bar`` was allocated to a higher address, the -RAM reclaimed from ``foo`` will only be of use for objects no bigger than -``foo``. In a complex or long running program the heap can become fragmented: -despite there being a substantial amount of RAM available, there is insufficient -contiguous space to allocate a particular object, and the program fails with a -memory error. - -The techniques outlined above aim to minimise this. Where large permanent buffers -or other objects are required it is best to instantiate these early in the -process of program execution before fragmentation can occur. Further improvements -may be made by monitoring the state of the heap and by controlling GC; these are -outlined below. - -Reporting -~~~~~~~~~ - -A number of library functions are available to report on memory allocation and -to control GC. These are to be found in the `gc` and `micropython` modules. -The following example may be pasted at the REPL (``ctrl e`` to enter paste mode, -``ctrl d`` to run it). - -.. code:: - - import gc - import micropython - gc.collect() - micropython.mem_info() - print('-----------------------------') - print('Initial free: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc())) - def func(): - a = bytearray(10000) - gc.collect() - print('Func definition: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc())) - func() - print('Func run free: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc())) - gc.collect() - print('Garbage collect free: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc())) - print('-----------------------------') - micropython.mem_info(1) - -Methods employed above: - -* `gc.collect()` Force a garbage collection. See footnote. -* `micropython.mem_info()` Print a summary of RAM utilisation. -* `gc.mem_free()` Return the free heap size in bytes. -* `gc.mem_alloc()` Return the number of bytes currently allocated. -* ``micropython.mem_info(1)`` Print a table of heap utilisation (detailed below). - -The numbers produced are dependent on the platform, but it can be seen that -declaring the function uses a small amount of RAM in the form of bytecode -emitted by the compiler (the RAM used by the compiler has been reclaimed). -Running the function uses over 10KiB, but on return ``a`` is garbage because it -is out of scope and cannot be referenced. The final `gc.collect()` recovers -that memory. - -The final output produced by ``micropython.mem_info(1)`` will vary in detail but -may be interpreted as follows: - -====== ================= -Symbol Meaning -====== ================= - . free block - h head block - = tail block - m marked head block - T tuple - L list - D dict - F float - B byte code - M module -====== ================= - -Each letter represents a single block of memory, a block being 16 bytes. So each -line of the heap dump represents 0x400 bytes or 1KiB of RAM. - -Control of Garbage Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A GC can be demanded at any time by issuing `gc.collect()`. It is advantageous -to do this at intervals, firstly to pre-empt fragmentation and secondly for -performance. A GC can take several milliseconds but is quicker when there is -little work to do (about 1ms on the Pyboard). An explicit call can minimise that -delay while ensuring it occurs at points in the program when it is acceptable. - -Automatic GC is provoked under the following circumstances. When an attempt at -allocation fails, a GC is performed and the allocation re-tried. Only if this -fails is an exception raised. Secondly an automatic GC will be triggered if the -amount of free RAM falls below a threshold. This threshold can be adapted as -execution progresses: - -.. code:: - - gc.collect() - gc.threshold(gc.mem_free() // 4 + gc.mem_alloc()) - -This will provoke a GC when more than 25% of the currently free heap becomes -occupied. - -In general modules should instantiate data objects at runtime using constructors -or other initialisation functions. The reason is that if this occurs on -initialisation the compiler may be starved of RAM when subsequent modules are -imported. If modules do instantiate data on import then `gc.collect()` issued -after the import will ameliorate the problem. - -String Operations ------------------ - -MicroPython handles strings in an efficient manner and understanding this can -help in designing applications to run on microcontrollers. When a module -is compiled, strings which occur multiple times are stored once only, a process -known as string interning. In MicroPython an interned string is known as a ``qstr``. -In a module imported normally that single instance will be located in RAM, but -as described above, in modules frozen as bytecode it will be located in flash. - -String comparisons are also performed efficiently using hashing rather than -character by character. The penalty for using strings rather than integers may -hence be small both in terms of performance and RAM usage - a fact which may -come as a surprise to C programmers. - -Postscript ----------- - -MicroPython passes, returns and (by default) copies objects by reference. A -reference occupies a single machine word so these processes are efficient in -RAM usage and speed. - -Where variables are required whose size is neither a byte nor a machine word -there are standard libraries which can assist in storing these efficiently and -in performing conversions. See the `array`, `ustruct` and `uctypes` -modules. - -Footnote: gc.collect() return value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On Unix and Windows platforms the `gc.collect()` method returns an integer -which signifies the number of distinct memory regions that were reclaimed in the -collection (more precisely, the number of heads that were turned into frees). For -efficiency reasons bare metal ports do not return this value. diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst deleted file mode 100644 index 4cd3d84cc..000000000 --- a/docs/reference/glossary.rst +++ /dev/null @@ -1,105 +0,0 @@ -Glossary -======== - -.. glossary:: - - baremetal - A system without (full-fledged) OS, like an :term:`MCU`. When - running on a baremetal system, MicroPython effectively becomes - its user-facing OS with a command interpreter (REPL). - - board - A PCB board. Oftentimes, the term is used to denote a particular - model of an :term:`MCU` system. Sometimes, it is used to actually - refer to :term:`MicroPython port` to a particular board (and then - may also refer to "boardless" ports like - :term:`Unix port <MicroPython Unix port>`). - - CPython - CPython is the reference implementation of Python programming - language, and the most well-known one, which most of the people - run. It is however one of many implementations (among which - Jython, IronPython, PyPy, and many more, including MicroPython). - As there is no formal specification of the Python language, only - CPython documentation, it is not always easy to draw a line - between Python the language and CPython its particular - implementation. This however leaves more freedom for other - implementations. For example, MicroPython does a lot of things - differently than CPython, while still aspiring to be a Python - language implementation. - - GPIO - General-purpose input/output. The simplest means to control - electrical signals. With GPIO, user can configure hardware - signal pin to be either input or output, and set or get - its digital signal value (logical "0" or "1"). MicroPython - abstracts GPIO access using :class:`machine.Pin` and :class:`machine.Signal` - classes. - - GPIO port - A group of :term:`GPIO` pins, usually based on hardware - properties of these pins (e.g. controllable by the same - register). - - MCU - Microcontroller. Microcontrollers usually have much less resources - than a full-fledged computing system, but smaller, cheaper and - require much less power. MicroPython is designed to be small and - optimized enough to run on an average modern microcontroller. - - micropython-lib - MicroPython is (usually) distributed as a single executable/binary - file with just few builtin modules. There is no extensive standard - library comparable with :term:`CPython`. Instead, there is a related, but - separate project - `micropython-lib <https://github.com/micropython/micropython-lib>`_ - which provides implementations for many modules from CPython's - standard library. However, large subset of these modules require - POSIX-like environment (Linux, MacOS, Windows may be partially - supported), and thus would work or make sense only with - `MicroPython Unix port`. Some subset of modules is however usable - for `baremetal` ports too. - - Unlike monolithic :term:`CPython` stdlib, micropython-lib modules - are intended to be installed individually - either using manual - copying or using :term:`upip`. - - MicroPython port - MicroPython supports different :term:`boards <board>`, RTOSes, - and OSes, and can be relatively easily adapted to new systems. - MicroPython with support for a particular system is called a - "port" to that system. Different ports may have widely different - functionality. This documentation is intended to be a reference - of the generic APIs available across different ports ("MicroPython - core"). Note that some ports may still omit some APIs described - here (e.g. due to resource constraints). Any such differences, - and port-specific extensions beyond MicroPython core functionality, - would be described in the separate port-specific documentation. - - MicroPython Unix port - Unix port is one of the major :term:`MicroPython ports <MicroPython port>`. - It is intended to run on POSIX-compatible operating systems, like - Linux, MacOS, FreeBSD, Solaris, etc. It also serves as the basis - of Windows port. The importance of Unix port lies in the fact - that while there are many different :term:`boards <board>`, so - two random users unlikely have the same board, almost all modern - OSes have some level of POSIX compatibility, so Unix port serves - as a kind of "common ground" to which any user can have access. - So, Unix port is used for initial prototyping, different kinds - of testing, development of machine-independent features, etc. - All users of MicroPython, even those which are interested only - in running MicroPython on :term:`MCU` systems, are recommended - to be familiar with Unix (or Windows) port, as it is important - productivity helper and a part of normal MicroPython workflow. - - port - Either :term:`MicroPython port` or :term:`GPIO port`. If not clear - from context, it's recommended to use full specification like one - of the above. - - upip - (Literally, "micro pip"). A package manage for MicroPython, inspired - by :term:`CPython`'s pip, but much smaller and with reduced functionality. - upip runs both on :term:`Unix port <MicroPython Unix port>` and on - :term:`baremetal` ports (those which offer filesystem and networking - support). diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index 4d822d6fa..000000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,33 +0,0 @@ -The MicroPython language -======================== - -MicroPython aims to implement the Python 3.4 standard (with selected -features from later versions) with respect to language syntax, and most -of the features of MicroPython are identical to those described by the -"Language Reference" documentation at -`docs.python.org <https://docs.python.org/3/reference/index.html>`_. - -The MicroPython standard library is described in the -:ref:`corresponding chapter <micropython_lib>`. The :ref:`cpython_diffs` -chapter describes differences between MicroPython and CPython (which -mostly concern standard library and types, but also some language-level -features). - -This chapter describes features and peculiarities of MicroPython -implementation and the best practices to use them. - -.. toctree:: - :maxdepth: 1 - - glossary.rst - repl.rst - isr_rules.rst - speed_python.rst - constrained.rst - -.. only:: port_pyboard - - .. toctree:: - :maxdepth: 1 - - asm_thumb2_index.rst diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst deleted file mode 100644 index 2db261c09..000000000 --- a/docs/reference/isr_rules.rst +++ /dev/null @@ -1,353 +0,0 @@ -.. _isr_rules: - -Writing interrupt handlers -========================== - -On suitable hardware MicroPython offers the ability to write interrupt handlers in Python. Interrupt handlers -- also known as interrupt service routines (ISR's) - are defined as callback functions. These are executed -in response to an event such as a timer trigger or a voltage change on a pin. Such events can occur at any point -in the execution of the program code. This carries significant consequences, some specific to the MicroPython -language. Others are common to all systems capable of responding to real time events. This document covers -the language specific issues first, followed by a brief introduction to real time programming for those new to it. - -This introduction uses vague terms like "slow" or "as fast as possible". This is deliberate, as speeds are -application dependent. Acceptable durations for an ISR are dependent on the rate at which interrupts occur, -the nature of the main program, and the presence of other concurrent events. - -Tips and recommended practices ------------------------------- - -This summarises the points detailed below and lists the principal recommendations for interrupt handler code. - -* Keep the code as short and simple as possible. -* Avoid memory allocation: no appending to lists or insertion into dictionaries, no floating point. -* Consider using ``micropython.schedule`` to work around the above constraint. -* Where an ISR returns multiple bytes use a pre-allocated ``bytearray``. If multiple integers are to be - shared between an ISR and the main program consider an array (``array.array``). -* Where data is shared between the main program and an ISR, consider disabling interrupts prior to accessing - the data in the main program and re-enabling them immediately afterwards (see Critical Sections). -* Allocate an emergency exception buffer (see below). - - -MicroPython Issues ------------------- - -The emergency exception buffer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If an error occurs in an ISR, MicroPython is unable to produce an error report unless a special buffer is created -for the purpose. Debugging is simplified if the following code is included in any program using interrupts. - -.. code:: python - - import micropython - micropython.alloc_emergency_exception_buf(100) - -Simplicity -~~~~~~~~~~ - -For a variety of reasons it is important to keep ISR code as short and simple as possible. It should do only what -has to be done immediately after the event which caused it: operations which can be deferred should be delegated -to the main program loop. Typically an ISR will deal with the hardware device which caused the interrupt, making -it ready for the next interrupt to occur. It will communicate with the main loop by updating shared data to indicate -that the interrupt has occurred, and it will return. An ISR should return control to the main loop as quickly -as possible. This is not a specific MicroPython issue so is covered in more detail :ref:`below <ISR>`. - -Communication between an ISR and the main program -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Normally an ISR needs to communicate with the main program. The simplest means of doing this is via one or more -shared data objects, either declared as global or shared via a class (see below). There are various restrictions -and hazards around doing this, which are covered in more detail below. Integers, ``bytes`` and ``bytearray`` objects -are commonly used for this purpose along with arrays (from the array module) which can store various data types. - -The use of object methods as callbacks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MicroPython supports this powerful technique which enables an ISR to share instance variables with the underlying -code. It also enables a class implementing a device driver to support multiple device instances. The following -example causes two LED's to flash at different rates. - -.. code:: python - - import pyb, micropython - micropython.alloc_emergency_exception_buf(100) - class Foo(object): - def __init__(self, timer, led): - self.led = led - timer.callback(self.cb) - def cb(self, tim): - self.led.toggle() - - red = Foo(pyb.Timer(4, freq=1), pyb.LED(1)) - green = Foo(pyb.Timer(2, freq=0.8), pyb.LED(2)) - -In this example the ``red`` instance associates timer 4 with LED 1: when a timer 4 interrupt occurs ``red.cb()`` -is called causing LED 1 to change state. The ``green`` instance operates similarly: a timer 2 interrupt -results in the execution of ``green.cb()`` and toggles LED 2. The use of instance methods confers two -benefits. Firstly a single class enables code to be shared between multiple hardware instances. Secondly, as -a bound method the callback function's first argument is ``self``. This enables the callback to access instance -data and to save state between successive calls. For example, if the class above had a variable ``self.count`` -set to zero in the constructor, ``cb()`` could increment the counter. The ``red`` and ``green`` instances would -then maintain independent counts of the number of times each LED had changed state. - -Creation of Python objects -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ISR's cannot create instances of Python objects. This is because MicroPython needs to allocate memory for the -object from a store of free memory block called the heap. This is not permitted in an interrupt handler because -heap allocation is not re-entrant. In other words the interrupt might occur when the main program is part way -through performing an allocation - to maintain the integrity of the heap the interpreter disallows memory -allocations in ISR code. - -A consequence of this is that ISR's can't use floating point arithmetic; this is because floats are Python objects. Similarly -an ISR can't append an item to a list. In practice it can be hard to determine exactly which code constructs will -attempt to perform memory allocation and provoke an error message: another reason for keeping ISR code short and simple. - -One way to avoid this issue is for the ISR to use pre-allocated buffers. For example a class constructor -creates a ``bytearray`` instance and a boolean flag. The ISR method assigns data to locations in the buffer and sets -the flag. The memory allocation occurs in the main program code when the object is instantiated rather than in the ISR. - -The MicroPython library I/O methods usually provide an option to use a pre-allocated buffer. For -example ``pyb.i2c.recv()`` can accept a mutable buffer as its first argument: this enables its use in an ISR. - -A means of creating an object without employing a class or globals is as follows: - -.. code:: python - - def set_volume(t, buf=bytearray(3)): - buf[0] = 0xa5 - buf[1] = t >> 4 - buf[2] = 0x5a - return buf - -The compiler instantiates the default ``buf`` argument when the function is -loaded for the first time (usually when the module it's in is imported). - -Use of Python objects -~~~~~~~~~~~~~~~~~~~~~ - -A further restriction on objects arises because of the way Python works. When an ``import`` statement is executed the -Python code is compiled to bytecode, with one line of code typically mapping to multiple bytecodes. When the code -runs the interpreter reads each bytecode and executes it as a series of machine code instructions. Given that an -interrupt can occur at any time between machine code instructions, the original line of Python code may be only -partially executed. Consequently a Python object such as a set, list or dictionary modified in the main loop -may lack internal consistency at the moment the interrupt occurs. - -A typical outcome is as follows. On rare occasions the ISR will run at the precise moment in time when the object -is partially updated. When the ISR tries to read the object, a crash results. Because such problems typically occur -on rare, random occasions they can be hard to diagnose. There are ways to circumvent this issue, described in -:ref:`Critical Sections <Critical>` below. - -It is important to be clear about what constitutes the modification of an object. An alteration to a built-in type -such as a dictionary is problematic. Altering the contents of an array or bytearray is not. This is because bytes -or words are written as a single machine code instruction which is not interruptible: in the parlance of real time -programming the write is atomic. A user defined object might instantiate an integer, array or bytearray. It is valid -for both the main loop and the ISR to alter the contents of these. - -MicroPython supports integers of arbitrary precision. Values between 2**30 -1 and -2**30 will be stored in -a single machine word. Larger values are stored as Python objects. Consequently changes to long integers cannot -be considered atomic. The use of long integers in ISR's is unsafe because memory allocation may be -attempted as the variable's value changes. - -Overcoming the float limitation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In general it is best to avoid using floats in ISR code: hardware devices normally handle integers and conversion -to floats is normally done in the main loop. However there are a few DSP algorithms which require floating point. -On platforms with hardware floating point (such as the Pyboard) the inline ARM Thumb assembler can be used to work -round this limitation. This is because the processor stores float values in a machine word; values can be shared -between the ISR and main program code via an array of floats. - -Using micropython.schedule -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This function enables an ISR to schedule a callback for execution "very soon". The callback is queued for -execution which will take place at a time when the heap is not locked. Hence it can create Python objects -and use floats. The callback is also guaranteed to run at a time when the main program has completed any -update of Python objects, so the callback will not encounter partially updated objects. - -Typical usage is to handle sensor hardware. The ISR acquires data from the hardware and enables it to -issue a further interrupt. It then schedules a callback to process the data. - -Scheduled callbacks should comply with the principles of interrupt handler design outlined below. This is to -avoid problems resulting from I/O activity and the modification of shared data which can arise in any code -which pre-empts the main program loop. - -Execution time needs to be considered in relation to the frequency with which interrupts can occur. If an -interrupt occurs while the previous callback is executing, a further instance of the callback will be queued -for execution; this will run after the current instance has completed. A sustained high interrupt repetition -rate therefore carries a risk of unconstrained queue growth and eventual failure with a ``RuntimeError``. - -Exceptions ----------- - -If an ISR raises an exception it will not propagate to the main loop. The interrupt will be disabled unless the -exception is handled by the ISR code. - -General Issues --------------- - -This is merely a brief introduction to the subject of real time programming. Beginners should note -that design errors in real time programs can lead to faults which are particularly hard to diagnose. This is because -they can occur rarely and at intervals which are essentially random. It is crucial to get the initial design right and -to anticipate issues before they arise. Both interrupt handlers and the main program need to be designed -with an appreciation of the following issues. - -.. _ISR: - -Interrupt Handler Design -~~~~~~~~~~~~~~~~~~~~~~~~ - -As mentioned above, ISR's should be designed to be as simple as possible. They should always return in a short, -predictable period of time. This is important because when the ISR is running, the main loop is not: inevitably -the main loop experiences pauses in its execution at random points in the code. Such pauses can be a source of hard -to diagnose bugs particularly if their duration is long or variable. In order to understand the implications of -ISR run time, a basic grasp of interrupt priorities is required. - -Interrupts are organised according to a priority scheme. ISR code may itself be interrupted by a higher priority -interrupt. This has implications if the two interrupts share data (see Critical Sections below). If such an interrupt -occurs it interposes a delay into the ISR code. If a lower priority interrupt occurs while the ISR is running, it -will be delayed until the ISR is complete: if the delay is too long, the lower priority interrupt may fail. A -further issue with slow ISR's is the case where a second interrupt of the same type occurs during its execution. -The second interrupt will be handled on termination of the first. However if the rate of incoming interrupts -consistently exceeds the capacity of the ISR to service them the outcome will not be a happy one. - -Consequently looping constructs should be avoided or minimised. I/O to devices other than to the interrupting device -should normally be avoided: I/O such as disk access, ``print`` statements and UART access is relatively slow, and -its duration may vary. A further issue here is that filesystem functions are not reentrant: using filesystem I/O -in an ISR and the main program would be hazardous. Crucially ISR code should not wait on an event. I/O is acceptable -if the code can be guaranteed to return in a predictable period, for example toggling a pin or LED. Accessing the -interrupting device via I2C or SPI may be necessary but the time taken for such accesses should be calculated or -measured and its impact on the application assessed. - -There is usually a need to share data between the ISR and the main loop. This may be done either through global -variables or via class or instance variables. Variables are typically integer or boolean types, or integer or byte -arrays (a pre-allocated integer array offers faster access than a list). Where multiple values are modified by -the ISR it is necessary to consider the case where the interrupt occurs at a time when the main program has -accessed some, but not all, of the values. This can lead to inconsistencies. - -Consider the following design. An ISR stores incoming data in a bytearray, then adds the number of bytes -received to an integer representing total bytes ready for processing. The main program reads the number of bytes, -processes the bytes, then clears down the number of bytes ready. This will work until an interrupt occurs just -after the main program has read the number of bytes. The ISR puts the added data into the buffer and updates -the number received, but the main program has already read the number, so processes the data originally received. -The newly arrived bytes are lost. - -There are various ways of avoiding this hazard, the simplest being to use a circular buffer. If it is not possible -to use a structure with inherent thread safety other ways are described below. - -Reentrancy -~~~~~~~~~~ - -A potential hazard may occur if a function or method is shared between the main program and one or more ISR's or -between multiple ISR's. The issue here is that the function may itself be interrupted and a further instance of -that function run. If this is to occur, the function must be designed to be reentrant. How this is done is an -advanced topic beyond the scope of this tutorial. - -.. _Critical: - -Critical Sections -~~~~~~~~~~~~~~~~~ - -An example of a critical section of code is one which accesses more than one variable which can be affected by an ISR. If -the interrupt happens to occur between accesses to the individual variables, their values will be inconsistent. This is -an instance of a hazard known as a race condition: the ISR and the main program loop race to alter the variables. To -avoid inconsistency a means must be employed to ensure that the ISR does not alter the values for the duration of -the critical section. One way to achieve this is to issue ``pyb.disable_irq()`` before the start of the section, and -``pyb.enable_irq()`` at the end. Here is an example of this approach: - -.. code:: python - - import pyb, micropython, array - micropython.alloc_emergency_exception_buf(100) - - class BoundsException(Exception): - pass - - ARRAYSIZE = const(20) - index = 0 - data = array.array('i', 0 for x in range(ARRAYSIZE)) - - def callback1(t): - global data, index - for x in range(5): - data[index] = pyb.rng() # simulate input - index += 1 - if index >= ARRAYSIZE: - raise BoundsException('Array bounds exceeded') - - tim4 = pyb.Timer(4, freq=100, callback=callback1) - - for loop in range(1000): - if index > 0: - irq_state = pyb.disable_irq() # Start of critical section - for x in range(index): - print(data[x]) - index = 0 - pyb.enable_irq(irq_state) # End of critical section - print('loop {}'.format(loop)) - pyb.delay(1) - - tim4.callback(None) - -A critical section can comprise a single line of code and a single variable. Consider the following code fragment. - -.. code:: python - - count = 0 - def cb(): # An interrupt callback - count +=1 - def main(): - # Code to set up the interrupt callback omitted - while True: - count += 1 - -This example illustrates a subtle source of bugs. The line ``count += 1`` in the main loop carries a specific race -condition hazard known as a read-modify-write. This is a classic cause of bugs in real time systems. In the main loop -MicroPython reads the value of ``t.counter``, adds 1 to it, and writes it back. On rare occasions the interrupt occurs -after the read and before the write. The interrupt modifies ``t.counter`` but its change is overwritten by the main -loop when the ISR returns. In a real system this could lead to rare, unpredictable failures. - -As mentioned above, care should be taken if an instance of a Python built in type is modified in the main code and -that instance is accessed in an ISR. The code performing the modification should be regarded as a critical -section to ensure that the instance is in a valid state when the ISR runs. - -Particular care needs to be taken if a dataset is shared between different ISR's. The hazard here is that the higher -priority interrupt may occur when the lower priority one has partially updated the shared data. Dealing with this -situation is an advanced topic beyond the scope of this introduction other than to note that mutex objects described -below can sometimes be used. - -Disabling interrupts for the duration of a critical section is the usual and simplest way to proceed, but it disables -all interrupts rather than merely the one with the potential to cause problems. It is generally undesirable to disable -an interrupt for long. In the case of timer interrupts it introduces variability to the time when a callback occurs. -In the case of device interrupts, it can lead to the device being serviced too late with possible loss of data or -overrun errors in the device hardware. Like ISR's, a critical section in the main code should have a short, predictable -duration. - -An approach to dealing with critical sections which radically reduces the time for which interrupts are disabled is to -use an object termed a mutex (name derived from the notion of mutual exclusion). The main program locks the mutex -before running the critical section and unlocks it at the end. The ISR tests whether the mutex is locked. If it is, -it avoids the critical section and returns. The design challenge is defining what the ISR should do in the event -that access to the critical variables is denied. A simple example of a mutex may be found -`here <https://github.com/peterhinch/micropython-samples.git>`_. Note that the mutex code does disable interrupts, -but only for the duration of eight machine instructions: the benefit of this approach is that other interrupts are -virtually unaffected. - -Interrupts and the REPL -~~~~~~~~~~~~~~~~~~~~~~~ - -Interrupt handlers, such as those associated with timers, can continue to run -after a program terminates. This may produce unexpected results where you might -have expected the object raising the callback to have gone out of scope. For -example on the Pyboard: - -.. code:: python - - def bar(): - foo = pyb.Timer(2, freq=4, callback=lambda t: print('.', end='')) - - bar() - -This continues to run until the timer is explicitly disabled or the board is -reset with ``ctrl D``. diff --git a/docs/reference/repl.rst b/docs/reference/repl.rst deleted file mode 100644 index 7a683ca22..000000000 --- a/docs/reference/repl.rst +++ /dev/null @@ -1,211 +0,0 @@ -The MicroPython Interactive Interpreter Mode (aka REPL) -======================================================= - -This section covers some characteristics of the MicroPython Interactive -Interpreter Mode. A commonly used term for this is REPL (read-eval-print-loop) -which will be used to refer to this interactive prompt. - -Auto-indent ------------ - -When typing python statements which end in a colon (for example if, for, while) -then the prompt will change to three dots (...) and the cursor will be indented -by 4 spaces. When you press return, the next line will continue at the same -level of indentation for regular statements or an additional level of indentation -where appropriate. If you press the backspace key then it will undo one -level of indentation. - -If your cursor is all the way back at the beginning, pressing RETURN will then -execute the code that you've entered. The following shows what you'd see -after entering a for statement (the underscore shows where the cursor winds up): - - >>> for i in range(3): - ... _ - -If you then enter an if statement, an additional level of indentation will be -provided: - - >>> for i in range(30): - ... if i > 3: - ... _ - -Now enter ``break`` followed by RETURN and press BACKSPACE: - - >>> for i in range(30): - ... if i > 3: - ... break - ... _ - -Finally type ``print(i)``, press RETURN, press BACKSPACE and press RETURN again: - - >>> for i in range(30): - ... if i > 3: - ... break - ... print(i) - ... - 0 - 1 - 2 - 3 - >>> - -Auto-indent won't be applied if the previous two lines were all spaces. This -means that you can finish entering a compound statement by pressing RETURN -twice, and then a third press will finish and execute. - -Auto-completion ---------------- - -While typing a command at the REPL, if the line typed so far corresponds to -the beginning of the name of something, then pressing TAB will show -possible things that could be entered. For example type ``m`` and press TAB -and it should expand to ``machine``. Enter a dot ``.`` and press TAB again. You -should see something like: - - >>> machine. - __name__ info unique_id reset - bootloader freq rng idle - sleep deepsleep disable_irq enable_irq - Pin - -The word will be expanded as much as possible until multiple possibilities exist. -For example, type ``machine.Pin.AF3`` and press TAB and it will expand to -``machine.Pin.AF3_TIM``. Pressing TAB a second time will show the possible -expansions: - - >>> machine.Pin.AF3_TIM - AF3_TIM10 AF3_TIM11 AF3_TIM8 AF3_TIM9 - >>> machine.Pin.AF3_TIM - -Interrupting a running program ------------------------------- - -You can interrupt a running program by pressing Ctrl-C. This will raise a KeyboardInterrupt -which will bring you back to the REPL, providing your program doesn't intercept the -KeyboardInterrupt exception. - -For example: - - >>> for i in range(1000000): - ... print(i) - ... - 0 - 1 - 2 - 3 - ... - 6466 - 6467 - 6468 - Traceback (most recent call last): - File "<stdin>", line 2, in <module> - KeyboardInterrupt: - >>> - -Paste Mode ----------- - -If you want to paste some code into your terminal window, the auto-indent feature -will mess things up. For example, if you had the following python code: :: - - def foo(): - print('This is a test to show paste mode') - print('Here is a second line') - foo() - -and you try to paste this into the normal REPL, then you will see something like -this: - - >>> def foo(): - ... print('This is a test to show paste mode') - ... print('Here is a second line') - ... foo() - ... - Traceback (most recent call last): - File "<stdin>", line 3 - IndentationError: unexpected indent - -If you press Ctrl-E, then you will enter paste mode, which essentially turns off -the auto-indent feature, and changes the prompt from ``>>>`` to ``===``. For example: - - >>> - paste mode; Ctrl-C to cancel, Ctrl-D to finish - === def foo(): - === print('This is a test to show paste mode') - === print('Here is a second line') - === foo() - === - This is a test to show paste mode - Here is a second line - >>> - -Paste Mode allows blank lines to be pasted. The pasted text is compiled as if -it were a file. Pressing Ctrl-D exits paste mode and initiates the compilation. - -Soft Reset ----------- - -A soft reset will reset the python interpreter, but tries not to reset the -method by which you're connected to the MicroPython board (USB-serial, or Wifi). - -You can perform a soft reset from the REPL by pressing Ctrl-D, or from your python -code by executing: :: - - raise SystemExit - -For example, if you reset your MicroPython board, and you execute a dir() -command, you'd see something like this: - - >>> dir() - ['__name__', 'pyb'] - -Now create some variables and repeat the dir() command: - - >>> i = 1 - >>> j = 23 - >>> x = 'abc' - >>> dir() - ['j', 'x', '__name__', 'pyb', 'i'] - >>> - -Now if you enter Ctrl-D, and repeat the dir() command, you'll see that your -variables no longer exist: - -.. code-block:: python - - PYB: sync filesystems - PYB: soft reboot - MicroPython v1.5-51-g6f70283-dirty on 2015-10-30; PYBv1.0 with STM32F405RG - Type "help()" for more information. - >>> dir() - ['__name__', 'pyb'] - >>> - -The special variable _ (underscore) ------------------------------------ - -When you use the REPL, you may perform computations and see the results. -MicroPython stores the results of the previous statement in the variable _ (underscore). -So you can use the underscore to save the result in a variable. For example: - - >>> 1 + 2 + 3 + 4 + 5 - 15 - >>> x = _ - >>> x - 15 - >>> - -Raw Mode --------- - -Raw mode is not something that a person would normally use. It is intended for -programmatic use. It essentially behaves like paste mode with echo turned off. - -Raw mode is entered using Ctrl-A. You then send your python code, followed by -a Ctrl-D. The Ctrl-D will be acknowledged by 'OK' and then the python code will -be compiled and executed. Any output (or errors) will be sent back. Entering -Ctrl-B will leave raw mode and return the the regular (aka friendly) REPL. - -The ``tools/pyboard.py`` program uses the raw REPL to execute python files on the -MicroPython board. - diff --git a/docs/reference/speed_python.rst b/docs/reference/speed_python.rst deleted file mode 100644 index 279a1bbcd..000000000 --- a/docs/reference/speed_python.rst +++ /dev/null @@ -1,342 +0,0 @@ -Maximising MicroPython Speed -============================ - -.. contents:: - -This tutorial describes ways of improving the performance of MicroPython code. -Optimisations involving other languages are covered elsewhere, namely the use -of modules written in C and the MicroPython inline assembler. - -The process of developing high performance code comprises the following stages -which should be performed in the order listed. - -* Design for speed. -* Code and debug. - -Optimisation steps: - -* Identify the slowest section of code. -* Improve the efficiency of the Python code. -* Use the native code emitter. -* Use the viper code emitter. -* Use hardware-specific optimisations. - -Designing for speed -------------------- - -Performance issues should be considered at the outset. This involves taking a view -on the sections of code which are most performance critical and devoting particular -attention to their design. The process of optimisation begins when the code has -been tested: if the design is correct at the outset optimisation will be -straightforward and may actually be unnecessary. - -Algorithms -~~~~~~~~~~ - -The most important aspect of designing any routine for performance is ensuring that -the best algorithm is employed. This is a topic for textbooks rather than for a -MicroPython guide but spectacular performance gains can sometimes be achieved -by adopting algorithms known for their efficiency. - -RAM Allocation -~~~~~~~~~~~~~~ - -To design efficient MicroPython code it is necessary to have an understanding of the -way the interpreter allocates RAM. When an object is created or grows in size -(for example where an item is appended to a list) the necessary RAM is allocated -from a block known as the heap. This takes a significant amount of time; -further it will on occasion trigger a process known as garbage collection which -can take several milliseconds. - -Consequently the performance of a function or method can be improved if an object is created -once only and not permitted to grow in size. This implies that the object persists -for the duration of its use: typically it will be instantiated in a class constructor -and used in various methods. - -This is covered in further detail :ref:`Controlling garbage collection <controlling_gc>` below. - -Buffers -~~~~~~~ - -An example of the above is the common case where a buffer is required, such as one -used for communication with a device. A typical driver will create the buffer in the -constructor and use it in its I/O methods which will be called repeatedly. - -The MicroPython libraries typically provide support for pre-allocated buffers. For -example, objects which support stream interface (e.g., file or UART) provide `read()` -method which allocates new buffer for read data, but also a `readinto()` method -to read data into an existing buffer. - -Floating Point -~~~~~~~~~~~~~~ - -Some MicroPython ports allocate floating point numbers on heap. Some other ports -may lack dedicated floating-point coprocessor, and perform arithmetic operations -on them in "software" at considerably lower speed than on integers. Where -performance is important, use integer operations and restrict the use of floating -point to sections of the code where performance is not paramount. For example, -capture ADC readings as integers values to an array in one quick go, and only then -convert them to floating-point numbers for signal processing. - -Arrays -~~~~~~ - -Consider the use of the various types of array classes as an alternative to lists. -The `array` module supports various element types with 8-bit elements supported -by Python's built in `bytes` and `bytearray` classes. These data structures all store -elements in contiguous memory locations. Once again to avoid memory allocation in critical -code these should be pre-allocated and passed as arguments or as bound objects. - -When passing slices of objects such as `bytearray` instances, Python creates -a copy which involves allocation of the size proportional to the size of slice. -This can be alleviated using a `memoryview` object. `memoryview` itself -is allocated on heap, but is a small, fixed-size object, regardless of the size -of slice it points too. - -.. code:: python - - ba = bytearray(10000) # big array - func(ba[30:2000]) # a copy is passed, ~2K new allocation - mv = memoryview(ba) # small object is allocated - func(mv[30:2000]) # a pointer to memory is passed - -A `memoryview` can only be applied to objects supporting the buffer protocol - this -includes arrays but not lists. Small caveat is that while memoryview object is live, -it also keeps alive the original buffer object. So, a memoryview isn't a universal -panacea. For instance, in the example above, if you are done with 10K buffer and -just need those bytes 30:2000 from it, it may be better to make a slice, and let -the 10K buffer go (be ready for garbage collection), instead of making a -long-living memoryview and keeping 10K blocked for GC. - -Nonetheless, `memoryview` is indispensable for advanced preallocated buffer -management. `readinto()` method discussed above puts data at the beginning -of buffer and fills in entire buffer. What if you need to put data in the -middle of existing buffer? Just create a memoryview into the needed section -of buffer and pass it to `readinto()`. - -Identifying the slowest section of code ---------------------------------------- - -This is a process known as profiling and is covered in textbooks and -(for standard Python) supported by various software tools. For the type of -smaller embedded application likely to be running on MicroPython platforms -the slowest function or method can usually be established by judicious use -of the timing ``ticks`` group of functions documented in `utime`. -Code execution time can be measured in ms, us, or CPU cycles. - -The following enables any function or method to be timed by adding an -``@timed_function`` decorator: - -.. code:: python - - def timed_function(f, *args, **kwargs): - myname = str(f).split(' ')[1] - def new_func(*args, **kwargs): - t = utime.ticks_us() - result = f(*args, **kwargs) - delta = utime.ticks_diff(utime.ticks_us(), t) - print('Function {} Time = {:6.3f}ms'.format(myname, delta/1000)) - return result - return new_func - -MicroPython code improvements ------------------------------ - -The const() declaration -~~~~~~~~~~~~~~~~~~~~~~~ - -MicroPython provides a ``const()`` declaration. This works in a similar way -to ``#define`` in C in that when the code is compiled to bytecode the compiler -substitutes the numeric value for the identifier. This avoids a dictionary -lookup at runtime. The argument to ``const()`` may be anything which, at -compile time, evaluates to an integer e.g. ``0x100`` or ``1 << 8``. - -.. _Caching: - -Caching object references -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Where a function or method repeatedly accesses objects performance is improved -by caching the object in a local variable: - -.. code:: python - - class foo(object): - def __init__(self): - ba = bytearray(100) - def bar(self, obj_display): - ba_ref = self.ba - fb = obj_display.framebuffer - # iterative code using these two objects - -This avoids the need repeatedly to look up ``self.ba`` and ``obj_display.framebuffer`` -in the body of the method ``bar()``. - -.. _controlling_gc: - -Controlling garbage collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When memory allocation is required, MicroPython attempts to locate an adequately -sized block on the heap. This may fail, usually because the heap is cluttered -with objects which are no longer referenced by code. If a failure occurs, the -process known as garbage collection reclaims the memory used by these redundant -objects and the allocation is then tried again - a process which can take several -milliseconds. - -There may be benefits in pre-empting this by periodically issuing `gc.collect()`. -Firstly doing a collection before it is actually required is quicker - typically on the -order of 1ms if done frequently. Secondly you can determine the point in code -where this time is used rather than have a longer delay occur at random points, -possibly in a speed critical section. Finally performing collections regularly -can reduce fragmentation in the heap. Severe fragmentation can lead to -non-recoverable allocation failures. - -The Native code emitter ------------------------ - -This causes the MicroPython compiler to emit native CPU opcodes rather than -bytecode. It covers the bulk of the MicroPython functionality, so most functions will require -no adaptation (but see below). It is invoked by means of a function decorator: - -.. code:: python - - @micropython.native - def foo(self, arg): - buf = self.linebuf # Cached object - # code - -There are certain limitations in the current implementation of the native code emitter. - -* Context managers are not supported (the ``with`` statement). -* Generators are not supported. -* If ``raise`` is used an argument must be supplied. - -The trade-off for the improved performance (roughly twices as fast as bytecode) is an -increase in compiled code size. - -The Viper code emitter ----------------------- - -The optimisations discussed above involve standards-compliant Python code. The -Viper code emitter is not fully compliant. It supports special Viper native data types -in pursuit of performance. Integer processing is non-compliant because it uses machine -words: arithmetic on 32 bit hardware is performed modulo 2**32. - -Like the Native emitter Viper produces machine instructions but further optimisations -are performed, substantially increasing performance especially for integer arithmetic and -bit manipulations. It is invoked using a decorator: - -.. code:: python - - @micropython.viper - def foo(self, arg: int) -> int: - # code - -As the above fragment illustrates it is beneficial to use Python type hints to assist the Viper optimiser. -Type hints provide information on the data types of arguments and of the return value; these -are a standard Python language feature formally defined here `PEP0484 <https://www.python.org/dev/peps/pep-0484/>`_. -Viper supports its own set of types namely ``int``, ``uint`` (unsigned integer), ``ptr``, ``ptr8``, -``ptr16`` and ``ptr32``. The ``ptrX`` types are discussed below. Currently the ``uint`` type serves -a single purpose: as a type hint for a function return value. If such a function returns ``0xffffffff`` -Python will interpret the result as 2**32 -1 rather than as -1. - -In addition to the restrictions imposed by the native emitter the following constraints apply: - -* Functions may have up to four arguments. -* Default argument values are not permitted. -* Floating point may be used but is not optimised. - -Viper provides pointer types to assist the optimiser. These comprise - -* ``ptr`` Pointer to an object. -* ``ptr8`` Points to a byte. -* ``ptr16`` Points to a 16 bit half-word. -* ``ptr32`` Points to a 32 bit machine word. - -The concept of a pointer may be unfamiliar to Python programmers. It has similarities -to a Python `memoryview` object in that it provides direct access to data stored in memory. -Items are accessed using subscript notation, but slices are not supported: a pointer can return -a single item only. Its purpose is to provide fast random access to data stored in contiguous -memory locations - such as data stored in objects which support the buffer protocol, and -memory-mapped peripheral registers in a microcontroller. It should be noted that programming -using pointers is hazardous: bounds checking is not performed and the compiler does nothing to -prevent buffer overrun errors. - -Typical usage is to cache variables: - -.. code:: python - - @micropython.viper - def foo(self, arg: int) -> int: - buf = ptr8(self.linebuf) # self.linebuf is a bytearray or bytes object - for x in range(20, 30): - bar = buf[x] # Access a data item through the pointer - # code omitted - -In this instance the compiler "knows" that ``buf`` is the address of an array of bytes; -it can emit code to rapidly compute the address of ``buf[x]`` at runtime. Where casts are -used to convert objects to Viper native types these should be performed at the start of -the function rather than in critical timing loops as the cast operation can take several -microseconds. The rules for casting are as follows: - -* Casting operators are currently: ``int``, ``bool``, ``uint``, ``ptr``, ``ptr8``, ``ptr16`` and ``ptr32``. -* The result of a cast will be a native Viper variable. -* Arguments to a cast can be a Python object or a native Viper variable. -* If argument is a native Viper variable, then cast is a no-op (i.e. costs nothing at runtime) - that just changes the type (e.g. from ``uint`` to ``ptr8``) so that you can then store/load - using this pointer. -* If the argument is a Python object and the cast is ``int`` or ``uint``, then the Python object - must be of integral type and the value of that integral object is returned. -* The argument to a bool cast must be integral type (boolean or integer); when used as a return - type the viper function will return True or False objects. -* If the argument is a Python object and the cast is ``ptr``, ``ptr``, ``ptr16`` or ``ptr32``, - then the Python object must either have the buffer protocol with read-write capabilities - (in which case a pointer to the start of the buffer is returned) or it must be of integral - type (in which case the value of that integral object is returned). - -The following example illustrates the use of a ``ptr16`` cast to toggle pin X1 ``n`` times: - -.. code:: python - - BIT0 = const(1) - @micropython.viper - def toggle_n(n: int): - odr = ptr16(stm.GPIOA + stm.GPIO_ODR) - for _ in range(n): - odr[0] ^= BIT0 - -A detailed technical description of the three code emitters may be found -on Kickstarter here `Note 1 <https://www.kickstarter.com/projects/214379695/micro-python-python-for-microcontrollers/posts/664832>`_ -and here `Note 2 <https://www.kickstarter.com/projects/214379695/micro-python-python-for-microcontrollers/posts/665145>`_ - -Accessing hardware directly ---------------------------- - -.. note:: - - Code examples in this section are given for the Pyboard. The techniques - described however may be applied to other MicroPython ports too. - -This comes into the category of more advanced programming and involves some knowledge -of the target MCU. Consider the example of toggling an output pin on the Pyboard. The -standard approach would be to write - -.. code:: python - - mypin.value(mypin.value() ^ 1) # mypin was instantiated as an output pin - -This involves the overhead of two calls to the `Pin` instance's :meth:`~machine.Pin.value()` -method. This overhead can be eliminated by performing a read/write to the relevant bit -of the chip's GPIO port output data register (odr). To facilitate this the ``stm`` -module provides a set of constants providing the addresses of the relevant registers. -A fast toggle of pin ``P4`` (CPU pin ``A14``) - corresponding to the green LED - -can be performed as follows: - -.. code:: python - - import machine - import stm - - BIT14 = const(1 << 14) - machine.mem16[stm.GPIOA + stm.GPIO_ODR] ^= BIT14 diff --git a/docs/sphinx_selective_exclude/LICENSE b/docs/sphinx_selective_exclude/LICENSE deleted file mode 100644 index 0b47ced8a..000000000 --- a/docs/sphinx_selective_exclude/LICENSE +++ /dev/null @@ -1,25 +0,0 @@ -Copyright (c) 2016 by the sphinx_selective_exclude authors. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -* Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/sphinx_selective_exclude/README.md b/docs/sphinx_selective_exclude/README.md deleted file mode 100644 index dab140739..000000000 --- a/docs/sphinx_selective_exclude/README.md +++ /dev/null @@ -1,138 +0,0 @@ -Sphinx eager ".. only::" directive and other selective rendition extensions -=========================================================================== - -Project home page: https://github.com/pfalcon/sphinx_selective_exclude - -The implementation of ".. only::" directive in Sphinx documentation -generation tool is known to violate principles of least user surprise -and user expectations in general. Instead of excluding content early -in the pipeline (pre-processor style), Sphinx defers exclusion until -output phase, and what's the worst, various stages processing ignore -"only" blocks and their exclusion status, so they may leak unexpected -information into ToC, indexes, etc. - -There's multiple issues submitted upstream on this matter: - -* https://github.com/sphinx-doc/sphinx/issues/2150 -* https://github.com/sphinx-doc/sphinx/issues/1717 -* https://github.com/sphinx-doc/sphinx/issues/1488 -* etc. - -They are largely ignored by Sphinx maintainers. - -This projects tries to rectify situation on users' side. It actually -changes the way Sphinx processes "only" directive, but does this -without forking the project, and instead is made as a standard -Sphinx extension, which a user may add to their documentation config. -Unlike normal extensions, extensions provided in this package -monkey-patch Sphinx core to work in a way expected by users. - -eager_only ----------- - -The core extension provided by the package is called `eager_only` and -is based on the idea by Andrea Cassioli (see bugreports above) to -process "only" directive as soon as possible during parsing phase. -This approach has some drawbacks, like producing warnings like -"WARNING: document isn't included in any toctree" if "only" is used -to shape up a toctree, or the fact that changing a documentation -builder (html/latex/etc.) will almost certainly require complete -rebuild of documentation. But these are relatively minor issues -comparing to completely broken way "only" works in upstream Sphinx. - -modindex_exclude ----------------- - -"only" directive allows for fine-grained conditional exclusion, but -sometimes you may want to exclude entire module(s) at once. Even if -you wrap an entire module description in "only" directive, like: - - .. only: option1 - .. module:: my_module - - ... - -You will still have an HTML page generated, albeit empty. It may also -go into indexes, so will be discoverable by users, leading to less -than ideal experience. `modindex_exclude` extension is design to -resolve this issue, by making sure that any reference of a module -is excluded from Python module index ("modindex"), as well as -general cross-reference index ("genindex"). In the latter case, -any symbol belong to a module will be excluded. Unlike `eager_only` -extension which appear to have issued with "latexpdf" builder, -`modindex_exclude` is useful for PDF, and allows to get cleaner -index for PDF, just the same as for HTML. - -search_auto_exclude -------------------- - -Even if you exclude some documents from toctree:: using only:: -directive, they will be indexed for full-text search, so user may -find them and get confused. This plugin follows very simple idea -that if you didn't include some documents in the toctree, then -you didn't want them to be accessible (e.g. for a particular -configuration), and so will make sure they aren't indexed either. - -This extension depends on `eager_only` and won't work without it. -Note that Sphinx will issue warnings, as usual, for any documents -not included in a toctree. This is considered a feature, and gives -you a chance to check that document exclusions are indeed right -for a particular configuration you build (and not that you forgot -to add something to a toctree). - -Summary -------- - -Based on the above, sphinx_selective_exclude offers extension to let -you: - -* Make "only::" directive work in an expected, intuitive manner, using - `eager_only` extension. -* However, if you apply only:: to toctree::, excluded documents will - still be available via full-text search, so you need to use - `search_auto_exclude` for that to work as expected. -* Similar to search, indexes may also require special treatment, hence - there's the `modindex_exclude` extension. - -Most likely, you will want to use all 3 extensions together - if you -really want build subsets of docimentation covering sufficiently different -configurations from a single doctree. However, if one of them is enough -to cover your usecase, that's OK to (and why they were separated into -3 extensions, to follow KISS and "least surprise" principles and to -not make people deal with things they aren't interested in). In this case, -however remember there're other extensions, if you later hit a usecase -when they're needed. - -Usage ------ - -To use these extensions, add https://github.com/pfalcon/sphinx_selective_exclude -as a git submodule to your project, in documentation folder (where -Sphinx conf.py is located). Alternatively, commit sphinx_selective_exclude -directory instead of making it a submodule (you will need to pick up -any project updates manually then). - -Add following lines to "extensions" settings in your conf.py (you -likely already have some standard Sphinx extensions enabled): - - extensions = [ - ... - 'sphinx_selective_exclude.eager_only', - 'sphinx_selective_exclude.search_auto_exclude', - 'sphinx_selective_exclude.modindex_exclude', - ] - -As discussed above, you may enable all extensions, or one by one. - -Please note that to make sure these extensions work well and avoid producing -output docs with artifacts, it is IMPERATIVE to remove cached doctree if -you rebuild documentation with another builder (i.e. with different output -format). Also, to stay on safe side, it's recommended to remove old doctree -anyway before generating production-ready documentation for publishing. To -do that, run something like: - - rm -rf _build/doctrees/ - -A typical artificat when not following these simple rules is that content -of some sections may be missing. If you face anything like that, just -remember what's written above and remove cached doctrees. diff --git a/docs/sphinx_selective_exclude/__init__.py b/docs/sphinx_selective_exclude/__init__.py deleted file mode 100644 index e69de29bb..000000000 --- a/docs/sphinx_selective_exclude/__init__.py +++ /dev/null diff --git a/docs/sphinx_selective_exclude/eager_only.py b/docs/sphinx_selective_exclude/eager_only.py deleted file mode 100644 index 82766c2e6..000000000 --- a/docs/sphinx_selective_exclude/eager_only.py +++ /dev/null @@ -1,45 +0,0 @@ -# -# This is a Sphinx documentation tool extension which makes .only:: -# directives be eagerly processed early in the parsing stage. This -# makes sure that content in .only:: blocks gets actually excluded -# as a typical user expects, instead of bits of information in -# these blocks leaking to documentation in various ways (e.g., -# indexes containing entries for functions which are actually in -# .only:: blocks and thus excluded from documentation, etc.) -# Note that with this extension, you may need to completely -# rebuild a doctree when switching builders (i.e. completely -# remove _build/doctree dir between generation of HTML vs PDF -# documentation). -# -# This extension works by monkey-patching Sphinx core, so potentially -# may not work with untested Sphinx versions. It tested to work with -# 1.2.2 and 1.4.2 -# -# Copyright (c) 2016 Paul Sokolovsky -# Based on idea by Andrea Cassioli: -# https://github.com/sphinx-doc/sphinx/issues/2150#issuecomment-171912290 -# Licensed under the terms of BSD license, see LICENSE file. -# -import sphinx -from docutils.parsers.rst import directives - - -class EagerOnly(sphinx.directives.other.Only): - - def run(self, *args): - # Evaluate the condition eagerly, and if false return no nodes right away - env = self.state.document.settings.env - env.app.builder.tags.add('TRUE') - #print(repr(self.arguments[0])) - if not env.app.builder.tags.eval_condition(self.arguments[0]): - return [] - - # Otherwise, do the usual processing - nodes = super(EagerOnly, self).run() - if len(nodes) == 1: - nodes[0]['expr'] = 'TRUE' - return nodes - - -def setup(app): - directives.register_directive('only', EagerOnly) diff --git a/docs/sphinx_selective_exclude/modindex_exclude.py b/docs/sphinx_selective_exclude/modindex_exclude.py deleted file mode 100644 index bf8db795e..000000000 --- a/docs/sphinx_selective_exclude/modindex_exclude.py +++ /dev/null @@ -1,75 +0,0 @@ -# -# This is a Sphinx documentation tool extension which allows to -# exclude some Python modules from the generated indexes. Modules -# are excluded both from "modindex" and "genindex" index tables -# (in the latter case, all members of a module are excluded). -# To control exclusion, set "modindex_exclude" variable in Sphinx -# conf.py to the list of modules to exclude. Note: these should be -# modules (as defined by py:module directive, not just raw filenames). -# This extension works by monkey-patching Sphinx core, so potentially -# may not work with untested Sphinx versions. It tested to work with -# 1.2.2 and 1.4.2 -# -# Copyright (c) 2016 Paul Sokolovsky -# Licensed under the terms of BSD license, see LICENSE file. -# -import sphinx - - -#org_PythonModuleIndex_generate = None -org_PyObject_add_target_and_index = None -org_PyModule_run = None - -EXCLUDES = {} - -# No longer used, PyModule_run() monkey-patch does all the job -def PythonModuleIndex_generate(self, docnames=None): - docnames = [] - excludes = self.domain.env.config['modindex_exclude'] - for modname, (docname, synopsis, platforms, deprecated) in self.domain.data['modules'].items(): - #print(docname) - if modname not in excludes: - docnames.append(docname) - - return org_PythonModuleIndex_generate(self, docnames) - - -def PyObject_add_target_and_index(self, name_cls, sig, signode): - if hasattr(self.env, "ref_context"): - # Sphinx 1.4 - ref_context = self.env.ref_context - else: - # Sphinx 1.2 - ref_context = self.env.temp_data - modname = self.options.get( - 'module', ref_context.get('py:module')) - #print("*", modname, name_cls) - if modname in self.env.config['modindex_exclude']: - return None - return org_PyObject_add_target_and_index(self, name_cls, sig, signode) - - -def PyModule_run(self): - env = self.state.document.settings.env - modname = self.arguments[0].strip() - excl = env.config['modindex_exclude'] - if modname in excl: - self.options['noindex'] = True - EXCLUDES.setdefault(modname, []).append(env.docname) - return org_PyModule_run(self) - - -def setup(app): - app.add_config_value('modindex_exclude', [], 'html') - -# global org_PythonModuleIndex_generate -# org_PythonModuleIndex_generate = sphinx.domains.python.PythonModuleIndex.generate -# sphinx.domains.python.PythonModuleIndex.generate = PythonModuleIndex_generate - - global org_PyObject_add_target_and_index - org_PyObject_add_target_and_index = sphinx.domains.python.PyObject.add_target_and_index - sphinx.domains.python.PyObject.add_target_and_index = PyObject_add_target_and_index - - global org_PyModule_run - org_PyModule_run = sphinx.domains.python.PyModule.run - sphinx.domains.python.PyModule.run = PyModule_run diff --git a/docs/sphinx_selective_exclude/search_auto_exclude.py b/docs/sphinx_selective_exclude/search_auto_exclude.py deleted file mode 100644 index b8b326dd2..000000000 --- a/docs/sphinx_selective_exclude/search_auto_exclude.py +++ /dev/null @@ -1,34 +0,0 @@ -# -# This is a Sphinx documentation tool extension which allows to -# automatically exclude from full-text search index document -# which are not referenced via toctree::. It's intended to be -# used with toctrees conditional on only:: directive, with the -# idea being that if you didn't include it in the ToC, you don't -# want the docs being findable by search either (for example, -# because these docs contain information not pertinent to a -# particular product configuration). -# -# This extension depends on "eager_only" extension and won't work -# without it. -# -# Copyright (c) 2016 Paul Sokolovsky -# Licensed under the terms of BSD license, see LICENSE file. -# -import sphinx - - -org_StandaloneHTMLBuilder_index_page = None - - -def StandaloneHTMLBuilder_index_page(self, pagename, doctree, title): - if pagename not in self.env.files_to_rebuild: - if pagename != self.env.config.master_doc and 'orphan' not in self.env.metadata[pagename]: - print("Excluding %s from full-text index because it's not referenced in ToC" % pagename) - return - return org_StandaloneHTMLBuilder_index_page(self, pagename, doctree, title) - - -def setup(app): - global org_StandaloneHTMLBuilder_index_page - org_StandaloneHTMLBuilder_index_page = sphinx.builders.html.StandaloneHTMLBuilder.index_page - sphinx.builders.html.StandaloneHTMLBuilder.index_page = StandaloneHTMLBuilder_index_page diff --git a/docs/supported_ports.rst b/docs/supported_ports.rst index 2a5b71a19..039ddea68 100644 --- a/docs/supported_ports.rst +++ b/docs/supported_ports.rst @@ -1,11 +1,12 @@ Supported Ports ============================== -Adafruit's CircuitPython derivative currently has limited support with a focus on -the Atmel SAMD21 port and ESP8266 port. +Adafruit's CircuitPython currently has limited support with a focus on supporting the Atmel SAMD +and ESP8266. .. toctree:: :maxdepth: 2 - ../atmel-samd/README - esp8266/index.rst + ../ports/atmel-samd/README + ../ports/esp8266/README + ../ports/nrf/README diff --git a/docs/templates/layout.html b/docs/templates/layout.html deleted file mode 100644 index a6caa0bc5..000000000 --- a/docs/templates/layout.html +++ /dev/null @@ -1,6 +0,0 @@ -{% extends "!layout.html" %} -{% set css_files = css_files + ["_static/customstyle.css"] %} - -{# we change the master_doc variable so that links to the index - page are to index.html instead of <port>_index.html #} -{% set master_doc = "index" %} diff --git a/docs/templates/replace.inc b/docs/templates/replace.inc index 319c53735..2636045f6 100644 --- a/docs/templates/replace.inc +++ b/docs/templates/replace.inc @@ -4,6 +4,6 @@ .. |see_cpython_module| replace:: - *This module implements a subset of the corresponding* `CPython` *module, - as described below. For more information, refer to the original - CPython documentation:* + *This module implements a subset of the corresponding* ``CPython`` *module, + as described below. For more information, refer to the original* + ``CPython`` *documentation:* diff --git a/docs/templates/topindex.html b/docs/templates/topindex.html deleted file mode 100644 index 76e5e18d7..000000000 --- a/docs/templates/topindex.html +++ /dev/null @@ -1,112 +0,0 @@ -{% extends "defindex.html" %} -{% block body %} - - <h1>MicroPython documentation</h1> - - <p> - {{ _('Welcome! This is the documentation for MicroPython') }} - v{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}. - </p> - - <p> - MicroPython runs on a variety of systems and each has their own specific - documentation. You are currently viewing the documentation for - <strong>{{ port_name }}</strong>. - </p> - - <!--p> - Documentation for other systems are available: - {% for p in all_ports %} - <a href="{{ p[1] }}">{{ p[0] }}</a>{% if not loop.last %}, {% endif %} - {% endfor %}. - </p--> - - <p><strong>Documentation for MicroPython and {{ port_name }}:</strong></p> - - <table class="contentstable"><tr> - <td width="40%" style="padding-left:2em;"> - {% if port in ("pyboard", "wipy", "esp8266") %} - <p class="biglink"> - <a class="biglink" href="{{ pathto(port + "/quickref") }}">Quick reference for {{ port_name }}</a><br/> - <span class="linkdescr">pinout for {{ port_name }} and snippets of useful code</span> - </p> - <p class="biglink"> - <a class="biglink" href="{{ pathto(port + "/general") }}">General information about {{ port_name }}</a><br/> - <span class="linkdescr">read this first for a quick overview</span> - </p> - <p class="biglink"> - <a class="biglink" href="{{ pathto(port + "/tutorial/index") }}">Tutorials and code examples</a><br/> - <span class="linkdescr">start here</span> - </p> - {% endif %} - <p class="biglink"> - <a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/> - {% if port == "pyboard" %} - <span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/pyb") }}">pyb module</a></span> - {% else %} - <span class="linkdescr">MicroPython libraries, including the <a href="{{ pathto("library/machine") }}">machine module</a></span> - {% endif %} - </p> - <p class="biglink"> - <a class="biglink" href="{{ pathto("genrst/index") }}">MicroPython Differences</a><br/> - <span class="linkdescr">MicroPython operations which differ from CPython</span> - </p> - </td> - <td width="40%" style="padding-left:2em;"> - <p class="biglink"> - <a class="biglink" href="{{ pathto("reference/index") }}">Language Reference</a><br/> - <span class="linkdescr">information about MicroPython specific language features</span> - </p> - <p class="biglink"> - <a class="biglink" href="{{ pathto("license") }}">License</a><br/> - <span class="linkdescr">MicroPython license information</span> - </p> - </td> - </tr></table> - - <p><strong>Indices and tables:</strong></p> - <table class="contentstable"><tr> - <td width="40%" style="padding-left:2em;"> - <p class="biglink"> - <a class="biglink" href="{{ pathto("py-modindex") }}">Module index</a><br/> - <span class="linkdescr">quick access to all modules</span> - </p> - <p class="biglink"> - <a class="biglink" href="{{ pathto("genindex") }}">Full index</a><br/> - <span class="linkdescr">all functions, classes, constants</span> - </p> - </td> - <td width="40%" style="padding-left:2em;"> - <p class="biglink"> - <a class="biglink" href="{{ pathto("reference/glossary") }}">Glossary</a><br/> - <span class="linkdescr">MicroPython terms explained</span> - </p> - <p class="biglink"> - <a class="biglink" href="{{ pathto(port + "_index") }}">Table of contents</a><br/> - <span class="linkdescr">a list of all sections and subsections</span> - </p> - </td></tr> - </table> - - <p><strong>External links:</strong></p> - - <table class="contentstable"><tr> - <td width="40%" style="padding-left:2em;"> - <p class="biglink"> - <a class="biglink" href="http://micropython.org">MicroPython homepage</a><br/> - <span class="linkdescr">the official MicroPython site</span> - </p> - <p class="biglink"> - <a class="biglink" href="http://forum.micropython.org">MicroPython forum</a><br/> - <span class="linkdescr">community discussion for all things related to MicroPython</span> - </p> - </td> - <td width="40%" style="padding-left:2em;"> - <p class="biglink"> - <a class="biglink" href="https://github.com/micropython">MicroPython on GitHub</a><br/> - <span class="linkdescr">contribute to the source code on GitHub</span> - </p> - </td> - </tr></table> - -{% endblock %} diff --git a/docs/templates/unsupported_in_circuitpython.inc b/docs/templates/unsupported_in_circuitpython.inc new file mode 100644 index 000000000..18c9215a8 --- /dev/null +++ b/docs/templates/unsupported_in_circuitpython.inc @@ -0,0 +1,5 @@ +.. warning:: + + This module is inherited from MicroPython and may not work in CircuitPython + as documented or at all! If they do work, they may change at any time. It is + unsupported. diff --git a/docs/templates/versions.html b/docs/templates/versions.html deleted file mode 100644 index 198630dd7..000000000 --- a/docs/templates/versions.html +++ /dev/null @@ -1,37 +0,0 @@ -<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions"> - <span class="rst-current-version" data-toggle="rst-current-version"> - <span class="fa fa-book"> Ports and Versions</span> - {{ port }} ({{ port_version }}) - <span class="fa fa-caret-down"></span> - </span> - <div class="rst-other-versions"> - <dl> - <dt>Ports</dt> - {% for slug, url in all_ports %} - <dd><a href="{{ url }}">{{ slug }}</a></dd> - {% endfor %} - </dl> - <dl> - <dt>Versions</dt> - {% for slug, url in all_versions %} - <dd><a href="{{ url }}">{{ slug }}</a></dd> - {% endfor %} - </dl> - <dl> - <dt>Downloads</dt> - {% for type, url in downloads %} - <dd><a href="{{ url }}">{{ type }}</a></dd> - {% endfor %} - </dl> - <hr/> - <dl> - <dt>External links</dt> - <dd> - <a href="http://www.micropython.org">micropython.org</a> - </dd> - <dd> - <a href="https://github.com/micropython/micropython">GitHub</a> - </dd> - </dl> - </div> -</div> diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 1c7e87f61..66bcc2764 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -23,7 +23,7 @@ happen on Linux and Mac OSX but its less likely. such as Feather M0 Express, Metro M0 Express and Circuit Playground Express:** -#. Download the appropriate flash .erase uf2 from `here <https://github.com/adafruit/Adafruit_SPIFlash/tree/master/examples/flash_erase_express>`_. +#. Download the appropriate flash .erase uf2 from `the Adafruit_SPIFlash repo <https://github.com/adafruit/Adafruit_SPIFlash/tree/master/examples/flash_erase_express>`_. #. Double-click the reset button. #. Copy the appropriate .uf2 to the xxxBOOT drive. #. The on-board NeoPixel will turn blue, indicating the erase has started. @@ -32,7 +32,7 @@ such as Feather M0 Express, Metro M0 Express and Circuit Playground Express:** **For boards without SPI flash, such as Feather M0 Proto, Gemma M0 and, Trinket M0:** -#. Download the appropriate erase .uf2 from `here <https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/uf2_flash_erasers>`_. +#. Download the appropriate erase .uf2 from `the Learn repo <https://github.com/adafruit/Adafruit_Learning_System_Guides/tree/master/uf2_flash_erasers>`_. #. Double-click the reset button. #. Copy the appropriate .uf2 to the xxxBOOT drive. #. The boot LED will start pulsing again, and the xxxBOOT drive will appear again. diff --git a/docs/unix_index.rst b/docs/unix_index.rst deleted file mode 100644 index 1bfeb0bda..000000000 --- a/docs/unix_index.rst +++ /dev/null @@ -1,9 +0,0 @@ -MicroPython documentation and references -======================================== - -.. toctree:: - - library/index.rst - reference/index.rst - genrst/index.rst - license.rst diff --git a/docs/unsupported_ports.rst b/docs/unsupported_ports.rst deleted file mode 100644 index e04537656..000000000 --- a/docs/unsupported_ports.rst +++ /dev/null @@ -1,14 +0,0 @@ -Unsupported Ports -============================== - -Adafruit's MicroPython derivative currently has limited support with a focus on -the Atmel SAMD21 port. The ports below still exist in the code to preserve -upstream compatibility but are not tested. Use at your own risk. - -We recommend using `upstream MicroPython <https://micropython.org>`_ for the below ports. - -.. toctree:: - :maxdepth: 2 - - pyboard/index.rst - wipy/index.rst diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst deleted file mode 100644 index f28edb4e4..000000000 --- a/docs/wipy/general.rst +++ /dev/null @@ -1,385 +0,0 @@ -General information about the WiPy -================================== - -No floating point support -------------------------- - -Due to space reasons, there's no floating point support, and no math module. This -means that floating point numbers cannot be used anywhere in the code, and that -all divisions must be performed using '//' instead of '/'. Example:: - - >>> r = 4 // 2 # this will work - >>> r = 4 / 2 # this WON'T - -Before applying power ---------------------- - -.. warning:: - - The GPIO pins of the WiPy are NOT 5V tolerant, connecting them to voltages higher - than 3.6V will cause irreparable damage to the board. ADC pins, when configured - in analog mode cannot withstand voltages above 1.8V. Keep these considerations in - mind when wiring your electronics. - -WLAN default behaviour ----------------------- - -When the WiPy boots with the default factory configuration starts in Access Point -mode with ``ssid`` that starts with: ``wipy-wlan`` and ``key: www.wipy.io``. -Connect to this network and the WiPy will be reachable at ``192.168.1.1``. In order -to gain access to the interactive prompt, open a telnet session to that IP address on -the default port (23). You will be asked for credentials: -``login: micro`` and ``password: python`` - -.. _wipy_telnet: - -Telnet REPL ------------ - -Linux stock telnet works like a charm (also on OSX), but other tools like putty -work quite well too. The default credentials are: **user:** ``micro``, **password:** ``python``. -See :ref:`network.server <network.server>` for info on how to change the defaults. -For instance, on a linux shell (when connected to the WiPy in AP mode):: - - $ telnet 192.168.1.1 - -.. _wipy_filesystem: - -Local file system and FTP access --------------------------------- - -There is a small internal file system (a drive) on the WiPy, called ``/flash``, -which is stored within the external serial flash memory. If a micro SD card -is hooked-up and mounted, it will be available as well. - -When the WiPy starts up, it always boots from the ``boot.py`` located in the -``/flash`` file system. On boot up, the current directory is ``/flash``. - -The file system is accessible via the native FTP server running in the WiPy. -Open your FTP client of choice and connect to: - -**url:** ``ftp://192.168.1.1``, **user:** ``micro``, **password:** ``python`` - -See :ref:`network.server <network.server>` for info on how to change the defaults. -The recommended clients are: Linux stock FTP (also in OSX), Filezilla and FireFTP. -For example, on a linux shell:: - - $ ftp 192.168.1.1 - -The FTP server on the WiPy doesn't support active mode, only passive, therefore, -if using the native unix ftp client, just after logging in do:: - - ftp> passive - -Besides that, the FTP server only supports one data connection at a time. Check out -the Filezilla settings section below for more info. - -FileZilla settings ------------------- -Do not use the quick connect button, instead, open the site manager and create a new -configuration. In the ``General`` tab make sure that encryption is set to: ``Only use -plain FTP (insecure)``. In the Transfer Settings tab limit the max number of connections -to one, otherwise FileZilla will try to open a second command connection when retrieving -and saving files, and for simplicity and to reduce code size, only one command and one -data connections are possible. Other FTP clients might behave in a similar way. - -.. _wipy_firmware_upgrade: - -Upgrading the firmware Over The Air ------------------------------------ - -OTA software updates can be performed through the FTP server. Upload the ``mcuimg.bin`` file -to: ``/flash/sys/mcuimg.bin`` it will take around 6s. You won't see the file being stored -inside ``/flash/sys/`` because it's actually saved bypassing the user file system, so it -ends up inside the internal **hidden** file system, but rest assured that it was successfully -transferred, and it has been signed with a MD5 checksum to verify its integrity. Now, reset -the WiPy by pressing the switch on the board, or by typing:: - - >>> import machine - >>> machine.reset() - -Software updates can be found in: https://github.com/wipy/wipy/releases (**Binaries.zip**). -It's always recommended to update to the latest software, but make sure to -read the **release notes** before. - -.. note:: - - The ``bootloader.bin`` found inside ``Binaries.zip`` is there only for reference, it's not - needed for the Over The Air update. - -In order to check your software version, do:: - - >>> import os - >>> os.uname().release - -If the version number is lower than the latest release found in -`the releases <https://github.com/wipy/wipy/releases>`_, go ahead and update your WiPy! - - -.. _wipy_boot_modes: - -Boot modes and safe boot ------------------------- - -If you power up normally, or press the reset button, the WiPy will boot -into standard mode; the ``boot.py`` file will be executed first, then -``main.py`` will run. - -You can override this boot sequence by pulling ``GP28`` **up** (connect -it to the 3v3 output pin) during reset. This procedure also allows going -back in time to old firmware versions. The WiPy can hold up to 3 different -firmware versions, which are: the factory firmware plus 2 user updates. - -After reset, if ``GP28`` is held high, the heartbeat LED will start flashing -slowly, if after 3 seconds the pin is still being held high, the LED will start -blinking a bit faster and the WiPy will select the previous user update to boot. -If the previous user update is the desired firmware image, ``GP28`` must be -released before 3 more seconds elapse. If 3 seconds later the pin is still high, -the factory firmware will be selected, the LED will flash quickly for 1.5 seconds -and the WiPy will proceed to boot. The firmware selection mechanism is as follows: - - -**Safe Boot Pin** ``GP28`` **released during:** - -+-------------------------+-------------------------+----------------------------+ -| 1st 3 secs window | 2nd 3 secs window | Final 1.5 secs window | -+=========================+=========================+============================+ -| | Safe boot, *latest* | | Safe boot, *previous* | | Safe boot, the *factory* | -| | firmware is selected | | user update selected | | firmware is selected | -+-------------------------+-------------------------+----------------------------+ - -On all of the above 3 scenarios, safe boot mode is entered, meaning that -the execution of both ``boot.py`` and ``main.py`` is skipped. This is -useful to recover from crash situations caused by the user scripts. The selection -made during safe boot is not persistent, therefore after the next normal reset -the latest firmware will run again. - -The heartbeat LED ------------------- - -By default the heartbeat LED flashes once every 4s to signal that the system is -alive. This can be overridden through the :mod:`wipy` module:: - - >>> import wipy - >>> wipy.heartbeat(False) - -There are currently 2 kinds of errors that you might see: - -1. If the heartbeat LED flashes quickly, then a Python script (eg ``main.py``) - has an error. Use the REPL to debug it. -2. If the heartbeat LED stays on, then there was a hard fault, you cannot - recover from this, the only way out is to press the reset switch. - -Details on sleep modes ----------------------- - -* ``machine.idle()``: Power consumption: ~12mA (in WLAN STA mode). Wake sources: - any hardware interrupt (including systick with period of 1ms), no special - configuration required. -* ``machine.sleep()``: 950uA (in WLAN STA mode). Wake sources are ``Pin``, ``RTC`` - and ``WLAN`` -* ``machine.deepsleep()``: ~350uA. Wake sources are ``Pin`` and ``RTC``. - -Additional details for machine.Pin ----------------------------------- - -On the WiPy board the pins are identified by their string id:: - - from machine import Pin - g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1) - -You can also configure the Pin to generate interrupts. For instance:: - - from machine import Pin - - def pincb(pin): - print(pin.id()) - - pin_int = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN) - pin_int.irq(trigger=Pin.IRQ_RISING, handler=pincb) - # the callback can be triggered manually - pin_int.irq()() - # to disable the callback - pin_int.irq().disable() - -Now every time a falling edge is seen on the gpio pin, the callback will be -executed. Caution: mechanical push buttons have "bounce" and pushing or -releasing a switch will often generate multiple edges. -See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed -explanation, along with various techniques for debouncing. - -All pin objects go through the pin mapper to come up with one of the -gpio pins. - -For the ``drive`` parameter the strengths are: - - - ``Pin.LOW_POWER`` - 2mA drive capability. - - ``Pin.MED_POWER`` - 4mA drive capability. - - ``Pin.HIGH_POWER`` - 6mA drive capability. - -For the ``alt`` parameter please refer to the pinout and alternate functions -table at <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_ -for the specific alternate functions that each pin supports. - -For interrupts, the ``priority`` can take values in the range 1-7. And the -``wake`` parameter has the following properties: - - - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board. - - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, - ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1 - of this pins can be enabled as a wake source at the same time, so, only - the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect. - - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, - ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the - 6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time. - -Additional Pin methods: - -.. method:: machine.Pin.alt_list() - - Returns a list of the alternate functions supported by the pin. List items are - a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)`` - -Additional details for machine.I2C ----------------------------------- - -On the WiPy there is a single hardware I2C peripheral, identified by "0". By -default this is the peripheral that is used when constructing an I2C instance. -The default pins are GP23 for SCL and GP13 for SDA, and one can create the -default I2C peripheral simply by doing:: - - i2c = machine.I2C() - -The pins and frequency can be specified as:: - - i2c = machine.I2C(freq=400000, scl='GP23', sda='GP13') - -Only certain pins can be used as SCL/SDA. Please refer to the pinout for further -information. - -Known issues ------------- - -Incompatible way to create SSL sockets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -SSL sockets need to be created the following way before wrapping them with. -``ssl.wrap_socket``:: - - import socket - import ssl - s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s) - -Certificates must be used in order to validate the other side of the connection, and also to -authenticate ourselves with the other end. Such certificates must be stored as files using the -FTP server, and they must be placed in specific paths with specific names. - -- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'** -- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'** -- The key for our own certificate goes in: **'/flash/cert/private.key'** - -.. note:: - - When these files are stored, they are placed inside the internal **hidden** file system - (just like firmware updates), and therefore they are never visible. - -For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located -in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_. -and put it in '/flash/cert/'. Then do:: - - import socket - import ssl - s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem') - ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1]) - -Incompatibilities in uhashlib module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Due to hardware implementation details of the WiPy, data must be buffered before being -digested, which would make it impossible to calculate the hash of big blocks of data that -do not fit in RAM. In this case, since most likely the total size of the data is known -in advance, the size can be passed to the constructor and hence the HASH hardware engine -of the WiPy can be properly initialized without needing buffering. If ``block_size`` is -to be given, an initial chunk of ``data`` must be passed as well. **When using this extension, -care must be taken to make sure that the length of all intermediate chunks (including the -initial one) is a multiple of 4 bytes.** The last chunk may be of any length. - -Example:: - - hash = uhashlib.sha1('abcd1234', 1001) # length of the initial piece is multiple of 4 bytes - hash.update('1234') # also multiple of 4 bytes - ... - hash.update('12345') # last chunk may be of any length - hash.digest() - -Unrelated function in machine module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. function:: main(filename) - - Set the filename of the main script to run after boot.py is finished. If - this function is not called then the default file main.py will be executed. - - It only makes sense to call this function from within boot.py. - -Adhoc way to control telnet/FTP server via network module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``Server`` class controls the behaviour and the configuration of the FTP and telnet -services running on the WiPy. Any changes performed using this class' methods will -affect both. - -Example:: - - import network - server = network.Server() - server.deinit() # disable the server - # enable the server again with new settings - server.init(login=('user', 'password'), timeout=600) - -.. class:: network.Server(id, ...) - - Create a server instance, see ``init`` for parameters of initialization. - -.. method:: server.init(\*, login=('micro', 'python'), timeout=300) - - Init (and effectively start the server). Optionally a new ``user``, ``password`` - and ``timeout`` (in seconds) can be passed. - -.. method:: server.deinit() - - Stop the server - -.. method:: server.timeout([timeout_in_seconds]) - - Get or set the server timeout. - -.. method:: server.isrunning() - - Returns ``True`` if the server is running, ``False`` otherwise. - -Adhoc VFS-like support -~~~~~~~~~~~~~~~~~~~~~~ - -WiPy doesn't implement full MicroPython VFS support, instead following -functions are defined in ``uos`` module: - -.. function:: mount(block_device, mount_point, \*, readonly=False) - - Mounts a block device (like an ``SD`` object) in the specified mount - point. Example:: - - os.mount(sd, '/sd') - -.. function:: unmount(path) - - Unmounts a previously mounted block device from the given path. - -.. function:: mkfs(block_device or path) - - Formats the specified path, must be either ``/flash`` or ``/sd``. - A block device can also be passed like an ``SD`` object before - being mounted. - diff --git a/docs/wipy/index.rst b/docs/wipy/index.rst deleted file mode 100644 index 9b355d496..000000000 --- a/docs/wipy/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -WiPy -================================== - -.. toctree:: - - quickref.rst - general.rst - tutorial/index.rst diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst deleted file mode 100644 index f60c81f5f..000000000 --- a/docs/wipy/quickref.rst +++ /dev/null @@ -1,218 +0,0 @@ -.. _quickref_: - -Quick reference for the WiPy -============================ - -.. image:: https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png - :alt: WiPy pinout and alternate functions table - :width: 800px - -General board control (including sleep modes) ---------------------------------------------- - -See the :mod:`machine` module:: - - import machine - - help(machine) # display all members from the machine module - machine.freq() # get the CPU frequency - machine.unique_id() # return the 6-byte unique id of the board (the WiPy's MAC address) - - machine.idle() # average current decreases to (~12mA), any interrupts wake it up - machine.sleep() # everything except for WLAN is powered down (~950uA avg. current) - # wakes from Pin, RTC or WLAN - machine.deepsleep() # deepest sleep mode, MCU starts from reset. Wakes from Pin and RTC. - -Pins and GPIO -------------- - -See :ref:`machine.Pin <machine.Pin>`. :: - - from machine import Pin - - # initialize GP2 in gpio mode (alt=0) and make it an output - p_out = Pin('GP2', mode=Pin.OUT) - p_out.value(1) - p_out.value(0) - p_out.toggle() - p_out(True) - - # make GP1 an input with the pull-up enabled - p_in = Pin('GP1', mode=Pin.IN, pull=Pin.PULL_UP) - p_in() # get value, 0 or 1 - -Timers ------- - -See :ref:`machine.Timer <machine.Timer>` and :ref:`machine.Pin <machine.Pin>`. -Timer ``id``'s take values from 0 to 3.:: - - from machine import Timer - from machine import Pin - - tim = Timer(0, mode=Timer.PERIODIC) - tim_a = tim.channel(Timer.A, freq=1000) - tim_a.freq(5) # 5 Hz - - p_out = Pin('GP2', mode=Pin.OUT) - tim_a.irq(trigger=Timer.TIMEOUT, handler=lambda t: p_out.toggle()) - -PWM (pulse width modulation) ----------------------------- - -See :ref:`machine.Pin <machine.Pin>` and :ref:`machine.Timer <machine.Timer>`. :: - - from machine import Timer - - # timer 1 in PWM mode and width must be 16 buts - tim = Timer(1, mode=Timer.PWM, width=16) - - # enable channel A @1KHz with a 50.55% duty cycle - tim_a = tim.channel(Timer.A, freq=1000, duty_cycle=5055) - -ADC (analog to digital conversion) ----------------------------------- - -See :ref:`machine.ADC <machine.ADC>`. :: - - from machine import ADC - - adc = ADC() - apin = adc.channel(pin='GP3') - apin() # read value, 0-4095 - -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 - -SPI bus -------- - -See :ref:`machine.SPI <machine.SPI>`. :: - - from machine import SPI - - # configure the SPI master @ 2MHz - spi = SPI(0, SPI.MASTER, baudrate=200000, polarity=0, phase=0) - spi.write('hello') - spi.read(5) # receive 5 bytes on the bus - rbuf = bytearray(5) - spi.write_readinto('hello', rbuf) # send and receive 5 bytes - -I2C bus -------- - -See :ref:`machine.I2C <machine.I2C>`. :: - - from machine import I2C - # configure the I2C bus - i2c = I2C(baudrate=100000) - i2c.scan() # returns list of slave addresses - i2c.writeto(0x42, 'hello') # send 5 bytes to slave with address 0x42 - i2c.readfrom(0x42, 5) # receive 5 bytes from slave - i2c.readfrom_mem(0x42, 0x10, 2) # read 2 bytes from slave 0x42, slave memory 0x10 - i2c.writeto_mem(0x42, 0x10, 'xy') # write 2 bytes to slave 0x42, slave memory 0x10 - -Watchdog timer (WDT) --------------------- - -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() - -Real time clock (RTC) ---------------------- - -See :ref:`machine.RTC <machine.RTC>` :: - - from machine import RTC - - rtc = RTC() # init with default time and date - rtc = RTC(datetime=(2015, 8, 29, 9, 0, 0, 0, None)) # init with a specific time and date - print(rtc.now()) - - def alarm_handler (rtc_o): - pass - # do some non blocking operations - # warning printing on an irq via telnet is not - # possible, only via UART - - # create a RTC alarm that expires after 5 seconds - rtc.alarm(time=5000, repeat=False) - - # enable RTC interrupts - rtc_i = rtc.irq(trigger=RTC.ALARM0, handler=alarm_handler, wake=machine.SLEEP) - - # go into suspended mode waiting for the RTC alarm to expire and wake us up - machine.sleep() - -SD card -------- - -See :ref:`machine.SD <machine.SD>`. :: - - from machine import SD - import os - - # clock pin, cmd pin, data0 pin - sd = SD(pins=('GP10', 'GP11', 'GP15')) - # or use default ones for the expansion board - sd = SD() - os.mount(sd, '/sd') - -WLAN (WiFi) ------------ - -See :ref:`network.WLAN <network.WLAN>` and :mod:`machine`. :: - - import machine - from network import WLAN - - # configure the WLAN subsystem in station mode (the default is AP) - wlan = WLAN(mode=WLAN.STA) - # go for fixed IP settings - wlan.ifconfig(config=('192.168.0.107', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - wlan.scan() # scan for available networks - wlan.connect(ssid='mynetwork', auth=(WLAN.WPA2, 'mynetworkkey')) - while not wlan.isconnected(): - pass - print(wlan.ifconfig()) - # enable wake on WLAN - wlan.irq(trigger=WLAN.ANY_EVENT, wake=machine.SLEEP) - # go to sleep - machine.sleep() - # now, connect to the FTP or the Telnet server and the WiPy will wake-up - -Telnet and FTP server ---------------------- - -See :ref:`network.Server <network.Server>` :: - - from network import Server - - # init with new user, password and seconds timeout - server = Server(login=('user', 'password'), timeout=60) - server.timeout(300) # change the timeout - server.timeout() # get the timeout - server.isrunning() # check whether the server is running or not - -Heart beat LED --------------- - -See :mod:`wipy`. :: - - import wipy - - wipy.heartbeat(False) # disable the heartbeat LED - wipy.heartbeat(True) # enable the heartbeat LED - wipy.heartbeat() # get the heartbeat state diff --git a/docs/wipy/tutorial/blynk.rst b/docs/wipy/tutorial/blynk.rst deleted file mode 100644 index b5a2f24a4..000000000 --- a/docs/wipy/tutorial/blynk.rst +++ /dev/null @@ -1,19 +0,0 @@ -Getting started with Blynk and the WiPy ---------------------------------------- - -Blynk is a platform with iOS and Android apps to control -Arduino, Raspberry Pi and the likes over the Internet. -You can easily build graphic interfaces for all your -projects by simply dragging and dropping widgets. - -There are several examples available that work out-of-the-box with -the WiPy. Before anything else, make sure that your WiPy is running -the latest software, check :ref:`OTA How-To <wipy_firmware_upgrade>` for instructions. - -1. Get the `Blynk library <https://github.com/wipy/wipy/blob/master/lib/blynk/BlynkLib.py>`_ and put it in ``/flash/lib/`` via FTP. -2. Get the `Blynk examples <https://github.com/wipy/wipy/tree/master/examples/blynk>`_, edit the network settings, and afterwards - upload them to ``/flash/lib/`` via FTP as well. -3. Follow the instructions on each example to setup the Blynk dashboard on your smartphone or tablet. -4. Give it a try, for instance:: - - >>> execfile('01_simple.py') diff --git a/docs/wipy/tutorial/index.rst b/docs/wipy/tutorial/index.rst deleted file mode 100644 index 816de27b5..000000000 --- a/docs/wipy/tutorial/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _wipy_tutorial_index: - -WiPy tutorials and examples -=========================== - -Before starting, make sure that you are running the latest firmware, -for instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`. - -.. toctree:: - :maxdepth: 1 - :numbered: - - intro.rst - repl.rst - blynk.rst - wlan.rst - timer.rst - reset.rst diff --git a/docs/wipy/tutorial/intro.rst b/docs/wipy/tutorial/intro.rst deleted file mode 100644 index 3acc0510f..000000000 --- a/docs/wipy/tutorial/intro.rst +++ /dev/null @@ -1,64 +0,0 @@ -Introduction to the WiPy -======================== - -To get the most out of your WiPy, there are a few basic things to -understand about how it works. - -Caring for your WiPy and expansion board ----------------------------------------- - -Because the WiPy/expansion board does not have a housing it needs a bit of care: - - - Be gentle when plugging/unplugging the USB cable. Whilst the USB connector - is well soldered and is relatively strong, if it breaks off it can be very - difficult to fix. - - - Static electricity can shock the components on the WiPy and destroy them. - If you experience a lot of static electricity in your area (eg dry and cold - climates), take extra care not to shock the WiPy. If your WiPy came - in a ESD bag, then this bag is the best way to store and carry the - WiPy as it will protect it against static discharges. - -As long as you take care of the hardware, you should be okay. It's almost -impossible to break the software on the WiPy, so feel free to play around -with writing code as much as you like. If the filesystem gets corrupt, see -below on how to reset it. In the worst case you might need to do a safe boot, -which is explained in detail :ref:`here <wipy_boot_modes>`. - -Plugging into the expansion board and powering on -------------------------------------------------- - -The expansion board can power the WiPy via USB. The WiPy comes with a sticker -on top of the RF shield that labels all pins, and this should match the label -numbers on the expansion board headers. When plugging it in, the WiPy antenna -will end up on top of the SD card connector of the expansion board. A video -showing how to do this can be found `here <https://www.youtube.com/watch?v=47D9MZ9zFQw>`_. - -Expansion board hardware guide ------------------------------- - -The document explaining the hardware details of the expansion board can be found -`here <https://github.com/wipy/wipy/blob/master/docs/User_manual_exp_board.pdf>`_. - -Powering by an external power source ------------------------------------- - -The WiPy can be powered by a battery or other external power source. - -**Be sure to connect the positive lead of the power supply to VIN, and -ground to GND. There is no polarity protection on the WiPy so you -must be careful when connecting anything to VIN.** - -- When powering via ``VIN``: - - **The input voltage must be between 3.6V and 5.5V.** - -- When powering via ``3V3``: - - **The input voltage must be exactly 3V3, ripple free and from a supply capable - of sourcing at least 300mA of current** - -Performing firmware upgrades ----------------------------- - -For detailed instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`. diff --git a/docs/wipy/tutorial/repl.rst b/docs/wipy/tutorial/repl.rst deleted file mode 100644 index e7b51f9c5..000000000 --- a/docs/wipy/tutorial/repl.rst +++ /dev/null @@ -1,130 +0,0 @@ -Getting a MicroPython REPL prompt -================================= - -REPL stands for Read Evaluate Print Loop, and is the name given to the -interactive MicroPython prompt that you can access on the WiPy. Using -the REPL is by far the easiest way to test out your code and run commands. -You can use the REPL in addition to writing scripts in ``main.py``. - -.. _wipy_uart: - -To use the REPL, you must connect to the WiPy either via :ref:`telnet <wipy_telnet>`, -or with a USB to serial converter wired to one of the two UARTs on the -WiPy. To enable REPL duplication on UART0 (the one accessible via the expansion board) -do:: - - >>> from machine import UART - >>> import os - >>> uart = UART(0, 115200) - >>> os.dupterm(uart) - -Place this piece of code inside your `boot.py` so that it's done automatically after -reset. - -Windows -------- - -First you need to install the FTDI drivers for the expansion board's USB to serial -converter. Then you need a terminal software. The best option is to download the -free program PuTTY: `putty.exe <http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html>`_. - -**In order to get to the telnet REPL:** - -Using putty, select ``Telnet`` as connection type, leave the default port (23) -and enter the IP address of your WiPy (192.168.1.1 when in ``WLAN.AP`` mode), -then click open. - -**In order to get to the REPL UART:** - -Using your serial program you must connect to the COM port that you found in the -previous step. With PuTTY, click on "Session" in the left-hand panel, then click -the "Serial" radio button on the right, then enter you COM port (eg COM4) in the -"Serial Line" box. Finally, click the "Open" button. - -Mac OS X --------- - -Open a terminal and run:: - - $ telnet 192.168.1.1 - -or:: - - $ screen /dev/tty.usbmodem* 115200 - -When you are finished and want to exit ``screen``, type CTRL-A CTRL-\\. If your keyboard does not have a \\-key (i.e. you need an obscure combination for \\ like ALT-SHIFT-7) you can remap the ``quit`` command: - -- create ``~/.screenrc`` -- add ``bind q quit`` - -This will allow you to quit ``screen`` by hitting CTRL-A Q. - -Linux ------ - -Open a terminal and run:: - - $ telnet 192.168.1.1 - -or:: - - $ screen /dev/ttyUSB0 115200 - -You can also try ``picocom`` or ``minicom`` instead of screen. You may have to -use ``/dev/ttyUSB01`` or a higher number for ``ttyUSB``. And, you may need to give -yourself the correct permissions to access this devices (eg group ``uucp`` or ``dialout``, -or use sudo). - -Using the REPL prompt ---------------------- - -Now let's try running some MicroPython code directly on the WiPy. - -With your serial program open (PuTTY, screen, picocom, etc) you may see a blank -screen with a flashing cursor. Press Enter and you should be presented with a -MicroPython prompt, i.e. ``>>>``. Let's make sure it is working with the obligatory test:: - - >>> print("hello WiPy!") - hello WiPy! - -In the above, you should not type in the ``>>>`` characters. They are there to -indicate that you should type the text after it at the prompt. In the end, once -you have entered the text ``print("hello WiPy!")`` and pressed Enter, the output -on your screen should look like it does above. - -If you already know some Python you can now try some basic commands here. - -If any of this is not working you can try either a hard reset or a soft reset; -see below. - -Go ahead and try typing in some other commands. For example:: - - >>> from machine import Pin - >>> import wipy - >>> wipy.heartbeat(False) # disable the heartbeat - >>> led = Pin('GP25', mode=Pin.OUT) - >>> led(1) - >>> led(0) - >>> led.toggle() - >>> 1 + 2 - 3 - >>> 4 // 2 - 2 - >>> 20 * 'py' - 'pypypypypypypypypypypypypypypypypypypypy' - -Resetting the board -------------------- - -If something goes wrong, you can reset the board in two ways. The first is to press CTRL-D -at the MicroPython prompt, which performs a soft reset. You will see a message something like:: - - >>> - PYB: soft reboot - MicroPython v1.4.6-146-g1d8b5e5 on 2015-10-21; WiPy with CC3200 - Type "help()" for more information. - >>> - -If that isn't working you can perform a hard reset (turn-it-off-and-on-again) by pressing the -RST switch (the small black button next to the heartbeat LED). During telnet, this will end -your session, disconnecting whatever program that you used to connect to the WiPy. diff --git a/docs/wipy/tutorial/reset.rst b/docs/wipy/tutorial/reset.rst deleted file mode 100644 index ece28498b..000000000 --- a/docs/wipy/tutorial/reset.rst +++ /dev/null @@ -1,54 +0,0 @@ -Reset and boot modes -==================== - -There are soft resets and hard resets. - - - A soft reset simply clears the state of the MicroPython virtual machine, - but leaves hardware peripherals unaffected. To do a soft reset, simply press - **Ctrl+D** on the REPL, or within a script do:: - - import sys - sys.exit() - - - A hard reset is the same as performing a power cycle to the board. In order to - hard reset the WiPy, press the switch on the board or:: - - import machine - machine.reset() - -Safe boot ---------- - -If something goes wrong with your WiPy, don't panic! It is almost -impossible for you to break the WiPy by programming the wrong thing. - -The first thing to try is to boot in safe mode: this temporarily skips -execution of ``boot.py`` and ``main.py`` and gives default WLAN settings. - -If you have problems with the filesystem you can :ref:`format the internal flash -drive <wipy_factory_reset>`. - -To boot in safe mode, follow the detailed instructions described :ref:`here <wipy_boot_modes>`. - -In safe mode, the ``boot.py`` and ``main.py`` files are not executed, and so -the WiPy boots up with default settings. This means you now have access -to the filesystem, and you can edit ``boot.py`` and ``main.py`` to fix any problems. - -Entering safe mode is temporary, and does not make any changes to the -files on the WiPy. - -.. _wipy_factory_reset: - -Factory reset the filesystem ----------------------------- - -If you WiPy's filesystem gets corrupted (very unlikely, but possible), you -can format it very easily by doing:: - - >>> import os - >>> os.mkfs('/flash') - -Resetting the filesystem deletes all files on the internal WiPy storage -(not the SD card), and restores the files ``boot.py`` and ``main.py`` back -to their original state after the next reset. - diff --git a/docs/wipy/tutorial/timer.rst b/docs/wipy/tutorial/timer.rst deleted file mode 100644 index c87ac4495..000000000 --- a/docs/wipy/tutorial/timer.rst +++ /dev/null @@ -1,70 +0,0 @@ -Hardware timers -=============== - -Timers can be used for a great variety of tasks, calling a function periodically, -counting events, and generating a PWM signal are among the most common use cases. -Each timer consists of two 16-bit channels and this channels can be tied together to -form one 32-bit timer. The operating mode needs to be configured per timer, but then -the period (or the frequency) can be independently configured on each channel. -By using the callback method, the timer event can call a Python function. - -Example usage to toggle an LED at a fixed frequency:: - - from machine import Timer - from machine import Pin - led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED - tim = Timer(3) # create a timer object using timer 3 - tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode - tim_ch = tim.channel(Timer.A, freq=5) # configure channel A at a frequency of 5Hz - tim_ch.irq(handler=lambda t:led.toggle(), trigger=Timer.TIMEOUT) # toggle a LED on every cycle of the timer - -Example using named function for the callback:: - - from machine import Timer - from machine import Pin - tim = Timer(1, mode=Timer.PERIODIC, width=32) - tim_a = tim.channel(Timer.A | Timer.B, freq=1) # 1 Hz frequency requires a 32 bit timer - - led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED - - def tick(timer): # we will receive the timer object when being called - global led - led.toggle() # toggle the LED - - tim_a.irq(handler=tick, trigger=Timer.TIMEOUT) # create the interrupt - -Further examples:: - - from machine import Timer - tim1 = Timer(1, mode=Timer.ONE_SHOT) # initialize it in one shot mode - tim2 = Timer(2, mode=Timer.PWM) # initialize it in PWM mode - tim1_ch = tim1.channel(Timer.A, freq=10, polarity=Timer.POSITIVE) # start the event counter with a frequency of 10Hz and triggered by positive edges - tim2_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=5000) # start the PWM on channel B with a 50% duty cycle - tim2_ch.freq(20) # set the frequency (can also get) - tim2_ch.duty_cycle(3010) # set the duty cycle to 30.1% (can also get) - tim2_ch.duty_cycle(3020, Timer.NEGATIVE) # set the duty cycle to 30.2% and change the polarity to negative - tim2_ch.period(2000000) # change the period to 2 seconds - - -Additional constants for Timer class ------------------------------------- - -.. data:: Timer.PWM - - PWM timer operating mode. - -.. data:: Timer.A -.. data:: Timer.B - - Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when - using a 32-bit timer. - -.. data:: Timer.POSITIVE -.. data:: Timer.NEGATIVE - - Timer channel polarity selection (only relevant in PWM mode). - -.. data:: Timer.TIMEOUT -.. data:: Timer.MATCH - - Timer channel IRQ triggers. diff --git a/docs/wipy/tutorial/wlan.rst b/docs/wipy/tutorial/wlan.rst deleted file mode 100644 index 434367cd9..000000000 --- a/docs/wipy/tutorial/wlan.rst +++ /dev/null @@ -1,71 +0,0 @@ -WLAN step by step -================= - -The WLAN is a system feature of the WiPy, therefore it is always enabled -(even while in ``machine.SLEEP``), except when deepsleep mode is entered. - -In order to retrieve the current WLAN instance, do:: - - >>> from network import WLAN - >>> wlan = WLAN() # we call the constructor without params - -You can check the current mode (which is always ``WLAN.AP`` after power up):: - - >>> wlan.mode() - -.. warning:: - When you change the WLAN mode following the instructions below, your WLAN - connection to the WiPy will be broken. This means you will not be able - to run these commands interactively over the WLAN. - - There are two ways around this:: - 1. put this setup code into your :ref:`boot.py file<wipy_filesystem>` so that it gets executed automatically after reset. - 2. :ref:`duplicate the REPL on UART <wipy_uart>`, so that you can run commands via USB. - -Connecting to your home router ------------------------------- - -The WLAN network card always boots in ``WLAN.AP`` mode, so we must first configure -it as a station:: - - from network import WLAN - wlan = WLAN(mode=WLAN.STA) - - -Now you can proceed to scan for networks:: - - nets = wlan.scan() - for net in nets: - if net.ssid == 'mywifi': - print('Network found!') - wlan.connect(net.ssid, auth=(net.sec, 'mywifikey'), timeout=5000) - while not wlan.isconnected(): - machine.idle() # save power while waiting - print('WLAN connection succeeded!') - break - -Assigning a static IP address when booting ------------------------------------------- - -If you want your WiPy to connect to your home router after boot-up, and with a fixed -IP address so that you can access it via telnet or FTP, use the following script as /flash/boot.py:: - - import machine - from network import WLAN - wlan = WLAN() # get current object, without changing the mode - - if machine.reset_cause() != machine.SOFT_RESET: - wlan.init(WLAN.STA) - # configuration below MUST match your home router settings!! - wlan.ifconfig(config=('192.168.178.107', '255.255.255.0', '192.168.178.1', '8.8.8.8')) - - if not wlan.isconnected(): - # change the line below to match your network ssid, security and password - wlan.connect('mywifi', auth=(WLAN.WPA2, 'mywifikey'), timeout=5000) - while not wlan.isconnected(): - machine.idle() # save power while waiting - -.. note:: - - Notice how we check for the reset cause and the connection status, this is crucial in order - to be able to soft reset the WiPy during a telnet session without breaking the connection. diff --git a/docs/wipy_index.rst b/docs/wipy_index.rst deleted file mode 100644 index 15c04c0fb..000000000 --- a/docs/wipy_index.rst +++ /dev/null @@ -1,12 +0,0 @@ -MicroPython documentation and references -======================================== - -.. toctree:: - - wipy/quickref.rst - wipy/general.rst - wipy/tutorial/index.rst - library/index.rst - reference/index.rst - genrst/index.rst - license.rst |
