diff options
| -rw-r--r-- | index.rst | 20 | ||||
| -rw-r--r-- | shared-bindings/modules/machine.c | 205 |
2 files changed, 104 insertions, 121 deletions
@@ -1,19 +1,23 @@ -Adafruit's MicroPython API Reference +Adafruit MicroPython API Reference ======================================== -Welcome! This is the documentation for Adafruit's version MicroPython. It is an -open source derivative of MicroPython for use on educational development boards -designed and sold by Adafruit including the Arduino Zero, Adafruit Feather M0 -Basic, Adafruit Feather HUZZAH and Adafruit Feather M0 Bluefruit LE. +Welcome! This is the documentation for Adafruit MicroPython. It is an open +source derivative of `MicroPython <https://micropython.org>`_ for use on +educational development boards designed and sold by `Adafruit +<https://adafruit.com>`_ including the `Arduino Zero +<https://www.arduino.cc/en/Main/ArduinoBoardZero>`_, `Adafruit Feather M0 Basic +<https://www.adafruit.com/product/2772>`_, `Adafruit Feather HUZZAH +<https://www.adafruit.com/products/2821>`_ and `Adafruit Feather M0 Bluefruit LE +<https://www.adafruit.com/products/2995>`_. Adafruit's MicroPython port features a unified Python APIs available under `shared-bindings` and a growing list of drivers that work with it. Currently only the Atmel SAMD21 port is supported but ESP8266 support will be added in the near future. -Adafruit has many excellent tutorials available through the Adafruit Learning -System. These docs are low-level API docs and may link out to separate getting -started guides. +`Adafruit <https://adafruit.com>`_ has many excellent tutorials available +through the `Adafruit Learning System <https://learn.adafruit.com/>`_. These +docs are low-level API docs and may link out to separate getting started guides. .. toctree:: :maxdepth: 2 diff --git a/shared-bindings/modules/machine.c b/shared-bindings/modules/machine.c index d2fd97ff1..e58eda62b 100644 --- a/shared-bindings/modules/machine.c +++ b/shared-bindings/modules/machine.c @@ -38,30 +38,29 @@ //| ================================================= //| //| .. module:: machine -//| :synopsis: functions related to the board +//| :synopsis: functions related to the board +//| :platform: SAMD21 //| //| The ``machine`` module contains specific functions related to the board. //| -//| This is soon to be renamed to distinguish it from upstream's machine! +//| This is soon to be renamed to distinguish it from upstream's `machine`! //| -//| .. currentmodule:: machine +//| :class:`I2C` --- Two wire serial protocol +//| ------------------------------------------ //| -//| class I2C -- a two-wire serial protocol -//| ======================================= +//| .. class:: I2C(scl, sda, \*, freq=400000) //| -//| I2C is a two-wire protocol for communicating between devices. At the -//| physical level it consists of 2 wires: SCL and SDA, the clock and data lines -//| respectively. +//| I2C is a two-wire protocol for communicating between devices. At the +//| physical level it consists of 2 wires: SCL and SDA, the clock and data lines +//| respectively. //| -//| I2C objects are created attached to a specific bus. They can be initialised -//| when created, or initialised later on. +//| I2C objects are created attached to a specific bus. They can be initialised +//| when created, or initialised later on. //| -//| Constructors -//| ------------ -//| .. class:: I2C(scl, sda, \*, freq=400000) +//| :param str scl: The clock pin +//| :param str sda: The data pin +//| :param int freq: The clock frequency //| -//| Construct and return a new I2C object. -//| See the init method below for a description of the arguments. STATIC mp_obj_t machine_i2c_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); machine_i2c_obj_t *self = m_new_obj(machine_i2c_obj_t); @@ -83,7 +82,11 @@ STATIC mp_obj_t machine_i2c_make_new(const mp_obj_type_t *type, size_t n_args, s return (mp_obj_t)self; } -//| .. method:: I2C.init() +//| .. method:: I2C.init() +//| +//| Initializes control of the underlying hardware so other classes cannot +//| use it. +//| STATIC mp_obj_t machine_i2c_obj_init(mp_obj_t self_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); mp_hal_i2c_init(self); @@ -91,7 +94,10 @@ STATIC mp_obj_t machine_i2c_obj_init(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_init_obj, machine_i2c_obj_init); -//| .. method:: I2C.deinit() +//| .. method:: I2C.deinit() +//| +//| Releases control of the underlying hardware so other classes can use it. +//| STATIC mp_obj_t machine_i2c_obj_deinit(mp_obj_t self_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); mp_hal_i2c_deinit(self); @@ -106,11 +112,11 @@ STATIC mp_obj_t machine_i2c_obj___exit__(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_i2c_obj___exit___obj, 4, 4, machine_i2c_obj___exit__); -//| .. method:: I2C.scan() +//| .. method:: I2C.scan() //| -//| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of -//| those that respond. A device responds if it pulls the SDA line low after -//| its address (including a read bit) is sent on the bus. +//| Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of +//| those that respond. A device responds if it pulls the SDA line low after +//| its address (including a read bit) is sent on the bus. //| STATIC mp_obj_t machine_i2c_scan(mp_obj_t self_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -126,16 +132,14 @@ STATIC mp_obj_t machine_i2c_scan(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(machine_i2c_scan_obj, machine_i2c_scan); -//| Standard bus operations -//| ----------------------- +//| .. method:: I2C.readfrom(addr, nbytes) //| -//| The following methods implement the standard I2C master read and write -//| operations that target a given slave device. +//| Read `nbytes` from the slave specified by `addr`. //| -//| .. method:: I2C.readfrom(addr, nbytes) -//| -//| Read `nbytes` from the slave specified by `addr`. -//| Returns a `bytes` object with the data read. +//| :param int addr: The 7 bit address of the device +//| :param int nbytes: The number of bytes to read +//| :return: the data read +//| :rtype: bytes //| STATIC mp_obj_t machine_i2c_readfrom(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t nbytes_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -146,13 +150,10 @@ STATIC mp_obj_t machine_i2c_readfrom(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_ } MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_readfrom_obj, machine_i2c_readfrom); -//| .. method:: I2C.readfrom_into(addr, buf) -//| -//| Read into `buf` from the slave specified by `addr`. -//| The number of bytes read will be the length of `buf`. +//| .. method:: I2C.readfrom_into(addr, buf) //| -//| On WiPy the return value is the number of bytes read. Otherwise the -//| return value is `None`. +//| Read into `buf` from the slave specified by `addr`. +//| The number of bytes read will be the length of `buf`. //| STATIC mp_obj_t machine_i2c_readfrom_into(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t buf_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -163,9 +164,9 @@ STATIC mp_obj_t machine_i2c_readfrom_into(mp_obj_t self_in, mp_obj_t addr_in, mp } MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_readfrom_into_obj, machine_i2c_readfrom_into); -//| .. method:: I2C.writeto(addr, buf) +//| .. method:: I2C.writeto(addr, buf) //| -//| Write the bytes from `buf` to the slave specified by `addr`. +//| Write the bytes from `buf` to the slave specified by `addr`. //| STATIC mp_obj_t machine_i2c_writeto(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t buf_in) { machine_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -176,22 +177,13 @@ STATIC mp_obj_t machine_i2c_writeto(mp_obj_t self_in, mp_obj_t addr_in, mp_obj_t } STATIC MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_writeto_obj, machine_i2c_writeto); -//| Memory operations -//| ----------------- +//| .. method:: I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8) //| -//| Some I2C devices act as a memory device (or set of registers) that can be -//| read from and written to. In this case there are two addresses associated -//| with an I2C transaction: the slave address and the memory address. The following -//| following methods are convenience functions to communicate with such -//| devices. -//| -//| .. method:: I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8) -//| -//| Read `nbytes` from the slave specified by `addr` starting from the memory -//| address specified by `memaddr`. -//| The argument `addrsize` specifies the address size in bits (on ESP8266 -//| this argument is not recognised and the address size is always 8 bits). -//| Returns a `bytes` object with the data read. +//| Read `nbytes` from the slave specified by `addr` starting from the memory +//| address specified by `memaddr`. +//| The argument `addrsize` specifies the address size in bits (on ESP8266 +//| this argument is not recognised and the address size is always 8 bits). +//| Returns a `bytes` object with the data read. //| STATIC mp_obj_t machine_i2c_readfrom_mem(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_addr, ARG_memaddr, ARG_n, ARG_addrsize }; @@ -216,16 +208,13 @@ STATIC mp_obj_t machine_i2c_readfrom_mem(size_t n_args, const mp_obj_t *pos_args MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_readfrom_mem_obj, 1, machine_i2c_readfrom_mem); -//| .. method:: I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8) +//| .. method:: I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8) //| -//| Read into `buf` from the slave specified by `addr` starting from the -//| memory address specified by `memaddr`. The number of bytes read is the -//| length of `buf`. -//| The argument `addrsize` specifies the address size in bits (on ESP8266 -//| this argument is not recognised and the address size is always 8 bits). -//| -//| On WiPy the return value is the number of bytes read. Otherwise the -//| return value is `None`. +//| Read into `buf` from the slave specified by `addr` starting from the +//| memory address specified by `memaddr`. The number of bytes read is the +//| length of `buf`. +//| The argument `addrsize` specifies the address size in bits (on ESP8266 +//| this argument is not recognised and the address size is always 8 bits). //| STATIC mp_obj_t machine_i2c_readfrom_mem_into(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize }; @@ -249,15 +238,12 @@ STATIC mp_obj_t machine_i2c_readfrom_mem_into(size_t n_args, const mp_obj_t *pos } MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_readfrom_mem_into_obj, 1, machine_i2c_readfrom_mem_into); -//| .. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8) -//| -//| Write `buf` to the slave specified by `addr` starting from the -//| memory address specified by `memaddr`. -//| The argument `addrsize` specifies the address size in bits (on ESP8266 -//| this argument is not recognised and the address size is always 8 bits). +//| .. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8) //| -//| On WiPy the return value is the number of bytes written. Otherwise the -//| return value is `None`. +//| Write `buf` to the slave specified by `addr` starting from the +//| memory address specified by `memaddr`. +//| The argument `addrsize` specifies the address size in bits (on ESP8266 +//| this argument is not recognised and the address size is always 8 bits). //| STATIC mp_obj_t machine_i2c_writeto_mem(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_addr, ARG_memaddr, ARG_buf, ARG_addrsize }; @@ -309,31 +295,29 @@ const mp_obj_type_t machine_i2c_type = { .locals_dict = (mp_obj_dict_t*)&machine_i2c_locals_dict, }; -//| class SPI -- a master-driven serial protocol -//| ============================================ +//| :class:`SPI` -- a 3-4 wire serial protocol +//| ----------------------------------------------- //| -//| SPI is a serial protocol that is driven by a master. This class only -//| manages three of the four SPI lines: SCK, MOSI, MISO. Its up to the client -//| to manage the appropriate slave select line. +//| SPI is a serial protocol that has exlusive pins for data in and out of the +//| master. It is typically faster than `I2C` because a separate pin is used to +//| control the active slave rather than a transitted address. This class only +//| manages three of the four SPI lines: `clock`, `MOSI`, `MISO`. Its up to the +//| client to manage the appropriate slave select line. (This is common because +//| multiple slaves can share the `clock`, `MOSI` and `MISO` lines and therefore +//| the hardware.) //| -//| Constructors -//| ------------ +//| .. class:: SPI(clock, MOSI, MISO, baudrate=1000000) //| -//| .. class:: SPI(clock, MOSI, MISO, baudrate=1000000) +//| Construct an SPI object on the given bus. ``id`` can be only 0. +//| With no additional parameters, the SPI object is created but not +//| initialised (it has the settings from the last initialisation of +//| the bus, if any). If extra arguments are given, the bus is initialised. +//| See ``init`` for parameters of initialisation. //| -//| Construct an SPI object on the given bus. ``id`` can be only 0. -//| With no additional parameters, the SPI object is created but not -//| initialised (it has the settings from the last initialisation of -//| the bus, if any). If extra arguments are given, the bus is initialised. -//| See ``init`` for parameters of initialisation. -//| -//| - ``clock`` is the pin to use for the clock. -//| - ``MOSI`` is the Master Out Slave In pin. -//| - ``MISO`` is the Master In Slave Out pin. -//| - ``baudrate`` is the SCK clock rate. -//| -//| Methods -//| ------- +//| - ``clock`` is the pin to use for the clock. +//| - ``MOSI`` is the Master Out Slave In pin. +//| - ``MISO`` is the Master In Slave Out pin. +//| - ``baudrate`` is the SCK clock rate. //| // TODO(tannewt): Support LSB SPI. @@ -364,9 +348,9 @@ STATIC mp_obj_t machine_spi_make_new(const mp_obj_type_t *type, size_t n_args, s return (mp_obj_t)self; } -//| .. method:: SPI.init() +//| .. method:: SPI.init() //| -//| Initialises the bus. +//| Initialises the bus. //| STATIC mp_obj_t machine_spi_obj_init(mp_obj_t self_in) { machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -375,9 +359,9 @@ STATIC mp_obj_t machine_spi_obj_init(mp_obj_t self_in) { } MP_DEFINE_CONST_FUN_OBJ_1(machine_spi_init_obj, machine_spi_obj_init); -//| .. method:: SPI.deinit() +//| .. method:: SPI.deinit() //| -//| Turn off the SPI bus. +//| Turn off the SPI bus. //| STATIC mp_obj_t machine_spi_obj_deinit(mp_obj_t self_in) { machine_spi_obj_t *self = MP_OBJ_TO_PTR(self_in); @@ -393,11 +377,11 @@ STATIC mp_obj_t machine_spi_obj___exit__(size_t n_args, const mp_obj_t *args) { } STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_spi_obj___exit___obj, 4, 4, machine_spi_obj___exit__); -//| .. method:: SPI.write_readinto(write_buf, read_buf) +//| .. method:: SPI.write_readinto(write_buf, read_buf) //| -//| Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the -//| same length. This is the same as a SPI transfer function on other platforms. -//| Returns the number of bytes written +//| Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the +//| same length. This is the same as a SPI transfer function on other platforms. +//| Returns the number of bytes written //| STATIC mp_obj_t mp_machine_spi_write_readinto(mp_obj_t self_in, mp_obj_t wr_buf, mp_obj_t rd_buf) { mp_buffer_info_t src; @@ -413,15 +397,10 @@ STATIC mp_obj_t mp_machine_spi_write_readinto(mp_obj_t self_in, mp_obj_t wr_buf, } MP_DEFINE_CONST_FUN_OBJ_3(mp_machine_spi_write_readinto_obj, mp_machine_spi_write_readinto); -//| Helper operations -//| ----------------- -//| The below operations are finer grained operations based upon ``SPI.write_readinto``. -//| They may be moved out of the core module later. -//| -//| .. method:: SPI.write(buf) +//| .. method:: SPI.write(buf) //| -//| Write the data contained in ``buf``. -//| Returns the number of bytes written. +//| Write the data contained in ``buf``. +//| Returns the number of bytes written. //| STATIC mp_obj_t mp_machine_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { mp_buffer_info_t src; @@ -432,10 +411,10 @@ STATIC mp_obj_t mp_machine_spi_write(mp_obj_t self_in, mp_obj_t wr_buf) { } MP_DEFINE_CONST_FUN_OBJ_2(mp_machine_spi_write_obj, mp_machine_spi_write); -//| .. method:: SPI.read(nbytes, *, write=0x00) +//| .. method:: SPI.read(nbytes, *, write=0x00) //| -//| Read the ``nbytes`` while writing the data specified by ``write``. -//| Return the number of bytes read. +//| Read the ``nbytes`` while writing the data specified by ``write``. +//| Return the number of bytes read. //| STATIC mp_obj_t mp_machine_spi_read(size_t n_args, const mp_obj_t *args) { vstr_t vstr; @@ -446,11 +425,11 @@ STATIC mp_obj_t mp_machine_spi_read(size_t n_args, const mp_obj_t *args) { } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_machine_spi_read_obj, 2, 3, mp_machine_spi_read); -//| .. method:: SPI.readinto(buf, *, write=0x00) +//| .. method:: SPI.readinto(buf, *, write=0x00) //| -//| Read into the buffer specified by ``buf`` while writing the data specified by -//| ``write``. -//| Return the number of bytes read. +//| Read into the buffer specified by ``buf`` while writing the data +//| specified by ``write``. +//| Return the number of bytes read. //| STATIC mp_obj_t mp_machine_spi_readinto(size_t n_args, const mp_obj_t *args) { mp_buffer_info_t bufinfo; |