1.. currentmodule:: machine 2.. _machine.SPI: 3 4class SPI -- a Serial Peripheral Interface bus protocol (controller side) 5========================================================================= 6 7SPI is a synchronous serial protocol that is driven by a controller. At the 8physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices 9can share the same bus. Each device should have a separate, 4th signal, 10CS (Chip Select), to select a particular device on a bus with which 11communication takes place. Management of a CS signal should happen in 12user code (via machine.Pin class). 13 14Both hardware and software SPI implementations exist via the 15:ref:`machine.SPI <machine.SPI>` and `machine.SoftSPI` classes. Hardware SPI uses underlying 16hardware support of the system to perform the reads/writes and is usually 17efficient and fast but may have restrictions on which pins can be used. 18Software SPI is implemented by bit-banging and can be used on any pin but 19is not as efficient. These classes have the same methods available and 20differ primarily in the way they are constructed. 21 22Constructors 23------------ 24 25.. class:: SPI(id, ...) 26 27 Construct an SPI object on the given bus, *id*. Values of *id* depend 28 on a particular port and its hardware. Values 0, 1, etc. are commonly used 29 to select hardware SPI block #0, #1, etc. 30 31 With no additional parameters, the SPI object is created but not 32 initialised (it has the settings from the last initialisation of 33 the bus, if any). If extra arguments are given, the bus is initialised. 34 See ``init`` for parameters of initialisation. 35 36.. _machine.SoftSPI: 37.. class:: SoftSPI(baudrate=500000, *, polarity=0, phase=0, bits=8, firstbit=MSB, sck=None, mosi=None, miso=None) 38 39 Construct a new software SPI object. Additional parameters must be 40 given, usually at least *sck*, *mosi* and *miso*, and these are used 41 to initialise the bus. See `SPI.init` for a description of the parameters. 42 43Methods 44------- 45 46.. method:: SPI.init(baudrate=1000000, *, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, sck=None, mosi=None, miso=None, pins=(SCK, MOSI, MISO)) 47 48 Initialise the SPI bus with the given parameters: 49 50 - ``baudrate`` is the SCK clock rate. 51 - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at. 52 - ``phase`` can be 0 or 1 to sample data on the first or second clock edge 53 respectively. 54 - ``bits`` is the width in bits of each transfer. Only 8 is guaranteed to be supported by all hardware. 55 - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. 56 - ``sck``, ``mosi``, ``miso`` are pins (machine.Pin) objects to use for bus signals. For most 57 hardware SPI blocks (as selected by ``id`` parameter to the constructor), pins are fixed 58 and cannot be changed. In some cases, hardware blocks allow 2-3 alternative pin sets for 59 a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver 60 (``id`` = -1). 61 - ``pins`` - WiPy port doesn't ``sck``, ``mosi``, ``miso`` arguments, and instead allows to 62 specify them as a tuple of ``pins`` parameter. 63 64 In the case of hardware SPI the actual clock frequency may be lower than the 65 requested baudrate. This is dependant on the platform hardware. The actual 66 rate may be determined by printing the SPI object. 67 68.. method:: SPI.deinit() 69 70 Turn off the SPI bus. 71 72.. method:: SPI.read(nbytes, write=0x00) 73 74 Read a number of bytes specified by ``nbytes`` while continuously writing 75 the single byte given by ``write``. 76 Returns a ``bytes`` object with the data that was read. 77 78.. method:: SPI.readinto(buf, write=0x00) 79 80 Read into the buffer specified by ``buf`` while continuously writing the 81 single byte given by ``write``. 82 Returns ``None``. 83 84 Note: on WiPy this function returns the number of bytes read. 85 86.. method:: SPI.write(buf) 87 88 Write the bytes contained in ``buf``. 89 Returns ``None``. 90 91 Note: on WiPy this function returns the number of bytes written. 92 93.. method:: SPI.write_readinto(write_buf, read_buf) 94 95 Write the bytes from ``write_buf`` while reading into ``read_buf``. The 96 buffers can be the same or different, but both buffers must have the 97 same length. 98 Returns ``None``. 99 100 Note: on WiPy this function returns the number of bytes written. 101 102Constants 103--------- 104 105.. data:: SPI.CONTROLLER 106 107 for initialising the SPI bus to controller; this is only used for the WiPy 108 109.. data:: SPI.MSB 110 111 set the first bit to be the most significant bit 112 113.. data:: SPI.LSB 114 115 set the first bit to be the least significant bit 116