From c4e58eaa9820f5e63d9d94cec5ffb403c1dffbe7 Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 11 Nov 2016 17:36:19 +1100 Subject: stmhal/i2c: Add option to I2C to enable/disable use of DMA transfers. New keyword option in constructor and init() method is "dma=". DMA is now disabled by default for I2C transfers because it currently does not handle I2C bus errors very well (eg if slave device doesn't ACK or NACK correctly during a transfer). --- docs/library/pyb.I2C.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index 67131feec..740031890 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) -- cgit v1.2.3 From a392b3aa75c9309afedd7e9d9f6aeb739c9d9dab Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 14 Nov 2016 23:31:40 +1100 Subject: docs: Remove references to readall() and update stream read() docs. --- docs/library/machine.UART.rst | 11 +++-------- docs/library/pyb.UART.rst | 11 ++++------- docs/library/pyb.USB_VCP.rst | 10 +++------- docs/library/usocket.rst | 8 ++------ 4 files changed, 12 insertions(+), 28 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index f832cf466..0b6b24e89 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.UART.rst b/docs/library/pyb.UART.rst index 4a692469f..b6c0d1a20 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 @@ -122,6 +122,9 @@ Methods 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 +133,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. diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index 4e34af258..4c4fe4516 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 9b279e5ba..e3b2b4501 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -178,14 +178,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]) -- cgit v1.2.3 From 64db4080cec88c7b3937229a653c65a631732379 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 16 Nov 2016 01:15:25 +0300 Subject: docs/library/index: Elaborate on u-modules. Also, remove an "only" directive in u-modules description. --- docs/library/index.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) (limited to 'docs/library') diff --git a/docs/library/index.rst b/docs/library/index.rst index b06c806f7..3621f9d88 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 -- cgit v1.2.3 From 63a5df3cb4c5dec1cb84b86750bb87ace4c1629e Mon Sep 17 00:00:00 2001 From: Damien George Date: Thu, 17 Nov 2016 17:34:48 +1100 Subject: docs/library/machine.I2C: Refine definitions of I2C methods. --- docs/library/machine.I2C.rst | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index f5820f103..3456b240e 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -102,29 +102,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 +136,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) + The method returns `None`. - Write the bytes from `buf` to the slave specified by `addr`. +.. method:: I2C.writeto(addr, buf, stop=True) - 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. - - 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 ----------------- -- cgit v1.2.3 From 46e59c52afe60d1c345df62158b2e5b6c64e9146 Mon Sep 17 00:00:00 2001 From: Peter Hinch Date: Tue, 8 Nov 2016 07:14:56 +0000 Subject: docs/library/pyb.Accel: Add hardware note about pins used by accel. --- docs/library/pyb.Accel.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/library') diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index 2ae357fe7..061996485 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. -- cgit v1.2.3 From 0caac94b986bb0b08918b68d48feb4c5a0c4991c Mon Sep 17 00:00:00 2001 From: Lorenz Schmid Date: Wed, 14 Dec 2016 23:07:42 +0100 Subject: docs/library/pyb.UART: Added clarification about timeouts. --- docs/library/pyb.UART.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/library') diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index b6c0d1a20..4f63c648f 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -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 -- cgit v1.2.3 From a5b3c7e7f9443319d9330ab6ab06c6b365226082 Mon Sep 17 00:00:00 2001 From: Lorenz Schmid Date: Wed, 14 Dec 2016 23:08:43 +0100 Subject: docs/library/pyb.UART: Moved writechar doc to sit with other writes. --- docs/library/pyb.UART.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/library') diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index 4f63c648f..76f347ffa 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -111,11 +111,6 @@ 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. @@ -167,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 -- cgit v1.2.3 From d377c837946dc7476918dcda1580467396e5a153 Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 30 Dec 2016 15:25:48 +1100 Subject: docs/library/machine.I2C: Fix I2C constructor docs to match impl. --- docs/library/machine.I2C.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 3456b240e..cdeb246eb 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 - - .. class:: I2C(scl, sda, \*, freq=400000) - - Construct and return a new I2C object. - See the init method below for a description of the arguments. +.. only:: not port_wipy + + .. class:: I2C(id=-1, \*, scl, sda, freq=400000) + + Construct and return a new I2C object using the following parameters: + + - `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 --------------- -- cgit v1.2.3 From c3f70c603efcb053810dbee8d5cc9f23ed62d01f Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 4 Jan 2017 23:48:19 +1100 Subject: docs/library/esp: Document esp.set_native_code_location() function. --- docs/library/esp.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'docs/library') diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 0836bba72..6481d1f91 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -45,3 +45,43 @@ 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. + + With the default boot/filesystem configuration there is one sector of flash + reserved for general use and one can use the following call to use it for + native code generation:: + + esp.set_native_code_location(esp.flash_user_start(), 4096) + + 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 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. -- cgit v1.2.3 From 36ec5c8f27d787c49f88b2dcf38955e169249d94 Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 6 Jan 2017 18:32:49 +1100 Subject: docs/library/esp: Remove para and add further warning about flash. There is no longer space reserved by default for native code. --- docs/library/esp.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'docs/library') diff --git a/docs/library/esp.rst b/docs/library/esp.rst index 6481d1f91..8cafb92cd 100644 --- a/docs/library/esp.rst +++ b/docs/library/esp.rst @@ -71,15 +71,11 @@ Functions flash that is not otherwise used, for example by the firmware or the filesystem. - With the default boot/filesystem configuration there is one sector of flash - reserved for general use and one can use the following call to use it for - native code generation:: - - esp.set_native_code_location(esp.flash_user_start(), 4096) - 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 -- cgit v1.2.3 From a1a8f01799c7a638db52ae008e85143c4b3f215a Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 7 Jan 2017 14:23:33 +0300 Subject: docs/usocket: Clarify that socket timeout raises OSError exception. --- docs/library/usocket.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index e3b2b4501..c46e8f4c5 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, -- cgit v1.2.3