PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Data Structures | Macros | Typedefs | Enumerations | Functions
I2C (Inter-Integrated Circuit)
HAL API Reference » HAL Drivers

## General Description

High level interface for interacting with the I2C resource.

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

# Features

- Controller or target functionality
- Configurable target address
- Configurable data rates
- Configurable interrupt and callback assignment from I2C events - mtb_hal_i2c_event_t

# Quick Start

Configure the behavior (controller/target) and the interface (bus frequency, target address) using the mtb_hal_i2c_configure function.
See Snippet 1: I2C Initialization and Configuration for example initialization as controller or target.

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

# Code Snippets

## Snippet 1: I2C Initialization and Configuration

This snippet initializes an I2C resource as controller or target and assigns the sda and scl pins.

Initializing as I2C controller

// Declare variables
cy_rslt_t rslt;
mtb_hal_i2c_t i2c_controller_obj;
// Define frequency
uint32_t I2C_CONTROLLER_FREQUENCY = 100000u;
// Define the I2C controller dev_config_struct structure
mtb_hal_i2c_cfg_t i2c_controller_config =
{
MTB_HAL_I2C_MODE_CONTROLLER,
0, // address is not used for controller mode
I2C_CONTROLLER_FREQUENCY,
MTB_HAL_I2C_DEFAULT_ADDR_MASK,
false,
};
rslt = mtb_hal_i2c_setup(&i2c_controller_obj, &dev_config_struct, &context, &i2c_clock);
// Configure the I2C resource to be controller
rslt = mtb_hal_i2c_configure(&i2c_controller_obj, &i2c_controller_config);
mtb_hal_i2c_configure
cy_rslt_t mtb_hal_i2c_configure(mtb_hal_i2c_t *obj, const mtb_hal_i2c_cfg_t *cfg)
Configure the I2C block.
Definition: mtb_hal_i2c.c:346
MTB_HAL_I2C_DEFAULT_ADDR_MASK
#define MTB_HAL_I2C_DEFAULT_ADDR_MASK
Named define for default address mask for use when initializing the mtb_hal_i2c_cfg_t structure.
Definition: mtb_hal_i2c.h:141
MTB_HAL_I2C_MODE_CONTROLLER
#define MTB_HAL_I2C_MODE_CONTROLLER
Named define for Controller mode for use when initializing the mtb_hal_i2c_cfg_t structure.
Definition: mtb_hal_i2c.h:138
mtb_hal_i2c_cfg_t
I2C configuration.
Definition: mtb_hal_i2c.h:236
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
mtb_hal_i2c_t
I2C object.
Definition: mtb_hal_hw_types_i2c_scb.h:88

Initializing as I2C target

// Declare variables
cy_rslt_t rslt;
mtb_hal_i2c_t i2c_target_obj;
// Define address
uint16_t I2C_TARGET_ADDRESS = 0x08u;
// Define address mask
uint16_t I2C_TARGET_ADDRESS_MASK = 0xFEu;
// Define frequency
uint32_t I2C_TARGET_FREQUENCY = 100000u;
// Define address is in FIFO or not
bool I2C_ENABLE_ADDRESS_EVENT = false;
// Define the target dev_config_struct structure
mtb_hal_i2c_cfg_t i2c_target_config =
{ MTB_HAL_I2C_MODE_TARGET, I2C_TARGET_ADDRESS, I2C_TARGET_FREQUENCY,
I2C_TARGET_ADDRESS_MASK,
I2C_ENABLE_ADDRESS_EVENT };
rslt = mtb_hal_i2c_setup(&i2c_target_obj, &dev_config_struct, &context, &i2c_clock);
// Configure the I2C resource to be target
rslt = mtb_hal_i2c_configure(&i2c_target_obj, &i2c_target_config);
MTB_HAL_I2C_MODE_TARGET
#define MTB_HAL_I2C_MODE_TARGET
Named define for Target mode for use when initializing the mtb_hal_i2c_cfg_t structure.
Definition: mtb_hal_i2c.h:135

## Snippet 2: Handling events

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

