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') 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') 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') 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') 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') 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') 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') 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 71ff0b549d179acb210b4a2cc44ba726f61eede4 Mon Sep 17 00:00:00 2001 From: Andrew Mulholland Date: Tue, 27 Dec 2016 14:16:56 +0000 Subject: docs/esp8266/tutorial: Update intro to add Getting the firmware section. Add a "Getting the firmware" section to better describe how to get hold of the MicroPython firmware, especially if you have a 512kb module. --- docs/esp8266/tutorial/intro.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index 87d446340..fe824cfff 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -35,11 +35,30 @@ If your board has a USB connector on it then most likely it is powered through this when connected to your PC. Otherwise you will need to power it directly. Please refer to the documentation for your board for further details. +Getting the firmware +-------------------- + +The first thing you need to do is download the most recent MicroPython firmware +.bin file to load onto your ESP8266 device. You can download it from the +`MicroPython downloads page `_. +From here, you have 3 main choices + +* Stable firmware builds for 1024kb modules and above. +* Daily firmware builds for 1024kb modules and above. +* Daily firmware builds for 512kb modules. + +The best bet is nearly always to go for the Stable firmware builds. +An exception to this though is if you have an ESP8266 module with only 512kb +of onboard storage. You can easily tell by trying to load a Stable firmware +build and if you get the error below, then you may have to use the Daily +firmware builds for 512kb modules. + WARNING: Unlikely to work as data goes beyond end of flash. + Deploying the firmware ---------------------- -The very first thing you need to do is put the MicroPython firmware (compiled -code) on your ESP8266 device. There are two main steps to do this: first you +Once you have the MicroPython firmware (compiled code), you need to load it onto +your ESP8266 device. There are two main steps to do this: first you need to put your device in boot-loader mode, and second you need to copy across the firmware. The exact procedure for these steps is highly dependent on the particular board and you will need to refer to its documentation for details. -- 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') 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 e1f495a4bdde1f4e24cd45e36420c1c9868b1503 Mon Sep 17 00:00:00 2001 From: Max Date: Tue, 3 Jan 2017 19:20:23 +0100 Subject: docs/esp8266/tutorial: Close socket after reading page content. --- docs/esp8266/tutorial/network_tcp.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/esp8266/tutorial/network_tcp.rst b/docs/esp8266/tutorial/network_tcp.rst index 80a494721..26a2f469c 100644 --- a/docs/esp8266/tutorial/network_tcp.rst +++ b/docs/esp8266/tutorial/network_tcp.rst @@ -72,6 +72,7 @@ Let's define a function that can download and print a URL:: print(str(data, 'utf8'), end='') else: break + s.close() Make sure that you import the socket module before running this function. Then you can try:: -- cgit v1.2.3 From 52c19875a4e9a95920e844b83a104997639bba2f Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 4 Jan 2017 10:15:03 +0300 Subject: esp8266/general: Add "Scarcity of runtime resources" section. With warnings of need to close files, sockets, etc. --- docs/esp8266/general.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst index 04afed46e..cd659f80a 100644 --- a/docs/esp8266/general.rst +++ b/docs/esp8266/general.rst @@ -58,6 +58,17 @@ For your convenience, some of technical specifications are provided below: and always-available BootROM bootloader, ESP8266 is not brickable. +Scarcity of runtime resources +----------------------------- + +ESP8266 has very modest resources (first of all, RAM memory). So, please +avoid allocating too big container objects (lists, dictionaries) and +buffers. There is also no full-fledged OS to keep track of resources +and automatically clean them up, so that's the task of a user/user +application: please be sure to close open files, sockets, etc. as soon +as possible after use. + + Boot process ------------ -- 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') 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') 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') 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 From 5653e3c72fc8555c6a060acf6447ac694a036053 Mon Sep 17 00:00:00 2001 From: Damien George Date: Sun, 8 Jan 2017 23:53:08 +1100 Subject: docs: Bump version to 1.8.7. --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 5ff8d640b..6026aee56 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -99,7 +99,7 @@ copyright = '2014-2016, Damien P. George and contributors' # The short X.Y version. version = '1.8' # The full version, including alpha/beta/rc tags. -release = '1.8.6' +release = '1.8.7' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3