SPI

The Arduino SPI API: SPI master on SPI1, the CH32X035's one SPI. More...

Classes
class	SPISettings
	A device's SPI settings: its maximum clock, bit order and mode, for SPIClass::beginTransaction(). More...
class	SPIClass
	An SPI master: the Arduino SPI API on one of the chip's SPI peripherals (the global SPI on this board). More...

Macros
#define	SPI_HAS_TRANSACTION   1
	Defined to 1: this SPI has beginTransaction(), endTransaction(), usingInterrupt() and SPISettings(clock, bitOrder, dataMode).
#define	CS_PIN_CONTROLLED_BY_USER   NUM_DIGITAL_PINS
	The "CS pin" that means the sketch drives its chip select itself, outside the SPI class (the default for every method).
#define	NO_CONFIG   ((int16_t)(-1))
	Indicates there is no configuration selected (internal).
#define	SPI_TRANSFER_TIMEOUT   1000
	How long one transfer call may take before it gives up, in ms (default 1000).
#define	NB_SPI_SETTINGS   4
	The number of CS pins whose settings an SPIClass remembers, 1 to 254 (default 4).

Enumerations
enum	SPITransferMode {   SPI_CONTINUE ,   SPI_LAST }
	What a transfer does with a CS pin the class drives, once it is done. More...

Variables
SPIClass	SPI
	The SPI: SPI1 on PA5 (SCK), PA6 (MISO) and PA7 (MOSI), the bus the board's panel and SD card are on.

Clock dividers for setClockDivider() (deprecated)
Compatibility with sketches designed for AVR at 16 MHz cannot be ensured, as the SPI clock depends on the system clock: here the divider applies to 48 MHz, and the result is then rounded down to 48 MHz / 2^n. New code passes the clock in Hz to SPISettings with SPI.beginTransaction() instead.
#define	SPI_CLOCK_DIV2   2
	48 MHz / 2 = 24 MHz
#define	SPI_CLOCK_DIV4   4
	48 MHz / 4 = 12 MHz
#define	SPI_CLOCK_DIV8   8
	48 MHz / 8 = 6 MHz
#define	SPI_CLOCK_DIV16   16
	48 MHz / 16 = 3 MHz
#define	SPI_CLOCK_DIV32   32
	48 MHz / 32 = 1.5 MHz
#define	SPI_CLOCK_DIV64   64
	48 MHz / 64 = 750 kHz
#define	SPI_CLOCK_DIV128   128
	48 MHz / 128 = 375 kHz

SPI modes, for SPISettings and setDataMode()
#define	SPI_MODE0   0x00
	clock idles low, data sampled on the rising edge (CPOL 0, CPHA 0)
#define	SPI_MODE1   0x01
	clock idles low, data sampled on the falling edge (CPOL 0, CPHA 1)
#define	SPI_MODE2   0x02
	clock idles high, data sampled on the falling edge (CPOL 1, CPHA 0)
#define	SPI_MODE3   0x03
	clock idles high, data sampled on the rising edge (CPOL 1, CPHA 1)

Receive or not, for SPISettings' noRecv
#define	SPI_TRANSMITRECEIVE   0x0
	send and receive (the default)
#define	SPI_TRANSMITONLY   0x1
	send only: what comes back is not read, and transfer() returns 0

Detailed Description

The Arduino SPI API: SPI master on SPI1, the CH32X035's one SPI.

#include <SPI.h>
 
SPI.begin();
SPI.beginTransaction(SPISettings(1000000, MSBFIRST, SPI_MODE0));
digitalWrite(myCs, LOW);
uint8_t answer = SPI.transfer(0x9F);
digitalWrite(myCs, HIGH);
SPI.endTransaction();

The global SPI is SPI1 on the board's PA5 (SCK), PA6 (MISO) and PA7 (MOSI), the only pins SPI1 has on this chip. Transfers are polled byte by byte (no DMA, no interrupts), and each call gives up after SPI_TRANSFER_TIMEOUT ms. The clock is 48 MHz divided by 2, 4 ... 256: a requested clock gets the fastest of those that does not exceed it (24 MHz down to 187.5 kHz), so the default 4 MHz request runs at 3 MHz.

