diff options
Diffstat (limited to 'docs/library')
59 files changed, 224 insertions, 5564 deletions
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``). |