djsundog
/
circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

atmel-samd: More updates to the docs including the in-code docs.

This commit is contained in:
Scott Shawcroft 2016-10-19 16:49:35 -07:00
parent 7ebc9a4511
commit 0cb0bd0f25
2 changed files with 106 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
index.rst
View File

@ -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

83
shared-bindings/modules/machine.c
View File

@ -39,15 +39,16 @@
//|
//| .. module:: machine
//| :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
@ -56,12 +57,10 @@
//| 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);
@ -84,6 +83,10 @@ STATIC mp_obj_t machine_i2c_make_new(const mp_obj_type_t *type, size_t n_args, s
}
//| .. 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);
@ -92,6 +95,9 @@ 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()
//|
//| 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);
@ -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
//| -----------------------
//|
//| The following methods implement the standard I2C master read and write
//| operations that target a given slave device.
//|
//| .. 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);
@ -151,9 +155,6 @@ MP_DEFINE_CONST_FUN_OBJ_3(machine_i2c_readfrom_obj, machine_i2c_readfrom);
//| Read into `buf` from the slave specified by `addr`.
//| The number of bytes read will be the length of `buf`.
//|
//| On WiPy the return value is the number of bytes read. Otherwise the
//| return value is `None`.
//|
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);
mp_buffer_info_t bufinfo;
@ -176,15 +177,6 @@ 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
//| -----------------
//|
//| 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
@ -224,9 +216,6 @@ MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_readfrom_mem_obj, 1, machine_i2c_readfrom
//| 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`.
//|
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 };
static const mp_arg_t allowed_args[] = {
@ -256,9 +245,6 @@ MP_DEFINE_CONST_FUN_OBJ_KW(machine_i2c_readfrom_mem_into_obj, 1, machine_i2c_rea
//| 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 written. Otherwise the
//| return value is `None`.
//|
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 };
static const mp_arg_t allowed_args[] = {
@ -309,15 +295,16 @@ 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.
//|
//| Constructors
//| ------------
//| 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.)
//|
//| .. class:: SPI(clock, MOSI, MISO, baudrate=1000000)
//|
@ -332,9 +319,6 @@ const mp_obj_type_t machine_i2c_type = {
//| - ``MISO`` is the Master In Slave Out pin.
//| - ``baudrate`` is the SCK clock rate.
//|
//| Methods
//| -------
//|
// TODO(tannewt): Support LSB SPI.
// TODO(tannewt): Support phase, polarity and bit order.
@ -413,11 +397,6 @@ 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)
//|
//| Write the data contained in ``buf``.
@ -448,8 +427,8 @@ MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(mp_machine_spi_read_obj, 2, 3, mp_machine_sp
//| .. method:: SPI.readinto(buf, *, write=0x00)
//|
//| Read into the buffer specified by ``buf`` while writing the data specified by
//| ``write``.
//| 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) {