cy_scb_i2c_8h

Provides I2C API declarations of the SCB driver.

Version

2.80

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0
Copyright

Copyright 2016-2021 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_SCB_I2C_SLAVE_RD_BUSY

There is a read transaction in progress.

CY_SCB_I2C_SLAVE_RD_IN_FIFO

All read data has been loaded into the TX FIFO, applicable only if the TX FIFO is used.

CY_SCB_I2C_SLAVE_RD_CMPLT

The master has finished reading data from the slave.

CY_SCB_I2C_SLAVE_RD_UNDRFL

Set when the master tried to read more bytes than available in the configured read buffer.

The slave is not able to finish the transaction and sends CY_SCB_I2C_DEFAULT_TX.

CY_SCB_I2C_SLAVE_WR_BUSY

There is a write transaction in progress.

CY_SCB_I2C_SLAVE_WR_CMPLT

The master has finished writing data into the slave.

CY_SCB_I2C_SLAVE_WR_OVRFL

The master attempted to write more bytes than space available in the configured Write buffer.

Note that all subsequent bytes are dropped.

CY_SCB_I2C_SLAVE_ARB_LOST

The slave lost arbitration, and the transaction was aborted.

CY_SCB_I2C_SLAVE_BUS_ERR

The slave captured an error on the bus during a master transaction (source of error is misplaced Start or Stop).

CY_SCB_I2C_MASTER_BUSY

The master is busy executing operation started by Cy_SCB_I2C_MasterRead or Cy_SCB_I2C_MasterWrite.

CY_SCB_I2C_MASTER_WR_IN_FIFO

All Write data has been loaded into the TX FIFO.

CY_SCB_I2C_MASTER_ADDR_NAK

The slave NACKed the address.

CY_SCB_I2C_MASTER_DATA_NAK

Write completed before all bytes were sent (last byte was NAKed)

CY_SCB_I2C_MASTER_ARB_LOST

The master lost arbitration, the transaction was aborted.

CY_SCB_I2C_MASTER_BUS_ERR

The master detected an erroneous start or stop, the transaction was aborted.

CY_SCB_I2C_MASTER_ABORT_START

The master transaction was aborted and the slave transaction is on-going because the slave was addressed before the master generated a start.

CY_SCB_I2C_SLAVE_READ_EVENT

Indicates that the slave was addressed and the master wants to read data.

This event can be used to configure the slave Read buffer.

CY_SCB_I2C_SLAVE_WRITE_EVENT

Indicates that the slave was addressed and the master wants to write data.

This event can be used to configure the slave Write buffer.

CY_SCB_I2C_SLAVE_RD_IN_FIFO_EVENT

All slave data from the configured Read buffer has been loaded into the TX FIFO.

The content of the Read buffer can be modified. Applicable only if the TX FIFO is used.

CY_SCB_I2C_SLAVE_RD_BUF_EMPTY_EVENT

The master has read all data out of the configured Read buffer.

This event can be used to configure the next Read buffer. If the buffer remains empty, the CY_SCB_I2C_DEFAULT_TX bytes are returned to the master.

CY_SCB_I2C_SLAVE_RD_CMPLT_EVENT

Indicates the master completed reading from the slave (set by the master NAK or Stop)

CY_SCB_I2C_SLAVE_WR_CMPLT_EVENT

Indicates the master completed writing to the slave (set by the master Stop or Restart)

CY_SCB_I2C_SLAVE_ERR_EVENT

Indicates the I2C hardware detected an error.

Check Cy_SCB_I2C_SlaveGetStatus to determine the source of the error.

CY_SCB_I2C_MASTER_WR_IN_FIFO_EVENT

All data specified by Cy_SCB_I2C_MasterWrite has been loaded into the TX FIFO.

The content of the master write buffer can be modified. Applicable only if the TX FIFO is used.

CY_SCB_I2C_MASTER_WR_CMPLT_EVENT

The master write started by Cy_SCB_I2C_MasterWrite is complete.

CY_SCB_I2C_MASTER_RD_CMPLT_EVENT

The master read started by Cy_SCB_I2C_MasterRead is complete.

CY_SCB_I2C_MASTER_ERR_EVENT

Indicates the I2C hardware has detected an error.

It occurs together with CY_SCB_I2C_MASTER_RD_CMPLT_EVENT or CY_SCB_I2C_MASTER_WR_CMPLT_EVENT depends on the direction of the transfer. Check Cy_SCB_I2C_MasterGetStatus to determine the source of the error.

CY_SCB_I2C_GENERAL_CALL_EVENT

Indicates the slave was addressed by the general call address.

CY_SCB_I2C_ADDR_IN_FIFO_EVENT

The slave address is in the RX FIFO.

Note that the address must be read from the RX FIFO using the Cy_SCB_ReadRxFifo function.

CY_SCB_I2C_DEFAULT_TX

This value is returned by the slave when there is no data in the Read buffer.

Typedefs

