![]() |
RA Flexible Software Package Documentation
Release v6.0.0
|
|
LIN driver for the SAU peripheral on RA MCUs. This module implements the LIN Interface.
SAU LIN supports Local Interface Network (LIN) transactions in master or slave mode. A callback must be provided, and is invoked when a transmission, reception, or other event has completed or occurred. The callback arguments contain information about the transaction status, bytes transferred and a pointer to the user-defined context.
The SAU LIN driver uses the SAU UART, TAU, and ICU peripherals to implement LIN communication.
Configuration | Options | Default | Description |
---|---|---|---|
Parameter Checking |
| Default (BSP) | If selected code for parameter checking is included in the build. |
Checksum Support |
| Enabled | When set to 'Disabled', code for checksum generation and validation is excluded from the build. Disable only when checksum generation and validation is not required for any LIN instance. |
Master Support |
| Disabled | Select whether code for master support is included in the build. |
Slave Support |
| Enabled | Select whether code for slave support is included in the build. |
Wake-up Support |
| Disabled | Select whether code for LIN bus sleep and wake-up signal detection is included in the build. Enable when at least one LIN instance requires sleep/wake-up support. |
Auto Synchronization Support |
| Enabled | When set to 'Disabled', code for auto synchronization is excluded from the build. Enable when at least one LIN slave instance is using auto synchronization. |
Configuration | Options | Default | Description |
---|---|---|---|
Name | Name must be a valid C symbol | g_lin0 | Module name. |
Mode |
| Slave | Select the LIN mode. |
Callback | Name must be a valid C symbol | sau_lin0_callback | A user callback function must be provided. It will be called from the interrupt service routine (ISR) in order to notify the application of LIN transmission/reception events and errors. |
UART Channel | MCU Specific Options | Select the LIN UART Channel. | |
TAU Channel | MCU Specific Options | Select the LIN TAU Channel. | |
ICU Channel | MCU Specific Options | Select the LIN ICU Channel. | |
Baud Rate | Value must be an integer greater than 0 | 19200 | Select the LIN Baudrate. |
Auto Synchronization |
| Enable | Enable LIN synchronization to the master's clock by measuring pulse intervals between the falling edges of the input signal from the RXDn pin during reception of the LIN sync byte. |
In both master and slave modes, the SAU UART operation clock can be selected from the available operation clocks for the SAU unit.
In slave mode, the TAU operation clock can be selected from the available operation clocks for the TAU channel.
For more information about module clock settings, please refer to the clock setting of UART (r_sau_uart) and Independent Channel, 16-bit and 8-bit timer (r_tau).
This module uses TXD and RXD to communicate to external devices. Connect TXD and RXD to an on-board or external LIN transceiver for LIN bus communication.
An external pull up resistor is required on TXD in both master and slave modes.
TAU is not used in master mode. In slave mode:
ICU is only required if using bus wake-up functionality (R_SAU_LIN_WakeupSend, R_SAU_LIN_SleepEnter, R_SAU_LIN_SleepExit).
SAU LIN data reception is disabled until a LIN header is received (slave mode) or a call to R_SAU_LIN_Read() is made (master mode).
The header is detected in slave mode only. Header reception is interrupt driven, and is enabled after a successful call to R_SAU_LIN_Open() in slave mode.
When the LIN break field is detected by the slave node, header reception begins without action from the application. When header reception completes, the user callback is called.
If the slave node needs to receive a data frame, it must call R_SAU_LIN_Read() before the first data is received in order to receive the data. The user callback is called when reception is complete. It is permitted to call R_SAU_LIN_Read() from the callback context.
If the master node needs to publish a response to its own header, the master node must call R_SAU_LIN_Write() and provide a pointer to the response data. The response will be published following the header. The user callback is called when the full frame transmission is complete.
If the slave node neither needs to receive the data frame, nor publish a response for a received header, no action is required to ignore the frame.
The header is not detected in master mode. Data frame reception is enabled only after a call to R_SAU_LIN_Read().
A header-only frame can be transmitted by calling R_SAU_LIN_Write() with a NULL data pointer. The user callback is called when transmission is complete.
If the master node needs to receive the data response, call R_SAU_LIN_Read() after header transmission has completed and before the first data is received. It is permitted to call R_SAU_LIN_Read() from the callback context.
If the master node needs to publish a response to its own header, the master node must call R_SAU_LIN_Write() with a non-NULL data pointer. The response will be published following the header. The user callback is called when the full frame transmission is complete.
R_SAU_LIN_SleepEnter can be called to place the bus into bus sleep mode. When in bus sleep mode, an external interrupt is enabled on the RXD pin which can be used to notify the application when bus activity on RXDn is detected.
R_SAU_LIN_SleepEnter does not place the MCU in a low power mode. To use it to wake from a low power mode, call R_SAU_LIN_SleepEnter, then use the Low Power Modes (r_lpm) driver to enter a low power mode.
Bus sleep mode can be exited in the following ways:
Both the master and slave can send the LIN wake-up signal by calling R_SAU_LIN_WakeupSend.
Wake-up retry schedules, if required, must be implemented by the application.
If a LIN master receives the wake-up signal from a slave, the master should wait until the entire LIN cluster is ready before sending new header frames to ensure the frames can be processed by the slaves. The amount of time until the cluster is ready is application specific.
The application is responsible for managing timeouts in case R_SAU_LIN_Read() is called, but the data is not received in the expected time period. If a timeout occurs, R_SAU_LIN_CommunicationAbort() may be called to cancel a pending read.
When an error occurs, reception is stopped and the user callback is called with the relevant error code.
Auto synchronization is optional. When it is disabled, the baud rate set in R_SAU_LIN_Open is never updated.
This feature works in slave mode only.
The following demonstrates a basic example of header reception and data response for a LIN slave.
The following demonstrates a basic example of frame reception for a LIN master.
The following demonstrates a basic example of frame transmission for a LIN master.
The following demonstrates a basic example of sending wake up signal for a LIN master. The usage of slave mode is the same.
The following demonstrates a basic example of entering sleep mode for a LIN slave. The usage in master mode is the same.
The following demonstrates a basic example of exiting the LIN slave sleep mode. The usage in master mode is the same.
Data Structures | |
struct | sau_lin_extended_cfg_t |
struct | sau_lin_instance_ctrl_t |
Enumerations | |
enum | sau_lin_state_t |
enum | sau_lin_synchronization_t |
struct sau_lin_extended_cfg_t |
SAU UART LIN extended configuration
Data Fields | ||
---|---|---|
const uart_instance_t * | p_uart | The UART instance used in SAU LIN. |
const external_irq_instance_t * | p_icu | The IRQ instance used in SAU LIN. |
struct sau_lin_instance_ctrl_t |
LIN Instance Control Block. DO NOT INITIALIZE.
enum sau_lin_state_t |
SAU LIN Event codes
fsp_err_t R_SAU_LIN_Open | ( | lin_ctrl_t *const | p_api_ctrl, |
lin_cfg_t const *const | p_cfg | ||
) |
Configures the LIN driver channel based on the input configuration.
Implements lin_api_t::open.
Example:
FSP_SUCCESS | Channel opened successfully. |
FSP_ERR_ASSERTION | Pointer to LIN control block, configuration structure, or required dependency is NULL |
FSP_ERR_ALREADY_OPEN | Control block has already been opened or channel is being used by another instance. Call close() then open() to reconfigure. |
FSP_ERR_INVALID_MODE | Setting not supported for selected mode |
fsp_err_t R_SAU_LIN_Write | ( | lin_ctrl_t *const | p_api_ctrl, |
const lin_transfer_params_t *const | p_transfer_params | ||
) |
Begins non-blocking transmission of a LIN frame.
In master mode, the LIN header (break, sync and protected identifier) is sent before the LIN data.
The LIN header is not transmitted in slave mode. Set p_transfer_params->p_data to the TX buffer to transmit.
On successful header-only transmission completion, the callback is called with event lin_event_t::LIN_EVENT_TX_HEADER_COMPLETE. On successful data transmission or header+data transmission completion, the callback is called with event lin_event_t::LIN_EVENT_TX_DATA_COMPLETE.
Implements lin_api_t::write.
Example:
FSP_SUCCESS | Data transmission started successfully. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_ASSERTION | Pointer to LIN control block, transfer parameters, or tx/rx buffer is NULL, or 0 bytes length provided。 |
FSP_ERR_IN_USE | A transmission or reception is currently in progress. Call R_SAU_LIN_CommunicationAbort to cancel it if desired, or wait for the current transfer operation to complete before starting a new one. |
fsp_err_t R_SAU_LIN_Read | ( | lin_ctrl_t *const | p_api_ctrl, |
lin_transfer_params_t *const | p_transfer_params | ||
) |
Begins non-blocking data reception to receive user specified number of bytes into destination buffer pointer.
The checksum type specifies the checksum type used for validation. If a non-standard algorithm is used, or the application prefers to validate the checksum outside the driver, or the application prefers to skip checksum validation, specify lin_checksum_type_t::LIN_CHECKSUM_TYPE_NONE. If checksum validation is skipped, the lin_checksum_type_t::LIN_EVENT_ERR_INVALID_CHECKSUM event is not possible. When lin_checksum_type_t::LIN_CHECKSUM_TYPE_NONE is used, the number of bytes specified in the receive buffer length will be received (the driver will not expect to receive an additional 1 checksum byte), so if a non-standard checksum is used, sufficient space must be allocated in the write buffer and accounted for in the provided length.
On successful data reception, the callback is called with event lin_event_t::LIN_EVENT_RX_DATA_COMPLETE.
Implements lin_api_t::read.
Example:
FSP_SUCCESS | Data reception started successfully. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_ASSERTION | Pointer to LIN control block, transfer parameters, or tx/rx buffer is NULL, or 0 bytes length provided, no header matching pid was received(only for slave mode). |
FSP_ERR_IN_USE | A transmission or reception is currently in progress. Call R_SAU_LIN_CommunicationAbort to cancel it if desired, or wait for the current transfer operation to complete before starting a new one. |
FSP_ERR_INVALID_CALL | Data reception is not possible because a header frame has not been received yet (slave mode only). |
fsp_err_t R_SAU_LIN_CommunicationAbort | ( | lin_ctrl_t *const | p_api_ctrl | ) |
Cancels in progress data read or write, or header read or write. Break field reception cannot be cancelled. For slave nodes, reception of a new header reception is still enabled after a call to this function.
Implements lin_api_t::communicationAbort.
FSP_SUCCESS | Data transfer aborted successfully or no transfer was in progress. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_ASSERTION | Pointer to LIN control block is NULL. |
FSP_ERR_INVALID_STATE | Driver is in bus sleep state. Call R_SAU_LIN_SleepExit to return to active state or wait for wakeup signal. |
fsp_err_t R_SAU_LIN_CallbackSet | ( | lin_ctrl_t *const | p_api_ctrl, |
void(*)(lin_callback_args_t *) | p_callback, | ||
void *const | p_context, | ||
lin_callback_args_t *const | p_callback_memory | ||
) |
Updates the user callback and callback context.
Implements lin_api_t::callbackSet.
FSP_SUCCESS | Callback updated successfully. |
FSP_ERR_ASSERTION | Pointer to LIN control block, callback function is NULL, or p_callback_memory is not NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_INVALID_STATE | Driver is in bus sleep state. Call R_SAU_LIN_SleepExit to return to active state or wait for wakeup signal. |
fsp_err_t R_SAU_LIN_WakeupSend | ( | lin_ctrl_t *const | p_api_ctrl | ) |
Begins non-blocking transmission of the LIN wakeup signal.
On successful wakeup signal transmission, the callback is called with event lin_event_t::LIN_EVENT_TX_WAKEUP_COMPLETE.
Implements lin_api_t::wakeupSend.
Example:
FSP_SUCCESS | Wakeup signal transmission successfully started. |
FSP_ERR_ASSERTION | Pointer to LIN control block is NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_UNSUPPORTED | Unsupported when Wake-up Support build option is disabled. |
FSP_ERR_INVALID_STATE | Driver is in bus sleep state. Call R_SAU_LIN_SleepExit to return to active state or wait for wakeup signal. |
fsp_err_t R_SAU_LIN_SleepEnter | ( | lin_ctrl_t *const | p_api_ctrl | ) |
Places the LIN node in bus sleep mode. Enables the external IRQ that can be used to detect the LIN wakeup signal.
On wakeup signal reception, the callback is called with event lin_event_t::LIN_EVENT_RX_WAKEUP_COMPLETE and bus sleep mode is automatically exited.
Implements lin_api_t::sleepEnter.
Example:
FSP_SUCCESS | Bus successfully transitioned to sleep state. |
FSP_ERR_ASSERTION | Pointer to LIN control block is NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_UNSUPPORTED | Unsupported when Wake-up Support build option is disabled. |
FSP_ERR_INVALID_STATE | Driver is in bus sleep state. Call R_SAU_LIN_SleepExit to return to active state or wait for wakeup signal. |
FSP_ERR_NOT_ENABLED | ICU module is not enabled. |
fsp_err_t R_SAU_LIN_SleepExit | ( | lin_ctrl_t *const | p_api_ctrl | ) |
Exits the bus sleep mode for LIN device. Disables wakeup signal detection.
Implements lin_api_t::sleepExit.
FSP_SUCCESS | Bus successfully transitioned to active state |
FSP_ERR_ASSERTION | Pointer to LIN control block is NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
FSP_ERR_UNSUPPORTED | Unsupported when Wake-up Support build option is disabled. |
FSP_ERR_NOT_ENABLED | ICU module is not enabled. |
fsp_err_t R_SAU_LIN_Close | ( | lin_ctrl_t *const | p_api_ctrl | ) |
Closes the LIN driver.
Implements lin_api_t::close.
Example:
FSP_SUCCESS | Channel successfully closed. |
FSP_ERR_ASSERTION | Pointer to LIN control block is NULL. |
FSP_ERR_NOT_OPEN | The control block has not been opened. |
fsp_err_t R_SAU_LIN_InformationFrameRead | ( | lin_ctrl_t *const | p_api_ctrl, |
lin_transfer_params_t *const | p_transfer_params | ||
) |
DEPRECATED. Use R_SAU_LIN_Read.
fsp_err_t R_SAU_LIN_StartFrameWrite | ( | lin_ctrl_t *const | p_api_ctrl, |
uint8_t const | id | ||
) |
[DEPRECATED] Use R_SAU_LIN_Write
fsp_err_t R_SAU_LIN_InformationFrameWrite | ( | lin_ctrl_t *const | p_api_ctrl, |
const lin_transfer_params_t *const | p_transfer_params | ||
) |
[DEPRECATED] Use R_SAU_LIN_Write