Driver API for I2C Bus Peripheral.
I2C - The Inter-Integrated Circuit (I2C) bus is an industry-standard.
The functions and other declarations used in this part of the driver are in cy_scb_i2c.h. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.
The I2C peripheral driver provides an API to implement I2C slave, master, or master-slave devices based on the SCB hardware block. I2C devices based on SCB hardware are compatible with I2C Standard-mode, Fast-mode, and Fast-mode Plus specifications as defined in the I2C-bus specification.
Features:
The I2C driver configuration can be divided to number of sequential steps listed below:
To set up the I2C driver, provide the configuration parameters in the cy_stc_scb_i2c_config_t structure. Provide i2cMode to the select operation mode slave, master or master-slave. The useRxFifo and useTxFifo parameters specify if RX and TX FIFO is used during operation. Typically, both FIFOs should be enabled to reduce possibility of clock stretching. However, using RX FIFO has side effects that needs to be taken into account (see useRxFifo field description in cy_stc_scb_i2c_config_t structure). For master modes, parameters lowPhaseDutyCycle, highPhaseDutyCycle and enableDigitalFilter can be used to define output data rate (refer to section Configure Data Rate for more information). For slave mode, provide the slaveAddress and slaveAddressMask. The other parameters are optional for operation.
To initialize the driver, call Cy_SCB_I2C_Init function providing a pointer to the populated cy_stc_scb_i2c_config_t structure and the allocated cy_stc_scb_i2c_context_t structure.
Set up I2C slave read and write buffer before enabling its operation using Cy_SCB_I2C_SlaveConfigReadBuf and Cy_SCB_I2C_SlaveConfigWriteBuf appropriately. Note that the master reads data from the slave read buffer and writes data into the slave write buffer.
Only dedicated SCB pins can be used for I2C operation. The HSIOM register must be configured to connect dedicated SCB I2C pins to the SCB block. Also the I2C pins must be configured in Open-Drain, Drives Low mode (this pins configuration implies usage of external pull-up resistors):
A clock source must be connected to the SCB block to oversample input and output signals, in this document this clock will be referred as clk_scb. You must use one of the 8-bit or 16-bit dividers. Use the SysClk (System Clock) driver API to do this.
To get I2C slave operation with the desired data rate, the clk_scb must be fast enough to provide sufficient oversampling. Use the SysClk (System Clock) driver API to do this.
To get I2C master operation with the desired data rate, the source clock frequency and SCL low and high phase duration must be configured. Use the SysClk (System Clock) driver API to configure source clock frequency. Then call Cy_SCB_I2C_SetDataRate to set the SCL low, high phase duration and digital filter. This function sets SCL low and high phase settings based on source clock frequency.
Alternatively, the low, high phase and digital filter can be set directly using configuration structure cy_stc_scb_i2c_config_t fields lowPhaseDutyCycle, highPhaseDutyCycle and enableDigitalFilter appropriately.
Refer to the technical reference manual (TRM) section I2C sub-section Oversampling and Bit Rate to get information how to configure I2C to run with the desired data rate.
The highPhaseDutyCycle counter does not start counting until the SCB detects that the SCL line is high. This is not the same as when the SCB sets the SCL high. The differences are explained by three delays:
If the above three delays combined are greater than one clk_scb cycle, then the high phase of the SCL will be extended. This may cause the actual data rate on the I2C bus to be slower than expected. This can be avoided by:
The interrupt is mandatory for I2C operation. The exception is the when only the Master Low-Level functions are used. The driver provides three interrupt functions: Cy_SCB_I2C_Interrupt, Cy_SCB_I2C_SlaveInterrupt, and Cy_SCB_I2C_MasterInterrupt. One of these functions must be called in the interrupt handler for the selected SCB instance. Call Cy_SCB_I2C_SlaveInterrupt when I2C is configured to operate as a slave, Cy_SCB_I2C_MasterInterrupt when I2C is configured to operate as a master and Cy_SCB_I2C_Interrupt when I2C is configured to operate as master and slave. Using the slave- or master-specific interrupt function allows reducing the flash consumed by the I2C driver. Also this interrupt must be enabled in the NVIC otherwise it will not work.
Finally, enable the I2C operation by calling Cy_SCB_I2C_Enable. Then I2C slave starts respond to the assigned address and I2C master ready to execute transfers.
The master API is divided into two categories: Master High-Level and Master Low-Level. Therefore, there are two methods for initiating I2C master transactions using either Low-Level or High-Level API. These two methods are described below. Only one method should be used at a time. They should not be mixed.
Call Cy_SCB_I2C_MasterRead or Cy_SCB_I2C_MasterWrite to communicate with the slave. These functions do not block and only start a transaction. After a transaction starts, the Cy_SCB_I2C_Interrupt handles further data transaction until its completion (successfully or with error occurring). To monitor the transaction, use Cy_SCB_I2C_MasterGetStatus or register callback function using Cy_SCB_I2C_RegisterEventCallback to be notified about I2C Callback Events.
Call Cy_SCB_I2C_MasterSendStart to generate a start, send an address with the Read/Write direction bit, and receive acknowledgment. After the address is ACKed by the slave, the transaction can be continued by calling Cy_SCB_I2C_MasterReadByte or Cy_SCB_I2C_MasterWriteByte depending on its direction. These functions handle one byte per call. Therefore, they should be called for each byte in the transaction. Note that for the Read transaction, the last byte must be NAKed. To complete the current transaction, call Cy_SCB_I2C_MasterSendStop or call Cy_SCB_I2C_MasterSendReStart to complete the current transaction and start a new one. Typically, do a restart to change the transaction direction without releasing the bus from the master control. The Low-Level functions are blocking and do not require calling Cy_SCB_I2C_Interrupt inside the interrupt handler. Using these functions requires extensive knowledge of the I2C protocol to execute transactions correctly.
Master Write Operation
Master Read Operation
Slave operation requires the Cy_SCB_I2C_Interrupt be called inside the interrupt handler. The read and write buffers must be provided for the slave to enable communication with the master. Use Cy_SCB_I2C_SlaveConfigReadBuf and Cy_SCB_I2C_SlaveConfigWriteBuf for this purpose. Note that after transaction completion the buffer must be configured again. Otherwise, the same buffer is used starting from the point where the master stopped a previous transaction. For example: The read buffer is configured to be 10 bytes and the master reads 8 bytes. If the read buffer is not configured again, the next master read will start from the 9th byte. To monitor the transaction status, use Cy_SCB_I2C_SlaveGetStatus or use Cy_SCB_I2C_RegisterEventCallback to register a callback function to be notified about I2C Callback Events.
Get Slave Events Notification
Polling Slave Completion Events
The I2C driver provides callback functions to handle power mode transition. The callback Cy_SCB_I2C_DeepSleepCallback must be called during execution of Cy_SysPm_CpuEnterDeepSleep Cy_SCB_I2C_HibernateCallback must be called during execution of Cy_SysPm_SystemEnterHibernate. To trigger the callback execution, the callback must be registered before calling the power mode transition function. Refer to SysPm (System Power Management) driver for more information about power mode transitions and callback registration.
API Reference | |
Macros | |
Functions | |
Data Structures | |
Enumerated Types | |