From 63a5df3cb4c5dec1cb84b86750bb87ace4c1629e Mon Sep 17 00:00:00 2001 From: Damien George Date: Thu, 17 Nov 2016 17:34:48 +1100 Subject: [PATCH] docs/library/machine.I2C: Refine definitions of I2C methods. --- docs/library/machine.I2C.rst | 40 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index f5820f103e..3456b240e1 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`. + The method returns `None`. -.. method:: I2C.writeto(addr, buf, \*, stop=True) +.. method:: I2C.writeto(addr, buf, stop=True) - Write the bytes from `buf` to the slave specified by `addr`. - - 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 -----------------