Skip to main content

spi.configure(modeFlags, dataRate)

Configures the SPI data format and rate

Availability

Device

Parameters

Name Type Description
modeFlags Constant A bitfield comprising flags the specify the SPI configuration
dataRate Integer The SPI bus data transmission frequency in kHz

Returns

Integer — the actual SPI data rate in kHz

Description

Available settings for the first parameter, modeFlag, which defines the bus’ operation, can be combined from the following:

SPI Mode Constant Value Description
SIMPLEX_RX 1 One wire receiver only (plus clock unless OR’d with NO_SCLK)*
SIMPLEX_TX 2 One wire transmitter only (plus clock unless OR’d with NO_SCLK)*
CLOCK_IDLE_HIGH 4 Clock idles high
CLOCK_IDLE_LOW 0 Clock idles low (default)
CLOCK_2ND_EDGE 8 Clock the second (trailing) edge
MSB_FIRST 0 Send most significant bit first (default)
LSB_FIRST 16 Send least significant bit first
NO_SCLK 32 SCLK pin is not used
USE_CS_L 64 Enable the use of the dedicated chip select pin (imp005 only, see below)

The values assigned to the constants may change in a future impOS release.

*Unless either SIMPLEX_RX or SIMPLEX_TX is included, the bus will default to full duplex communications.

Many vendors use the terms CPOL (clock polarity) and CPHA (clock phase) in their datasheets, or refer to one of four SPI modes. To translate that information into impOS API constants, use the following table:

Mode CPOL CPHA Flags
0 0 0 CLOCK_IDLE_LOW
1 0 1 CLOCK_IDLE_LOW | CLOCK_2ND_EDGE
2 1 0 CLOCK_IDLE_HIGH
3 1 1 CLOCK_IDLE_HIGH | CLOCK_2ND_EDGE

The method automatically enables the SPI bus.

An imp can only generate certain data rates for SPI, which range from 117kHz to 30MHz, depending on which type of imp you are using. The actual data rate selected will be the nearest available value which does not exceed the requested value, rounding down. This value, specified in kHz, is returned by the method. If the requested value is below the minimum value, the minimum value will be used.

The specific SPI data rates available (in kHz) are as follows:

imp001, imp002 imp003 imp004m imp005 imp006
spi189spi257AllAllAllspiXTUVW
15,00030,00018,00024,000 The SPI data rates
available range
from 5kHz to 22.8MHz
The SPI is clocked
by dividing 160MHz
by any integer
from 7 to 32,000
inclusive
Min. 187kHz, max. 750kHz
750015,000900012,000
3750750045006000
1875375022503000All others
937.50187511251500Min. 187kHz,
theoretical max. 24MHz
468.75937.50562.50750
234.375468.75281.25375
117.1875234.375140.625187

Module-specific Notes

imp005

Available Mode Constants

Some of the SPI Mode Constants listed above are not supported by the imp005, specifically CLOCK_IDLE_HIGH, CLOCK_2ND_EDGE, LSB_FIRST and NO_SCLK. If these constants are used in code running on an imp005, an error will be thrown.

Dedicated Chip Select

The imp005’s hardware.spi0 peripheral is on dedicated pins, so the chip-select (nCS) signal can’t be generated in the way that imp001-imp004 users will be used to: namely, by using a normal digital output and pin.write(). This is because the imp005’s dedicated SPI0_CS_L pin isn’t a general-purpose digital output and so doesn’t have a corresponding pin object. Instead, the new spi.chipselect() method controls the SPI0_CS_L pin.

By contrast, the imp005’s other SPI peripheral, hardware.spiBCAD, is on general-purpose pins. So the chip-select signal can, if desired, be generated using hardware.pinD and pin.write() just as on earlier imps. This allows code to be written that also works on earlier imps’ SPI peripherals. But as an alternative, hardware.spiBCAD can be configured with the additional SPI Mode Constant USE_CS_L, which makes it behave like spi0, with the chip-select signal controlled using spi.chipselect(): this allows code to be written that works the same way on both of the imp005’s SPI peripherals.

Data Transfer

Unlike other imps, the imp005 does not use DMA for SPI data transfers. Instead, each byte is written out individually, and this means there will always be a small gap between each byte.

However, the chip-select line is not dropped between bytes: it remains low (active).

Example Code

The following code shows you how to write to an 8-bit shift register — a 74HC595 — via SPI. Note that this implementation uses a second GPIO pin — the first, pin 8, is used for Slave Select — to reset the SPI device.