Skip to content

Commit 9110e36

Browse files
jeplerjepler
committed
Use main/selected terminology in docstrings
Also copy some notes from busio docstrings to bitbangio docstrings
1 parent 2a1c37c commit 9110e36

6 files changed

Lines changed: 46 additions & 27 deletions

File tree

‎shared-bindings/bitbangio/I2C.c‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,14 @@
4545
//| physical level it consists of 2 wires: SCL and SDA, the clock and data
4646
//| lines respectively.
4747
//|
48+
//| .. seealso:: Using this class directly requires careful lock management.
49+
//| Instead, use :class:`~adafruit_bus_device.i2c_device.I2CDevice` to
50+
//| manage locks.
51+
//|
52+
//| .. seealso:: Using this class to directly read registers requires manual
53+
//| bit unpacking. Instead, use an existing driver or make one with
54+
//| :ref:`Register <register-module-reference>` data descriptors.
55+
//|
4856
//| :param ~microcontroller.Pin scl: The clock pin
4957
//| :param ~microcontroller.Pin sda: The data pin
5058
//| :param int frequency: The clock frequency of the bus
@@ -158,7 +166,7 @@ STATIC mp_obj_t bitbangio_i2c_obj_unlock(mp_obj_t self_in) {
158166
MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_unlock_obj, bitbangio_i2c_obj_unlock);
159167

160168
//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any:
161-
//| """Read into ``buffer`` from the slave specified by ``address``.
169+
//| """Read into ``buffer`` from the device selected by ``address``.
162170
//| The number of bytes read will be the length of ``buffer``.
163171
//| At least one byte must be read.
164172
//|
@@ -210,7 +218,7 @@ STATIC mp_obj_t bitbangio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_a
210218
MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_readfrom_into_obj, 3, bitbangio_i2c_readfrom_into);
211219

212220
//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any:
213-
//| """Write the bytes from ``buffer`` to the slave specified by ``address`` and then transmits a
221+
//| """Write the bytes from ``buffer`` to the device selected by ``address`` and then transmits a
214222
//| stop bit. Use `writeto_then_readfrom` when needing a write, no stop and repeated start
215223
//| before a read.
216224
//|
@@ -270,7 +278,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_writeto_obj, 1, bitbangio_i2c_wr
270278

271279

272280
//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any:
273-
//| """Write the bytes from ``out_buffer`` to the slave specified by ``address``, generate no stop
281+
//| """Write the bytes from ``out_buffer`` to the device selected by ``address``, generate no stop
274282
//| bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and
275283
//| ``in_buffer`` can be the same buffer because they are used sequentially.
276284
//|

‎shared-bindings/bitbangio/SPI.c‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,19 +43,29 @@
4343
//| """A 3-4 wire serial protocol
4444
//|
4545
//| SPI is a serial protocol that has exclusive pins for data in and out of the
46-
//| master. It is typically faster than :py:class:`~bitbangio.I2C` because a
47-
//| separate pin is used to control the active slave rather than a transmitted
46+
//| main device. It is typically faster than :py:class:`~bitbangio.I2C` because a
47+
//| separate pin is used to select a device rather than a transmitted
4848
//| address. This class only manages three of the four SPI lines: `!clock`,
49-
//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave
50-
//| select line. (This is common because multiple slaves can share the `!clock`,
51-
//| `!MOSI` and `!MISO` lines and therefore the hardware.)"""
49+
//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate
50+
//| select line, often abbreviated `!CS` or `!SS`. (This is common because
51+
//| multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines
52+
//| and therefore the hardware.)"""
5253
//|
5354
//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None):
5455
//| """Construct an SPI object on the given pins.
5556
//|
57+
//| .. seealso:: Using this class directly requires careful lock management.
58+
//| Instead, use :class:`~adafruit_bus_device.spi_device.SPIDevice` to
59+
//| manage locks.
60+
//|
61+
//| .. seealso:: Using this class to directly read registers requires manual
62+
//| bit unpacking. Instead, use an existing driver or make one with
63+
//| :ref:`Register <register-module-reference>` data descriptors.
64+
//|
65+
//|
5666
//| :param ~microcontroller.Pin clock: the pin to use for the clock.
57-
//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin.
58-
//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin."""
67+
//| :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
68+
//| :param ~microcontroller.Pin MISO: the Main In Selected Out pin."""
5969
//| ...
6070
//|
6171

‎shared-bindings/busio/I2C.c‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ STATIC mp_obj_t busio_i2c_obj_unlock(mp_obj_t self_in) {
177177
MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock);
178178

179179
//| def readfrom_into(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None) -> Any:
180-
//| """Read into ``buffer`` from the slave specified by ``address``.
180+
//| """Read into ``buffer`` from the device selected by ``address``.
181181
//| The number of bytes read will be the length of ``buffer``.
182182
//| At least one byte must be read.
183183
//|
@@ -229,7 +229,7 @@ STATIC mp_obj_t busio_i2c_readfrom_into(size_t n_args, const mp_obj_t *pos_args,
229229
MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 3, busio_i2c_readfrom_into);
230230

231231
//| def writeto(self, address: int, buffer: bytearray, *, start: int = 0, end: int = None, stop: bool = True) -> Any:
232-
//| """Write the bytes from ``buffer`` to the slave specified by ``address``.
232+
//| """Write the bytes from ``buffer`` to the device selected by ``address``.
233233
//| Transmits a stop bit when stop is True. Setting stop=False is deprecated and stop will be
234234
//| removed in CircuitPython 6.x. Use `writeto_then_readfrom` when needing a write, no stop and
235235
//| repeated start before a read.
@@ -288,7 +288,7 @@ STATIC mp_obj_t busio_i2c_writeto(size_t n_args, const mp_obj_t *pos_args, mp_ma
288288
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto);
289289

