diff options
| author | Damien George <damien.p.george@gmail.com> | 2018-08-04 16:18:52 +1000 |
|---|---|---|
| committer | Damien George <damien.p.george@gmail.com> | 2019-05-20 14:51:56 +1000 |
| commit | 8bec0e869d2285275487faebcc21a6278ebd311e (patch) | |
| tree | 1b8116b197cc550b07bd411899efade1763aec33 | |
| parent | 1f63e9b701aa6398ddb2e0db5e3a0f7f5adb4fcf (diff) | |
docs/machine.I2C: Add writevto method to write a vector of byte bufs.
This allows to efficiently send to an I2C slave data that is made up of
more than one buffer. Instead of needing to allocate temporary memory to
combine buffers together this new method allows to pass in a tuple or list
of buffers. The name is based on the POSIX function writev() which has
similar intentions and signature.
The reasons for taking this approach (compared to having an interface with
separate start/write/stop methods) are:
- It's a backwards compatible extension.
- It's convenient for the user.
- It's efficient because there is only one Python call, then the C code can
do everything in one go.
- It's efficient on the I2C bus because the implementation can do
everything in one go without pauses between blocks of bytes.
- It should be possible to implement this extension in all ports, for
hardware and software I2C.
Further discussion is found in issue #3482, PR #4020 and PR #4763.
| -rw-r--r-- | docs/library/machine.I2C.rst | 14 |
1 files changed, 14 insertions, 0 deletions
diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 71ca9b0d3..f58912437 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -131,6 +131,20 @@ operations that target a given slave device. generated at the end of the transfer, even if a NACK is received. The function returns the number of ACKs that were received. +.. method:: I2C.writevto(addr, vector, stop=True) + + Write the bytes contained in *vector* to the slave specified by *addr*. + *vector* should be a tuple or list of objects with the buffer protocol. + The *addr* is sent once and then the bytes from each object in *vector* + are written out sequentially. The objects in *vector* may be zero bytes + in length in which case they don't contribute to the output. + + If a NACK is received following the write of a byte from one of the + objects in *vector* then the remaining bytes, and any remaining objects, + 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 ----------------- |