|
fsp_err_t | R_SCI_I2C_Open (i2c_master_ctrl_t *const p_api_ctrl, i2c_master_cfg_t const *const p_cfg) |
|
fsp_err_t | R_SCI_I2C_Read (i2c_master_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes, bool const restart) |
|
fsp_err_t | R_SCI_I2C_Write (i2c_master_ctrl_t *const p_api_ctrl, uint8_t *const p_src, uint32_t const bytes, bool const restart) |
|
fsp_err_t | R_SCI_I2C_Abort (i2c_master_ctrl_t *const p_api_ctrl) |
|
fsp_err_t | R_SCI_I2C_SlaveAddressSet (i2c_master_ctrl_t *const p_api_ctrl, uint32_t const slave, i2c_master_addr_mode_t const addr_mode) |
|
fsp_err_t | R_SCI_I2C_CallbackSet (i2c_master_ctrl_t *const p_api_ctrl, void(*p_callback)(i2c_master_callback_args_t *), void const *const p_context, i2c_master_callback_args_t *const p_callback_memory) |
|
fsp_err_t | R_SCI_I2C_StatusGet (i2c_master_ctrl_t *const p_api_ctrl, i2c_master_status_t *p_status) |
|
fsp_err_t | R_SCI_I2C_Close (i2c_master_ctrl_t *const p_api_ctrl) |
|
Driver for the SCI peripheral on RA MCUs. This module implements the I2C Master Interface.
Overview
The Simple I2C master on SCI HAL module supports transactions with an I2C Slave device. Callbacks must be provided which would be invoked when a transmission or receive has been completed. The callback arguments will contain information about the transaction status, bytes transferred and a pointer to the user defined context.
Features
- Supports multiple transmission rates
- Standard Mode Support with up to 100 kHz transaction rate.
- Fast Mode Support with up to 400 kHz transaction rate.
- SDA Delay in nanoseconds can be specified as a part of the configuration.
- I2C Master Read from a slave device.
- I2C Master Write to a slave device.
- Abort any in-progress transactions.
- Set the address of the slave device.
- Non-blocking behavior is achieved by the use of callbacks.
- Additional build-time features
- Optional (build time) DTC support for read and write respectively.
- Optional (build time) support for 10-bit slave addressing.
Configuration
Build Time Configurations for r_sci_i2c
The following build time configurations are defined in fsp_cfg/r_sci_i2c_cfg.h:
Configuration | Options | Default | Description |
Parameter Checking |
-
Default (BSP)
-
Enabled
-
Disabled
| Default (BSP) | If selected code for parameter checking is included in the build. |
DTC on Transmission and Reception |
| Disabled | If enabled, DTC instances will be included in the build for both transmission and reception. |
10-bit slave addressing |
| Disabled | If enabled, the driver will support 10-bit slave addressing mode along with the default 7-bit slave addressing mode. |
Configurations for Connectivity > I2C Master (r_sci_i2c)
This module can be added to the Stacks tab via New Stack > Connectivity > I2C Master (r_sci_i2c). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.
Configuration | Options | Default | Description |
Name | Name must be a valid C symbol | g_i2c0 | Module name. |
Channel | Value must be an integer between 0 and 9 | 0 | Select the SCI channel. |
Slave Address | Value must be a hex value | 0x00 | Specify the slave address. |
Address Mode |
| 7-Bit | Select the address mode. |
Rate |
| Standard | Select the I2C data rate.
If the requested transfer rate cannot be achieved, the settings with the largest possible transfer rate that is less than or equal to the requested transfer rate are used. The theoretical calculated transfer rate and SDA delay are printed in a comment in the generated sci_i2c_extended_cfg_t structure. |
SDA Output Delay (nano seconds) | Must be a valid non-negative integer with maximum configurable value of 300 | 300 | Specify the SDA output delay in nanoseconds. |
Noise filter setting |
-
Use clock signal divided by 1 with noise filter
-
Use clock signal divided by 2 with noise filter
-
Use clock signal divided by 4 with noise filter
-
Use clock signal divided by 8 with noise filter
| Use clock signal divided by 1 with noise filter | Select the sampling clock for the digital noise filter |
Bit Rate Modulation |
| Enable | Enabling bitrate modulation reduces the percent error of the actual bitrate with respect to the requested baud rate. It does this by modulating the number of cycles per clock output pulse, so the clock is no longer a square wave. |
Callback | Name must be a valid C symbol | sci_i2c_master_callback | A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR). |
Interrupt Priority Level | MCU Specific Options | | Select the interrupt priority level. This is set for TXI, RXI (if used), TEI interrupts. |
RX Interrupt Priority Level [Only used when DTC is enabled] | MCU Specific Options | | Select the interrupt priority level. This is set for RXI only when DTC is enabled. |
Clock Configuration
The clock for this module is derived from the following peripheral clock for each MCU group:
MCU Group | Peripheral Clock |
RA2A1 | PCLKB |
RA2A2 | PCLKB |
RA2E1 | PCLKB |
RA2E2 | PCLKB |
RA2E3 | PCLKB |
RA2L1 | PCLKB |
RA4E1 | PCLKA |
RA4E2 | PCLKA |
RA4M1 | PCLKA |
RA4M2 | PCLKA |
RA4M3 | PCLKA |
RA4T1 | PCLKA |
RA4W1 | PCLKA |
RA6E1 | PCLKA |
RA6E2 | PCLKA |
RA6M1 | PCLKA |
RA6M2 | PCLKA |
RA6M3 | PCLKA |
RA6M4 | PCLKA |
RA6M5 | PCLKA |
RA6T1 | PCLKA |
RA6T3 | PCLKA |
The actual I2C transfer rate will be calculated and set by the tooling depending on the selected transfer rate and the SDA delay. If the PCLK is configured in such a manner that the selected internal rate cannot be achieved, an error will be returned.
Pin Configuration
The SCI I2C peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device. An I2C channel would consist of two pins - SDA and SCL for data/address and clock respectively.
Usage Notes
Interrupt Configuration
- Receive buffer full (RXI), transmit buffer empty (TXI) and transmit end (TEI) interrupts for the selected channel used must be enabled in the properties of the selected device.
- Set equal priority levels for all the interrupts mentioned above. Setting the interrupts to different priority levels could result in improper operation.
SCI I2C Master Rate Calculation
- The RA Configuration editor calculates the internal baud-rate setting based on the configured transfer rate and SDA Delay. The closest possible baud-rate that can be achieved (less than or equal to the requested rate) at the current PCLK settings is calculated and used.
- If a valid clock rate could not be calculated, an error is returned by the tool.
Enabling DTC with the SCI I2C
- DTC transfer support is configurable and is disabled from the build by default. SCI I2C driver provides two DTC instances for transmission and reception respectively.
- DTC is helpful for minimizing interrupts during large transactions. Many I2C applications have shorter transactions. These applications will likely not see any improvement with DTC. I2C often runs at a much slower speed than the CPU core clock. Some applications with longer transactions may prefer servicing the interrupts at the I2C bitrate to the overhead of bringing in the DTC driver.
- For further details on DTC please refer Transfer (r_dtc)
Multiple Devices on the Bus
- A single SCI I2C instance can be used to communicate with multiple slave devices on the same channel by using the SlaveAddressSet API.
Restart
- SCI I2C master can hold the the bus after an I2C transaction by issuing Restart. This will mimic a stop followed by start condition.
Examples
Basic Example
This is a basic example of minimal use of the r_sci_i2c in an application. This example shows how this driver can be used for basic read and write operations.
void basic_example (void)
{
uint32_t i;
uint32_t timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
assert(FSP_SUCCESS == err);
for (i = 0; i < I2C_BUFFER_SIZE_BYTES; i++)
{
g_i2c_tx_buffer[i] = (uint8_t) i;
}
err =
R_SCI_I2C_Write(&g_i2c_device_ctrl_1, &g_i2c_tx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
err =
R_SCI_I2C_Read(&g_i2c_device_ctrl_1, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
if (0U != memcmp(g_i2c_tx_buffer, g_i2c_rx_buffer, I2C_BUFFER_SIZE_BYTES))
{
__BKPT(0);
}
}
Multiple Slave devices on the same channel (bus)
This example demonstrates how a single SCI I2C driver can be used to communicate with different slave devices which are on the same channel.
void single_channel_multi_slave (void)
{
uint32_t timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
assert(FSP_SUCCESS == err);
memset(g_i2c_rx_buffer, '0', I2C_BUFFER_SIZE_BYTES);
err =
R_SCI_I2C_Read(&g_i2c_device_ctrl_2, &g_i2c_rx_buffer[0], I2C_BUFFER_SIZE_BYTES,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
assert(FSP_SUCCESS == err);
g_i2c_tx_buffer[0] = (uint8_t) I2C_EXAMPLE_DATA_1;
g_i2c_tx_buffer[1] = (uint8_t) I2C_EXAMPLE_DATA_2;
timeout_ms = I2C_TRANSACTION_BUSY_DELAY;
err =
R_SCI_I2C_Write(&g_i2c_device_ctrl_2, &g_i2c_tx_buffer[0], 2U,
false);
assert(FSP_SUCCESS == err);
{
timeout_ms--;;
}
{
__BKPT(0);
}
}
◆ sci_i2c_clock_settings_t
struct sci_i2c_clock_settings_t |
Data Fields |
bool |
bitrate_modulation |
Bit-rate Modulation Function enable or disable. |
uint8_t |
brr_value |
Bit rate register settings. |
uint8_t |
clk_divisor_value |
Clock Select settings. |
uint8_t |
mddr_value |
Modulation Duty Register settings. |
uint8_t |
cycles_value |
SDA Delay Output Cycles Select. |
uint8_t |
snfr_value |
Noise Filter Setting Register value. |
◆ sci_i2c_instance_ctrl_t
struct sci_i2c_instance_ctrl_t |
I2C control structure. DO NOT INITIALIZE.
◆ sci_i2c_extended_cfg_t
struct sci_i2c_extended_cfg_t |
SCI I2C extended configuration
◆ R_SCI_I2C_Open()
Opens the I2C device.
- Return values
-
FSP_SUCCESS | Requested clock rate was set exactly. |
FSP_ERR_ALREADY_OPEN | Module is already open. |
FSP_ERR_IP_CHANNEL_NOT_PRESENT | Channel is not available on this MCU. |
FSP_ERR_ASSERTION | Parameter check failure due to one or more reasons below:
- p_api_ctrl or p_cfg is NULL.
- extended parameter is NULL.
- Callback parameter is NULL.
- Clock rate requested is greater than 400KHz
- Invalid IRQ number assigned
|
◆ R_SCI_I2C_Read()
Performs a read from the I2C device. The caller will be notified when the operation has completed (successfully) by an I2C_MASTER_EVENT_RX_COMPLETE in the callback.
- Return values
-
FSP_SUCCESS | Function executed without issue. |
FSP_ERR_ASSERTION | The parameter p_ctrl, p_dest is NULL, bytes is 0. |
FSP_ERR_INVALID_SIZE | Provided number of bytes more than uint16_t size (65535) while DTC is used for data transfer. |
FSP_ERR_NOT_OPEN | Device was not even opened. |
◆ R_SCI_I2C_Write()
Performs a write to the I2C device.
This function will fail if there is already an in-progress I2C transfer on the associated channel. Otherwise, the I2C write operation will begin. When no callback is provided by the user, this function performs a blocking write. Otherwise, the write operation is non-blocking and the caller will be notified when the operation has finished by an I2C_EVENT_TX_COMPLETE in the callback.
- Return values
-
FSP_SUCCESS | Function executed without issue. |
FSP_ERR_ASSERTION | p_ctrl, p_src is NULL. |
FSP_ERR_INVALID_SIZE | Provided number of bytes more than uint16_t size (65535) while DTC is used for data transfer. |
FSP_ERR_NOT_OPEN | Device was not even opened. |
◆ R_SCI_I2C_Abort()
Aborts any in-progress transfer and forces the I2C peripheral into a ready state.
This function will safely terminate any in-progress I2C transfer with the device. If a transfer is aborted, the user will be notified via callback with an abort event. Since the callback is optional, this function will also return a specific error code in this situation.
- Return values
-
FSP_SUCCESS | Transaction was aborted without issue. |
FSP_ERR_ASSERTION | p_ctrl is NULL. |
FSP_ERR_NOT_OPEN | Device was not even opened. |
◆ R_SCI_I2C_SlaveAddressSet()
Sets address and addressing mode of the slave device.
This function is used to set the device address and addressing mode of the slave without reconfiguring the entire bus.
- Return values
-
FSP_SUCCESS | Address of the slave is set correctly. |
FSP_ERR_ASSERTION | p_ctrl or address is NULL. |
FSP_ERR_NOT_OPEN | Device was not even opened. |
FSP_ERR_IN_USE | An I2C Transaction is in progress. |
◆ R_SCI_I2C_CallbackSet()
Updates the user callback and has option of providing memory for callback structure. Implements i2c_master_api_t::callbackSet
- Return values
-
FSP_SUCCESS | Callback updated successfully. |
FSP_ERR_ASSERTION | A required pointer is NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_NO_CALLBACK_MEMORY | p_callback is non-secure and p_callback_memory is either secure or NULL. |
◆ R_SCI_I2C_StatusGet()
Provides driver status.
- Return values
-
FSP_SUCCESS | Status stored in p_status. |
FSP_ERR_ASSERTION | NULL pointer. |
◆ R_SCI_I2C_Close()
Closes the I2C device. Power down I2C peripheral.
This function will safely terminate any in-progress I2C transfer with the device. If a transfer is aborted, the user will be notified via callback with an abort event. Since the callback is optional, this function will also return a specific error code in this situation.
- Return values
-
FSP_SUCCESS | Device closed without issue. |
FSP_ERR_ASSERTION | The parameter p_ctrl is NULL. |
FSP_ERR_NOT_OPEN | Device was not even opened. |