This library was written specifically for the TEENSy 3.0 SPI. It will not work on Arduino or any other system.
This library supports using the alternate SPI pins, the gray pins on the pinout diagram.
***
It should be noted that I experienced some problems when using SLAVE mode, with 8 bit frames,
with a large array length, at the fastest clock rate. I was able to go to the next clock
divider (SPI_CLOCK_DIV4 = 12.0 MHz) and this solved my problem. I can also use a smaller
array length with no issues. I think that at very high speed, with short frame size, the
master SPI can over-run my slave ISR scan time.
***
The SLAVE "return data" is loaded every time the ISR is called. So on the first byte received,
there will be no data loaded into the "return data" register. So expect no return data (zero's)
on the very first frame transferred.
***
Many slave devices require that the CS pin stay active until several bytes have been transfered.
For these, it may be useful to specify your own CS pin and do a digitalWrite(CSpin, state) outside
of the tx function.
Example:
digitalWrite(CS18, LOW);
t3SPI.tx8(data1, CTARn, CS);
t3SPI.tx8(data2, CTARn, CS);
digitalWrite(CS18, HIGH);
******* F U N C T I O N D E F I N I T I O N S *******
********************************************
******* FUNCTIONS FOR MASTER MODE *******
begin_MASTER();
******* This funtion initializes the SPI(0) to its most basic configuration.
SPI: Master Mode
CTAR: CTAR0
Clock Divider: 8 = 5.3 Mhz
Frame Size: 8 bits
SPI Mode: 0
Bit Order: LSB First
CS State: Active Low
Clock: Pin 13 (output)
MOSI: Pin 11 (output)
MISO: Pin 12 (intput)
CS0: Pin 10 (output)
begin_MASTER(sck, mosi, miso, cs, activeState);
******* This funtion initializes the SPI(0) with user-defined pins.
You can initialize Alternate Pins here.
sck OPTIONS: SCK = Pin 13
ALT_SCK = Pin 14
mosi OPTIONS: MOSI = Pin 11
ALT_MOSI = Pin 7
miso OPTIONS: MISO = Pin 12
ALT_MISO = Pin 8
cs OPTIONS: CS0 = Pin 10
CS1 = Pin 9
CS2 = Pin 20
CS3 = Pin 21
CS4 = Pin 15
ALT_CS0 = Alternate CS0 on Pin 2
ALT_CS1 = Alternate CS1 on Pin 6
ALT_CS2 = Alternate CS2 on Pin 23
ALT_CS3 = Alternate CS3 on Pin 22
activeState OPTIONS: ActiveLOW = CS pin normally HIGH, goes LOW durring transfer
ActiveHIGH = CS pin normally LOW, goes HIGH durring transfer
setCTAR(CTARn, size, dataMode, bo, cdiv);
******* This funtion configures the CTARn
The CTAR's specify how data will be sent out.
There are two CTAR registers, CTAT0 and CTAR1.
This is useful when you are using one Master to communicate to multiple slave devices.
CTARn OPTIONS: CTAR0 = configures CTAR0
CTAR1 = configures CTAR1
size OPTIONS: 8 = sets a frame size of 8 bits (per transfer)
16 = sets a frame size of 16 bits (per transfer)
dataMode OPTIONS: 0 - 3 = industry standard SPI clock modes, see wikipedia SPI Mode
bo OPTIONS: LSB_FIRST = Least significant bit transfered first
MSB_FIRST = Most significant bit transfered first.
cdiv OPTIONS: #define SPI_CLOCK_DIV2 0b0000 //24.0 MHz
SPI_CLOCK_DIV4 = 12.0 MHz
SPI_CLOCK_DIV6 = 08.0 MHz
SPI_CLOCK_DIV8 = 05.3 MHz
SPI_CLOCK_DIV16 = 03.0 MHz
SPI_CLOCK_DIV32 = 01.5 MHz
SPI_CLOCK_DIV64 = 750 KHz
SPI_CLOCK_DIV128= 375 KHz
There are more modes available, but not includeded in this library.
enableCS(cs, activeState);
******* This funtion enables CS pins.
This is useful if you want to use more CS pins to control multiple SPI devices.
You can initialize Alternate Pins here.
cs OPTIONS: CS0 = Pin 10
CS1 = Pin 9
CS2 = Pin 20
CS3 = Pin 21
CS4 = Pin 15
ALT_CS0 = Alternate CS0 on Pin 2
ALT_CS1 = Alternate CS1 on Pin 6
ALT_CS2 = Alternate CS2 on Pin 23
ALT_CS3 = Alternate CS3 on Pin 22
activeState OPTIONS: ActiveLOW = CS pin normally HIGH, goes LOW durring transfer
ActiveHIGH = CS pin normally LOW, goes HIGH durring transfer
tx8(data, length, CTARn, PCS);
******* This funtion sends a packet of 8 bit data
dataOUT OPTIONS: This is where you put the name of your (8 bit) outgoing data array
length OPTIONS: Put the length of the outgoing data array here
CTARn OPTIONS: CTAR0 :Use the attributes that were set in CTAR0
CTAR1 :Use the attributes that were set in CTAR1
PCS OPTIONS: Any CS pin what has been enabled. (example: CS0, ALT_CS2)
tx16(data, length, CTARn, PCS);
******* This funtion sends a packet of 16 bit data
dataOUT OPTIONS: This is where you put the name of your (16 bit) outgoing data array
length OPTIONS: Put the length of the outgoing data array here
CTARn OPTIONS: CTAR0 :Use the attributes that were set in CTAR0
CTAR1 :Use the attributes that were set in CTAR1
PCS OPTIONS: Any CS pin what has been enabled. (example: CS0, ALT_CS2)
txrx8(dataOUT, dataIN, length, CTARn, PCS);
******* This funtion sends a packet of 8 bit data & receives a packet of 8 bit data from the slave device
dataOUT OPTIONS: This is where you put the name of your (8 bit) outgoing data array
dataIN OPTIONS: This is where you put the name of your (8 bit) incoming data array
length OPTIONS: Put the length of the outgoing data array here
CTARn OPTIONS: CTAR0 :Use the attributes that were set in CTAR0
CTAR1 :Use the attributes that were set in CTAR1
PCS OPTIONS: Any CS pin what has been enabled. (example: CS0, ALT_CS2)
txrx16(dataOUT, dataIN, length, CTARn, PCS);
******* This funtion sends a packet of 16 bit data & receives a packet of 16 bit data from the slave device
dataOUT OPTIONS: This is where you put the name of your (16 bit) outgoing data array
dataIN OPTIONS: This is where you put the name of your (16 bit) incoming data array
length OPTIONS: Put the length of the outgoing data array here
CTARn OPTIONS: CTAR0 :Use the attributes that were set in CTAR0
CTAR1 :Use the attributes that were set in CTAR1
PCS OPTIONS: Any CS pin what has been enabled. (example: CS0, ALT_CS2)
********************************************
******* FUNCTIONS FOR SLAVE MODE ********
begin_SLAVE();
******* This funtion initializes the SPI(0) to its most basic configuration.
SPI: SLAVE Mode
CTAR: CTAR0_SLAVE
Frame Size: 8 bits
SPI Mode: 0
Clock: Pin 13 (input)
MOSI: Pin 11 (output)
MISO: Pin 12 (input)
CS0: Pin 10 (input)
begin_SLAVE(sck, mosi, miso, cs);
******* This funtion initializes the SPI(0) with user-defined pins.
You can initialize Alternate Pins here.
CS is always CS0 (or ALT_CS0) & ACTIVE_LOW in slave mode.
sck OPTIONS: SCK = Pin 13
ALT_SCK = Pin 14
mosi OPTIONS: MOSI = Pin 11
ALT_MOSI = Pin 7
miso OPTIONS: MISO = Pin 12
ALT_MISO = Pin 8
cs OPTIONS: CS0 = Pin 10
ALT_CS0 = Alternate CS0 on Pin 2
setCTAR_SLAVE(size, dataMode);
******* This funtion configures the CTAR0_SLAVE.
The CTAR's specify how data will be received.
SPI0_CTAR0_SLAVE is the CTAR used in SLAVE Mode.
Data is always shifted out LSB_FIRST in SLAVE Mode.
The Frame Size MUST be the same as defined on the MASTER device.
The dataMode should be the same as defined on the MASTER device.
size OPTIONS: 8 = sets a frame size of 8 bits (per transfer)
16 = sets a frame size of 16 bits (per transfer)
dataMode OPTIONS: 0 - 3 = industry standard SPI clock modes, see wikipedia SPI Mode
******* NOTE *******
The SPI SLAVE uses an Interrupt Service Routine to notify the device that a frame of data has been received.
A rx function must be used in ISR to tell the device how to handle it received data.
It looks like this (example):
void spi0_isr(void){
rx8(outgoingData, dataLength);}
The following 4 functions can be put in the ISR to handle incoming data. Do not use more than rx function in the ISR.
rx8(dataIN, length);
******* This funtion receives a packet of 8 bit data
dataIN OPTIONS: This is where you put the name of your (8 bit) incoming data array
length OPTIONS: Put the length of the incoming data array here
rx16(dataIN, length);
******* This funtion receives a packet of 16 bit data
dataIN OPTIONS: This is where you put the name of your (16 bit) incoming data array
length OPTIONS: Put the length of the incoming data array here
rxtx8(dataIN, dataOUT, length);
******* This funtion receives a packet of 8 bit data & returns a packet of 8 bit data to the master device
dataIN OPTIONS: This is where you put the name of your (8 bit) incoming data array
dataOUT OPTIONS: This is where you put the name of your (8 bit) outgoing data array
length OPTIONS: Put the length of the incoming data array here
rxtx16(dataIN, dataOUT, length);
******* This funtion receives a packet of 16 bit data & returns a packet of 16 bit data to the master device
dataIN OPTIONS: This is where you put the name of your (16 bit) incoming data array
dataOUT OPTIONS: This is where you put the name of your (16 bit) outgoing data array
length OPTIONS: Put the length of the incoming data array here
********************************************
************* GLOBAL FUNCTIONS *************
start();
******* This enables SPI functions.
stop();
******* This halts SPI functions.
end();
******* This disables SPI functions.
printStatistics(length);
******* This function prints certain SPI statistics to the Serial monitor.
You must set the following variables to get acurate data:
T3SPI.timeStamp1=micros();
T3SPI.timeStamp2=micros();
length OPTIONS: Put the length of the outgoing or incoming data array here
********************************************
************ PRIVATE FUNCTIONS *************
******* These functions cannot be used in the sketch but are used within the class.
setMCR(mode);
******* This funtion initializes the SPI(0) to basic Master or Slave Mode.
mode OPTIONS: MASTER = Master SPI Mode
SLAVE = Slave SPI Mode
setFrameSize(CTARn, size);
******* This funtion sets the frame size.
CTARn OPTIONS: CTAR0 = configures CTAR0
CTAR1 = configures CTAR1
CTAR_SLAVE = configures CTAR0_SLAVE
size OPTIONS: 8 = sets a frame size of 8 bits (per transfer)
16 = sets a frame size of 16 bits (per transfer)
setMode(CTARn, dataMode);
******* This funtion sets the spi data mode.
CTARn OPTIONS: CTAR0 = configures CTAR0
CTAR1 = configures CTAR1
dataMode OPTIONS: 0 - 3 = industry standard SPI clock modes, see wikipedia SPI Mode
setBitOrder(CTARn, bo);
******* This funtion sets the outgoing bit order.
CTARn OPTIONS: CTAR0 = configures CTAR0
CTAR1 = configures CTAR1
bo OPTIONS: LSB_FIRST = Least significant bit transfered first
MSB_FIRST = Most significant bit transfered first.
setClockDivider(CTARn, cdiv);
******* This funtion sets the clock divider in MASTER mode.
CTARn OPTIONS: CTAR0 = configures CTAR0
CTAR1 = configures CTAR1
cdiv OPTIONS: #define SPI_CLOCK_DIV2 0b0000 //24.0 MHz
SPI_CLOCK_DIV4 = 12.0 MHz
SPI_CLOCK_DIV6 = 08.0 MHz
SPI_CLOCK_DIV8 = 05.3 MHz
SPI_CLOCK_DIV16 = 03.0 MHz
SPI_CLOCK_DIV32 = 01.5 MHz
SPI_CLOCK_DIV64 = 750 KHz
SPI_CLOCK_DIV128= 375 KHz
There are more modes available, but not includeded in this library.
enablePins(sck, mosi, miso, cs, activeState);
******* This funtion enables the SPI pins
You can initialize Alternate Pins here.
sck OPTIONS: SCK = Pin 13
ALT_SCK = Pin 14
mosi OPTIONS: MOSI = Pin 11
ALT_MOSI = Pin 7
miso OPTIONS: MISO = Pin 12
ALT_MISO = Pin 8
cs OPTIONS: CS0 = Pin 10
CS1 = Pin 9
CS2 = Pin 20
CS3 = Pin 21
CS4 = Pin 15
ALT_CS0 = Alternate CS0 on Pin 2
ALT_CS1 = Alternate CS1 on Pin 6
ALT_CS2 = Alternate CS2 on Pin 23
ALT_CS3 = Alternate CS3 on Pin 22
activeState OPTIONS: ActiveLOW = CS pin normally HIGH, goes LOW durring transfer
ActiveLOW = CS pin normally LOW, goes HIGH durring transfer
enablePins_SLAVE(sck, mosi, miso, cs);
******* This funtion enables the SPI pins for SLAVE mode.
You can initialize Alternate Pins here.
sck OPTIONS: SCK = Pin 13
ALT_SCK = Pin 14
mosi OPTIONS: MOSI = Pin 11
ALT_MOSI = Pin 7
miso OPTIONS: MISO = Pin 12
ALT_MISO = Pin 8
cs OPTIONS: CS0 = Pin 10
ALT_CS0 = Alternate CS0 on Pin 2
setCS_ActiveLOW(pin);
******* This funtion sets CS pins as ACTIVE_LOW.
CS pins initialize to ACTIVE_HIGH
pin OPTIONS: CS0_ActiveLow = Sets the CS as ACTIVE_LOW
CS1_ActiveLow = Sets the CS as ACTIVE_LOW
CS2_ActiveLow = Sets the CS as ACTIVE_LOW
CS3_ActiveLow = Sets the CS as ACTIVE_LOW
CS4_ActiveLow = Sets the CS as ACTIVE_LOW
********************************************
************** Defined Macros **************
As long as the T3SPI is #included, these three macros can be used outside of the T3SPI class.
Because they are defined, you don't need to use the class pointer to use them.
*Use SPI_WRITE_16, not use t3SPI.SPI_WRITE_16
SPI_WRITE_16(data, CTARn, CS);
******* This macro sends a 16 bit byte.
data OPTIONS: put your 16 bit variable here.
CTARn OPTIONS: CTAR0 :Use the attributes that were set in CTAR0
CTAR1 :Use the attributes that were set in CTAR1
PCS OPTIONS: Any CS pin what has been enabled. (example: CS0, ALT_CS2)
SPI_WRITE_8(data, CTARn, CS);
******* This macro sends a 8 bit byte.
data OPTIONS: put your 8 bit variable here.
CTARn OPTIONS: CTAR0 :Use the attributes that were set in CTAR0
CTAR1 :Use the attributes that were set in CTAR1
PCS OPTIONS: Any CS pin what has been enabled. (example: CS0, ALT_CS2)
SPI_WAIT( );
******* This macro waits for the current transfer to finish sending. It is useful for many
standard speed slave devices.