I2C (Inter-Integrated Circuit)

General Description

High level interface for interacting with the I2C resource.

The I2C protocol is a synchronous serial interface protocol. This driver supports both master and slave mode of operation. The communication frequency and address (for slave operation) can be configured.

Features

• Master or slave functionality
• Configurable slave address
• Configurable data rates
• Configurable interrupt and callback assignment from I2C events - cyhal_i2c_event_t

Quick Start

Initialize an I2C instance using the cyhal_i2c_init and provide sda (I2C data) and scl (I2C clock) pins.
By default, this initializes the resource as an I2C master.
Configure the behavior (master/slave) and the interface (bus frequency, slave address) using the cyhal_i2c_configure function.
See Snippet 1: I2C Initialization and Configuration for example initialization as master or slave.

Note

The clock parameter (const cyhal_clock_divider_t *clk) is optional and can be set to NULL to generate and use an available clock resource with a default frequency (CYHAL_I2C_MASTER_DEFAULT_FREQ).

Code Snippets

Snippet 1: I2C Initialization and Configuration

This snippet initializes an I2C resource as master or slave and assigns the sda and scl pins.

Initializing as I2C master

    // Declare variables
    cy_rslt_t   rslt;
    cyhal_i2c_t i2c_master_obj;
 
    // Define frequency
    uint32_t I2C_MASTER_FREQUENCY = 100000u;
 
    // Define the I2C master configuration structure
    cyhal_i2c_cfg_t i2c_master_config =
    {
        CYHAL_I2C_MODE_MASTER,
        0, // address is not used for master mode
        I2C_MASTER_FREQUENCY
    };
 
    // Initialize I2C master, set the SDA and SCL pins and assign a new clock
    rslt = cyhal_i2c_init(&i2c_master_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL);
 
    // Configure the I2C resource to be master
    rslt = cyhal_i2c_configure(&i2c_master_obj, &i2c_master_config);

Initializing as I2C slave

    // Declare variables
    cy_rslt_t   rslt;
    cyhal_i2c_t i2c_slave_obj;
 
    // Define address
    uint16_t I2C_SLAVE_ADDRESS = 0x08u;
    // Define address mask
    uint16_t I2C_SLAVE_ADDRESS_MASK = 0xFEu;
    // Define frequency
    uint32_t I2C_SLAVE_FREQUENCY = 100000u;
    // Define address is in FIFO or not
    bool I2C_ENABLE_ADDRESS_EVENT = false;
 
    // Define the slave configuration structure
    cyhal_i2c_cfg_t i2c_slave_config =
        { CYHAL_I2C_MODE_SLAVE, I2C_SLAVE_ADDRESS, I2C_SLAVE_FREQUENCY };
 
    cyhal_i2c_adv_cfg_t i2c_slave_advanced_config =
        { i2c_slave_config, I2C_SLAVE_ADDRESS_MASK, I2C_ENABLE_ADDRESS_EVENT };
    // Initialize I2C slave, set the SDA and SCL pins and assign a new clock
    rslt = cyhal_i2c_init(&i2c_slave_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL);
 
    // Configure the I2C resource to be slave
    rslt = cyhal_i2c_configure(&i2c_slave_obj, &i2c_slave_config);
 
    // Advanced configuration of the I2C resource to be slave
    rslt = cyhal_i2c_configure_adv(&i2c_slave_obj, &i2c_slave_advanced_config);
 

Snippet 2: Handling events