void handle_i2c_events(void* callback_arg, mtb_hal_i2c_event_t event)
{
// To remove unused variable warning
(void)callback_arg;
// Check write complete event
if (0UL != (MTB_HAL_I2C_TARGET_WR_CMPLT_EVENT & event))
{
// Perform the required functions
}
// Check read complete event
if (0UL != (MTB_HAL_I2C_TARGET_RD_CMPLT_EVENT & event))
{
// Perform the required functions
}
// Check for errors
if (0UL == (MTB_HAL_I2C_TARGET_ERR_EVENT & event))
{
// Perform the required function
}
}
mtb_hal_i2c_command_rsp_t handle_i2c_address_events(void* callback_arg,
mtb_hal_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 != (MTB_HAL_I2C_GENERAL_CALL_EVENT & event))
{
// Perform the required functions
}
// Check read complete event
if (0UL != (MTB_HAL_I2C_ADDR_MATCH_EVENT & event))
{
// Perform the required functions
}
return MTB_HAL_I2C_CMD_ACK;
}
mtb_hal_i2c_command_rsp_t handle_i2c_byte_callback_event(void* arg, uint8_t byte_received)
{
/* Set up to ACK only when byte_received is as expected */
if (byte_received == *(uint8_t*)arg)
{
return MTB_HAL_I2C_CMD_ACK;
}
else
{
return MTB_HAL_I2C_CMD_NAK;
}
}
cy_rslt_t snippet_mtb_hal_i2c_target_callback_init(void)
{
// Declare variables
cy_rslt_t rslt;
mtb_hal_i2c_t i2c_target_obj;
uint8_t expected_rx_arg = 0x08u;
// Define the target dev_config_struct structure
mtb_hal_i2c_cfg_t i2c_target_config =
{ MTB_HAL_I2C_MODE_TARGET, 0x08u, 100000u, MTB_HAL_I2C_DEFAULT_ADDR_MASK, false };
rslt = mtb_hal_i2c_setup(&i2c_target_obj, &dev_config_struct, &context, &i2c_clock);
// Configure the I2C resource to be target
if (CY_RSLT_SUCCESS == rslt)
{
rslt = mtb_hal_i2c_configure(&i2c_target_obj, &i2c_target_config);
}
// Set up the interrupt vector before enabling events.
// Call mtb_hal_i2c_process_interrupt(&i2c_target_obj) in the interrupt handler.
if (CY_RSLT_SUCCESS == rslt)
{
// Register I2C target event callback
mtb_hal_i2c_register_callback(&i2c_target_obj,
(mtb_hal_i2c_event_callback_t)handle_i2c_events,
NULL);
// Enable I2C Events
mtb_hal_i2c_enable_event(&i2c_target_obj, (mtb_hal_i2c_event_t) \
(MTB_HAL_I2C_TARGET_WR_CMPLT_EVENT \
| MTB_HAL_I2C_TARGET_RD_CMPLT_EVENT \
| MTB_HAL_I2C_TARGET_ERR_EVENT), \
true);
// Register I2C target address callback
mtb_hal_i2c_register_address_callback(&i2c_target_obj,
(mtb_hal_i2c_address_callback_t)handle_i2c_address_events,
NULL);
// Enable I2C Address Events
mtb_hal_i2c_enable_address_event(&i2c_target_obj, (mtb_hal_i2c_addr_event_t) \
(MTB_HAL_I2C_ADDR_MATCH_EVENT), \
true);
// Register byte received callback
mtb_hal_i2c_register_byte_received_callback(&i2c_target_obj, handle_i2c_byte_callback_event,
(void*)&expected_rx_arg);
}
return rslt;
}
mtb_hal_i2c_address_callback_t
mtb_hal_i2c_command_rsp_t(* mtb_hal_i2c_address_callback_t)(void *callback_arg, mtb_hal_i2c_addr_event_t event, uint8_t address)
Handler for I2C address events.
Definition: mtb_hal_i2c.h:227
mtb_hal_i2c_event_callback_t
void(* mtb_hal_i2c_event_callback_t)(void *callback_arg, mtb_hal_i2c_event_t event)
Handler for I2C events.
Definition: mtb_hal_i2c.h:225
mtb_hal_i2c_enable_event
void mtb_hal_i2c_enable_event(mtb_hal_i2c_t *obj, mtb_hal_i2c_event_t event, bool enable)
Configure and Enable or Disable I2C Interrupt.
Definition: mtb_hal_i2c.c:673
mtb_hal_i2c_register_callback
void mtb_hal_i2c_register_callback(mtb_hal_i2c_t *obj, mtb_hal_i2c_event_callback_t callback, void *callback_arg)
Register an I2C event callback handler
Definition: mtb_hal_i2c.c:616
mtb_hal_i2c_register_byte_received_callback
void mtb_hal_i2c_register_byte_received_callback(mtb_hal_i2c_t *obj, mtb_hal_i2c_byte_callback_t callback, void *callback_arg)
Register an I2C byte received callback handler
Definition: mtb_hal_i2c.c:645
mtb_hal_i2c_enable_address_event
void mtb_hal_i2c_enable_address_event(mtb_hal_i2c_t *obj, mtb_hal_i2c_addr_event_t event, bool enable)
Configure and Enable or Disable I2C Address Interrupt.
Definition: mtb_hal_i2c.c:689
mtb_hal_i2c_event_t
mtb_hal_i2c_event_t
I2C enum to enable/disable/report event cause flags.
Definition: mtb_hal_i2c.h:145
mtb_hal_i2c_command_rsp_t
mtb_hal_i2c_command_rsp_t
I2C Command ACK / NAK.
Definition: mtb_hal_i2c.h:208
mtb_hal_i2c_register_address_callback
void mtb_hal_i2c_register_address_callback(mtb_hal_i2c_t *obj, mtb_hal_i2c_address_callback_t callback, void *callback_arg)
Register an I2C address callback handler
Definition: mtb_hal_i2c.c:630
mtb_hal_i2c_addr_event_t
mtb_hal_i2c_addr_event_t
I2C enum to enable/disable/report address interrupt cause flags.
Definition: mtb_hal_i2c.h:190
MTB_HAL_I2C_TARGET_WR_CMPLT_EVENT
@ MTB_HAL_I2C_TARGET_WR_CMPLT_EVENT
Indicates the controller completed writing to the target (set by the controller Stop or Restart)
Definition: mtb_hal_i2c.h:161
MTB_HAL_I2C_TARGET_ERR_EVENT
@ MTB_HAL_I2C_TARGET_ERR_EVENT
Indicates the I2C target detected an error.
Definition: mtb_hal_i2c.h:163
MTB_HAL_I2C_TARGET_RD_CMPLT_EVENT
@ MTB_HAL_I2C_TARGET_RD_CMPLT_EVENT
Indicates the controller completed reading from the target (set by the controller NAK or Stop)
Definition: mtb_hal_i2c.h:158
MTB_HAL_I2C_CMD_ACK
@ MTB_HAL_I2C_CMD_ACK
Send ACK to current byte.
Definition: mtb_hal_i2c.h:209
MTB_HAL_I2C_CMD_NAK
@ MTB_HAL_I2C_CMD_NAK
Send NAK to current byte.
Definition: mtb_hal_i2c.h:210
MTB_HAL_I2C_GENERAL_CALL_EVENT
@ MTB_HAL_I2C_GENERAL_CALL_EVENT
Indicates the target was addressed by the general call address.
Definition: mtb_hal_i2c.h:194
MTB_HAL_I2C_ADDR_MATCH_EVENT
@ MTB_HAL_I2C_ADDR_MATCH_EVENT
Indicates the target matching address received.
Definition: mtb_hal_i2c.h:196
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486

