|
STC15W408AS library 0.18.0
|
Macros | |
| #define | spi_init_master_pins_SPI_PIN_GROUP_1() |
| Configure the SPI pins of pin group 1 for master mode. | |
| #define | spi_init_master_pins_SPI_PIN_GROUP_2() |
| Configure the SPI pins of pin group 2 for master mode. | |
| #define | spi_init_master_pins_SPI_PIN_GROUP_3() |
| Configure the SPI pins of pin group 3 for master mode. | |
| #define | spi_init_slave_pins_SPI_PIN_GROUP_1() |
| Configure the SPI pins of pin group 1 for slave mode. | |
| #define | spi_init_slave_pins_SPI_PIN_GROUP_2() |
| Configure the SPI pins of pin group 2 for slave mode. | |
| #define | spi_init_slave_pins_SPI_PIN_GROUP_3() |
| Configure the SPI pins of pin group 3 for slave mode. | |
| #define | spi_ss_clr_SPI_PIN_GROUP_1() (bit_clr(P1, SBIT2)) |
| Pull the SS pin of pin group 1 low. | |
| #define | spi_ss_set_SPI_PIN_GROUP_1() (bit_set(P1, SBIT2)) |
| Pull the SS pin of pin group 1 high. | |
| #define | spi_ss_clr_SPI_PIN_GROUP_2() (bit_clr(P2, SBIT4)) |
| Pull the SS pin of pin group 2 low. | |
| #define | spi_ss_set_SPI_PIN_GROUP_2() (bit_set(P2, SBIT4)) |
| Pull the SS pin of pin group 2 high. | |
| #define | spi_ss_clr_SPI_PIN_GROUP_3() (bit_clr(P5, SBIT4)) |
| Pull the SS pin of pin group 3 low. | |
| #define | spi_ss_set_SPI_PIN_GROUP_3() (bit_set(P5, SBIT4)) |
| Pull the SS pin of pin group 3 high. | |
Enumerations | |
| enum | spi_clock_t { SPI_CLOCK_DIV_4 = 0b00000000 , SPI_CLOCK_DIV_16 = 0b00000001 , SPI_CLOCK_DIV_64 = 0b00000010 , SPI_CLOCK_DIV_128 = 0b00000011 } |
| SPI clock rate. More... | |
| enum | spi_mode_t { SPI_MODE_0 = 0b00000000 , SPI_MODE_1 = 0b00000100 , SPI_MODE_2 = 0b00001000 , SPI_MODE_3 = 0b00001100 } |
| SPI mode. More... | |
| enum | spi_pin_group_t { SPI_PIN_GROUP_1 = 0 , SPI_PIN_GROUP_2 = 1 , SPI_PIN_GROUP_3 = 2 } |
| SPI pin group. More... | |
init | |
SPI initialization routines | |
| #define | spi_init_master_pins(group) spi_init_master_pins_##group() |
| Configure the SPI pins for master mode. | |
| #define | spi_init_slave_pins(group) spi_init_slave_pins_##group() |
| Configure the SPI pins for slave mode. | |
| #define | spi_init_master(group, mode, clock, lsb_first) |
| SPI initialization in master mode. | |
| #define | spi_init_slave(group, mode, lsb_first) |
| SPI initialization in slave mode. | |
| #define | spi_destroy(void) |
| Deinitialize the SPI module. | |
pin group | |
SPI pin mapping functions | |
| #define | spi_set_pin_group(group) |
| Set the SS/MOSI/MISO/SCLK pin group. | |
| #define | spi_get_pin_group() ((spi_pin_group_t)(bit_shift_right(get_reg(P_SW1, (SPI_S0_MASK | SPI_S1_MASK)), SPI_S0_BIT))) |
| Get the SS/MOSI/MISO/SCLK pin group. | |
slave select | |
SPI slave select (SS) pin handling in master mode | |
| #define | spi_ss_clr(group) spi_ss_clr_##group() |
| Select an external slave. | |
| #define | spi_ss_set(group) spi_ss_set_##group() |
| Deselect an external slave. | |
sync | |
SPI synchronous transfer functions | |
| #define | spi_write_sync(data) |
| Write a byte over SPI. | |
| #define | spi_transfer_sync(value, data) |
| Transfer a byte over SPI. | |
async | |
SPI asynchronous transfer functions | |
| #define | spi_async_transfer_start(data) |
| Start an asynchronous SPI transfer. | |
| #define | is_spi_async_transfer_complete() (test_if_bit_set(SPSTAT, SPI_SPIF_MSK)) |
| Get the SPI asynchronous transfer status. | |
| #define | spi_async_transfer_finish() (bit_set(SPSTAT, SPI_SPSTAT_CLEAR_MSK)) |
| Clear the SPI transfer complete and write collision flags. | |
| #define | spi_async_get_result() (SPDAT) |
| Get the byte received in the asynchronous transfer. | |
status | |
SPI state functions | |
| #define | is_spi_enabled() (test_if_bit_set(SPCTL, SPI_SPEN_MSK)) |
| Get the SPI enable status. | |
| #define | is_spi_master() (test_if_bit_set(SPCTL, SPI_MSTR_MSK)) |
| Get the SPI master/slave mode status. | |
| #define | is_spi_write_collision() (test_if_bit_set(SPSTAT, SPI_WCOL_MSK)) |
| Get the SPI write collision status. | |
| #define | spi_get_mode() ((spi_mode_t)get_reg(SPCTL, (SPI_CPOL_MSK | SPI_CPHA_MSK))) |
| Get the SPI mode. | |
| #define | spi_get_clock() ((spi_clock_t)get_reg(SPCTL, SPI_SPR_MSK)) |
| Get the SPI clock divider. | |
Functions and data structures related to SPI module
SPI - Serial Peripheral Interface. It is a full duplex synchronous serial link with a master and one or more slaves. Four wires are used: SS (slave select), MOSI (master output, slave input), MISO (master input, slave output) and SCLK (serial clock).
The SPI module could work in master or slave mode. In master mode the clock rate is selected from the CPU clock (SYSclk) with one of the four available dividers. In slave mode the module is clocked by the master and the clock rate setting is ignored.
Four clock phase and polarity combinations (modes 0..3) and either data order (MSB or LSB first) are supported.
Transfers could be done in sync mode, which blocks until the transfer is finished, or in async mode. In async mode the SPI transfer complete event generates an interrupt. Before async transfers mcu interrupts and the SPI interrupt should be enabled by calling enable_spi_interrupt() from interrupt.h.
Pin mapping is selected with spi_set_pin_group(). Three pin groups are available and the group selection is stored in the P_SW1 register:
| Group | SS | MOSI | MISO | SCLK |
|---|---|---|---|---|
| 1 | P1.2 | P1.3 | P1.4 | P1.5 |
| 2 | P2.4 | P2.3 | P2.2 | P2.1 |
| 3 | P5.4 | P4.0 | P4.1 | P4.3 |
Note that not every pin group is available on every MCU series and package. For example the STC15W408AS exposes group 1 on every package, group 2 only on 28 pin packages and has no P4 port pins bonded out for group 3 at all.
| #define is_spi_async_transfer_complete | ( | ) | (test_if_bit_set(SPSTAT, SPI_SPIF_MSK)) |
Get the SPI asynchronous transfer status.
| #define is_spi_enabled | ( | ) | (test_if_bit_set(SPCTL, SPI_SPEN_MSK)) |
Get the SPI enable status.
| #define is_spi_master | ( | ) | (test_if_bit_set(SPCTL, SPI_MSTR_MSK)) |
Get the SPI master/slave mode status.
| #define is_spi_write_collision | ( | ) | (test_if_bit_set(SPSTAT, SPI_WCOL_MSK)) |
Get the SPI write collision status.
The WCOL flag is set if the SPI data register is written while a transfer is still in progress. The flag is cleared by spi_async_transfer_finish() or by spi_write_sync().
| #define spi_async_get_result | ( | ) | (SPDAT) |
Get the byte received in the asynchronous transfer.
The SPI data register is double buffered, so it holds the byte received during the last completed transfer.
This routine is supposed to be used inside the SPI interrupt handler. Typically spi_async_transfer_finish() is called after it to clear the transfer complete flag.
| #define spi_async_transfer_finish | ( | ) | (bit_set(SPSTAT, SPI_SPSTAT_CLEAR_MSK)) |
Clear the SPI transfer complete and write collision flags.
| #define spi_async_transfer_start | ( | data | ) |
Start an asynchronous SPI transfer.
Clears the status flags and writes a byte into the SPI data register, which starts the transfer. The program is not blocked after that. When the transfer is finished the MCU generates an SPI interrupt.
| data | uint8_t byte to transmit |
| #define spi_destroy | ( | void | ) |
Deinitialize the SPI module.
Disables the SPI interface by clearing the SPEN bit and clears the transfer complete and write collision flags. After that the SPI pins function as normal I/O port pins, but their configured modes (push-pull output, input only) are kept.
| #define spi_get_clock | ( | ) | ((spi_clock_t)get_reg(SPCTL, SPI_SPR_MSK)) |
Get the SPI clock divider.
| #define spi_get_mode | ( | ) | ((spi_mode_t)get_reg(SPCTL, (SPI_CPOL_MSK | SPI_CPHA_MSK))) |
Get the SPI mode.
| #define spi_get_pin_group | ( | ) | ((spi_pin_group_t)(bit_shift_right(get_reg(P_SW1, (SPI_S0_MASK | SPI_S1_MASK)), SPI_S0_BIT))) |
Get the SS/MOSI/MISO/SCLK pin group.
| #define spi_init_master | ( | group, | |
| mode, | |||
| clock, | |||
| lsb_first | |||
| ) |
SPI initialization in master mode.
Selects the pin group with spi_set_pin_group(), configures the SS, MOSI, MISO and SCLK pins and writes the SPCTL register with the SPI enable, master mode, clock divider, mode and data order bits.
The SS pin is configured as an output and kept high. In modes with CPHA=0 (SPI_MODE_0 and SPI_MODE_2) the SS pin is not ignored (SSIG=0), so it has to be pulled low with spi_ss_clr() before every byte transfer and released with spi_ss_set() after it. In modes with CPHA=1 the SS pin is ignored (SSIG=1) and could be left high all the time.
| group | spi_pin_group_t pin group to use. Must be a compile time constant, for example SPI_PIN_GROUP_1 |
| mode | spi_mode_t SPI mode (CPOL and CPHA combination) |
| clock | spi_clock_t SPI clock divider, SPI clock is derived from SYSclk |
| lsb_first | bool data order, true transmits LSB first, false MSB first |
| #define spi_init_master_pins | ( | group | ) | spi_init_master_pins_##group() |
Configure the SPI pins for master mode.
Configures the SS, MOSI and SCLK pins as push-pull outputs and the MISO pin as input only for the given pin group. The SS pin is kept high, so an external slave stays deselected and the SPI is not switched to slave mode by the SS pin.
| group | spi_pin_group_t pin group to use. Must be a compile time constant, for example SPI_PIN_GROUP_1 |
| #define spi_init_master_pins_SPI_PIN_GROUP_1 | ( | ) |
Configure the SPI pins of pin group 1 for master mode.
SS on P1.2 as push-pull output and kept high, MOSI on P1.3 as push-pull output, MISO on P1.4 as input only, SCLK on P1.5 as push-pull output.
Used by spi_init_master_pins(). Normally there is no need to call it directly.
| #define spi_init_master_pins_SPI_PIN_GROUP_2 | ( | ) |
Configure the SPI pins of pin group 2 for master mode.
SS_2 on P2.4 as push-pull output and kept high, MOSI_2 on P2.3 as push-pull output, MISO_2 on P2.2 as input only, SCLK_2 on P2.1 as push-pull output.
Used by spi_init_master_pins(). Normally there is no need to call it directly.
| #define spi_init_master_pins_SPI_PIN_GROUP_3 | ( | ) |
Configure the SPI pins of pin group 3 for master mode.
SS_3 on P5.4 as push-pull output and kept high, MOSI_3 on P4.0 as push-pull output, MISO_3 on P4.1 as input only, SCLK_3 on P4.3 as push-pull output.
Used by spi_init_master_pins(). Normally there is no need to call it directly.
| #define spi_init_slave | ( | group, | |
| mode, | |||
| lsb_first | |||
| ) |
SPI initialization in slave mode.
Selects the pin group with spi_set_pin_group(), configures the SS, MOSI, MISO and SCLK pins and writes the SPCTL register with the SPI enable, mode and data order bits. The SS pin always selects the device (SSIG=0) and the SPI is clocked by an external master, so the clock rate setting is not used.
| group | spi_pin_group_t pin group to use. Must be a compile time constant, for example SPI_PIN_GROUP_1 |
| mode | spi_mode_t SPI mode (CPOL and CPHA combination) |
| lsb_first | bool data order, true transmits LSB first, false MSB first |
| #define spi_init_slave_pins | ( | group | ) | spi_init_slave_pins_##group() |
Configure the SPI pins for slave mode.
Configures the SS, MOSI and SCLK pins as input only and the MISO pin as push-pull output for the given pin group.
| group | spi_pin_group_t pin group to use. Must be a compile time constant, for example SPI_PIN_GROUP_1 |
| #define spi_init_slave_pins_SPI_PIN_GROUP_1 | ( | ) |
Configure the SPI pins of pin group 1 for slave mode.
SS on P1.2 as input only, MOSI on P1.3 as input only, MISO on P1.4 as push-pull output, SCLK on P1.5 as input only.
Used by spi_init_slave_pins(). Normally there is no need to call it directly.
| #define spi_init_slave_pins_SPI_PIN_GROUP_2 | ( | ) |
Configure the SPI pins of pin group 2 for slave mode.
SS_2 on P2.4 as input only, MOSI_2 on P2.3 as input only, MISO_2 on P2.2 as push-pull output, SCLK_2 on P2.1 as input only.
Used by spi_init_slave_pins(). Normally there is no need to call it directly.
| #define spi_init_slave_pins_SPI_PIN_GROUP_3 | ( | ) |
Configure the SPI pins of pin group 3 for slave mode.
SS_3 on P5.4 as input only, MOSI_3 on P4.0 as input only, MISO_3 on P4.1 as push-pull output, SCLK_3 on P4.3 as input only.
Used by spi_init_slave_pins(). Normally there is no need to call it directly.
| #define spi_set_pin_group | ( | group | ) |
Set the SS/MOSI/MISO/SCLK pin group.
Select which pins are used as SS, MOSI, MISO and SCLK. Pins are selected with the P_SW1 register SPI_S1 and SPI_S0 bits.
By default (after MCU power on) pin group 1 is used.
| group | spi_pin_group_t pin group to use |
| #define spi_ss_clr | ( | group | ) | spi_ss_clr_##group() |
Select an external slave.
Pulls the SS pin low. The SS pin is configured as a push-pull output by spi_init_master().
| group | spi_pin_group_t pin group in use. Must be the literal enum constant, for example SPI_PIN_GROUP_1, not a variable: the pin group is selected at compile time by token pasting, so unlike spi_set_pin_group() this routine cannot take a runtime value |
| #define spi_ss_clr_SPI_PIN_GROUP_1 | ( | ) | (bit_clr(P1, SBIT2)) |
Pull the SS pin of pin group 1 low.
SS on P1.2 is configured as a push-pull output by spi_init_master_pins_SPI_PIN_GROUP_1()
| #define spi_ss_clr_SPI_PIN_GROUP_2 | ( | ) | (bit_clr(P2, SBIT4)) |
Pull the SS pin of pin group 2 low.
SS_2 on P2.4 is configured as a push-pull output by spi_init_master_pins_SPI_PIN_GROUP_2()
| #define spi_ss_clr_SPI_PIN_GROUP_3 | ( | ) | (bit_clr(P5, SBIT4)) |
Pull the SS pin of pin group 3 low.
SS_3 on P5.4 is configured as a push-pull output by spi_init_master_pins_SPI_PIN_GROUP_3()
| #define spi_ss_set | ( | group | ) | spi_ss_set_##group() |
Deselect an external slave.
Pulls the SS pin high. The SS pin is configured as a push-pull output by spi_init_master().
| group | spi_pin_group_t pin group in use. Must be the literal enum constant, for example SPI_PIN_GROUP_1, not a variable: the pin group is selected at compile time by token pasting, so unlike spi_set_pin_group() this routine cannot take a runtime value |
| #define spi_transfer_sync | ( | value, | |
| data | |||
| ) |
Transfer a byte over SPI.
Writes a byte into the SPI data register, which starts the transfer, blocks until the transfer is finished and stores the received byte.
| value | uint8_t* received byte |
| data | uint8_t byte to transmit |
| #define spi_write_sync | ( | data | ) |
Write a byte over SPI.
Clears the status flags, writes a byte into the SPI data register, which starts the transfer, and blocks until the transfer is finished. The received byte is discarded.
| data | uint8_t byte to transmit |
| enum spi_clock_t |
SPI clock rate.
describes possible SPI clock dividers. The SPI clock is derived from the CPU clock (SYSclk). Used in master mode only, in slave mode the module is clocked by an external master.
| Enumerator | |
|---|---|
| SPI_CLOCK_DIV_4 | SYSclk / 4 |
| SPI_CLOCK_DIV_16 | SYSclk / 16 |
| SPI_CLOCK_DIV_64 | SYSclk / 64, used after MCU power on |
| SPI_CLOCK_DIV_128 | SYSclk / 128 |
| enum spi_mode_t |
SPI mode.
describes all four combinations of the CPOL (clock polarity) and CPHA (clock phase) bits. The current mode could be read back with spi_get_mode().
Note that in modes with CPHA=0 (SPI_MODE_0 and SPI_MODE_2) the SS pin is not ignored (SSIG=0), so it has to be pulled low with spi_ss_clr() before every byte transfer and released with spi_ss_set() after it.
| enum spi_pin_group_t |
SPI pin group.
describes possible SS/MOSI/MISO/SCLK pin mapping variants. Group selection is done with spi_set_pin_group().
Note that not every pin group is available on every MCU series and package. For example the STC15W408AS exposes group 1 on every package, group 2 only on 28 pin packages and has no P4 port pins bonded out for group 3 at all.
1.9.8