This snippet shows how to enable and handle I2C events using cyhal_i2c_enable_event and cyhal_i2c_register_callback.
The callback parameter of cyhal_i2c_register_callback is used to pass the callback handler that will be invoked when an event occurs.
The event parameter of cyhal_i2c_enable_event is used to pass the bitmasks of events ( cyhal_i2c_event_t) to be enabled.

 
void handle_i2c_events(void* callback_arg, cyhal_i2c_event_t event)
{
    // To remove unused variable warning
    (void)callback_arg;
 
    // Check write complete event
    if (0UL != (CYHAL_I2C_SLAVE_WR_CMPLT_EVENT & event))
    {
        // Perform the required functions
    }
    // Check read complete event
    if (0UL != (CYHAL_I2C_SLAVE_RD_CMPLT_EVENT & event))
    {
        // Perform the required functions
    }
    // Check for errors
    if (0UL == (CYHAL_I2C_SLAVE_ERR_EVENT & event))
    {
        // Perform the required function
    }
}
 
 
cyhal_i2c_command_rsp_t handle_i2c_address_events(void* callback_arg, cyhal_i2c_addr_event_t event,
                                                  uint8_t device_address)
{
    // To remove unused variable warning
    (void)callback_arg;
    (void)device_address;
 
    // Check write complete event
    if (0UL != (CYHAL_I2C_GENERAL_CALL_EVENT & event))
    {
        // Perform the required functions
    }
    // Check read complete event
    if (0UL != (CYHAL_I2C_ADDR_MATCH_EVENT & event))
    {
        // Perform the required functions
    }
    return CYHAL_I2C_CMD_ACK;
}
 
 
cy_rslt_t snippet_cyhal_i2c_slave_callback_init()
{
    // Declare variables
    cy_rslt_t   rslt;
    cyhal_i2c_t i2c_slave_obj;
 
    // Define the slave configuration structure
    cyhal_i2c_cfg_t i2c_slave_config = { CYHAL_I2C_MODE_SLAVE, 0x08u, 100000u };
 
    // Initialize I2C slave, set the SDA and SCL pins and assign a new clock
    rslt = cyhal_i2c_init(&i2c_slave_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL);
 
    // Configure the I2C resource to be slave
    if (CY_RSLT_SUCCESS == rslt)
    {
        rslt = cyhal_i2c_configure(&i2c_slave_obj, &i2c_slave_config);
    }
 
    if (CY_RSLT_SUCCESS == rslt)
    {
        // Register I2C slave event callback
        cyhal_i2c_register_callback(&i2c_slave_obj, (cyhal_i2c_event_callback_t)handle_i2c_events,
                                    NULL);
 
        // Enable I2C Events
        cyhal_i2c_enable_event(&i2c_slave_obj, (cyhal_i2c_event_t)   \
                               (CYHAL_I2C_SLAVE_WR_CMPLT_EVENT \
                                | CYHAL_I2C_SLAVE_RD_CMPLT_EVENT \
                                | CYHAL_I2C_SLAVE_ERR_EVENT),    \
                               3u, true);
 
        // Register I2C slave address callback
        cyhal_i2c_register_address_callback(&i2c_slave_obj,
                                            (cyhal_i2c_address_callback_t)handle_i2c_address_events,
                                            NULL);
 
        // Enable I2C Address Events
        cyhal_i2c_enable_address_event(&i2c_slave_obj, (cyhal_i2c_addr_event_t)   \
                                       (CYHAL_I2C_ADDR_MATCH_EVENT),    \
                                       3u, true);
    }
 
    return rslt;
}
 
 

Snippet 3: I2C Master Asynchronous Transfer

This snippet shows how to implement asynchronous transfers using cyhal_i2c_master_transfer_async.
cyhal_i2c_abort_async is used to stop the transfer, in this case when an error occurs.

// Declare variables
cyhal_i2c_t i2c_master_obj;
uint8_t     tx_buff[3] = { 1, 2, 3 };
uint8_t     rx_buff[3];
 
// Defining master callback handler
void master_event_handler(void* callback_arg, cyhal_i2c_event_t event)
{
    // To remove unused variable warning
    (void)callback_arg;
 
    // Check write complete event
    if (0UL != (CYHAL_I2C_MASTER_WR_CMPLT_EVENT & event))
    {
        // Perform the required functions
    }
    // Check read complete event
    if (0UL != (CYHAL_I2C_MASTER_RD_CMPLT_EVENT & event))
    {
        // Perform the required functions
    }
    if (0UL != (CYHAL_I2C_MASTER_ERR_EVENT & event))
    {
        // In case of error abort transfer
        cyhal_i2c_abort_async(&i2c_master_obj);
    }
}
 
 
cy_rslt_t snippet_cyhal_async_transfer(void)
{
    cy_rslt_t rslt;
 
    // Define address
    uint16_t I2C_SLAVE_ADDRESS = 0x08u;
    // Define frequency
    uint32_t I2C_MASTER_FREQUENCY = 100000u;
 
    // Configure I2C Master
    cyhal_i2c_cfg_t i2c_master_config = { CYHAL_I2C_MODE_MASTER, 0, I2C_MASTER_FREQUENCY };
 
    rslt = cyhal_i2c_init(&i2c_master_obj, CYBSP_I2C_SDA, CYBSP_I2C_SCL, NULL);
 
    if (CY_RSLT_SUCCESS == rslt)
    {
        rslt = cyhal_i2c_configure(&i2c_master_obj, &i2c_master_config);
    }
 
    if (CY_RSLT_SUCCESS == rslt)
    {
        cyhal_i2c_register_callback(&i2c_master_obj,
                                    (cyhal_i2c_event_callback_t)master_event_handler,
                                    NULL);
        cyhal_i2c_enable_event(&i2c_master_obj, (cyhal_i2c_event_t)   \
                               (CYHAL_I2C_MASTER_WR_CMPLT_EVENT \
                                | CYHAL_I2C_MASTER_RD_CMPLT_EVENT \
                                | CYHAL_I2C_MASTER_ERR_EVENT),    \
                               3u, true);
 
        // Initiate master write and read transfer using tx_buff and rx_buff respectively.
        rslt = cyhal_i2c_master_transfer_async(&i2c_master_obj, I2C_SLAVE_ADDRESS, tx_buff, 3,
                                               rx_buff, 3);
    }
 
    return rslt;
}
 
 

More Information

Peripheral Driver Library (PDL)

• PSoC™ 6 PDL: SCB (Serial Communication Block)

Code examples (Github)

• PSoC™ 6 MCU: I2C Master
• PSoC™ 6 MCU: I2C Slave Using Callbacks

API Reference
	I2C HAL Results
	I2C specific return codes.

Data Structures
struct	cyhal_i2c_cfg_t
	Initial I2C configuration. More...
struct	cyhal_i2c_adv_cfg_t
	I2C advanced configuration. More...

Macros
#define	CYHAL_I2C_MODE_SLAVE   (true)
	Named define for Slave mode for use when initializing the cyhal_i2c_cfg_t structure.
#define	CYHAL_I2C_MODE_MASTER   (false)
	Named define for Master mode for use when initializing the cyhal_i2c_cfg_t structure.
#define	CYHAL_I2C_DEFAULT_ADDR_MASK   (0xFE)
	Named define for default address mask for use when initializing the cyhal_i2c_adv_cfg_t structure.

Typedefs
typedef void(*	cyhal_i2c_event_callback_t) (void *callback_arg, cyhal_i2c_event_t event)
	Handler for I2C events.
typedef cyhal_i2c_command_rsp_t(*	cyhal_i2c_address_callback_t) (void *callback_arg, cyhal_i2c_addr_event_t event, uint8_t address)
	Handler for I2C address events.

Enumerations
enum	cyhal_i2c_event_t {   CYHAL_I2C_EVENT_NONE = 0 ,   CYHAL_I2C_SLAVE_READ_EVENT = 1 << 1 ,   CYHAL_I2C_SLAVE_WRITE_EVENT = 1 << 2 ,   CYHAL_I2C_SLAVE_RD_IN_FIFO_EVENT = 1 << 3 ,   CYHAL_I2C_SLAVE_RD_BUF_EMPTY_EVENT = 1 << 4 ,   CYHAL_I2C_SLAVE_RD_CMPLT_EVENT = 1 << 5 ,   CYHAL_I2C_SLAVE_WR_CMPLT_EVENT = 1 << 6 ,   CYHAL_I2C_SLAVE_ERR_EVENT = 1 << 7 ,   CYHAL_I2C_MASTER_WR_IN_FIFO_EVENT = 1 << 17 ,   CYHAL_I2C_MASTER_WR_CMPLT_EVENT = 1 << 18 ,   CYHAL_I2C_MASTER_RD_CMPLT_EVENT = 1 << 19 ,   CYHAL_I2C_MASTER_ERR_EVENT = 1 << 20 }
	Enum to enable/disable/report interrupt cause flags. More...
enum	cyhal_i2c_addr_event_t {   CYHAL_I2C_ADDR_EVENT_NONE = 0 ,   CYHAL_I2C_GENERAL_CALL_EVENT = 1 << 1 ,   CYHAL_I2C_ADDR_MATCH_EVENT = 1 << 2 }
	Enum to enable/disable/report address interrupt cause flags. More...
enum	cyhal_i2c_fifo_type_t {   CYHAL_I2C_FIFO_RX ,   CYHAL_I2C_FIFO_TX }
	I2C FIFO type. More...
enum	cyhal_i2c_command_rsp_t {   CYHAL_I2C_CMD_ACK ,   CYHAL_I2C_CMD_NAK }
	I2C Command ACK / NAK. More...
enum	cyhal_i2c_output_t {   CYHAL_I2C_OUTPUT_TRIGGER_RX_FIFO_LEVEL_REACHED ,   CYHAL_I2C_OUTPUT_TRIGGER_TX_FIFO_LEVEL_REACHED }
	Enum of possible output signals from an I2C. More...

Functions
cy_rslt_t	cyhal_i2c_init (cyhal_i2c_t *obj, cyhal_gpio_t sda, cyhal_gpio_t scl, const cyhal_clock_t *clk)
	Initialize the I2C peripheral, and configures its specified pins. More...
void	cyhal_i2c_free (cyhal_i2c_t *obj)
	Deinitialize the i2c object. More...
cy_rslt_t	cyhal_i2c_configure (cyhal_i2c_t *obj, const cyhal_i2c_cfg_t *cfg)
	Configure the I2C block. More...
cy_rslt_t	cyhal_i2c_configure_adv (cyhal_i2c_t *obj, const cyhal_i2c_adv_cfg_t *cfg)
	Configure the I2C block with advanced parameters. More...