# More Information

Peripheral Driver Library (PDL)

- PSOC™ 6 PDL: SCB (Serial Communication Block)

Code examples (Github)

- PSOC™ 6 MCU: I2C Controller
- PSOC™ 6 MCU: I2C Target Using Callbacks

## API Reference
| I2C HAL Results
| I2C specific return codes.

## Data Structures
struct | mtb_hal_i2c_cfg_t
| I2C configuration. More...

## Macros
#define | MTB_HAL_I2C_MODE_TARGET (true)
| Named define for Target mode for use when initializing the mtb_hal_i2c_cfg_t structure.
#define | MTB_HAL_I2C_MODE_CONTROLLER (false)
| Named define for Controller mode for use when initializing the mtb_hal_i2c_cfg_t structure.
#define | MTB_HAL_I2C_DEFAULT_ADDR_MASK (0xFE)
| Named define for default address mask for use when initializing the mtb_hal_i2c_cfg_t structure.

## Typedefs
typedef void(* | mtb_hal_i2c_event_callback_t) (void *callback_arg, mtb_hal_i2c_event_t event)
| Handler for I2C events.
typedef mtb_hal_i2c_command_rsp_t(* | mtb_hal_i2c_address_callback_t) (void *callback_arg, mtb_hal_i2c_addr_event_t event, uint8_t address)
| Handler for I2C address events.
typedef mtb_hal_i2c_command_rsp_t(* | mtb_hal_i2c_byte_callback_t) (void *callback_arg, uint8_t byte_received)
| Handler for I2C byte received events.