Settings are remembered per chip-select pin, for up to NB_SPI_SETTINGS pins. A transfer for a pin that has none (never given to begin() or beginTransaction(), or forgotten by endTransaction()) does nothing and returns 0.

Note

On the CHGame board SPI1 is shared by the LCD (CS PIN_LCD_CS, PA4, which is also the default SS) and the SD card (CS PIN_SD_CS, PB11), and CHGfx drives it directly by DMA. Use this class only for a device of your own on SPI1, only between gfx_wait() and the next flush, and keep the panel's and the card's CS high. For the card, use CHSd.

Warning

begin(), beginTransaction() and a transfer for another CS pin reset SPI1 and program it afresh (clock, mode, bit order), and end() switches SPI1's clock off. CHGfx sets SPI1 up only in gfx_begin() and gfx_setSpiDiv(), so hand it back before the next flush with gfx_setSpiDiv(gfx_spiDiv()), which programs all of SPI1 for the panel again (and switches its clock back on).

Macro Definition Documentation

SPI_HAS_TRANSACTION

#define SPI_HAS_TRANSACTION   1

Defined to 1: this SPI has beginTransaction(), endTransaction(), usingInterrupt() and SPISettings(clock, bitOrder, dataMode).

SPI_CLOCK_DIV2

#define SPI_CLOCK_DIV2   2

48 MHz / 2 = 24 MHz

SPI_CLOCK_DIV4

#define SPI_CLOCK_DIV4   4

48 MHz / 4 = 12 MHz

SPI_CLOCK_DIV8

#define SPI_CLOCK_DIV8   8

48 MHz / 8 = 6 MHz

SPI_CLOCK_DIV16

#define SPI_CLOCK_DIV16   16

48 MHz / 16 = 3 MHz

SPI_CLOCK_DIV32

#define SPI_CLOCK_DIV32   32

48 MHz / 32 = 1.5 MHz

SPI_CLOCK_DIV64

#define SPI_CLOCK_DIV64   64

48 MHz / 64 = 750 kHz

SPI_CLOCK_DIV128

#define SPI_CLOCK_DIV128   128

48 MHz / 128 = 375 kHz

SPI_MODE0

#define SPI_MODE0   0x00

clock idles low, data sampled on the rising edge (CPOL 0, CPHA 0)

SPI_MODE1

#define SPI_MODE1   0x01

clock idles low, data sampled on the falling edge (CPOL 0, CPHA 1)

SPI_MODE2

#define SPI_MODE2   0x02

clock idles high, data sampled on the falling edge (CPOL 1, CPHA 0)

SPI_MODE3

#define SPI_MODE3   0x03

clock idles high, data sampled on the rising edge (CPOL 1, CPHA 1)

SPI_TRANSMITRECEIVE

#define SPI_TRANSMITRECEIVE   0x0

send and receive (the default)

SPI_TRANSMITONLY

#define SPI_TRANSMITONLY   0x1

send only: what comes back is not read, and transfer() returns 0

CS_PIN_CONTROLLED_BY_USER

#define CS_PIN_CONTROLLED_BY_USER   NUM_DIGITAL_PINS

The "CS pin" that means the sketch drives its chip select itself, outside the SPI class (the default for every method).

NO_CONFIG

#define NO_CONFIG   ((int16_t)(-1))

Indicates there is no configuration selected (internal).

SPI_TRANSFER_TIMEOUT

#define SPI_TRANSFER_TIMEOUT   1000

How long one transfer call may take before it gives up, in ms (default 1000).

SPI.cpp uses it, so a different value must be defined for the whole build (build.extra_flags), not just in the sketch.

NB_SPI_SETTINGS

#define NB_SPI_SETTINGS   4

The number of CS pins whose settings an SPIClass remembers, 1 to 254 (default 4).

Can be redefined in variant.h.

Enumeration Type Documentation

SPITransferMode

enum SPITransferMode

What a transfer does with a CS pin the class drives, once it is done.

Enumerator
SPI_CONTINUE	Transfer not finished: CS pin kept active (low)
SPI_LAST	Transfer ended: CS pin released (high)

Variable Documentation

SPI

SPIClass SPI

extern

The SPI: SPI1 on PA5 (SCK), PA6 (MISO) and PA7 (MOSI), the bus the board's panel and SD card are on.