cy_rslt_t	cyhal_i2c_master_write (cyhal_i2c_t *obj, uint16_t dev_addr, const uint8_t *data, uint16_t size, uint32_t timeout, bool send_stop)
	I2C master blocking write. More...
cy_rslt_t	cyhal_i2c_master_read (cyhal_i2c_t *obj, uint16_t dev_addr, uint8_t *data, uint16_t size, uint32_t timeout, bool send_stop)
	I2C master blocking read. More...
cy_rslt_t	cyhal_i2c_slave_config_write_buffer (cyhal_i2c_t *obj, const uint8_t *data, uint16_t size)
	The function configures the write buffer on an I2C Slave. More...
cy_rslt_t	cyhal_i2c_slave_config_read_buffer (cyhal_i2c_t *obj, uint8_t *data, uint16_t size)
	The function configures the read buffer on an I2C Slave. More...
cy_rslt_t	cyhal_i2c_master_mem_write (cyhal_i2c_t *obj, uint16_t address, uint16_t mem_addr, uint16_t mem_addr_size, const uint8_t *data, uint16_t size, uint32_t timeout)
	Perform an I2C write using a block of data stored at the specified memory location. More...
cy_rslt_t	cyhal_i2c_master_mem_read (cyhal_i2c_t *obj, uint16_t address, uint16_t mem_addr, uint16_t mem_addr_size, uint8_t *data, uint16_t size, uint32_t timeout)
	Perform an I2C read using a block of data stored at the specified memory location. More...
cy_rslt_t	cyhal_i2c_master_transfer_async (cyhal_i2c_t *obj, uint16_t address, const void *tx, size_t tx_size, void *rx, size_t rx_size)
	Initiate a non-blocking I2C master asynchronous transfer. More...
cy_rslt_t	cyhal_i2c_abort_async (cyhal_i2c_t *obj)
	Abort asynchronous transfer. More...
void	cyhal_i2c_register_callback (cyhal_i2c_t *obj, cyhal_i2c_event_callback_t callback, void *callback_arg)
	Register an I2C event callback handler More...
void	cyhal_i2c_register_address_callback (cyhal_i2c_t *obj, cyhal_i2c_address_callback_t callback, void *callback_arg)
	Register an I2C address callback handler More...
void	cyhal_i2c_enable_event (cyhal_i2c_t *obj, cyhal_i2c_event_t event, uint8_t intr_priority, bool enable)
	Configure and Enable or Disable I2C Interrupt. More...
void	cyhal_i2c_enable_address_event (cyhal_i2c_t *obj, cyhal_i2c_addr_event_t event, uint8_t intr_priority, bool enable)
	Configure and Enable or Disable I2C Address Interrupt. More...
cy_rslt_t	cyhal_i2c_set_fifo_level (cyhal_i2c_t *obj, cyhal_i2c_fifo_type_t type, uint16_t level)
	Sets a threshold level for a FIFO that will generate an interrupt and a trigger output. More...
cy_rslt_t	cyhal_i2c_enable_output (cyhal_i2c_t *obj, cyhal_i2c_output_t output, cyhal_source_t *source)
	Enables the specified output signal from an I2C. More...
cy_rslt_t	cyhal_i2c_disable_output (cyhal_i2c_t *obj, cyhal_i2c_output_t output)
	Disables the specified output signal from an I2C. More...
cy_rslt_t	cyhal_i2c_init_cfg (cyhal_i2c_t *obj, const cyhal_i2c_configurator_t *cfg)
	Initialize the I2C peripheral using a configurator generated configuration struct. More...
uint32_t	cyhal_i2c_slave_readable (cyhal_i2c_t *obj)
	Returns the number of bytes written by the I2C master. More...
uint32_t	cyhal_i2c_slave_writable (cyhal_i2c_t *obj)
	Returns the number of bytes can be read by the I2C master. More...
cy_rslt_t	cyhal_i2c_slave_read (cyhal_i2c_t *obj, uint8_t *dst_buff, uint16_t *size, uint32_t timeout)
	Wait for master send data to RX buffer and store them to the user-defined buffer. More...
cy_rslt_t	cyhal_i2c_slave_write (cyhal_i2c_t *obj, const uint8_t *src_buff, uint16_t *size, uint32_t timeout)
	Write data from the user-defined buffer to I2C TX buffer. More...
cy_rslt_t	cyhal_i2c_slave_abort_read (cyhal_i2c_t *obj)
	The function aborts the configured slave read buffer to be read by the master. More...
cy_rslt_t	cyhal_i2c_clear (cyhal_i2c_t *obj)
	Clear the I2C buffers. More...

---

Data Structure Documentation

cyhal_i2c_cfg_t

struct cyhal_i2c_cfg_t

Data Fields
bool	is_slave	Operates as a slave when set to (true), else as a master (false)
uint16_t	address	Address of this slave resource (7-bit), should be set to 0 for master.
uint32_t	frequencyhal_hz	Frequency that the I2C bus runs at (I2C data rate in bits per second) Refer to the device datasheet for the supported I2C data rates.

cyhal_i2c_adv_cfg_t

struct cyhal_i2c_adv_cfg_t

Data Fields
cyhal_i2c_cfg_t	basic_cfg	Basic I2C configuration.
uint8_t	address_mask	Mask of the slave resource. Not applicable for the master.
bool	enable_address_callback	Indicates address callback feature is enabled or disable. When it's true the address callback will be invoked.

Enumeration Type Documentation

cyhal_i2c_event_t

enum cyhal_i2c_event_t

Enum to enable/disable/report interrupt cause flags.

Enumerator
CYHAL_I2C_EVENT_NONE	No event.
CYHAL_I2C_SLAVE_READ_EVENT	Indicates that the slave was addressed and the master wants to read data.
CYHAL_I2C_SLAVE_WRITE_EVENT	Indicates that the slave was addressed and the master wants to write data.
CYHAL_I2C_SLAVE_RD_IN_FIFO_EVENT	All slave data from the configured Read buffer has been loaded into the TX FIFO.
CYHAL_I2C_SLAVE_RD_BUF_EMPTY_EVENT	The master has read all data out of the configured Read buffer.
CYHAL_I2C_SLAVE_RD_CMPLT_EVENT	Indicates the master completed reading from the slave (set by the master NAK or Stop)
CYHAL_I2C_SLAVE_WR_CMPLT_EVENT	Indicates the master completed writing to the slave (set by the master Stop or Restart)
CYHAL_I2C_SLAVE_ERR_EVENT	Indicates the I2C hardware detected an error.
CYHAL_I2C_MASTER_WR_IN_FIFO_EVENT	All data specified by cyhal_i2c_master_transfer_async has been loaded into the TX FIFO.
CYHAL_I2C_MASTER_WR_CMPLT_EVENT	The master write started by cyhal_i2c_master_transfer_async is complete.
CYHAL_I2C_MASTER_RD_CMPLT_EVENT	The master read started by cyhal_i2c_master_transfer_async is complete.
CYHAL_I2C_MASTER_ERR_EVENT	Indicates the I2C hardware has detected an error.

cyhal_i2c_addr_event_t

enum cyhal_i2c_addr_event_t

Enum to enable/disable/report address interrupt cause flags.

Enumerator
CYHAL_I2C_ADDR_EVENT_NONE	No event.
CYHAL_I2C_GENERAL_CALL_EVENT	Indicates the slave was addressed by the general call address.
CYHAL_I2C_ADDR_MATCH_EVENT	Indicates the slave matching address received.

cyhal_i2c_fifo_type_t

enum cyhal_i2c_fifo_type_t

I2C FIFO type.

Enumerator
CYHAL_I2C_FIFO_RX	Set RX FIFO level.
CYHAL_I2C_FIFO_TX	Set TX FIFO level.

cyhal_i2c_command_rsp_t

enum cyhal_i2c_command_rsp_t

I2C Command ACK / NAK.

Enumerator
CYHAL_I2C_CMD_ACK	Send ACK to current byte.
CYHAL_I2C_CMD_NAK	Send NAK to current byte.

cyhal_i2c_output_t

enum cyhal_i2c_output_t

Enum of possible output signals from an I2C.

Enumerator
CYHAL_I2C_OUTPUT_TRIGGER_RX_FIFO_LEVEL_REACHED	Output the RX FIFO signal which is triggered when the receive FIFO has more entries than the configured level.
CYHAL_I2C_OUTPUT_TRIGGER_TX_FIFO_LEVEL_REACHED	Output the TX FIFO signal which is triggered when the transmit FIFO has less entries than the configured level.

Function Documentation

cyhal_i2c_init()

cy_rslt_t cyhal_i2c_init	(	cyhal_i2c_t *	obj,
		cyhal_gpio_t	sda,
		cyhal_gpio_t	scl,
		const cyhal_clock_t *	clk
	)

Initialize the I2C peripheral, and configures its specified pins.

By default it is configured as a Master with a bus frequency = CYHAL_I2C_MASTER_DEFAULT_FREQ. Use cyhal_i2c_configure() to change the default behavior.
NOTE: Master/Slave specific functions only work when the block is configured to be in that mode.
See Snippet 1: I2C Initialization and Configuration

Parameters

[out]	obj	Pointer to an I2C object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	sda	The sda pin
[in]	scl	The scl pin
[in]	clk	The clock to use can be shared, if not provided a new clock will be allocated

Returns

The status of the init request

cyhal_i2c_free()

void cyhal_i2c_free

(

cyhal_i2c_t *

obj

)

Deinitialize the i2c object.

Parameters

[in,out]

obj

The i2c object

cyhal_i2c_configure()

cy_rslt_t cyhal_i2c_configure	(	cyhal_i2c_t *	obj,
		const cyhal_i2c_cfg_t *	cfg
	)

Configure the I2C block.

NOTE: Master/Slave specific functions only work when the block is configured to be in that mode.
See Snippet 1: I2C Initialization and Configuration

Parameters

[in]	obj	The I2C object
[in]	cfg	Configuration settings to apply

Returns

The status of the configure request

cyhal_i2c_configure_adv()

cy_rslt_t cyhal_i2c_configure_adv	(	cyhal_i2c_t *	obj,
		const cyhal_i2c_adv_cfg_t *	cfg
	)

Configure the I2C block with advanced parameters.

Refer to cyhal_i2c_adv_cfg_t structure for the description of advanced parameters. NOTE: Master/Slave specific functions only work when the block is configured to be in that mode.
See Snippet 1: I2C Initialization and Configuration

Parameters

[in]	obj	The I2C object
[in]	cfg	Advanced configuration settings to apply

Returns

The status of the configure request

cyhal_i2c_master_write()

cy_rslt_t cyhal_i2c_master_write	(	cyhal_i2c_t *	obj,
		uint16_t	dev_addr,
		const uint8_t *	data,
		uint16_t	size,
		uint32_t	timeout,
		bool	send_stop
	)

I2C master blocking write.

This will write size bytes of data from the buffer pointed to by data. It will not return until either all of the data has been written, or the timeout has elapsed.

Parameters

[in]	obj	The I2C object
[in]	dev_addr	device address (7-bit)
[in]	data	I2C send data
[in]	size	I2C send data size
[in]	timeout	timeout in millisecond, set this value to 0 if you want to wait forever
[in]	send_stop	whether the stop should be send, used to support repeat start conditions

Returns

The status of the master_write request

cyhal_i2c_master_read()

cy_rslt_t cyhal_i2c_master_read	(	cyhal_i2c_t *	obj,
		uint16_t	dev_addr,
		uint8_t *	data,
		uint16_t	size,
		uint32_t	timeout,
		bool	send_stop
	)

I2C master blocking read.

This will read size bytes of data into the buffer pointed to by data. It will not return until either all of the data has been read, or the timeout has elapsed.

Parameters

[in]	obj	The I2C object
[in]	dev_addr	device address (7-bit)
[out]	data	I2C receive data
[in]	size	I2C receive data size
[in]	timeout	timeout in millisecond, set this value to 0 if you want to wait forever
[in]	send_stop	whether the stop should be send, used to support repeat start conditions

Returns

The status of the master_read request

cyhal_i2c_slave_config_write_buffer()

cy_rslt_t cyhal_i2c_slave_config_write_buffer	(	cyhal_i2c_t *	obj,
		const uint8_t *	data,
		uint16_t	size
	)

The function configures the write buffer on an I2C Slave.

This is the buffer to which the master writes data to. The user needs to setup a new buffer every time (i.e. call cyhal_i2c_slave_config_write_buffer and cyhal_i2c_slave_config_read_buffer every time the buffer has been used up)
See related code example: PSoC™ 6 MCU: I2C Master

Parameters

[in]	obj	The I2C object
[in]	data	I2C slave send data
[in]	size	I2C slave send data size

Returns

The status of the slave_config_write_buffer request

cyhal_i2c_slave_config_read_buffer()

cy_rslt_t cyhal_i2c_slave_config_read_buffer	(	cyhal_i2c_t *	obj,
		uint8_t *	data,
		uint16_t	size
	)

The function configures the read buffer on an I2C Slave.

This is the buffer from which the master reads data from. The user needs to setup a new buffer every time (i.e. call cyhal_i2c_slave_config_write_buffer and cyhal_i2c_slave_config_read_buffer every time the buffer has been used up)
See related code example: PSoC™ 6 MCU: I2C Master

Parameters

[in]	obj	The I2C object
[out]	data	I2C slave receive data
[in]	size	I2C slave receive data size

Returns

The status of the slave_config_read_buffer request

cyhal_i2c_master_mem_write()

cy_rslt_t cyhal_i2c_master_mem_write	(	cyhal_i2c_t *	obj,
		uint16_t	address,
		uint16_t	mem_addr,
		uint16_t	mem_addr_size,
		const uint8_t *	data,
		uint16_t	size,
		uint32_t	timeout
	)

Perform an I2C write using a block of data stored at the specified memory location.

Parameters

[in]	obj	The I2C object
[in]	address	device address (7-bit)
[in]	mem_addr	mem address to store the written data
[in]	mem_addr_size	number of bytes in the mem address
[in]	data	I2C master send data
[in]	size	I2C master send data size
[in]	timeout	timeout in millisecond, set this value to 0 if you want to wait forever

Returns

The status of the write request

cyhal_i2c_master_mem_read()

cy_rslt_t cyhal_i2c_master_mem_read	(	cyhal_i2c_t *	obj,
		uint16_t	address,
		uint16_t	mem_addr,
		uint16_t	mem_addr_size,
		uint8_t *	data,
		uint16_t	size,
		uint32_t	timeout
	)

Perform an I2C read using a block of data stored at the specified memory location.

Parameters

[in]	obj	The I2C object
[in]	address	device address (7-bit)
[in]	mem_addr	mem address to read the data from
[in]	mem_addr_size	number of bytes in the mem address
[out]	data	I2C master receive data
[in]	size	I2C master receive data size
[in]	timeout	timeout in millisecond, set this value to 0 if you want to wait forever

Returns

The status of the read request

cyhal_i2c_master_transfer_async()

cy_rslt_t cyhal_i2c_master_transfer_async	(	cyhal_i2c_t *	obj,
		uint16_t	address,
		const void *	tx,
		size_t	tx_size,
		void *	rx,
		size_t	rx_size
	)

Initiate a non-blocking I2C master asynchronous transfer.

Supports simultaneous write and read operation.

This will transfer rx_size bytes into the buffer pointed to by rx, while simultaneously transfering tx_size bytes of data from the buffer pointed to by tx, both in the background. When the requested quantity of data has been received, the CYHAL_I2C_MASTER_RD_CMPLT_EVENT will be raised. When the requested quantity of data has been transmitted, the CYHAL_I2C_MASTER_WR_CMPLT_EVENT will be raised. See cyhal_i2c_register_callback and cyhal_i2c_enable_event. If either of tx_size or rx_size is '0', the respective write or read operation is not performed. See Snippet 3: I2C Master Asynchronous Transfer

Parameters

[in]	obj	The I2C object
[in]	address	device address (7-bit)
[in]	tx	The transmit buffer
[in]	tx_size	The number of bytes to transmit. Use '0' if write operation is not required.
[out]	rx	The receive buffer
[in]	rx_size	The number of bytes to receive. Use '0' if read operation is not required.

Returns

The status of the master_transfer_async request

cyhal_i2c_abort_async()

cy_rslt_t cyhal_i2c_abort_async

(

cyhal_i2c_t *

obj

)

Abort asynchronous transfer.

This function aborts the ongoing transfer by generating a stop condition.
See Snippet 3: I2C Master Asynchronous Transfer

Parameters

[in]

obj

The I2C object

Returns

The status of the abort_async request

cyhal_i2c_register_callback()

void cyhal_i2c_register_callback	(	cyhal_i2c_t *	obj,
		cyhal_i2c_event_callback_t	callback,
		void *	callback_arg
	)

Register an I2C event callback handler

This function will be called when one of the events enabled by cyhal_i2c_enable_event occurs.

See Snippet 2: Handling events

Parameters

[in]	obj	The I2C object
[in]	callback	The callback handler which will be invoked when an event triggers
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_i2c_register_address_callback()

void cyhal_i2c_register_address_callback	(	cyhal_i2c_t *	obj,
		cyhal_i2c_address_callback_t	callback,
		void *	callback_arg
	)

Register an I2C address callback handler

This function will be called when one of the events enabled by cyhal_i2c_enable_address_event occurs. NOTE: This function will not have an effect if enable_address_callback parameter of cyhal_i2c_adv_cfg_t structure was false when cyhal_i2c_configure_adv was called.

See Snippet 2: Handling events

Parameters

[in]	obj	The I2C object
[in]	callback	The callback handler which will be invoked when an event triggers
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_i2c_enable_event()

void cyhal_i2c_enable_event	(	cyhal_i2c_t *	obj,
		cyhal_i2c_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure and Enable or Disable I2C Interrupt.

When an enabled event occurs, the function specified by cyhal_i2c_register_callback will be called.

See Snippet 2: Handling events

Parameters

[in]	obj	The I2C object
[in]	event	The I2C event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off

cyhal_i2c_enable_address_event()

void cyhal_i2c_enable_address_event	(	cyhal_i2c_t *	obj,
		cyhal_i2c_addr_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure and Enable or Disable I2C Address Interrupt.

When an enabled event occurs, the function specified by cyhal_i2c_register_address_callback will be called.

See Snippet 2: Handling events

Parameters

[in]	obj	The I2C object
[in]	event	The I2C address event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off

cyhal_i2c_set_fifo_level()

cy_rslt_t cyhal_i2c_set_fifo_level	(	cyhal_i2c_t *	obj,
		cyhal_i2c_fifo_type_t	type,
		uint16_t	level
	)

Sets a threshold level for a FIFO that will generate an interrupt and a trigger output.

The RX FIFO interrupt and trigger will be activated when the receive FIFO has more entries than the threshold. The TX FIFO interrupt and trigger will be activated when the transmit FIFO has less entries than the threshold.

Parameters

[in]	obj	The I2C object
[in]	type	FIFO type to set level for
[in]	level	Level threshold to set

Returns

The status of the level set

cyhal_i2c_enable_output()

cy_rslt_t cyhal_i2c_enable_output	(	cyhal_i2c_t *	obj,
		cyhal_i2c_output_t	output,
		cyhal_source_t *	source
	)

Enables the specified output signal from an I2C.

Parameters

[in]	obj	The I2C object
[in]	output	Which output signal to enable
[out]	source	Pointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.

Returns

The status of the output enable

cyhal_i2c_disable_output()

cy_rslt_t cyhal_i2c_disable_output	(	cyhal_i2c_t *	obj,
		cyhal_i2c_output_t	output
	)

Disables the specified output signal from an I2C.

Parameters

[in]	obj	The I2C object
[in]	output	Which output signal to disable

Returns

The status of the output disable

cyhal_i2c_init_cfg()

cy_rslt_t cyhal_i2c_init_cfg	(	cyhal_i2c_t *	obj,
		const cyhal_i2c_configurator_t *	cfg
	)

Initialize the I2C peripheral using a configurator generated configuration struct.

Parameters

[in]	obj	The I2C peripheral to configure
[in]	cfg	Configuration structure generated by a configurator.

Returns

The status of the operation

cyhal_i2c_slave_readable()

uint32_t cyhal_i2c_slave_readable

(

cyhal_i2c_t *

obj

)

Returns the number of bytes written by the I2C master.

Calling the cyhal_i2c_slave_config_write_buffer API will clear the counter of bytes sent by master

Parameters

[in]

obj

The I2C object

Returns

The number of bytes written by the I2C master.

cyhal_i2c_slave_writable()

uint32_t cyhal_i2c_slave_writable

(

cyhal_i2c_t *

obj

)

Returns the number of bytes can be read by the I2C master.

Calling the cyhal_i2c_slave_config_read_buffer API will clear the counter of bytes read by master

Parameters

[in]

obj

The I2C object

Returns

The number of bytes can be read by the I2C master.

cyhal_i2c_slave_read()

cy_rslt_t cyhal_i2c_slave_read	(	cyhal_i2c_t *	obj,
		uint8_t *	dst_buff,
		uint16_t *	size,
		uint32_t	timeout
	)

Wait for master send data to RX buffer and store them to the user-defined buffer.

NOTE: If size of actual data is less then expected the function copy only available data.

Parameters

[in]	obj	The I2C object
[in]	dst_buff	Pointer on memory to store the data from the slave RX buffer.
[in,out]	size	[in] The number of bytes to read, [out] number actually read.
[in]	timeout	Timeout in millisecond, set this value to 0 if you don't want to wait at all.

Returns

The status of the read request

cyhal_i2c_slave_write()

cy_rslt_t cyhal_i2c_slave_write	(	cyhal_i2c_t *	obj,
		const uint8_t *	src_buff,
		uint16_t *	size,
		uint32_t	timeout
	)

Write data from the user-defined buffer to I2C TX buffer.

NOTE: If size of actual data is less then expected the function copy only available data.

Parameters

[in]	obj	The I2C object
[in]	src_buff	Pointer on memory to copy the data to the slave TX buffer.
[in,out]	size	[in] The number of bytes to send, [out] number actually sent.
[in]	timeout	Timeout in millisecond, set this value to 0 if you don't want to wait at all.

Returns

The status of the write request

cyhal_i2c_slave_abort_read()

cy_rslt_t cyhal_i2c_slave_abort_read

(

cyhal_i2c_t *

obj

)

The function aborts the configured slave read buffer to be read by the master.

If the master reads and "abort operation" is requested, the CYHAL_I2C_SLAVE_RD_BUF_EMPTY_EVENT event occurs.

Parameters

[in]

obj

The I2C object

Returns

The status of the slave_abort_read request

cyhal_i2c_clear()

cy_rslt_t cyhal_i2c_clear

(

cyhal_i2c_t *

obj

)

Clear the I2C buffers.

Parameters

[in]

obj

The I2C object

Returns

The status of the clear request