Skip to content

Commit c816b89

Browse files
dpgeorgedpgeorge
committed
docs/library/machine.I2C: Update to reflect ESP8266 implementation.
This machine.I2C documentation is now closer to a more port-neutral description, although there are still differences between WiPy and ESP8266.
1 parent 8c35f39 commit c816b89

1 file changed

Lines changed: 121 additions & 33 deletions

File tree

‎docs/library/machine.I2C.rst‎

Lines changed: 121 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,15 @@ Constructors
4949
Construct an I2C object on the given bus. `bus` can only be 0.
5050
If the bus is not given, the default one will be selected (0).
5151

52-
Methods
53-
-------
52+
.. only:: port_esp8266
5453

55-
.. method:: i2c.deinit()
54+
.. class:: machine.I2C(scl, sda, \*, freq=400000)
5655

57-
Turn off the I2C bus.
56+
Construct and return a new I2C object.
57+
See the init method below for a description of the arguments.
58+
59+
General Methods
60+
---------------
5861

5962
.. only:: port_wipy
6063

@@ -66,52 +69,137 @@ Methods
6669
- ``baudrate`` is the SCL clock rate
6770
- ``pins`` is an optional tuple with the pins to assign to the I2C bus.
6871

69-
.. method:: i2c.readfrom(addr, nbytes)
72+
.. only:: port_esp8266
73+
74+
.. method:: i2c.init(scl, sda, \*, freq=400000)
75+
76+
Initialise the I2C bus with the given arguments:
7077

71-
Read ``nbytes`` from the slave specified by ``addr``.
72-
Returns a ``bytes`` object with the data read.
78+
- `scl` is a pin object for the SCL line
79+
- `sda` is a pin object for the SDA line
80+
- `freq` is the SCL clock rate
7381

74-
.. method:: i2c.readfrom_into(addr, buf)
82+
.. method:: i2c.deinit()
7583

76-
Read into ``buf`` from the slave specified by ``addr``.
77-
Returns the number of bytes read.
84+
Turn off the I2C bus.
7885

79-
.. method:: i2c.writeto(addr, buf, \*, stop=True)
86+
Availability: WiPy.
8087

81-
Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
82-
if the transfer should be continued.
83-
Returns the number of bytes written.
88+
.. method:: i2c.scan()
8489

85-
.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
90+
Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of
91+
those that respond. A device responds if it pulls the SDA line low after
92+
its address (including a read bit) is sent on the bus.
8693

87-
Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
88-
address specified by ``memaddr``.
89-
Param ``addrsize`` specifies the address size in bits.
90-
Returns a ``bytes`` object with the data read.
94+
Note: on WiPy the I2C object must be in master mode for this method to be valid.
9195

92-
.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
96+
Primitive I2C operations
97+
------------------------
9398

94-
Read into ``buf`` from the slave specified by ``addr`` starting from the memory
95-
address specified by ``memaddr``.
96-
Param ``addrsize`` specifies the address size in bits.
97-
Returns the number of bytes read.
99+
The following methods implement the primitive I2C master bus operations and can
100+
be combined to make any I2C transaction. They are provided if you need more
101+
control over the bus, otherwise the standard methods (see below) can be used.
98102

99-
.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
103+
.. method:: i2c.start()
100104

101-
Write ``buf`` to the slave specified by ``addr`` starting from the
102-
memory address specified by ``memaddr``. Param ``addrsize`` specifies the
103-
address size in bits.
104-
Set ``stop`` to ``False`` if the transfer should be continued.
105-
Returns the number of bytes written.
105+
Send a start bit on the bus (SDA transitions to low while SCL is high).
106106

107-
.. method:: i2c.scan()
107+
Availability: ESP8266.
108+
109+
.. method:: i2c.stop()
110+
111+
Send a stop bit on the bus (SDA transitions to high while SCL is high).
112+
113+
Availability: ESP8266.
114+
115+
.. method:: i2c.readinto(buf)
116+
117+
Reads bytes from the bus and stores them into `buf`. The number of bytes
118+
read is the length of `buf`. An ACK will be sent on the bus after
119+
receiving all but the last byte, and a NACK will be sent following the last
120+
byte.
121+
122+
Availability: ESP8266.
123+
124+
.. method:: i2c.write(buf)
125+
126+
Write all the bytes from `buf` to the bus. Checks that an ACK is received
127+
after each byte and raises an OSError if not.
128+
129+
Availability: ESP8266.
130+
131+
Standard bus operations
132+
-----------------------
133+
134+
The following methods implement the standard I2C master read and write
135+
operations that target a given slave device.
108136

109-
Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond.
110-
Only valid when in master mode.
137+
.. method:: i2c.readfrom(addr, nbytes)
138+
139+
Read `nbytes` from the slave specified by `addr`.
140+
Returns a `bytes` object with the data read.
141+
142+
.. method:: i2c.readfrom_into(addr, buf)
143+
144+
Read into `buf` from the slave specified by `addr`.
145+
The number of bytes read will be the length of `buf`.
146+
147+
On WiPy the return value is the number of bytes read. Otherwise the
148+
return value is `None`.
149+
150+
.. method:: i2c.writeto(addr, buf, \*, stop=True)
151+
152+
Write the bytes from `buf` to the slave specified by `addr`.
153+
154+
The `stop` argument (only available on WiPy) tells if a stop bit should be
155+
sent at the end of the transfer. If `False` the transfer should be
156+
continued later on.
157+
158+
On WiPy the return value is the number of bytes written. Otherwise the
159+
return value is `None`.
160+
161+
Memory operations
162+
-----------------
163+
164+
Some I2C devices act as a memory device (or set of registers) that can be read
165+
from and written to. In this case there are two addresses associated with an
166+
I2C transaction: the slave address and the memory address. The following
167+
methods are convenience functions to communicate with such devices.
168+
169+
.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
170+
171+
Read `nbytes` from the slave specified by `addr` starting from the memory
172+
address specified by `memaddr`.
173+
The argument `addrsize` specifies the address size in bits (on ESP8266
174+
this argument is not recognised and the address size is always 8 bits).
175+
Returns a `bytes` object with the data read.
176+
177+
.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
178+
179+
Read into `buf` from the slave specified by `addr` starting from the
180+
memory address specified by `memaddr`. The number of bytes read is the
181+
length of `buf`.
182+
The argument `addrsize` specifies the address size in bits (on ESP8266
183+
this argument is not recognised and the address size is always 8 bits).
184+
185+
On WiPy the return value is the number of bytes read. Otherwise the
186+
return value is `None`.
187+
188+
.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
189+
190+
Write `buf` to the slave specified by `addr` starting from the
191+
memory address specified by `memaddr`.
192+
The argument `addrsize` specifies the address size in bits (on ESP8266
193+
this argument is not recognised and the address size is always 8 bits).
194+
195+
On WiPy the return value is the number of bytes written. Otherwise the
196+
return value is `None`.
111197

112198
Constants
113199
---------
114200

115201
.. data:: I2C.MASTER
116202

117203
for initialising the bus to master mode
204+
205+
Availability: WiPy.

0 commit comments

Comments
 (0)