typedef void (*cy_cb_scb_i2c_handle_events_t)(uint32_t event)

Provides the typedef for the callback function called in the Cy_SCB_I2C_Interrupt to notify the user about occurrences of I2C Callback Events.

typedef cy_en_scb_i2c_command_t (*cy_cb_scb_i2c_handle_addr_t)(uint32_t event)

Provides the typedef for the callback function called in the Cy_SCB_I2C_Interrupt to notify the user about occurrences of I2C Address Callback Events.

This callback must return a decision to ACK (continue transaction) or NAK (end transaction) the received address. Note if the slave is configured to accept an address in RX FIFO, it must read from it using the Cy_SCB_ReadRxFifo function.

Enums

enum cy_en_scb_i2c_status_t

cy_en_scb_i2c_status_t: I2C status codes.

Values:

enumerator CY_SCB_I2C_SUCCESS

Operation completed successfully.

enumerator CY_SCB_I2C_BAD_PARAM

One or more of input parameters are invalid.

enumerator CY_SCB_I2C_MASTER_NOT_READY

The master is not ready to start a new transaction.

Either the master is still processing a previous transaction or in the master-slave mode, the slave operation is in progress.

enumerator CY_SCB_I2C_MASTER_MANUAL_TIMEOUT

The master operation timed out before completing.

Applicable only for the Master Low-Level functions.

enumerator CY_SCB_I2C_MASTER_MANUAL_ADDR_NAK

The slave NACKed the address.

Applicable only for the Master Low-Level functions.

enumerator CY_SCB_I2C_MASTER_MANUAL_NAK

The slave NACKed the data byte.

Applicable only for the Master Low-Level.

enumerator CY_SCB_I2C_MASTER_MANUAL_ARB_LOST

The master lost arbitration, the transaction was aborted.

Applicable only for the Master Low-Level functions.

enumerator CY_SCB_I2C_MASTER_MANUAL_BUS_ERR

The master detected an erroneous start or stop, the transaction was aborted.

Applicable only for the Master Low-Level functions.

enumerator CY_SCB_I2C_MASTER_MANUAL_ABORT_START

The master transaction was aborted and the slave transaction is on-going because the slave was addressed before the master generated a start.

Applicable only for the Master Low-Level functions.

enum cy_en_scb_i2c_mode_t

cy_en_scb_i2c_mode_t: I2C Operation Modes.

Values:

enumerator CY_SCB_I2C_SLAVE

Configures SCB for I2C Slave operation.

enumerator CY_SCB_I2C_MASTER

Configures SCB for I2C Master operation.

enumerator CY_SCB_I2C_MASTER_SLAVE

Configures SCB for I2C Master-Slave operation.

enum cy_en_scb_i2c_direction_t

cy_en_scb_i2c_direction_t: I2C Transaction Direction.

Values:

enumerator CY_SCB_I2C_WRITE_XFER

Current transaction is Write.

enumerator CY_SCB_I2C_READ_XFER

Current transaction is Read.

enum cy_en_scb_i2c_command_t

cy_en_scb_i2c_command_t: I2C Command ACK / NAK.

Values:

enumerator CY_SCB_I2C_ACK

Send ACK to current byte.

enumerator CY_SCB_I2C_NAK

Send NAK to current byte.

Functions

cy_en_scb_i2c_status_t Cy_SCB_I2C_Init(CySCB_Type *base, cy_stc_scb_i2c_config_t const *config, cy_stc_scb_i2c_context_t *context)

Initializes the SCB for the I2C operation.

note

If SCB is already enabled, ensure that the SCB block is disabled Cy_SCB_I2C_Disable before calling this function.

Parameters
  • base – The pointer to the I2C SCB instance.

  • config – The pointer to the configuration structure cy_stc_scb_i2c_config_t.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

void Cy_SCB_I2C_DeInit(CySCB_Type *base)

De-initializes the SCB block and returns register values to default.

note

Ensure that the SCB block is disabled Cy_SCB_I2C_Disable before calling this function.

Parameters

base – The pointer to the I2C SCB instance.

__STATIC_INLINE void Cy_SCB_I2C_Enable (CySCB_Type *base)

Enables the SCB block for the I2C operation.

note

Ensure SCB is initialized with Cy_SCB_I2C_Init before calling this function

Parameters

base – The pointer to the I2C SCB instance.

