diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/esp.rst | 36 | ||||
| -rw-r--r-- | docs/library/index.rst | 23 | ||||
| -rw-r--r-- | docs/library/machine.I2C.rst | 59 | ||||
| -rw-r--r-- | docs/library/machine.UART.rst | 11 | ||||
| -rw-r--r-- | docs/library/pyb.Accel.rst | 8 | ||||
| -rw-r--r-- | docs/library/pyb.I2C.rst | 5 | ||||
| -rw-r--r-- | docs/library/pyb.UART.rst | 27 | ||||
| -rw-r--r-- | docs/library/pyb.USB_VCP.rst | 10 | ||||
| -rw-r--r-- | docs/library/usocket.rst | 18 |
9 files changed, 127 insertions, 70 deletions
diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 0836bba72e..8cafb92cd0 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -45,3 +45,39 @@ Functions .. function:: flash_write(byte_offset, bytes) .. function:: flash_erase(sector_no) + +.. function:: set_native_code_location(start, length) + + Set the location that native code will be placed for execution after it is + compiled. Native code is emitted when the ``@micropython.native``, + ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied + to a function. The ESP8266 must execute code from either iRAM or the lower + 1MByte of flash (which is memory mapped), and this function controls the + location. + + If `start` and `length` are both `None` then the native code location is + set to the unused portion of memory at the end of the iRAM1 region. The + size of this unused portion depends on the firmware and is typically quite + small (around 500 bytes), and is enough to store a few very small + functions. The advantage of using this iRAM1 region is that it does not + get worn out by writing to it. + + If neither `start` nor `length` are `None` then they should be integers. + `start` should specify the byte offset from the beginning of the flash at + which native code should be stored. `length` specifies how many bytes of + flash from `start` can be used to store native code. `start` and `length` + should be multiples of the sector size (being 4096 bytes). The flash will + be automatically erased before writing to it so be sure to use a region of + flash that is not otherwise used, for example by the firmware or the + filesystem. + + When using the flash to store native code `start+length` must be less + than or equal to 1MByte. Note that the flash can be worn out if repeated + erasures (and writes) are made so use this feature sparingly. + In particular, native code needs to be recompiled and rewritten to flash + on each boot (including wake from deepsleep). + + In both cases above, using iRAM1 or flash, if there is no more room left + in the specified region then the use of a native decorator on a function + will lead to `MemoryError` exception being raised during compilation of + that function. diff --git a/docs/library/index.rst b/docs/library/index.rst index b06c806f73..3621f9d880 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -36,15 +36,20 @@ 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. - -.. only:: not port_unix - - The modules are available 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. +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 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 diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index f5820f103e..cdeb246ebb 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -49,12 +49,23 @@ Constructors Construct an I2C object on the given bus. `bus` can only be 0. If the bus is not given, the default one will be selected (0). -.. only:: port_esp8266 +.. only:: not port_wipy + + .. class:: I2C(id=-1, \*, scl, sda, freq=400000) - .. class:: I2C(scl, sda, \*, freq=400000) + Construct and return a new I2C object using the following parameters: - Construct and return a new I2C object. - See the init method below for a description of the arguments. + - `id` identifies the 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 --------------- @@ -102,29 +113,31 @@ control over the bus, otherwise the standard methods (see below) can be used. .. method:: I2C.start() - Send a start bit on the bus (SDA transitions to low while SCL is high). + Generate a START condition on the bus (SDA transitions to low while SCL is high). Availability: ESP8266. .. method:: I2C.stop() - Send a stop bit on the bus (SDA transitions to high while SCL is high). + Generate a STOP condition on the bus (SDA transitions to high while SCL is high). Availability: ESP8266. -.. method:: I2C.readinto(buf) +.. 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, and a NACK will be sent following the last - byte. + 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 all the bytes from `buf` to the bus. Checks that an ACK is received - after each byte and raises an OSError if not. + 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. @@ -134,29 +147,27 @@ 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) +.. 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) +.. 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. - On WiPy the return value is the number of bytes read. Otherwise the - return value is `None`. - -.. method:: I2C.writeto(addr, buf, \*, stop=True) - - Write the bytes from `buf` to the slave specified by `addr`. + The method returns `None`. - The `stop` argument (only available on WiPy) tells if a stop bit should be - sent at the end of the transfer. If `False` the transfer should be - continued later on. +.. method:: I2C.writeto(addr, buf, stop=True) - On WiPy the return value is the number of bytes written. Otherwise the - return value is `None`. + 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 ----------------- diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index f832cf4664..0b6b24e894 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -31,7 +31,7 @@ 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.readall() # read all available characters + 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 @@ -95,17 +95,12 @@ Methods .. method:: UART.read([nbytes]) - Read characters. If ``nbytes`` is specified then read at most that many bytes. + 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.readall() - - Read as much data as possible. - - Return value: a bytes object or ``None`` on timeout. - .. method:: UART.readinto(buf[, nbytes]) Read bytes into the ``buf``. If ``nbytes`` is specified then read at most diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index 2ae357fe70..061996485f 100644 --- a/docs/library/pyb.Accel.rst +++ b/docs/library/pyb.Accel.rst @@ -46,3 +46,11 @@ Methods .. 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.I2C.rst b/docs/library/pyb.I2C.rst index 67131feec0..7400318902 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -92,7 +92,7 @@ Methods .. only:: port_pyboard - .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False) + .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False, dma=False) Initialise the I2C bus with the given parameters: @@ -100,6 +100,9 @@ Methods - ``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) diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index 4a692469f8..76f347ffa8 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -27,7 +27,7 @@ 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.readall() # read all available characters + 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 @@ -87,8 +87,8 @@ Methods - ``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 the first character. - - ``timeout_char`` is the timeout in milliseconds to wait between characters. + - ``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 @@ -111,17 +111,15 @@ Methods Returns the number of bytes waiting (may be 0). - .. 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.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 @@ -130,12 +128,6 @@ Methods Return value: a bytes object containing the bytes read in. Returns ``None`` on timeout. -.. method:: UART.readall() - - Read as much data as possible. Returns after the timeout has elapsed. - - Return value: a bytes object or ``None`` if timeout prevents any data being read. - .. method:: UART.readchar() Receive a single character on the bus. @@ -170,6 +162,13 @@ Methods 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 diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index 4e34af2586..4c4fe45168 100644 --- a/docs/library/pyb.USB_VCP.rst +++ b/docs/library/pyb.USB_VCP.rst @@ -44,16 +44,12 @@ Methods .. 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 acts as - ``readall()``. USB_VCP stream implicitly works in non-blocking mode, + 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.readall() - - Read all available bytes from the serial device and return them as - a bytes object, or ``None`` if no pending data available. - .. method:: USB_VCP.readinto(buf, [maxlen]) Read bytes from the serial device and store them into ``buf``, which diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 9b279e5ba7..c46e8f4c53 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -149,10 +149,18 @@ Methods Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations - will raise a timeout exception if the timeout period value has elapsed before the operation has + will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode. + .. admonition:: Difference to CPython + :class: attention + + CPython raises a ``socket.timeout`` exception in case of timeout, + which is an ``OSError`` subclass. MicroPython raises an OSError directly + instead. If you use ``except OSError:`` to catch the exception, + your code will work both in MicroPython and CPython. + .. method:: socket.setblocking(flag) Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, @@ -178,14 +186,10 @@ Methods Closing the file object returned by makefile() WILL close the original socket as well. - .. method:: socket.read(size) + .. method:: socket.read([size]) Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it - behaves just like ``socket.readall()``, see below. - - .. method:: socket.readall() - - Read all data available from the socket until ``EOF``. This function will not return until + reads all data available from the socket until ``EOF``; as such the method will not return until the socket is closed. .. method:: socket.readinto(buf[, nbytes]) |