290290
//| def writeto_then_readfrom(self, address: int, out_buffer: bytearray, in_buffer: bytearray, *, out_start: int = 0, out_end: int = None, in_start: int = 0, in_end: int = None) -> Any:
291-
//| """Write the bytes from ``out_buffer`` to the slave specified by ``address``, generate no stop
291+
//| """Write the bytes from ``out_buffer`` to the device selected by ``address``, generate no stop
292292
//| bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and
293293
//| ``in_buffer`` can be the same buffer because they are used sequentially.
294294
//|

‎shared-bindings/busio/SPI.c‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,13 @@
4545
//| """A 3-4 wire serial protocol
4646
//|
4747
//| SPI is a serial protocol that has exclusive pins for data in and out of the
48-
//| master. It is typically faster than :py:class:`~busio.I2C` because a
49-
//| separate pin is used to control the active slave rather than a transitted
48+
//| main device. It is typically faster than :py:class:`~bitbangio.I2C` because a
49+
//| separate pin is used to select a device rather than a transmitted
5050
//| address. This class only manages three of the four SPI lines: `!clock`,
51-
//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate slave
52-
//| select line. (This is common because multiple slaves can share the `!clock`,
53-
//| `!MOSI` and `!MISO` lines and therefore the hardware.)"""
51+
//| `!MOSI`, `!MISO`. Its up to the client to manage the appropriate
52+
//| select line, often abbreviated `!CS` or `!SS`. (This is common because
53+
//| multiple secondaries can share the `!clock`, `!MOSI` and `!MISO` lines
54+
//| and therefore the hardware.)"""
5455
//|
5556
//| def __init__(self, clock: microcontroller.Pin, MOSI: microcontroller.Pin = None, MISO: microcontroller.Pin = None):
5657
//|
@@ -72,8 +73,8 @@
7273
//| :ref:`Register <register-module-reference>` data descriptors.
7374
//|
7475
//| :param ~microcontroller.Pin clock: the pin to use for the clock.
75-
//| :param ~microcontroller.Pin MOSI: the Master Out Slave In pin.
76-
//| :param ~microcontroller.Pin MISO: the Master In Slave Out pin."""
76+
//| :param ~microcontroller.Pin MOSI: the Main Out Selected In pin.
77+
//| :param ~microcontroller.Pin MISO: the Main In Selected Out pin."""
7778
//| ...
7879
//|
7980

‎shared-bindings/i2cslave/I2CSlave.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_obj___exit__(size_t n_args, const mp_obj_t *a
134134
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(i2cslave_i2c_slave___exit___obj, 4, 4, i2cslave_i2c_slave_obj___exit__);
135135

136136
//| def request(self, timeout: float = -1) -> Any:
137-
//| """Wait for an I2C request from a master.
137+
//| """Wait for an I2C request.
138138
//|
139139
//| :param float timeout: Timeout in seconds. Zero means wait forever, a negative value means check once
140140
//| :return: I2C Slave Request or None if timeout=-1 and there's no request
@@ -228,12 +228,12 @@ const mp_obj_type_t i2cslave_i2c_slave_type = {
228228
//| class I2CSlaveRequest:
229229
//|
230230
//| def __init__(self, slave: i2cslave.I2CSlave, address: int, is_read: bool, is_restart: bool):
231-
//| """I2C transfer request from a master.
231+
//| """Information about an I2C transfer request
232232
//| This cannot be instantiated directly, but is returned by :py:meth:`I2CSlave.request`.
233233
//|
234234
//| :param slave: The I2C Slave receiving this request
235235
//| :param address: I2C address
236-
//| :param is_read: I2C Master read request
236+
//| :param is_read: True if the main device is requesting data
237237
//| :param is_restart: Repeated Start Condition"""
238238
//|
239239
STATIC mp_obj_t i2cslave_i2c_slave_request_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) {
@@ -270,7 +270,7 @@ STATIC mp_obj_t i2cslave_i2c_slave_request_get_address(mp_obj_t self_in) {
270270
MP_DEFINE_CONST_PROP_GET(i2cslave_i2c_slave_request_address_obj, i2cslave_i2c_slave_request_get_address);
271271

272272
//| is_read: bool = ...
273-
//| """The I2C master is reading from the device."""
273+
//| """The I2C main controller is reading from this device."""
274274
//|
275275
STATIC mp_obj_t i2cslave_i2c_slave_request_get_is_read(mp_obj_t self_in) {
276276
mp_check_self(MP_OBJ_IS_TYPE(self_in, &i2cslave_i2c_slave_request_type));

‎shared-bindings/i2cslave/__init__.c‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,17 +53,17 @@
5353
//| if not r:
5454
//| # Maybe do some housekeeping
5555
//| continue
56-
//| with r: # Closes the transfer if necessary by sending a NACK or feeding the master dummy bytes
56+
//| with r: # Closes the transfer if necessary by sending a NACK or feeding dummy bytes
5757
//| if r.address == 0x40:
58-
//| if not r.is_read: # Master write which is Slave read
58+
//| if not r.is_read: # Main write which is Selected read
5959
//| b = r.read(1)
6060
//| if not b or b[0] > 15:
6161
//| break
6262
//| index = b[0]
6363
//| b = r.read(1)
6464
//| if b:
6565
//| regs[index] = b[0]
66-
//| elif r.is_restart: # Combined transfer: This is the Master read message
66+
//| elif r.is_restart: # Combined transfer: This is the Main read message
6767
//| n = r.write(bytes([regs[index]]))
6868
//| #else:
6969
//| # A read transfer is not supported in this example

0 commit comments

Comments
 (0)