## Enumerations
enum | mtb_hal_i2c_event_t { MTB_HAL_I2C_EVENT_NONE = 0 , MTB_HAL_I2C_TARGET_READ_EVENT = (MTB_HAL_MAP_I2C_TARGET_READ_EVENT) , MTB_HAL_I2C_TARGET_WRITE_EVENT = (MTB_HAL_MAP_I2C_TARGET_WRITE_EVENT) , MTB_HAL_I2C_TARGET_RD_IN_FIFO_EVENT = (MTB_HAL_MAP_I2C_TARGET_RD_IN_FIFO_EVENT) , MTB_HAL_I2C_TARGET_RD_BUF_EMPTY_EVENT = (MTB_HAL_MAP_I2C_TARGET_RD_BUF_EMPTY_EVENT) , MTB_HAL_I2C_TARGET_RD_CMPLT_EVENT = (MTB_HAL_MAP_I2C_TARGET_RD_CMPLT_EVENT) , MTB_HAL_I2C_TARGET_WR_CMPLT_EVENT = (MTB_HAL_MAP_I2C_TARGET_WR_CMPLT_EVENT) , MTB_HAL_I2C_TARGET_ERR_EVENT = (MTB_HAL_MAP_I2C_TARGET_ERR_EVENT) , MTB_HAL_I2C_TARGET_RESTART_EVENT = (MTB_HAL_MAP_I2C_TARGET_RESTART_EVENT) , MTB_HAL_I2C_TARGET_STOP_EVENT = (MTB_HAL_MAP_I2C_TARGET_STOP_EVENT) , MTB_HAL_I2C_TARGET_ARB_LOST_EVENT = (MTB_HAL_MAP_I2C_TARGET_ARB_LOST_EVENT) , MTB_HAL_I2C_TARGET_TIMEOUT0_EVENT = (MTB_HAL_MAP_I2C_TARGET_TIMEOUT0_EVENT) , MTB_HAL_I2C_TARGET_TIMEOUT1_EVENT = (MTB_HAL_MAP_I2C_TARGET_TIMEOUT1_EVENT) , MTB_HAL_I2C_TARGET_TIMEOUT2_EVENT = (MTB_HAL_MAP_I2C_TARGET_TIMEOUT2_EVENT) , MTB_HAL_I2C_CONTROLLER_ERR_EVENT = (MTB_HAL_MAP_I2C_CONTROLLER_ERR_EVENT) , MTB_HAL_I2C_CONTROLLER_ARB_LOST_EVENT = (MTB_HAL_MAP_I2C_CONTROLLER_ARB_LOST_EVENT) , MTB_HAL_I2C_CONTROLLER_TIMEOUT0_EVENT = (MTB_HAL_MAP_I2C_CONTROLLER_TIMEOUT0_EVENT) , MTB_HAL_I2C_CONTROLLER_TIMEOUT1_EVENT = (MTB_HAL_MAP_I2C_CONTROLLER_TIMEOUT1_EVENT) , MTB_HAL_I2C_CONTROLLER_TIMEOUT2_EVENT = (MTB_HAL_MAP_I2C_CONTROLLER_TIMEOUT2_EVENT) }
| I2C enum to enable/disable/report event cause flags. More...
enum | mtb_hal_i2c_addr_event_t { MTB_HAL_I2C_ADDR_EVENT_NONE = 0 , MTB_HAL_I2C_GENERAL_CALL_EVENT = (MTB_HAL_MAP_I2C_GENERAL_CALL_EVENT) , MTB_HAL_I2C_ADDR_MATCH_EVENT = (MTB_HAL_MAP_I2C_ADDR_IN_FIFO_EVENT) }
| I2C enum to enable/disable/report address interrupt cause flags. More...
enum | mtb_hal_i2c_fifo_type_t { MTB_HAL_I2C_FIFO_RX , MTB_HAL_I2C_FIFO_TX }
| I2C FIFO type. More...
enum | mtb_hal_i2c_command_rsp_t { MTB_HAL_I2C_CMD_ACK , MTB_HAL_I2C_CMD_NAK }
| I2C Command ACK / NAK. More...
enum | mtb_hal_i2c_output_t { MTB_HAL_I2C_OUTPUT_TRIGGER_RX_FIFO_LEVEL_REACHED , MTB_HAL_I2C_OUTPUT_TRIGGER_TX_FIFO_LEVEL_REACHED }
| Enum of possible output signals from an I2C. More...

