SPI – Serial Peripheral Interface Bus Protocol

2025-11-14

This class provides bus protocol of serial peripheral interface (SPI) .

Constructor

machine.SPI 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 812.5kHz
    1 ： 1.625MHz
    2 ： 3.25MHz
    3 ： 6.5MHz
    4 ： 13MHz
    5 ： 26MHz
    6 ： 52MHz

    • The 52MHz clock frequency has high requirements for hardware. 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 960kHz
    1 ： 4.8MHz
    2 ： 9.6MHz
    3 ： 16MHz
    4 ： 19.2MHz
    5 ： 25MHz
    6 ： 50MHz

    • The 50MHz clock frequency has high requirements for hardware. 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 100kHz
    1 ： 200MHz
    2 ： 300MHz
    3 ： 400MHz
    4 ： 500MHz
    5 ： 600MHz
    6 ： 700MHz 7 ： 812.5kHz
    8 ： 1.625MHz
    9 ： 3.25MHz
    10 ： 6.5MHz
    11 ： 13MHz
    12 ： 26MHz
    13 ： 52MHz

    • The 52MHz clock frequency has high requirements for hardware. 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 812.5kHz
    1 ： 1.625MHz
    2 ： 3.25MHz
    3 ： 6.5MHz
    4 ： 13MHz

  • [group] - Select to use SPI on different pins, with a default value of 0.
    1 ： This group of pins does not support mounting nor flash. 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 812.5kHz
    1 ： 1.625MHz
    2 ： 3.25MHz
    3 ： 6.5MHz
    4 ： 13MHz 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 781.25KHz
    1 ： 1.5625MHz
    2 ： 3.125MHz
    3 ： 5MHz
    4 ： 6.25MHz
    5 ： 10MHz
    6 ： 12.5MHz
    7 ： 20MHz
    8 ： 25MHz
    9 ： 33.33MHz 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 781.25KHz
    X ： XMHz (X in [1,39]) 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    0 ： 97.656kHz
    1 ： 100kHz
    2 ： 812.5kHz
    3 ： 1.3MHz
    4 ： 1.625MHz
    5 ： 2MHz
    6 ： 3.25MHz
    7 ： 4.333MHz
    8 ： 6.6MHz
    9 ： 11.93MHz
    10 ： 13MHz
    11 ： 13.92MHz
    12 ： 16.7MHz
    13 ： 20.875MHz
    14 ： 27.83MHz 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 500kHz
    1 ： 1MHz
    2 ： 5MHz
    3 ： 10MHz
    4 ： 20MHz 

class machine.SPI(spi, mode, clk, [group])

Parameter:

  • port - Integer type. Channel selection: [0,1].

  • mode - SPI working mode.
    Clock polarity CPOL: The pin level of clock signal SCLK when SPI is idle (0: low level; 1: high level)
    0 ： CPOL=0, CPHA=0
    1 ： CPOL=0, CPHA=1
    2 ： CPOL=1, CPHA=0
    3 ： CPOL=1, CPHA=1

  • clk - Clock frequency.
    0 ： 500kHz
    1~30 ： (1~30)*1MHz

Example: 

>>> from machine import SPI
>>> # Creates a SPI object
>>> spi_obj = SPI(1, 0, 1)

SPI Pin Correspondences:

SPI CS CLK MOSI MISO
spi0 pin4 pin1 pin3 pin2
spi1 pin58 pin61 pin59 pin60
SPI CS CLK MOSI MISO
spi0 pin134 pin133 pin132 pin131
spi1 pin26 pin27 pin24 pin25
SPI CS CLK MOSI MISO
spi0 pin31 pin30 pin32 pin33
spi1 pin52 pin53 pin50 pin51
SPI CS CLK MOSI MISO
spi0 pin6 pin5 pin4 pin3
SPI CS CLK MOSI MISO
spi0 pin25 pin26 pin27 pin28
spi1 pin41 pin40 pin64 pin65
spi2 pin19 pin18 pin23 pin22
SPI CS CLK MOSI MISO
spi0
group0 		pin58 pin61 pin59 pin60
spi0
group1 		pin4 pin1 pin3 pin2
spi1
group0 		pin4 pin1 pin3 pin2
spi1
group1 		pin65 pin67 pin66 pin63
spi2 pin49 pin54 pin53 pin52
SPI CS CLK MOSI MISO
spi0 pin25 pin26 pin64 pin88
spi1 pin5 pin4 pin6 pin7
SPI CS CLK MOSI MISO
spi0
group0 		pin31 pin30 pin32 pin33
spi0
group1 		pin52 pin53 pin50 pin51
spi1
group0 		pin52 pin53 pin50 pin51
spi1
group1 		pin69 pin68 pin85 pin84
spi2 pin76 pin77 pin78 pin16
SPI CS CLK MOSI MISO
spi0
group0 		pin31 pin30 pin32 pin33
spi0
group1 		pin52 pin53 pin50 pin51
spi1
group0 		pin52 pin53 pin50 pin51
spi1
group1(EG810M_EU unsupported) 		pin69 pin68 pin85 pin84
spi2 pin76 pin77 pin78 pin16
SPI CS CLK MOSI MISO
spi0 pin25 pin26 pin27 pin28
spi1 pin5 pin4 pin6 pin7
SPI CS CLK MOSI MISO
spi0 pin37 pin40 pin38 pin39
spi1 pin26 pin27 pin25 pin24
SPI CS CLK MOSI MISO
spi0 pin37 pin40 pin38 pin39
spi1 pin26 pin27 pin25 pin24
SPI CS CLK MOSI MISO
spi0(EC600ECN_LE&LQ unsupported) pin65 pin67 pin66 pin64
spi1 pin69 pin71 pin70 pin72
SPI CS CLK MOSI MISO
spi0 pin28 pin39 pin29 pin38
spi1(EC800ECN_LE&LQ&CG unsupported) pin52 pin53 pin50 pin51
SPI CS CLK MOSI MISO
spi0 pin4 pin1 pin3 pin2
spi1(EC800ECN_LE&LQ&CG unsupported) pin53 pin52 pin54 pin51
SPI CS CLK MOSI MISO
spi1 pin79 pin101 pin100 pin108
SPI CS CLK MOSI MISO
spi0(EG912UGLAA unsupported) pin25 pin26 pin64 pin88
spi1 pin5 pin4 pin6 pin7
SPI CS CLK MOSI MISO
spi1 pin4 pin1 pin3 pin2
spi2 pin58 pin61 pin59 pin60
SPI CS CLK MOSI MISO
spi0 pin31 pin30 pin32 pin33
spi1 pin52 pin53 pin50 pin51
spi2 pin74 pin75 pin76 pin77
SPI CS CLK MOSI MISO
spi0 pin31 pin30 pin32 pin33
spi1 pin52 pin53 pin50 pin51
spi2 pin74 pin75 pin76 pin77
SPI CS CLK MOSI MISO
spi0 pin21 pin22 pin29 pin23
SPI CS CLK MOSI MISO
spi0 pin29 pin30 pin37 pin31
SPI CS CLK MOSI MISO
spi0 pin41 pin42 pin43 pin44
SPI CS CLK MOSI MISO
spi0 pin41 pin42 pin43 pin44
SPI CS CLK MOSI MISO
spi0 pin5 pin4 pin6 pin7
SPI CS CLK MOSI MISO
spi0 pin49 pin29 pin101 pin28
spi1 pin52 pin53 pin50 pin51
SPI CS CLK MOSI MISO
spi0 pin86 pin85 pin88 pin87

Methods

SPI.read 

SPI.read(recv_data, datalen)

This method reads data.

Parameter:

  • recv_data - Bytearray type. An array used to receive data.
  • datalen - Integer type. Length of the data to be read.

Return Value:

0 - Successful execution

-1 - Failed execution

SPI.write 

SPI.write(data, datalen)

This method writes data.

Parameter:

  • data - Bytearray type. Data to be written.
  • datalen - Integer type. Length of data to be written.

Return Value:

0 - Successful execution

-1 - Failed execution

SPI.write_read 

SPI.write_read(r_data, data, datalen)

This method writes and reads data.

Parameter:

  • r_data - Bytearray type. An array used to receive data.
  • data - Bytearray type. Data to be sent.
  • datalen - Integer type. Length of data to be read.

Return Value:

0 - Successful execution

-1 - Failed execution

SPI.close 

SPI.close()

This method close SPI.

Return Value:

0 - Successful execution

-1 - Failed execution

Example:

Please use this function with the peripherals. 

import log
from machine import SPI
import utime



spi_obj = SPI(0, 0, 1)

# Sets the log output level 
log.basicConfig(level=log.INFO)
spi_log = log.getLogger("SPI")


if __name__ == '__main__':
    r_data = bytearray(5)  # Creates a buff for receiving data
    data = b"world"  # Tests data

    ret = spi_obj.write_read(r_data, data, 5)  # Writes data and receives data to r_data
    spi_log.info(r_data)
Module Selection: