diff options
28 files changed, 362 insertions, 283 deletions
@@ -319,6 +319,6 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/3/': None, - 'https://circuitpython.readthedocs.io/projects/bus_device/en/latest/': None, - 'https://circuitpython.readthedocs.io/projects/register/en/latest/': None} +intersphinx_mapping = {"cpython": ('https://docs.python.org/3/', None), + "bus_device": ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None), + "register": ('https://circuitpython.readthedocs.io/projects/register/en/latest/', None)} diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 69860b7dc..8ce47041f 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -33,6 +33,8 @@ not have the ``adafruit_`` module or package prefix. Both should have the CircuitPython repository topic on GitHub. +.. _lifetime-and-contextmanagers: + Lifetime and ContextManagers -------------------------------------------------------------------------------- @@ -41,6 +43,49 @@ device requires deinitialization, then provide it through ``deinit()`` and also provide ``__enter__`` and ``__exit__`` to create a context manager usable with ``with``. +For example, a user can then use ``deinit()```:: + + import digitalio + import board + + led = digitalio.DigitalInOut(board.D13) + led.direction = digitalio.DigitalInOut.Direction.OUT + + for i in range(10): + led.value = True + time.sleep(0.5) + + led.value = False + time.sleep(0.5) + led.deinit() + +This will deinit the underlying hardware at the end of the program as long as no +exceptions occur. + +Alternatively, using a ``with`` statement ensures that the hardware is deinitialized:: + + import digitalio + import board + + with digitalio.DigitalInOut(board.D13) as led: + led.direction = digitalio.DigitalInOut.Direction.OUT + + for i in range(10): + led.value = True + time.sleep(0.5) + + led.value = False + time.sleep(0.5) + +Python's ``with`` statement ensures that the deinit code is run regardless of +whether the code within the with statement executes without exceptions. + +For small programs like the examples this isn't a major concern because all +user usable hardware is reset after programs are run or the REPL is run. However, +for more complex programs that may use hardware intermittently and may also +handle exceptions on their own, deinitializing the hardware using a with +statement will ensure hardware isn't enabled longer than needed. + Verify your device -------------------------------------------------------------------------------- diff --git a/shared-bindings/analogio/AnalogIn.c b/shared-bindings/analogio/AnalogIn.c index f07302250..23b08470f 100644 --- a/shared-bindings/analogio/AnalogIn.c +++ b/shared-bindings/analogio/AnalogIn.c @@ -45,8 +45,8 @@ //| import analogio //| from board import * //| -//| with analogio.AnalogIn(A1) as adc: -//| val = adc.value +//| adc = analogio.AnalogIn(A1) +//| val = adc.value //| //| .. class:: AnalogIn(pin) @@ -93,7 +93,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogin_deinit_obj, analogio_analogin_deinit //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t analogio_analogin___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 6b02f8c0a..6b65878b4 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -45,8 +45,8 @@ //| import analogio //| from microcontroller import pin //| -//| with analogio.AnalogOut(pin.PA02) as dac: # output on pin PA02 -//| dac.value = 32768 # makes PA02 1.65V +//| dac = analogio.AnalogOut(pin.PA02) # output on pin PA02 +//| dac.value = 32768 # makes PA02 1.65V //| //| .. class:: AnalogOut(pin) @@ -91,7 +91,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(analogio_analogout_deinit_obj, analogio_analogo //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t analogio_analogout___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/analogio/__init__.c b/shared-bindings/analogio/__init__.c index 39d6bdcda..b468bcde0 100644 --- a/shared-bindings/analogio/__init__.c +++ b/shared-bindings/analogio/__init__.c @@ -53,21 +53,24 @@ //| AnalogIn //| AnalogOut //| -//| All libraries change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. +//| All classes change hardware state and should be deinitialized when they +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| //| For example:: //| //| import analogio //| from board import * //| -//| with analogio.AnalogIn(A0) as pin: -//| print(pin.value) +//| pin = analogio.AnalogIn(A0) +//| print(pin.value) +//| pin.deinit() //| //| This example will initialize the the device, read //| :py:data:`~analogio.AnalogIn.value` and then -//| :py:meth:`~analogio.AnalogIn.deinit` the hardware. +//| :py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional +//| because CircuitPython will do it automatically after the program finishes. //| STATIC const mp_rom_map_elem_t analogio_module_globals_table[] = { diff --git a/shared-bindings/audioio/AudioOut.c b/shared-bindings/audioio/AudioOut.c index a765994d5..b47652104 100644 --- a/shared-bindings/audioio/AudioOut.c +++ b/shared-bindings/audioio/AudioOut.c @@ -66,10 +66,10 @@ //| for i in range(length): //| b[i] = int(math.sin(math.pi * 2 * i / 18) * (2 ** 15) + 2 ** 15) //| -//| with audioio.AudioOut(board.SPEAKER, sin_wave) as sample: -//| sample.play(loop=True) -//| time.sleep(1) -//| sample.stop() +//| sample = audioio.AudioOut(board.SPEAKER, sin_wave) +//| sample.play(loop=True) +//| time.sleep(1) +//| sample.stop() //| //| Playing a wave file from flash:: //| @@ -136,7 +136,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(audioio_audioout_deinit_obj, audioio_audioout_d //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t audioio_audioout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/audioio/__init__.c b/shared-bindings/audioio/__init__.c index 3e831a171..07305a45a 100644 --- a/shared-bindings/audioio/__init__.c +++ b/shared-bindings/audioio/__init__.c @@ -49,9 +49,10 @@ //| //| AudioOut //| -//| All libraries change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. +//| All classes change hardware state and should be deinitialized when they +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC const mp_rom_map_elem_t audioio_module_globals_table[] = { diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index 6c2c4223f..147a8d4f1 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -90,7 +90,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_deinit_obj, bitbangio_i2c_obj_deinit); //| .. method:: I2C.__exit__() //| -//| Automatically deinitializes the hardware on context exit. +//| Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t bitbangio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/bitbangio/OneWire.c b/shared-bindings/bitbangio/OneWire.c index 14645444d..bbdf7c8f5 100644 --- a/shared-bindings/bitbangio/OneWire.c +++ b/shared-bindings/bitbangio/OneWire.c @@ -55,11 +55,11 @@ //| import bitbangio //| import board //| -//| with bitbangio.OneWire(board.D7) as onewire: -//| onewire.reset() -//| onewire.write_bit(True) -//| onewire.write_bit(False) -//| print(onewire.read_bit()) +//| onewire = bitbangio.OneWire(board.D7) +//| onewire.reset() +//| onewire.write_bit(True) +//| onewire.write_bit(False) +//| print(onewire.read_bit()) //| STATIC mp_obj_t bitbangio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) { mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true); @@ -101,7 +101,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_onewire_deinit_obj, bitbangio_onewire //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t bitbangio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index f8cf90628..8589025d9 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -102,7 +102,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_spi_deinit_obj, bitbangio_spi_obj_deinit); //| .. method:: SPI.__exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t bitbangio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/bitbangio/__init__.c b/shared-bindings/bitbangio/__init__.c index 85acab0d3..3123fb199 100644 --- a/shared-bindings/bitbangio/__init__.c +++ b/shared-bindings/bitbangio/__init__.c @@ -64,21 +64,24 @@ //| OneWire //| SPI //| -//| All libraries change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. +//| All classes change hardware state and should be deinitialized when they +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| //| For example:: //| //| import bitbangio //| from board import * //| -//| with bitbangio.I2C(SCL, SDA) as i2c: -//| i2c.scan() +//| i2c = bitbangio.I2C(SCL, SDA) +//| print(i2c.scan()) +//| i2c.deinit() //| //| This example will initialize the the device, run //| :py:meth:`~bitbangio.I2C.scan` and then :py:meth:`~bitbangio.I2C.deinit` the -//| hardware. +//| hardware. The last step is optional because CircuitPython automatically +//| resets hardware after a program finishes. //| STATIC const mp_rom_map_elem_t bitbangio_module_globals_table[] = { diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index b1794fdfb..a10a792fd 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -85,9 +85,9 @@ STATIC mp_obj_t busio_i2c_make_new(const mp_obj_type_t *type, size_t n_args, siz //| Releases control of the underlying hardware so other classes can use it. //| STATIC mp_obj_t busio_i2c_obj_deinit(mp_obj_t self_in) { - busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); - common_hal_busio_i2c_deinit(self); - return mp_const_none; + busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); + common_hal_busio_i2c_deinit(self); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_deinit_obj, busio_i2c_obj_deinit); @@ -99,7 +99,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_deinit_obj, busio_i2c_obj_deinit); //| .. method:: I2C.__exit__() //| -//| Automatically deinitializes the hardware on context exit. +//| Automatically deinitializes the hardware on context exit. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t busio_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -123,17 +124,17 @@ static void check_lock(busio_i2c_obj_t *self) { //| :rtype: list //| STATIC mp_obj_t busio_i2c_scan(mp_obj_t self_in) { - busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); - check_lock(self); - mp_obj_t list = mp_obj_new_list(0, NULL); - // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved - for (int addr = 0x08; addr < 0x78; ++addr) { - bool success = common_hal_busio_i2c_probe(self, addr); - if (success) { - mp_obj_list_append(list, MP_OBJ_NEW_SMALL_INT(addr)); - } - } - return list; + busio_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); + check_lock(self); + mp_obj_t list = mp_obj_new_list(0, NULL); + // 7-bit addresses 0b0000xxx and 0b1111xxx are reserved + for (int addr = 0x08; addr < 0x78; ++addr) { + bool success = common_hal_busio_i2c_probe(self, addr); + if (success) { + mp_obj_list_append(list, MP_OBJ_NEW_SMALL_INT(addr)); + } + } + return list; } MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); diff --git a/shared-bindings/busio/OneWire.c b/shared-bindings/busio/OneWire.c index 52aed2135..f270d9d92 100644 --- a/shared-bindings/busio/OneWire.c +++ b/shared-bindings/busio/OneWire.c @@ -55,11 +55,11 @@ //| import busio //| import board //| -//| with busio.OneWire(board.D7) as onewire: -//| onewire.reset() -//| onewire.write_bit(True) -//| onewire.write_bit(False) -//| print(onewire.read_bit()) +//| onewire = busio.OneWire(board.D7) +//| onewire.reset() +//| onewire.write_bit(True) +//| onewire.write_bit(False) +//| print(onewire.read_bit()) //| STATIC mp_obj_t busio_onewire_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) { mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true); @@ -101,7 +101,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_onewire_deinit_obj, busio_onewire_deinit) //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t busio_onewire_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 0fb0c7ddf..9f073234e 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -115,7 +115,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_deinit_obj, busio_spi_obj_deinit); //| .. method:: SPI.__exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t busio_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index 11ee91355..6b053ad7e 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -63,54 +63,54 @@ extern const busio_uart_parity_obj_t busio_uart_parity_even_obj; extern const busio_uart_parity_obj_t busio_uart_parity_odd_obj; STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) { - mp_arg_check_num(n_args, n_kw, 0, MP_OBJ_FUN_ARGS_MAX, true); - busio_uart_obj_t *self = m_new_obj(busio_uart_obj_t); - self->base.type = &busio_uart_type; - mp_map_t kw_args; - mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args); - enum { ARG_tx, ARG_rx, ARG_baudrate, ARG_bits, ARG_parity, ARG_stop, ARG_timeout, ARG_receiver_buffer_size}; - static const mp_arg_t allowed_args[] = { - { MP_QSTR_tx, MP_ARG_REQUIRED | MP_ARG_OBJ }, - { MP_QSTR_rx, MP_ARG_REQUIRED | MP_ARG_OBJ }, - { MP_QSTR_baudrate, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 9600} }, - { MP_QSTR_bits, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 8} }, - { MP_QSTR_parity, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} }, - { MP_QSTR_stop, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1} }, - { MP_QSTR_timeout, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1000} }, - { MP_QSTR_receiver_buffer_size, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 64} }, - }; - mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; - mp_arg_parse_all(n_args, pos_args, &kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - - assert_pin(args[ARG_rx].u_obj, true); - const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(args[ARG_rx].u_obj); - assert_pin_free(rx); - - assert_pin(args[ARG_tx].u_obj, true); - const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(args[ARG_tx].u_obj); - assert_pin_free(tx); - - uint8_t bits = args[ARG_bits].u_int; - if (bits < 7 || bits > 9) { - mp_raise_ValueError("bits must be 7, 8 or 9"); - } - - uart_parity_t parity = PARITY_NONE; - if (args[ARG_parity].u_obj == &busio_uart_parity_even_obj) { - parity = PARITY_EVEN; - } else if (args[ARG_parity].u_obj == &busio_uart_parity_odd_obj) { - parity = PARITY_ODD; - } - - uint8_t stop = args[ARG_stop].u_int; - if (stop != 1 && stop != 2) { - mp_raise_ValueError("stop must be 1 or 2"); - } - - common_hal_busio_uart_construct(self, tx, rx, - args[ARG_baudrate].u_int, bits, parity, stop, args[ARG_timeout].u_int, - args[ARG_receiver_buffer_size].u_int); - return (mp_obj_t)self; + mp_arg_check_num(n_args, n_kw, 0, MP_OBJ_FUN_ARGS_MAX, true); + busio_uart_obj_t *self = m_new_obj(busio_uart_obj_t); + self->base.type = &busio_uart_type; + mp_map_t kw_args; + mp_map_init_fixed_table(&kw_args, n_kw, pos_args + n_args); + enum { ARG_tx, ARG_rx, ARG_baudrate, ARG_bits, ARG_parity, ARG_stop, ARG_timeout, ARG_receiver_buffer_size}; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_tx, MP_ARG_REQUIRED | MP_ARG_OBJ }, + { MP_QSTR_rx, MP_ARG_REQUIRED | MP_ARG_OBJ }, + { MP_QSTR_baudrate, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 9600} }, + { MP_QSTR_bits, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 8} }, + { MP_QSTR_parity, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_none} }, + { MP_QSTR_stop, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1} }, + { MP_QSTR_timeout, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 1000} }, + { MP_QSTR_receiver_buffer_size, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 64} }, + }; + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args, pos_args, &kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + assert_pin(args[ARG_rx].u_obj, true); + const mcu_pin_obj_t* rx = MP_OBJ_TO_PTR(args[ARG_rx].u_obj); + assert_pin_free(rx); + + assert_pin(args[ARG_tx].u_obj, true); + const mcu_pin_obj_t* tx = MP_OBJ_TO_PTR(args[ARG_tx].u_obj); + assert_pin_free(tx); + + uint8_t bits = args[ARG_bits].u_int; + if (bits < 7 || bits > 9) { + mp_raise_ValueError("bits must be 7, 8 or 9"); + } + + uart_parity_t parity = PARITY_NONE; + if (args[ARG_parity].u_obj == &busio_uart_parity_even_obj) { + parity = PARITY_EVEN; + } else if (args[ARG_parity].u_obj == &busio_uart_parity_odd_obj) { + parity = PARITY_ODD; + } + + uint8_t stop = args[ARG_stop].u_int; + if (stop != 1 && stop != 2) { + mp_raise_ValueError("stop must be 1 or 2"); + } + + common_hal_busio_uart_construct(self, tx, rx, + args[ARG_baudrate].u_int, bits, parity, stop, args[ARG_timeout].u_int, + args[ARG_receiver_buffer_size].u_int); + return (mp_obj_t)self; } //| .. method:: deinit() @@ -118,9 +118,9 @@ STATIC mp_obj_t busio_uart_make_new(const mp_obj_type_t *type, size_t n_args, si //| Deinitialises the UART and releases any hardware resources for reuse. //| STATIC mp_obj_t busio_uart_obj_deinit(mp_obj_t self_in) { - busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); - common_hal_busio_uart_deinit(self); - return mp_const_none; + busio_uart_obj_t *self = MP_OBJ_TO_PTR(self_in); + common_hal_busio_uart_deinit(self); + return mp_const_none; } STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_deinit_obj, busio_uart_obj_deinit); @@ -132,7 +132,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(busio_uart_deinit_obj, busio_uart_obj_deinit); //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t busio_uart_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/busio/__init__.c b/shared-bindings/busio/__init__.c index 9e075752d..4686e7287 100644 --- a/shared-bindings/busio/__init__.c +++ b/shared-bindings/busio/__init__.c @@ -65,21 +65,24 @@ //| SPI //| UART //| -//| All libraries change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. +//| All classes change hardware state and should be deinitialized when they +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| //| For example:: //| //| import busio //| from board import * //| -//| with busio.I2C(SCL, SDA) as i2c: -//| i2c.scan() +//| i2c = busio.I2C(SCL, SDA) +//| print(i2c.scan()) +//| i2c.deinit() //| //| This example will initialize the the device, run //| :py:meth:`~busio.I2C.scan` and then :py:meth:`~busio.I2C.deinit` the -//| hardware. +//| hardware. The last step is optional because CircuitPython automatically +//| resets hardware after a program finishes. //| STATIC const mp_rom_map_elem_t busio_module_globals_table[] = { diff --git a/shared-bindings/digitalio/DigitalInOut.c b/shared-bindings/digitalio/DigitalInOut.c index e5b7c4241..6b85bc6ea 100644 --- a/shared-bindings/digitalio/DigitalInOut.c +++ b/shared-bindings/digitalio/DigitalInOut.c @@ -76,9 +76,9 @@ STATIC mp_obj_t digitalio_digitalinout_make_new(const mp_obj_type_t *type, //| Turn off the DigitalInOut and release the pin for other use. //| STATIC mp_obj_t digitalio_digitalinout_obj_deinit(mp_obj_t self_in) { - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); - common_hal_digitalio_digitalinout_deinit(self); - return mp_const_none; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); + common_hal_digitalio_digitalinout_deinit(self); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalinout_obj_deinit); @@ -90,7 +90,8 @@ MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_deinit_obj, digitalio_digitalin //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t digitalio_digitalinout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; @@ -115,22 +116,22 @@ extern const digitalio_digitalinout_drive_mode_obj_t digitalio_digitalinout_driv extern const digitalio_digitalinout_drive_mode_obj_t digitalio_digitalinout_drive_mode_open_drain_obj; STATIC mp_obj_t digitalio_digitalinout_switch_to_output(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { - enum { ARG_value, ARG_drive_mode }; - static const mp_arg_t allowed_args[] = { - { MP_QSTR_value, MP_ARG_BOOL, {.u_bool = false} }, - { MP_QSTR_drive_mode, MP_ARG_OBJ, {.u_rom_obj = &digitalio_digitalinout_drive_mode_push_pull_obj} }, - }; - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); - mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; - mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - - enum digitalinout_drive_mode_t drive_mode = DRIVE_MODE_PUSH_PULL; - if (args[ARG_drive_mode].u_rom_obj == &digitalio_digitalinout_drive_mode_open_drain_obj) { - drive_mode = DRIVE_MODE_OPEN_DRAIN; - } - // do the transfer - common_hal_digitalio_digitalinout_switch_to_output(self, args[ARG_value].u_bool, drive_mode); - return mp_const_none; + enum { ARG_value, ARG_drive_mode }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_value, MP_ARG_BOOL, {.u_bool = false} }, + { MP_QSTR_drive_mode, MP_ARG_OBJ, {.u_rom_obj = &digitalio_digitalinout_drive_mode_push_pull_obj} }, + }; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + enum digitalinout_drive_mode_t drive_mode = DRIVE_MODE_PUSH_PULL; + if (args[ARG_drive_mode].u_rom_obj == &digitalio_digitalinout_drive_mode_open_drain_obj) { + drive_mode = DRIVE_MODE_OPEN_DRAIN; + } + // do the transfer + common_hal_digitalio_digitalinout_switch_to_output(self, args[ARG_value].u_bool, drive_mode); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digitalio_digitalinout_switch_to_output); @@ -145,11 +146,11 @@ MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_output_obj, 1, digit //| import digitalio //| import board //| -//| with digitalio.DigitalInOut(board.SLIDE_SWITCH) as switch: -//| switch.switch_to_input(pull=digitalio.DigitalInOut.Pull.UP) -//| # Or, after switch_to_input -//| switch.pull = digitalio.DigitalInOut.Pull.UP -//| print(switch.value) +//| switch = digitalio.DigitalInOut(board.SLIDE_SWITCH) +//| switch.switch_to_input(pull=digitalio.DigitalInOut.Pull.UP) +//| # Or, after switch_to_input +//| switch.pull = digitalio.DigitalInOut.Pull.UP +//| print(switch.value) //| typedef struct { mp_obj_base_t base; @@ -158,34 +159,34 @@ extern const digitalio_digitalinout_pull_obj_t digitalio_digitalinout_pull_up_ob extern const digitalio_digitalinout_pull_obj_t digitalio_digitalinout_pull_down_obj; STATIC mp_obj_t digitalio_digitalinout_switch_to_input(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { - enum { ARG_pull }; - static const mp_arg_t allowed_args[] = { - { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} }, - }; - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); - mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; - mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); - - enum digitalinout_pull_t pull = PULL_NONE; - if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_up_obj) { - pull = PULL_UP; - }else if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_down_obj) { - pull = PULL_DOWN; - } - // do the transfer - common_hal_digitalio_digitalinout_switch_to_input(self, pull); - return mp_const_none; + enum { ARG_pull }; + static const mp_arg_t allowed_args[] = { + { MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = mp_const_none} }, + }; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); + mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)]; + mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); + + enum digitalinout_pull_t pull = PULL_NONE; + if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_up_obj) { + pull = PULL_UP; + }else if (args[ARG_pull].u_rom_obj == &digitalio_digitalinout_pull_down_obj) { + pull = PULL_DOWN; + } + // do the transfer + common_hal_digitalio_digitalinout_switch_to_input(self, pull); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_KW(digitalio_digitalinout_switch_to_input_obj, 1, digitalio_digitalinout_switch_to_input); //| .. attribute:: direction //| -//| The direction of the pin. +//| The direction of the pin. //| -//| Setting this will use the defaults from the corresponding -//| :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If -//| you want to set pull, value or drive mode prior to switching, then use -//| those methods instead. +//| Setting this will use the defaults from the corresponding +//| :py:meth:`switch_to_input` or :py:meth:`switch_to_output` method. If +//| you want to set pull, value or drive mode prior to switching, then use +//| those methods instead. //| typedef struct { mp_obj_base_t base; @@ -194,12 +195,12 @@ extern const digitalio_digitalinout_direction_obj_t digitalio_digitalinout_direc extern const digitalio_digitalinout_direction_obj_t digitalio_digitalinout_direction_out_obj; STATIC mp_obj_t digitalio_digitalinout_obj_get_direction(mp_obj_t self_in) { - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); - enum digitalinout_direction_t direction = common_hal_digitalio_digitalinout_get_direction(self); - if (direction == DIRECTION_IN) { - return (mp_obj_t)&digitalio_digitalinout_direction_in_obj; - } - return (mp_obj_t)&digitalio_digitalinout_direction_out_obj; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); + enum digitalinout_direction_t direction = common_hal_digitalio_digitalinout_get_direction(self); + if (direction == DIRECTION_IN) { + return (mp_obj_t)&digitalio_digitalinout_direction_in_obj; + } + return (mp_obj_t)&digitalio_digitalinout_direction_out_obj; } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_get_direction_obj, digitalio_digitalinout_obj_get_direction); @@ -225,7 +226,7 @@ const mp_obj_property_t digitalio_digitalinout_direction_obj = { //| .. attribute:: value //| -//| The digital logic level of the pin. +//| The digital logic level of the pin. //| STATIC mp_obj_t digitalio_digitalinout_obj_get_value(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -254,7 +255,7 @@ const mp_obj_property_t digitalio_digitalinout_value_obj = { //| .. attribute:: drive_mode //| -//| Get or set the pin drive mode. +//| Get or set the pin drive mode. //| STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) { digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -271,17 +272,17 @@ STATIC mp_obj_t digitalio_digitalinout_obj_get_drive_mode(mp_obj_t self_in) { MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_get_drive_mode_obj, digitalio_digitalinout_obj_get_drive_mode); STATIC mp_obj_t digitalio_digitalinout_obj_set_drive_mode(mp_obj_t self_in, mp_obj_t drive_mode) { - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); - if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_IN) { - mp_raise_AttributeError("Drive mode not used when direction is input."); - return mp_const_none; - } - enum digitalinout_drive_mode_t c_drive_mode = DRIVE_MODE_PUSH_PULL; - if (drive_mode == &digitalio_digitalinout_drive_mode_open_drain_obj) { - c_drive_mode = DRIVE_MODE_OPEN_DRAIN; - } - common_hal_digitalio_digitalinout_set_drive_mode(self, c_drive_mode); - return mp_const_none; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); + if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_IN) { + mp_raise_AttributeError("Drive mode not used when direction is input."); + return mp_const_none; + } + enum digitalinout_drive_mode_t c_drive_mode = DRIVE_MODE_PUSH_PULL; + if (drive_mode == &digitalio_digitalinout_drive_mode_open_drain_obj) { + c_drive_mode = DRIVE_MODE_OPEN_DRAIN; + } + common_hal_digitalio_digitalinout_set_drive_mode(self, c_drive_mode); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_2(digitalio_digitalinout_set_drive_mode_obj, digitalio_digitalinout_obj_set_drive_mode); @@ -294,40 +295,40 @@ const mp_obj_property_t digitalio_digitalinout_drive_mode_obj = { //| .. attribute:: pull //| -//| Get or set the pin pull. +//| Get or set the pin pull. //| -//| :raises AttributeError: if the direction is ~`Direction.OUT`. +//| :raises AttributeError: if the direction is ~`Direction.OUT`. //| STATIC mp_obj_t digitalio_digitalinout_obj_get_pull(mp_obj_t self_in) { - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); - if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) { - mp_raise_AttributeError("Pull not used when direction is output."); - return mp_const_none; - } - enum digitalinout_pull_t pull = common_hal_digitalio_digitalinout_get_pull(self); - if (pull == PULL_UP) { - return (mp_obj_t)&digitalio_digitalinout_pull_up_obj; - } else if (pull == PULL_DOWN) { - return (mp_obj_t)&digitalio_digitalinout_pull_down_obj; - } - return (mp_obj_t)&mp_const_none_obj; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); + if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) { + mp_raise_AttributeError("Pull not used when direction is output."); + return mp_const_none; + } + enum digitalinout_pull_t pull = common_hal_digitalio_digitalinout_get_pull(self); + if (pull == PULL_UP) { + return (mp_obj_t)&digitalio_digitalinout_pull_up_obj; + } else if (pull == PULL_DOWN) { + return (mp_obj_t)&digitalio_digitalinout_pull_down_obj; + } + return (mp_obj_t)&mp_const_none_obj; } MP_DEFINE_CONST_FUN_OBJ_1(digitalio_digitalinout_get_pull_obj, digitalio_digitalinout_obj_get_pull); STATIC mp_obj_t digitalio_digitalinout_obj_set_pull(mp_obj_t self_in, mp_obj_t pull_obj) { - digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); - if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) { - mp_raise_AttributeError("Pull not used when direction is output."); - return mp_const_none; - } - enum digitalinout_pull_t pull = PULL_NONE; - if (pull_obj == &digitalio_digitalinout_pull_up_obj) { - pull = PULL_UP; - } else if (pull_obj == &digitalio_digitalinout_pull_down_obj) { - pull = PULL_DOWN; - } - common_hal_digitalio_digitalinout_set_pull(self, pull); - return mp_const_none; + digitalio_digitalinout_obj_t *self = MP_OBJ_TO_PTR(self_in); + if (common_hal_digitalio_digitalinout_get_direction(self) == DIRECTION_OUT) { + mp_raise_AttributeError("Pull not used when direction is output."); + return mp_const_none; + } + enum digitalinout_pull_t pull = PULL_NONE; + if (pull_obj == &digitalio_digitalinout_pull_up_obj) { + pull = PULL_UP; + } else if (pull_obj == &digitalio_digitalinout_pull_down_obj) { + pull = PULL_DOWN; + } + common_hal_digitalio_digitalinout_set_pull(self, pull); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_2(digitalio_digitalinout_set_pull_obj, digitalio_digitalinout_obj_set_pull); diff --git a/shared-bindings/digitalio/__init__.c b/shared-bindings/digitalio/__init__.c index 687110671..7767f236f 100644 --- a/shared-bindings/digitalio/__init__.c +++ b/shared-bindings/digitalio/__init__.c @@ -52,16 +52,17 @@ //| DigitalInOut //| //| All classes change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| //| For example:: //| //| import digitalio //| from board import * //| -//| with digitalio.DigitalInOut(D13) as pin: -//| print(pin.value) +//| pin = digitalio.DigitalInOut(D13) +//| print(pin.value) //| //| This example will initialize the the device, read //| :py:data:`~digitalio.DigitalInOut.value` and then @@ -73,9 +74,9 @@ //| from board import * //| import time //| -//| with digitalio.DigitalInOut(D13) as led: -//| led.switch_to_output() -//| while True: +//| led = digitalio.DigitalInOut(D13) +//| led.direction = digitalio.DigitalInOut.Direction.OUT +//| while True: //| led.value = True //| time.sleep(0.1) //| led.value = False diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst index beb7ba68b..e44c60f83 100644 --- a/shared-bindings/index.rst +++ b/shared-bindings/index.rst @@ -7,6 +7,8 @@ in a port if no underlying hardware support is present or if flash space is limited. For example, a microcontroller without analog features will not have `analogio`. +.. _module-support-matrix: + Support Matrix --------------- diff --git a/shared-bindings/pulseio/PWMOut.c b/shared-bindings/pulseio/PWMOut.c index 850033502..80036ae72 100644 --- a/shared-bindings/pulseio/PWMOut.c +++ b/shared-bindings/pulseio/PWMOut.c @@ -60,16 +60,16 @@ //| import pulseio //| import board //| -//| with pulseio.PWMOut(board.D13) as pwm: # output on D13 -//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz +//| pwm = pulseio.PWMOut(board.D13) # output on D13 +//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at the default 500hz //| //| PWM at specific frequency (servos and motors):: //| //| import pulseio //| import board //| -//| with pulseio.PWMOut(board.D13, frequency=50) as pwm: -//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz +//| pwm = pulseio.PWMOut(board.D13, frequency=50) +//| pwm.duty_cycle = 2 ** 15 # Cycles the pin with 50% duty cycle (half of 2 ** 16) at 50hz //| //| Variable frequency (usually tones):: //| @@ -77,10 +77,10 @@ //| import board //| import time //| -//| with pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True) as pwm: -//| time.sleep(0.2) -//| pwm.frequency = 880 -//| time.sleep(0.1) +//| pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15, frequency=440, variable_frequency=True) +//| time.sleep(0.2) +//| pwm.frequency = 880 +//| time.sleep(0.1) //| STATIC mp_obj_t pulseio_pwmout_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) { mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true); @@ -131,7 +131,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pwmout_deinit_obj, pulseio_pwmout_deini //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t pulseio_pwmout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/pulseio/PulseIn.c b/shared-bindings/pulseio/PulseIn.c index a5d5d0c72..89196e841 100644 --- a/shared-bindings/pulseio/PulseIn.c +++ b/shared-bindings/pulseio/PulseIn.c @@ -61,22 +61,23 @@ //| import pulseio //| import board //| -//| with pulseio.PulseIn(board.D7) as pulses: -//| # Wait for an active pulse -//| while len(pulses) == 0: -//| pass -//| # Pause while we do something with the pulses -//| pulses.pause() +//| pulses = pulseio.PulseIn(board.D7) //| -//| # Print the pulses. pulses[0] is an active pulse unless the length -//| # reached max length and idle pulses are recorded. -//| print(pulses) +//| # Wait for an active pulse +//| while len(pulses) == 0: +//| pass +//| # Pause while we do something with the pulses +//| pulses.pause() //| -//| # Clear the rest -//| pulse_in.clear() +//| # Print the pulses. pulses[0] is an active pulse unless the length +//| # reached max length and idle pulses are recorded. +//| print(pulses) //| -//| # Resume with an 80 microsecond active pulse -//| pulse_in.resume(80) +//| # Clear the rest +//| pulse_in.clear() +//| +//| # Resume with an 80 microsecond active pulse +//| pulse_in.resume(80) //| STATIC mp_obj_t pulseio_pulsein_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *pos_args) { mp_arg_check_num(n_args, n_kw, 1, MP_OBJ_FUN_ARGS_MAX, true); @@ -122,7 +123,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulsein_deinit_obj, pulseio_pulsein_dei //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t pulseio_pulsein_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/pulseio/PulseOut.c b/shared-bindings/pulseio/PulseOut.c index 7b05e704c..0b1391f74 100644 --- a/shared-bindings/pulseio/PulseOut.c +++ b/shared-bindings/pulseio/PulseOut.c @@ -54,15 +54,15 @@ //| import pulseio //| import board //| -//| with pulseio.PWMOut(board.D13, duty_cycle=2 ** 15) as pwm: -//| pulse = pulseio.PulseOut(pwm) -//| # on off on off on -//| pulses = array.array('H', [65000, 1000, 65000, 65000, 1000]) -//| pulse.send(pulses) +//| pwm = pulseio.PWMOut(board.D13, duty_cycle=2 ** 15) +//| pulse = pulseio.PulseOut(pwm) +//| # on off on off on +//| pulses = array.array('H', [65000, 1000, 65000, 65000, 1000]) +//| pulse.send(pulses) //| -//| # Modify the array of pulses. -//| pulses[0] = 200 -//| pulse.send(pulses) +//| # Modify the array of pulses. +//| pulses[0] = 200 +//| pulse.send(pulses) //| STATIC mp_obj_t pulseio_pulseout_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) { mp_arg_check_num(n_args, n_kw, 1, 1, true); @@ -100,7 +100,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pulseio_pulseout_deinit_obj, pulseio_pulseout_d //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t pulseio_pulseout_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/pulseio/__init__.c b/shared-bindings/pulseio/__init__.c index bf3272108..1114b604b 100644 --- a/shared-bindings/pulseio/__init__.c +++ b/shared-bindings/pulseio/__init__.c @@ -53,9 +53,15 @@ //| PulseOut //| PWMOut //| -//| All libraries change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. + +//| .. warning:: This module is not available in some SAMD21 builds. See the +//| :ref:`module-support-matrix` for more info. +//| + +//| All classes change hardware state and should be deinitialized when they +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| //| For example:: //| @@ -63,13 +69,15 @@ //| import time //| from board import * //| -//| with pulseio.PWMOut(D13) as pin: -//| pin.duty_cycle = 2 ** 15 -//| time.sleep(0.1) +//| pwm = pulseio.PWMOut(D13) +//| pwm.duty_cycle = 2 ** 15 +//| time.sleep(0.1) //| //| This example will initialize the the device, set -//| :py:data:`~pulseio.PWMOut.duty_cycle`, sleep 0.1 seconds and then -//| :py:meth:`~pulseio.PWMOut.deinit` the hardware. +//| :py:data:`~pulseio.PWMOut.duty_cycle`, and then sleep 0.1 seconds. +//| CircuitPython will automatically turn off the PWM when it resets all +//| hardware after program completion. Use ``deinit()`` or a ``with`` statement +//| to do it yourself. //| STATIC const mp_rom_map_elem_t pulseio_module_globals_table[] = { diff --git a/shared-bindings/time/__init__.c b/shared-bindings/time/__init__.c index b258b3bbd..9ad631a63 100644 --- a/shared-bindings/time/__init__.c +++ b/shared-bindings/time/__init__.c @@ -39,7 +39,7 @@ //| :synopsis: time and timing related functions //| :platform: SAMD21 //| -//| The `time` module is a strict subset of the CPython `time` module. So, code +//| The `time` module is a strict subset of the CPython `cpython:time` module. So, code //| written in MicroPython will work in CPython but not necessarily the other //| way around. //| diff --git a/shared-bindings/touchio/TouchIn.c b/shared-bindings/touchio/TouchIn.c index f4e82994c..894781423 100644 --- a/shared-bindings/touchio/TouchIn.c +++ b/shared-bindings/touchio/TouchIn.c @@ -45,9 +45,10 @@ //| import touchio //| from board import * //| -//| with touchio.TouchIn(A1) as touch: -//| if touch.value: -//| print("touched!") +//| touch = touchio.TouchIn(A1) +//| while True: +//| if touch.value: +//| print("touched!") //| //| .. class:: TouchIn(pin) @@ -92,7 +93,8 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(touchio_touchin_deinit_obj, touchio_touchin_dei //| .. method:: __exit__() //| -//| Automatically deinitializes the hardware when exiting a context. +//| Automatically deinitializes the hardware when exiting a context. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| STATIC mp_obj_t touchio_touchin_obj___exit__(size_t n_args, const mp_obj_t *args) { (void)n_args; diff --git a/shared-bindings/touchio/__init__.c b/shared-bindings/touchio/__init__.c index a930c1af7..6adbe09cf 100644 --- a/shared-bindings/touchio/__init__.c +++ b/shared-bindings/touchio/__init__.c @@ -52,21 +52,21 @@ //| //| TouchIn //| -//| All libraries change hardware state and should be deinitialized when they -//| are no longer needed. To do so, either call :py:meth:`!deinit` or use a -//| context manager. +//| All classes change hardware state and should be deinitialized when they +//| are no longer needed if the program continues after use. To do so, either +//| call :py:meth:`!deinit` or use a context manager. See +//| :ref:`lifetime-and-contextmanagers` for more info. //| //| For example:: //| //| import touchio //| from board import * //| -//| with touchio.TouchIn(D6) as touch_pin: -//| print(touch_pin.value) +//| touch_pin = touchio.TouchIn(D6) +//| print(touch_pin.value) //| -//| This example will initialize the the device, run -//| :py:data:`~touchio.TouchIn.value` and then :py:meth:`~touchio.TouchIn.deinit` -//| the hardware. +//| This example will initialize the the device, and print the +//| :py:data:`~touchio.TouchIn.value`. //| STATIC const mp_rom_map_elem_t touchio_module_globals_table[] = { diff --git a/shared-bindings/usb_hid/Device.c b/shared-bindings/usb_hid/Device.c index 3a3cc5170..7e5d3d9e8 100644 --- a/shared-bindings/usb_hid/Device.c +++ b/shared-bindings/usb_hid/Device.c @@ -55,13 +55,13 @@ STATIC mp_obj_t usb_hid_device_make_new(const mp_obj_type_t *type, //| Send a HID report. //| STATIC mp_obj_t usb_hid_device_send_report(mp_obj_t self_in, mp_obj_t buffer) { - usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); + usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); - mp_buffer_info_t bufinfo; - mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ); + mp_buffer_info_t bufinfo; + mp_get_buffer_raise(buffer, &bufinfo, MP_BUFFER_READ); - common_hal_usb_hid_device_send_report(self, ((uint8_t*) bufinfo.buf), bufinfo.len); - return mp_const_none; + common_hal_usb_hid_device_send_report(self, ((uint8_t*) bufinfo.buf), bufinfo.len); + return mp_const_none; } MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_report); @@ -73,8 +73,8 @@ MP_DEFINE_CONST_FUN_OBJ_2(usb_hid_device_send_report_obj, usb_hid_device_send_re //| :rtype: int //| STATIC mp_obj_t usb_hid_device_obj_get_usage_page(mp_obj_t self_in) { - usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); - return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage_page(self)); + usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); + return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage_page(self)); } MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_device_get_usage_page_obj, usb_hid_device_obj_get_usage_page); @@ -95,8 +95,8 @@ const mp_obj_property_t usb_hid_device_usage_page_obj = { //| :rtype: int //| STATIC mp_obj_t usb_hid_device_obj_get_usage(mp_obj_t self_in) { - usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); - return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage(self)); + usb_hid_device_obj_t *self = MP_OBJ_TO_PTR(self_in); + return MP_OBJ_NEW_SMALL_INT(common_hal_usb_hid_device_get_usage(self)); } MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_device_get_usage_obj, usb_hid_device_obj_get_usage); diff --git a/shared-bindings/usb_hid/__init__.c b/shared-bindings/usb_hid/__init__.c index a870cb4a1..3ad5b06e0 100644 --- a/shared-bindings/usb_hid/__init__.c +++ b/shared-bindings/usb_hid/__init__.c @@ -41,10 +41,6 @@ //| The `usb_hid` module allows you to output data as a HID device. //| -//| .. warning:: This module may be dropped from builds without external flash -//| in the future. Please file an issue if this a problem and explain why. -//| - //| .. attribute:: usb_hid.devices //| //| Tuple of all active HID device interfaces. |