void Cy_SCB_I2C_Disable(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

Disables the SCB block and clears context statuses.

Note that after the block is disabled, the TX and RX FIFOs and hardware statuses are cleared. Also, the hardware stops driving the output and ignores the input.

note

Calling this function when I2C is busy (master preforms transaction or slave was addressed and is communicating with master) may cause transaction corruption because the hardware stops driving the outputs and ignores the inputs. Ensure that I2C is not busy before calling this function.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_SCB_I2C_SetDataRate(CySCB_Type *base, uint32_t dataRateHz, uint32_t scbClockHz)

Configures the SCB to work at the desired data rate.

note

This function does not change the values of the clock divider connected to the SCB, it changes only the SCB clock oversample registers. If this function is not able to achieve the desired data rate, then the clock divider must be adjusted. Call this function only while the SCB is disabled. For the slave, this function only checks that the attached clock is fast enough to meet the desired data rate. It does not change any registers.

Parameters
  • base – The pointer to the I2C SCB instance.

  • dataRateHz – The desired data Rate in Hz.

  • scbClockHz – The frequency of the clock connected to the SCB in Hz.

Returns

The achieved data rate in Hz.

When zero value is returned there is an error in the input parameters: data rate or clk_scb is out of valid range.

uint32_t Cy_SCB_I2C_GetDataRate(CySCB_Type const *base, uint32_t scbClockHz)

Returns the data rate for the selected SCB block.

Parameters
  • base – The pointer to the I2C SCB instance.

  • scbClockHz – The frequency of the clock connected to the SCB in Hz.

Returns

The data rate in Hz.

For slave mode when zero value is returned the clk_scb is out of valid range.

__STATIC_INLINE void Cy_SCB_I2C_SlaveSetAddress (CySCB_Type *base, uint8_t addr)

Sets the slave address for the I2C slave.

Parameters
  • base – The pointer to the I2C SCB instance.

  • addr – The 7-bit right justified slave address.

__STATIC_INLINE uint32_t Cy_SCB_I2C_SlaveGetAddress (CySCB_Type const *base)

Returns the slave address of the I2C slave.

Parameters

base – The pointer to the I2C SCB instance.

Returns

The 7-bit right justified slave address.

__STATIC_INLINE void Cy_SCB_I2C_SlaveSetAddressMask (CySCB_Type *base, uint8_t addrMask)

Sets the slave address mask for the I2C slave.

The LSBit must always be 0. In all other bit positions a 1 indicates that the incoming address must match the corresponding bit in the slave address. A 0 in the mask means that the incoming address does not need to match. Example Slave Address = 0x0C. Slave Address Mask = 0x08. This means that the hardware will accept both 0x08 and 0x0C as valid addresses.

Parameters
  • base – The pointer to the I2C SCB instance.

  • addrMask – The 8-bit address mask, the upper 7 bits correspond to the slave address. LSBit must always be 0.

__STATIC_INLINE uint32_t Cy_SCB_I2C_SlaveGetAddressMask (CySCB_Type const *base)

Returns the slave address mask.

Parameters

base – The pointer to the I2C SCB instance.

Returns

The 8-bit address mask, the upper 7 bits correspond to the slave address. LSBit must always be 0.

__STATIC_INLINE bool Cy_SCB_I2C_IsBusBusy (CySCB_Type const *base)

Checks whether the I2C bus is busy.

note

After the SCB block is enabled or reset, the valid bus busy-status returns after half of the SCL period.

Parameters

base – The pointer to the I2C SCB instance.

Returns

A bus status: busy or not busy.

__STATIC_INLINE void Cy_SCB_I2C_MasterSetLowPhaseDutyCycle (CySCB_Type *base, uint32_t clockCycles)

This function sets the number of SCB clock cycles in the low phase of SCL.

If Cy_SCB_I2C_SetDataRate is called after this function, the values specified in this function are overwritten.

note

This function should be used at your own risk. Changing the number of clock cycles in a phase of SCL may violate the I2C specification. Make this change only while the block is disabled.

Parameters
  • base – The pointer to the I2C SCB instance.

  • clockCycles – The number of SCB clock cycles in the low phase of SCL. The valid range is 7 to 16.

__STATIC_INLINE void Cy_SCB_I2C_MasterSetHighPhaseDutyCycle (CySCB_Type *base, uint32_t clockCycles)

This function sets the number of SCB clock cycles in the high phase of SCL.

If Cy_SCB_I2C_SetDataRate is called after this function, the values specified in this function get overwritten.

note

This function should be used at your own risk. Changing the number of clock cycles in a phase of SCL may violate the I2C specification. Make this change only while the block is disabled.

Parameters
  • base – The pointer to the I2C SCB instance.

  • clockCycles – The number of SCB clock cycles in the high phase of SCL. The valid range is 5 to 16.

void Cy_SCB_I2C_SlaveConfigReadBuf(CySCB_Type const *base, uint8_t *buffer, uint32_t size, cy_stc_scb_i2c_context_t *context)

Configures the buffer pointer and the read buffer size.

This is the buffer from which the master reads data. After this function is called, data transfer from the read buffer to the master is handled by Cy_SCB_I2C_Interrupt.

When the Read transaction is completed (master generated Stop, ReStart or error occurred), the CY_SCB_I2C_SLAVE_RD_BUSY status is cleared and the CY_SCB_I2C_SLAVE_RD_CMPLT is set. Also the CY_SCB_I2C_SLAVE_RD_CMPLT_EVENT event is generated.

note

  • The Read buffer must not be modified and stay allocated until it has been read by the master.

  • If this function has not been called, and the master tries to read data from the slave a CY_SCB_I2C_DEFAULT_TX is returned to the master.

  • If the master tries to read more bytes than available in the Read buffer, a CY_SCB_I2C_SLAVE_RD_BUF_EMPTY_EVENT event occurs. The CY_SCB_I2C_DEFAULT_TX is returned to the master if the buffer remains empty after an event notification.

Parameters
  • base – The pointer to the I2C SCB instance.

  • buffer – The pointer to the buffer with data to be read by the master.

  • size – Size of the buffer.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_I2C_SlaveAbortRead(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

Aborts the configured slave read buffer to be read by the master.

If the master reads and “abort operation” is requested, the CY_SCB_I2C_SLAVE_RD_BUF_EMPTY_EVENT event occurs. The CY_SCB_I2C_DEFAULT_TX is returned to the master if the buffer remains empty after the event notification.

Side Effects

If the TX FIFO is used, this function clears it. The TX FIFO clear operation also clears the shift register, thus the shifter can be cleared in the middle of a data element transfer, corrupting it. The data element corruption means that all bits that have not been transmitted are transmitted as “ones” on the bus.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_I2C_SlaveConfigWriteBuf(CySCB_Type const *base, uint8_t *buffer, uint32_t size, cy_stc_scb_i2c_context_t *context)

Configures the buffer pointer and size of the write buffer.

This is the buffer that the master writes data to. After this function is called data transfer from the master into the write buffer is handled by Cy_SCB_I2C_Interrupt.

When write transaction is completed (master generated Stop, ReStart or error occurred) the CY_SCB_I2C_SLAVE_WR_BUSY status is cleared and the CY_SCB_I2C_SLAVE_WR_CMPLT is set, also the CY_SCB_I2C_SLAVE_WR_CMPLT_EVENT event is generated.

note

  • The write buffer must not be modified and must stay allocated until it has been written by the master.

  • If this function has not been called and the master tries to write data, the first byte is NAKed and discarded.

  • If the master writes more bytes than the slave can store in the write buffer, the CY_SCB_I2C_SLAVE_WR_OVRFL status is set and the slave will NACK last byte, unless the RX FIFO is used. Then the slave will NAK only after RX FIFO becomes full.

  • If the RX FIFO is used, the minimum write buffer size is automatically the size of the RX FIFO. If a write buffer is less than the RX FIFO size, extra bytes are ACKed and stored into RX FIFO but ignored by firmware.

Parameters
  • base – The pointer to the I2C SCB instance.

  • buffer – The pointer to buffer to store data written by the master.

  • size – Size of the buffer.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_I2C_SlaveAbortWrite(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

Aborts the configured slave write buffer to be written by the master.

If master writes and an “abort operation” is requested, the next incoming byte will be NAKed.

note

If the RX FIFO is used, the NAK will not be sent until RX FIFO becomes full, however bytes accepted after an abort request are ignored.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_SCB_I2C_SlaveGetStatus(CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)

Returns the current I2C slave status.

This status is a bit mask and the value returned may have multiple bits set.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

I2C Slave Status.

uint32_t Cy_SCB_I2C_SlaveClearReadStatus(CySCB_Type const *base, cy_stc_scb_i2c_context_t *context)

Clears the read status and error conditions flags and returns their values.

note

The CY_SCB_I2C_SLAVE_RD_BUSY flag is not cleared.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

I2C Slave Status.

uint32_t Cy_SCB_I2C_SlaveClearWriteStatus(CySCB_Type const *base, cy_stc_scb_i2c_context_t *context)

Clears the write status flags and error condition flags and returns their values.

note

The CY_SCB_I2C_SLAVE_WR_BUSY flag is not cleared.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

I2C Slave Status.

uint32_t Cy_SCB_I2C_SlaveGetReadTransferCount(CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)

Returns the number of bytes read by the master since the last time Cy_SCB_I2C_SlaveConfigReadBuf was called.

note

  • This function returns an invalid value if a read transaction was aborted or any listed event occurs during the transaction: CY_SCB_I2C_SLAVE_ARB_LOST, CY_SCB_I2C_SLAVE_BUS_ERR.

  • This number is updated only when a transaction completes, either through an error or successfully.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

The number of bytes read by the master.

uint32_t Cy_SCB_I2C_SlaveGetWriteTransferCount(CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)

Returns the number of bytes written by the master since the last time Cy_SCB_I2C_SlaveConfigWriteBuf was called.

note

  • This function returns an invalid value if write transaction was aborted or any listed event occurs during the transaction: CY_SCB_I2C_SLAVE_ARB_LOST, CY_SCB_I2C_SLAVE_BUS_ERR.

  • This number is updated only when the transaction completes, either through an error or successfully.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Number of bytes written by the master.

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterWrite(CySCB_Type *base, cy_stc_scb_i2c_master_xfer_config_t *xferConfig, cy_stc_scb_i2c_context_t *context)

This function configures the master to automatically write an entire buffer of data to a slave device.

After the transaction is initiated by this function it returns and Cy_SCB_I2C_Interrupt manages further data transfer.

When a write transaction is completed (requested number of bytes are written or error occurred) the CY_SCB_I2C_MASTER_BUSY status is cleared and the CY_SCB_I2C_MASTER_WR_CMPLT_EVENT event is generated.

note

  • The buffer must not be modified and must stay allocated until data has been copied into the TX FIFO.

  • Cy_SCB_I2C_MasterWrite requests the SCB hardware to generate a start condition when there is no pending transfer and returns (does not wait until hardware generate a start condition). If the I2C bus is busy the hardware will not generate the until bus becomes free. The SCB hardware sets the busy status after the Start detection, and clears it on the Stop detection. Noise caused by the ESD or other events may cause an erroneous Start condition on the bus. Then, the master will never generate a Start condition because the hardware assumes the bus is busy. If this occurs, the Cy_SCB_I2C_MasterGetStatus returns CY_SCB_I2C_MASTER_BUSY status and the transaction will never finish. The option is to implement a timeout to detect the transfer completion. If the transfer never completes, the SCB needs a reset by calling the Cy_SCB_I2C_Disable and Cy_SCB_I2C_Enable functions. The Cy_SCB_I2C_MasterAbortWrite function will not work, the block must be reset.

Parameters
  • base – The pointer to the I2C SCB instance.

  • xferConfig – Master transfer configuration structure cy_stc_scb_i2c_master_xfer_config_t.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

void Cy_SCB_I2C_MasterAbortWrite(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

This function requests the master to abort write operation by generating a Stop condition.

The function does not wait until this action is completed. Therefore next write operation can be initiated only after the CY_SCB_I2C_MASTER_BUSY is cleared.

Side Effects

If the TX FIFO is used, it is cleared before Stop generation. The TX FIFO clear operation also clears shift register. Thus, the shifter could be cleared in the middle of a data element transfer, corrupting it. The remaining bits to transfer within corrupted data element are complemented with ones.

If the clear operation is requested while the master transmits the address, the direction of transaction is changed to read and one byte is read before Stop is issued. This byte is discarded.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterRead(CySCB_Type *base, cy_stc_scb_i2c_master_xfer_config_t *xferConfig, cy_stc_scb_i2c_context_t *context)

This function configures the master to automatically read an entire buffer of data from the slave device.

After the transaction is initiated by this function it returns and Cy_SCB_I2C_Interrupt manages further data transfer.

When a read transaction is completed (requested number of bytes are read or error occurred) the CY_SCB_I2C_MASTER_BUSY status is cleared and the CY_SCB_I2C_MASTER_RD_CMPLT_EVENT event is generated.

Note that the master must read at least one byte.

note

  • The buffer must not be modified and must stay allocated until read operation completion.

  • Cy_SCB_I2C_MasterRead requests the SCB hardware to generate a start condition when there is no pending transfer and returns (does not wait until hardware generate a start condition). If the I2C bus is busy the hardware will not generate the until bus becomes free. The SCB hardware sets the busy status after the Start detection, and clears it on the Stop detection. Noise caused by the ESD or other events may cause an erroneous Start condition on the bus. Then, the master will never generate a Start condition because the hardware assumes the bus is busy. If this occurs, the Cy_SCB_I2C_MasterGetStatus returns CY_SCB_I2C_MASTER_BUSY status and the transaction will never finish. The option is to implement a timeout to detect the transfer completion. If the transfer never completes, the SCB needs a reset by calling the Cy_SCB_I2C_Disable and Cy_SCB_I2C_Enable functions. The Cy_SCB_I2C_MasterAbortRead function will not work, the block must be reset.

Parameters
  • base – The pointer to the I2C SCB instance.

  • xferConfig – Master transfer configuration structure cy_stc_scb_i2c_master_xfer_config_t.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

void Cy_SCB_I2C_MasterAbortRead(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

This function requests master to abort read operation by NAKing the next byte and generating a Stop condition.

The function does not wait until these actions are completed. Therefore the next operation can be initiated only after the CY_SCB_I2C_MASTER_BUSY is cleared.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

uint32_t Cy_SCB_I2C_MasterGetStatus(CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)

Returns the current I2C master status.

This status is a bit mask and the value returned may have multiple bits set.

note

Status is cleared by calling Cy_SCB_I2C_MasterRead or Cy_SCB_I2C_MasterWrite.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

I2C Master Status. Note that not all I2C master statuses are returned by this function. Refer to more details of each status.

uint32_t Cy_SCB_I2C_MasterGetTransferCount(CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context)

Returns the number of bytes transferred since the last call of Cy_SCB_I2C_MasterWrite or Cy_SCB_I2C_MasterRead function.

note

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

Number of bytes read or written by the master.

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterSendStart(CySCB_Type *base, uint32_t address, cy_en_scb_i2c_direction_t bitRnW, uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context)

Generates a Start condition and sends a slave address with the Read/Write bit.

This function is blocking. It does not return until the Start condition and address byte are sent and a ACK/NAK is received, or an error or timeout occurs.

note

After a read transaction is initiated and the slave ACKs the address, at least one byte must be read before completing the transaction or changing its direction.

Parameters
  • base – The pointer to the I2C SCB instance.

  • address – 7 bit right justified slave address.

  • bitRnW – This sets the value of the Read/Write bit in the address, thus defining the direction of the following transfer. See cy_en_scb_i2c_direction_t for the set of constants.

  • timeoutMs – Defines in milliseconds the time for which this function can block. If that time expires, the function returns. If a zero is passed, the function waits forever for the action to complete. If a timeout occurs, the SCB block is reset. Note The maximum value is UINT32_MAX/1000.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterSendReStart(CySCB_Type *base, uint32_t address, cy_en_scb_i2c_direction_t bitRnW, uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context)

Generates a ReStart condition and sends a slave address with the Read/Write bit.

This function is blocking. It does not return until the ReStart condition and address byte are sent and an ACK/NAK is received, or an error or timeout occurs.

note

  • A successful transaction must be initiated by Cy_SCB_I2C_MasterSendStart before calling this function. If this condition is not met, this function does nothing and returns CY_SCB_I2C_MASTER_NOT_READY.

  • After a read transaction is initiated and the slave ACKs the address, at least one byte must be read before completing the transaction or changing its direction.

Parameters
  • base – The pointer to the I2C SCB instance.

  • address – A 7-bit right-justified slave address.

  • bitRnW – This sets the value of the Read/Write bit in the address, thus defining the direction of the following transfer. See cy_en_scb_i2c_direction_t for the set of constants.

  • timeoutMs – Defines in milliseconds the time for which this function can block. If that time expires, the function returns. If a zero is passed, the function waits forever for the action to complete. If a timeout occurs, the SCB block is reset. Note The maximum value is UINT32_MAX/1000.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterSendStop(CySCB_Type *base, uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context)

Generates a Stop condition to complete the current transaction.

This function is blocking. It does not return until the Stop condition is generated, or an error or timeout occurs.

note

Parameters
  • base – The pointer to the I2C SCB instance.

  • timeoutMs – Defines in milliseconds the time for which this function can block. If that time expires, the function returns. If a zero is passed, the function waits forever for the action to complete. If a timeout occurs, the SCB block is reset. Note The maximum value is UINT32_MAX/1000.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterReadByte(CySCB_Type *base, cy_en_scb_i2c_command_t ackNack, uint8_t *byte, uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context)

Reads one byte from a slave and generates an ACK or prepares to generate a NAK.

The NAK will be generated before a Stop or ReStart condition by Cy_SCB_I2C_MasterSendStop or Cy_SCB_I2C_MasterSendReStart function appropriately. This function is blocking. It does not return until a byte is received, or an error or timeout occurs.

note

A successful transaction must be initiated by Cy_SCB_I2C_MasterSendStart or Cy_SCB_I2C_MasterSendReStart before calling this function. If this condition is not met, this function does nothing and returns CY_SCB_I2C_MASTER_NOT_READY.

Parameters
  • base – The pointer to the I2C SCB instance.

  • ackNack – A response to a received byte. See cy_en_scb_i2c_command_t for the set of constants.

  • byte – The pointer to the location to store the Read byte.

  • timeoutMs – Defines in milliseconds the time for which this function can block. If that time expires, the function returns. If a zero is passed, the function waits forever for the action to complete. If a timeout occurs, the SCB block is reset. Note The maximum value is UINT32_MAX/1000.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterWriteByte(CySCB_Type *base, uint8_t byte, uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context)

Sends one byte to a slave.

This function is blocking. It does not return until a byte is transmitted, or an error or timeout occurs.

note

A successful transaction must be initiated by Cy_SCB_I2C_MasterSendStart or Cy_SCB_I2C_MasterSendReStart before calling this function. If this condition is not met, this function does nothing and returns CY_SCB_I2C_MASTER_NOT_READY.

Parameters
  • base – The pointer to the I2C SCB instance.

  • byte – The byte to write to a slave.

  • timeoutMs – Defines in milliseconds the time for which this function can block. If that time expires, the function returns. If a zero is passed, the function waits forever for the action to complete. If a timeout occurs, the SCB block is reset. Note The maximum value is UINT32_MAX/1000.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns

cy_en_scb_i2c_status_t

void Cy_SCB_I2C_Interrupt(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

This is the interrupt function for the SCB configured in the I2C mode.

The interrupt is mandatory for I2C operation and this function must be called inside the user-defined interrupt service. The exception is the I2C master, which uses only the Master Low-Level functions. To reduce the flash consumed by the I2C driver call Cy_SCB_I2C_SlaveInterrupt when I2C mode is the slave and Cy_SCB_I2C_MasterInterrupt when I2C mode is the master.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_I2C_SlaveInterrupt(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

This is the interrupt function for the SCB configured in I2C mode as the slave.

This function should be called inside the user-defined interrupt service routine to make any of the slave functions to work.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

void Cy_SCB_I2C_MasterInterrupt(CySCB_Type *base, cy_stc_scb_i2c_context_t *context)

This is the interrupt function for the SCB configured in I2C mode as the master.

This function should be called inside the user-defined interrupt service routine to make Master High-Level functions to work.

Parameters
  • base – The pointer to the I2C SCB instance.

  • context – The pointer to the context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user must not modify anything in this structure.

__STATIC_INLINE void Cy_SCB_I2C_RegisterEventCallback (CySCB_Type const *base, cy_cb_scb_i2c_handle_events_t callback, cy_stc_scb_i2c_context_t *context)

Registers a callback function that notifies that I2C Callback Events occurred in the Cy_SCB_I2C_Interrupt.

note

To remove the callback, pass NULL as the pointer to the callback function.

Parameters
  • base – The pointer to the I2C SCB instance.

  • callback – The pointer to a callback function. See cy_cb_scb_i2c_handle_events_t for the function prototype.

  • context – The pointer to context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used while the I2C operation for internal configuration and data retention. The user should not modify anything in this structure.

__STATIC_INLINE void Cy_SCB_I2C_RegisterAddrCallback (CySCB_Type const *base, cy_cb_scb_i2c_handle_addr_t callback, cy_stc_scb_i2c_context_t *context)

Registers a callback function that notifies that I2C Address Callback Events occurred in the Cy_SCB_I2C_Interrupt.

note

To remove the callback, pass NULL as the pointer to a callback function.

Parameters
  • base – The pointer to the I2C SCB instance.

  • callback – The pointer to a callback function. See cy_cb_scb_i2c_handle_addr_t for the function prototype.

  • context – The pointer to context structure cy_stc_scb_i2c_context_t allocated by the user. The structure is used during the I2C operation for internal configuration and data retention. The user should not modify anything in this structure.

cy_en_syspm_status_t Cy_SCB_I2C_DeepSleepCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)

This function handles the transition of the I2C SCB into and out of Deep Sleep mode.

It prevents the device from entering Deep Sleep mode if the I2C slave or master is actively communicating. The behavior of the I2C SCB in Deep Sleep depends on whether the SCB block is wakeup-capable or not:

  • Wakeup-capable: during Deep Sleep mode on incoming I2C slave address the slave receives address and stretches the clock until the device is awoken from Deep Sleep mode. If the slave address occurs before the device enters Deep Sleep mode, the device will not enter Deep Sleep mode. Only the I2C slave can be configured to be a wakeup source from Deep Sleep mode.

  • Not wakeup-capable: the SCB is disabled in Deep Sleep mode. It is re-enabled if the device fails to enter Deep Sleep mode or when the device is awoken from Deep Sleep mode. While the SCB is disabled it stops driving the outputs and ignores the inputs. The slave NACKs all incoming addresses.

This function must be called during execution of Cy_SysPm_CpuEnterDeepSleep. To do it, register this function as a callback before calling Cy_SysPm_CpuEnterDeepSleep : specify CY_SYSPM_DEEPSLEEP as the callback type and call Cy_SysPm_RegisterCallback.

note

Only applicable for rev-08 of the CY8CKIT-062-BLE. For proper operation, when the I2C slave is configured to be a wakeup source from Deep Sleep mode, this function must be copied and modified by the user. The I2C clock disable code must be inserted in the CY_SYSPM_BEFORE_TRANSITION and clock enable code in the CY_SYSPM_AFTER_TRANSITION mode processing.

Parameters
Returns

cy_en_syspm_status_t

cy_en_syspm_status_t Cy_SCB_I2C_HibernateCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)

This function handles the transition of the I2C SCB block into Hibernate mode.

It prevents the device from entering Hibernate mode if the I2C slave or master is actively communicating. If the I2C is ready to enter Hibernate mode it is disabled. If the device failed to enter Hibernate mode, the SCB is enabled. After the SCB is disabled, it stops driving the outputs and ignores the inputs. The slave NACKs all incoming addresses.

This function must be called during execution of Cy_SysPm_SystemEnterHibernate. To do it, register this function as a callback before calling Cy_SysPm_SystemEnterHibernate : specify CY_SYSPM_HIBERNATE as the callback type and call Cy_SysPm_RegisterCallback.

Parameters
Returns

cy_en_syspm_status_t

struct cy_stc_scb_i2c_config_t
#include <>

I2C configuration structure.

Public Members

cy_en_scb_i2c_mode_t i2cMode

Specifies the mode of operation.

bool useRxFifo

The SCB provides an RX FIFO in hardware (consult the selected device datasheet to get the actual FIFO size).

The useRxFifo field defines how the driver firmware reads data from the RX FIFO:

  • If this option is enabled, the hardware is configured to automatically ACK incoming data, and interrupt is enabled to take data out of the RX FIFO when it has some number of bytes (typically, when it is half full).

  • If this option is disabled, the interrupt is enabled to take data out of the RX FIFO when a byte is available. Also, hardware does not automatically ACK the data. Firmware must tell the hardware to ACK the byte (so each byte requires interrupt processing). Typically, this option should be enabled to configure hardware to automatically ACK incoming data. Otherwise hardware might not get the command to ACK or NACK a byte fast enough, and clock stretching is applied (the transaction is delayed) until the command is set. When this option is enabled, the number of interrupts required to process the transaction is significantly reduced because several bytes are handled at once. However, there is a side effect:

  • For master mode, the drawback is that the master may receive more data than desired due to the interrupt latency. An interrupt fires when the second-to-last byte has been received. This interrupt tells the hardware to stop receiving data. If the latency of this interrupt is longer than one transaction of the byte on the I2C bus, then the hardware automatically ACKs the following bytes until the interrupt is serviced or the RX FIFO becomes full.

  • For slave mode, the drawback is that the slave only NACKs the master when the RX FIFO becomes full, NOT when the slave write firmware buffer becomes full.

    In either master or slave mode, all received extra bytes are dropped.

    note

    The useRxFifo option is not available if acceptAddrInFifo is true.

bool useTxFifo

The SCB provides a TX FIFO in hardware (consult the selected device datasheet to get the actual FIFO size).

The useTxFifo option defines how the driver firmware loads data into the TX FIFO:

  • If this option is enabled, the TX FIFO is fully loaded with data and the interrupt is enabled to keep the TX FIFO loaded until the end of the transaction.

  • If this option is disabled, a single byte is loaded into the TX FIFO and the interrupt enabled to load the next byte when the TX FIFO becomes empty (so each byte requires interrupt processing). Typically, this option should be enabled to keep the TX FIFO loaded with data and reduce the probability of clock stretching. When there is no data to transfer, clock stretching is applied (the transaction is delayed) until the data is loaded. When this option is enabled, the number of interrupts required to process the transaction is significantly reduced because several bytes are handled at once. The drawback of enabling useTxFifo is that the abort operation clears the TX FIFO. The TX FIFO clear operation also clears the shift register. As a result the shifter may be cleared in the middle of a byte transaction, corrupting it. The remaining bits to transaction within the corrupted byte are complemented with 1s. If this is an issue, then do not enable this option.

uint8_t slaveAddress

The 7-bit right justified slave address, used only for the slave mode.

uint8_t slaveAddressMask

The slave address mask is used to mask bits of the slave address during the address match procedure (it is used only for the slave mode).

Bit 0 of the address mask corresponds to the read/write direction bit and is always a do not care in the address match therefore must be set 0. Bit value 0 - excludes bit from address comparison. Bit value 1 - the bit needs to match with the corresponding bit of the I2C slave address.

bool acceptAddrInFifo

True - the slave address is accepted in the RX FIFO, false - the slave addresses are not accepted in the RX FIFO.

bool ackGeneralAddr

True - accept the general call address; false - ignore the general call address.

bool enableWakeFromSleep

When set, the slave will wake the device from Deep Sleep on an address match (the device datasheet must be consulted to determine which SCBs support this mode)

bool enableDigitalFilter

Enables a digital 3-tap median filter to be applied to the inputs of filter glitches on the lines.

uint32_t lowPhaseDutyCycle

The number of SCB clock cycles in the low phase of SCL.

Only applicable in master modes. The valid range is 7 to 16.

uint32_t highPhaseDutyCycle

The number of SCB clock cycles in the high phase of SCL.

Only applicable in master modes. The valid range is 5 to 16.

struct cy_stc_scb_i2c_context_t
#include <>

I2C context structure.

All fields for the context structure are internal. Firmware never reads or writes these values. Firmware allocates the structure and provides the address of the structure to the driver in function calls. Firmware must ensure that the defined instance of this structure remains in scope while the drive is in use.

struct cy_stc_scb_i2c_master_xfer_config_t
#include <>

The I2C Master transfer structure.

Public Members

uint8_t slaveAddress

The 7-bit right justified slave address to communicate with.

uint8_t *buffer

The pointer to the buffer for data to read from the slave or data to write into the slave.

uint32_t bufferSize

The size of the buffer.

bool xferPending

The transfer operation is pending - the stop condition will not be generated.

A new transfer starts from start condition and ends with or without stop condition. The stop condition releases I2C bus from master control. When stop is not generated master keeps bus control (transfer is pending) and can issue the next transfer using restart condition instead of start. The I2C driver automatically generates start or restart condition depends on current state. Note if master lost arbitration during transfer it stops control the bus and does not send/receive data or generate stop condition - the transfer ends.