## Functions
cy_rslt_t | mtb_hal_i2c_configure (mtb_hal_i2c_t *obj, const mtb_hal_i2c_cfg_t *cfg)
| Configure the I2C block. More...
cy_rslt_t | mtb_hal_i2c_controller_write (mtb_hal_i2c_t *obj, uint16_t dev_addr, const uint8_t *data, uint16_t size, uint32_t timeout, bool send_stop)
| I2C controller blocking write. More...
cy_rslt_t | mtb_hal_i2c_controller_read (mtb_hal_i2c_t *obj, uint16_t dev_addr, uint8_t *data, uint16_t size, uint32_t timeout, bool send_stop)
| I2C controller blocking read. More...
cy_rslt_t | mtb_hal_i2c_target_config_read_buffer (mtb_hal_i2c_t *obj, const uint8_t *data, uint16_t size)
| The function configures the read buffer on an I2C Target. More...
cy_rslt_t | mtb_hal_i2c_target_config_write_buffer (mtb_hal_i2c_t *obj, uint8_t *data, uint16_t size)
| The function configures the write buffer on an I2C Target. More...
void | mtb_hal_i2c_register_callback (mtb_hal_i2c_t *obj, mtb_hal_i2c_event_callback_t callback, void *callback_arg)
| Register an I2C event callback handler More...
void | mtb_hal_i2c_register_address_callback (mtb_hal_i2c_t *obj, mtb_hal_i2c_address_callback_t callback, void *callback_arg)
| Register an I2C address callback handler More...
void | mtb_hal_i2c_register_byte_received_callback (mtb_hal_i2c_t *obj, mtb_hal_i2c_byte_callback_t callback, void *callback_arg)
| Register an I2C byte received callback handler More...
void | mtb_hal_i2c_enable_event (mtb_hal_i2c_t *obj, mtb_hal_i2c_event_t event, bool enable)
| Configure and Enable or Disable I2C Interrupt. More...
void | mtb_hal_i2c_enable_address_event (mtb_hal_i2c_t *obj, mtb_hal_i2c_addr_event_t event, bool enable)
| Configure and Enable or Disable I2C Address Interrupt. More...
uint32_t | mtb_hal_i2c_target_readable (mtb_hal_i2c_t *obj)
| Returns the number of bytes written by the I2C controller. More...
uint32_t | mtb_hal_i2c_target_writable (mtb_hal_i2c_t *obj)
| Returns the number of bytes can be read by the I2C controller. More...
cy_rslt_t | mtb_hal_i2c_target_read (mtb_hal_i2c_t *obj, uint8_t *dst_buff, uint16_t *size, uint32_t timeout)
| Wait for controller send data to RX buffer and store them to the user-defined buffer. More...
cy_rslt_t | mtb_hal_i2c_target_write (mtb_hal_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 | mtb_hal_i2c_target_abort_read (mtb_hal_i2c_t *obj)
| The function aborts the configured target read buffer to be read by the controller. More...
cy_rslt_t | mtb_hal_i2c_clear (mtb_hal_i2c_t *obj)
| Clear the I2C buffers. More...
cy_rslt_t | mtb_hal_i2c_process_interrupt (mtb_hal_i2c_t *obj)
| Process interrupts related related to an I2C instance. More...

## Data Structure Documentation

## ◆ mtb_hal_i2c_cfg_t

struct mtb_hal_i2c_cfg_t

Data Fields
bool | is_target | Operates as a target when set to (true), else as a controller (false).
uint16_t | address | Address of this target resource (7-bit), should be set to 0 for controller.
uint32_t | frequency_hz | Frequency that the I2C bus runs at (I2C data rate in bits per second)
uint8_t | address_mask | Mask of the target resource. Not applicable for the controller.
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

## ◆ mtb_hal_i2c_event_t

enum mtb_hal_i2c_event_t

I2C enum to enable/disable/report event cause flags.

Enumerator
MTB_HAL_I2C_EVENT_NONE | No event.
MTB_HAL_I2C_TARGET_READ_EVENT | Indicates that the target was addressed and the controller wants to read data.
MTB_HAL_I2C_TARGET_WRITE_EVENT | Indicates that the target was addressed and the controller wants to write data.
MTB_HAL_I2C_TARGET_RD_IN_FIFO_EVENT | All target data from the configured Read buffer has been loaded into the TX FIFO.
MTB_HAL_I2C_TARGET_RD_BUF_EMPTY_EVENT | The controller has read all data out of the configured Read buffer.
MTB_HAL_I2C_TARGET_RD_CMPLT_EVENT | Indicates the controller completed reading from the target (set by the controller NAK or Stop)
MTB_HAL_I2C_TARGET_WR_CMPLT_EVENT | Indicates the controller completed writing to the target (set by the controller Stop or Restart)
MTB_HAL_I2C_TARGET_ERR_EVENT | Indicates the I2C target detected an error.
MTB_HAL_I2C_TARGET_RESTART_EVENT | Indicates that the target received a restart bit.
MTB_HAL_I2C_TARGET_STOP_EVENT | Indicates that the target received a stop bit.
MTB_HAL_I2C_TARGET_ARB_LOST_EVENT | Indicates that the target detected an arbitration lost event.
MTB_HAL_I2C_TARGET_TIMEOUT0_EVENT | Indicates that the target detected a timeout from counter 0.
MTB_HAL_I2C_TARGET_TIMEOUT1_EVENT | Indicates that the target detected a timeout from counter 1.
MTB_HAL_I2C_TARGET_TIMEOUT2_EVENT | Indicates that the target detected a timeout from counter 2.
MTB_HAL_I2C_CONTROLLER_ERR_EVENT | Indicates the I2C controller detected an error.
MTB_HAL_I2C_CONTROLLER_ARB_LOST_EVENT | Indicates that the controller detected an arbitration lost event.
MTB_HAL_I2C_CONTROLLER_TIMEOUT0_EVENT | Indicates that the controller detected a timeout from counter 0.
MTB_HAL_I2C_CONTROLLER_TIMEOUT1_EVENT | Indicates that the controller detected a timeout from counter 1.
MTB_HAL_I2C_CONTROLLER_TIMEOUT2_EVENT | Indicates that the controller detected a timeout from counter 2.

## ◆ mtb_hal_i2c_addr_event_t

enum mtb_hal_i2c_addr_event_t

I2C enum to enable/disable/report address interrupt cause flags.

Enumerator
MTB_HAL_I2C_ADDR_EVENT_NONE | No event.
MTB_HAL_I2C_GENERAL_CALL_EVENT | Indicates the target was addressed by the general call address.
MTB_HAL_I2C_ADDR_MATCH_EVENT | Indicates the target matching address received.

## ◆ mtb_hal_i2c_fifo_type_t

enum mtb_hal_i2c_fifo_type_t

I2C FIFO type.

Enumerator
MTB_HAL_I2C_FIFO_RX | Set RX FIFO level.
MTB_HAL_I2C_FIFO_TX | Set TX FIFO level.

## ◆ mtb_hal_i2c_command_rsp_t

enum mtb_hal_i2c_command_rsp_t

I2C Command ACK / NAK.

Enumerator
MTB_HAL_I2C_CMD_ACK | Send ACK to current byte.
MTB_HAL_I2C_CMD_NAK | Send NAK to current byte.

## ◆ mtb_hal_i2c_output_t

enum mtb_hal_i2c_output_t

Enum of possible output signals from an I2C.

Enumerator
MTB_HAL_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.
MTB_HAL_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

## ◆ mtb_hal_i2c_configure()

cy_rslt_t mtb_hal_i2c_configure | ( | mtb_hal_i2c_t * | obj,
|  | const mtb_hal_i2c_cfg_t * | cfg
| ) |  |

Configure the I2C block.

Note
  Controller/Target 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

## ◆ mtb_hal_i2c_controller_write()

cy_rslt_t mtb_hal_i2c_controller_write | ( | mtb_hal_i2c_t * | obj,
|  | uint16_t | dev_addr,
|  | const uint8_t * | data,
|  | uint16_t | size,
|  | uint32_t | timeout,
|  | bool | send_stop
| ) |  |

I2C controller 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 controller_write request

## ◆ mtb_hal_i2c_controller_read()

cy_rslt_t mtb_hal_i2c_controller_read | ( | mtb_hal_i2c_t * | obj,
|  | uint16_t | dev_addr,
|  | uint8_t * | data,
|  | uint16_t | size,
|  | uint32_t | timeout,
|  | bool | send_stop
| ) |  |

I2C controller 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 controller_read request

## ◆ mtb_hal_i2c_target_config_read_buffer()

cy_rslt_t mtb_hal_i2c_target_config_read_buffer | ( | mtb_hal_i2c_t * | obj,
|  | const uint8_t * | data,
|  | uint16_t | size
| ) |  |

The function configures the read buffer on an I2C Target.

This is the buffer that the target recieves data into. The user needs to setup a new buffer every time (i.e. call mtb_hal_i2c_target_config_write_buffer and mtb_hal_i2c_target_config_read_buffer every time the buffer has been used up)
See related code example: PSOC™ 6 MCU: I2C Controller

Parameters

  [in] | obj | The I2C object
  [in] | data | I2C target receive data buffer
  [in] | size | I2C target receive data buffer size

Returns
  The status of the target_config_read_buffer request

## ◆ mtb_hal_i2c_target_config_write_buffer()

cy_rslt_t mtb_hal_i2c_target_config_write_buffer | ( | mtb_hal_i2c_t * | obj,
|  | uint8_t * | data,
|  | uint16_t | size
| ) |  |

The function configures the write buffer on an I2C Target.

This is the buffer that stores data to be written to the controller. The user needs to setup a new buffer every time (i.e. call mtb_hal_i2c_target_config_write_buffer and mtb_hal_i2c_target_config_read_buffer every time the buffer has been used up)
See related code example: PSOC™ 6 MCU: I2C Controller

Parameters

  [in] | obj | The I2C object
  [out] | data | I2C target write data buffer
  [in] | size | I2C target write data buffer size

Returns
  The status of the target_config_write_buffer request

## ◆ mtb_hal_i2c_register_callback()

void mtb_hal_i2c_register_callback | ( | mtb_hal_i2c_t * | obj,
|  | mtb_hal_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 mtb_hal_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

## ◆ mtb_hal_i2c_register_address_callback()

void mtb_hal_i2c_register_address_callback | ( | mtb_hal_i2c_t * | obj,
|  | mtb_hal_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 mtb_hal_i2c_enable_address_event occurs.

Note
  This function will not have an effect if enable_address_callback parameter of mtb_hal_i2c_cfg_t structure was false when mtb_hal_i2c_configure 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

## ◆ mtb_hal_i2c_register_byte_received_callback()

void mtb_hal_i2c_register_byte_received_callback | ( | mtb_hal_i2c_t * | obj,
|  | mtb_hal_i2c_byte_callback_t | callback,
|  | void * | callback_arg
| ) |  |

Register an I2C byte received callback handler

This function will be called when a byte is received. Either an ACK or a NACK message will be sent depending on the returned value from the callback.

Parameters

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

## ◆ mtb_hal_i2c_enable_event()

void mtb_hal_i2c_enable_event | ( | mtb_hal_i2c_t * | obj,
|  | mtb_hal_i2c_event_t | event,
|  | bool | enable
| ) |  |

Configure and Enable or Disable I2C Interrupt.

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

See Snippet 2: Handling events

Parameters

  [in] | obj | The I2C object
  [in] | event | The I2C event type
  [in] | enable | True to turn on interrupts, False to turn off

## ◆ mtb_hal_i2c_enable_address_event()

void mtb_hal_i2c_enable_address_event | ( | mtb_hal_i2c_t * | obj,
|  | mtb_hal_i2c_addr_event_t | event,
|  | bool | enable
| ) |  |

Configure and Enable or Disable I2C Address Interrupt.

When an enabled event occurs, the function specified by mtb_hal_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] | enable | True to turn on interrupts, False to turn off

## ◆ mtb_hal_i2c_target_readable()

uint32_t mtb_hal_i2c_target_readable | ( | mtb_hal_i2c_t * | obj | ) |

Returns the number of bytes written by the I2C controller.

Calling the mtb_hal_i2c_target_config_read_buffer API will clear the counter of bytes sent by controller

Parameters

  [in] | obj | The I2C object

Returns
  The number of bytes written by the I2C controller.

## ◆ mtb_hal_i2c_target_writable()

uint32_t mtb_hal_i2c_target_writable | ( | mtb_hal_i2c_t * | obj | ) |

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

Calling the mtb_hal_i2c_target_config_write_buffer API will clear the counter of bytes read by controller

Parameters

  [in] | obj | The I2C object

Returns
  The number of bytes can be read by the I2C controller.

## ◆ mtb_hal_i2c_target_read()

cy_rslt_t mtb_hal_i2c_target_read | ( | mtb_hal_i2c_t * | obj,
|  | uint8_t * | dst_buff,
|  | uint16_t * | size,
|  | uint32_t | timeout
| ) |  |

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

Note
  If the read size requested is greater than the data available, the function only copies the available data. The given buffer in dst_buff should match the one configured in mtb_hal_i2c_target_config_read_buffer to avoid additional copy operation.

Parameters

  [in] | obj | The I2C object
  [in] | dst_buff | Pointer on memory to store the data from the target 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

## ◆ mtb_hal_i2c_target_write()

cy_rslt_t mtb_hal_i2c_target_write | ( | mtb_hal_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 the size of the data is greater than can fit the buffer, the function only copies data that can fit. The given buffer in src_buff should match the one configured in mtb_hal_i2c_target_config_write_buffer to avoid additional copy operation.

Parameters

  [in] | obj | The I2C object
  [in] | src_buff | Pointer on memory to copy the data to the target 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

## ◆ mtb_hal_i2c_target_abort_read()

cy_rslt_t mtb_hal_i2c_target_abort_read | ( | mtb_hal_i2c_t * | obj | ) |

The function aborts the configured target read buffer to be read by the controller.

If the controller reads and "abort operation" is requested, the MTB_HAL_I2C_TARGET_RD_BUF_EMPTY_EVENT event occurs.

Parameters

  [in] | obj | The I2C object

Returns
  The status of the target abort read request

## ◆ mtb_hal_i2c_clear()

cy_rslt_t mtb_hal_i2c_clear | ( | mtb_hal_i2c_t * | obj | ) |

Clear the I2C buffers.

Parameters

  [in] | obj | The I2C object

Returns
  The status of the clear request

## ◆ mtb_hal_i2c_process_interrupt()

cy_rslt_t mtb_hal_i2c_process_interrupt | ( | mtb_hal_i2c_t * | obj | ) |

Process interrupts related related to an I2C instance.

Parameters

  obj | HAL object for which the interrupt should be processed

Returns
  CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error