From a0b2f48c2f501fb60ec312756fe4b17e81f94cc5 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 17 Oct 2016 18:05:16 +0300 Subject: [PATCH] docs/machine.SPI: Bring up to date with Hardware API, make vendor-neutral. --- docs/library/machine.SPI.rst | 47 +++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index 73b3a3996d..7c6627614a 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -1,10 +1,13 @@ .. currentmodule:: machine -class SPI -- a master-driven serial protocol -============================================ +class SPI -- a Serial Peripheral Interface bus protocol +======================================================= -SPI is a serial protocol that is driven by a master. At the physical level -there are 3 lines: SCK, MOSI, MISO. +SPI is a serial protocol that is driven by a master. At the physical level, +bus consistens of 3 lines: SCK, MOSI, MISO. Multiple devices can share the +same bus. Each device should have a separate, 4th signal, SS (Slave Select), +to select a particualr device on a bus with which communication takes place. +Management of an SS signal should happen in user code (via machine.Pin class). .. only:: port_wipy @@ -21,31 +24,37 @@ there are 3 lines: SCK, MOSI, MISO. Constructors ------------ -.. only:: port_wipy +.. class:: SPI(id, ...) - .. class:: SPI(id, ...) + Construct an SPI object on the given bus, ``id``. Values of ``id`` depend + on a particular port and its hardware. Values 0, 1, etc. are commonly used + to select hardware SPI block #0, #1, etc. Value -1 can be used for + bitbanging (software) implementation of SPI (if supported by a port). - 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. + 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. Methods ------- -.. method:: SPI.init(mode, baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=(CLK, MOSI, MISO)) +.. method:: SPI.init(baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=(CLK, MOSI, MISO), sck=None, mosi=None, miso=None) Initialise the SPI bus with the given parameters: - - ``mode`` must be ``SPI.MASTER``. - ``baudrate`` is the SCK clock rate. - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. - ``phase`` can be 0 or 1 to sample data on the first or second clock edge respectively. - - ``bits`` is the width of each transfer, accepted values are 8, 16 and 32. - - ``firstbit`` can be ``SPI.MSB`` only. - - ``pins`` is an optional tuple with the pins to assign to the SPI bus. + - ``bits`` is the width in bits of each transfer. Only 8 of is guaranteed to be supported by all hardware. + - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. + - ``pins`` is an optional tuple with the pins to assign to the SPI bus (deprecated, only for WiPy). + - ``sck``, ``mosi``, ``miso`` are pins (machine.Pin) objects to use for bus signals. For most + hardware SPI blocks (as selected by ``id`` parameter to the constructore), pins are fixed + and cannot be changed. In some cases, hardware blocks allow 2-3 alterbative pin sets for + a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver + (``id``=-1). .. method:: SPI.deinit() @@ -71,7 +80,7 @@ Methods Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the same length. - Returns the number of bytes written + Returns the number of bytes written. Constants --------- @@ -83,3 +92,7 @@ Constants .. data:: SPI.MSB set the first bit to be the most significant bit + +.. data:: SPI.LSB + + set the first bit to be the least significant bit