CEC (r_cec)

Functions
fsp_err_t	R_CEC_Open (cec_ctrl_t *const p_ctrl, cec_cfg_t const *const p_cfg)
fsp_err_t	R_CEC_MediaInit (cec_ctrl_t *const p_ctrl, cec_addr_t local_address)
fsp_err_t	R_CEC_Close (cec_ctrl_t *const p_ctrl)
fsp_err_t	R_CEC_Write (cec_ctrl_t *const p_ctrl, cec_message_t const *const p_message, uint32_t message_size)
fsp_err_t	R_CEC_StatusGet (cec_ctrl_t *const p_ctrl, cec_status_t *const p_status)
fsp_err_t	R_CEC_CallbackSet (cec_ctrl_t *const p_ctrl, void(*p_callback)(cec_callback_args_t *), void const *const p_context, cec_callback_args_t *const p_callback_memory)

Detailed Description

Driver for the CEC peripheral on RA MCUs. This module implements the CEC Interface.

Overview

The HDMI CEC HAL module provides a high-level API for CEC applications and supports the CEC peripheral available on RA microcontroller hardware. A user-callback function must be defined that the driver will invoke when data received, transmission complete, or error interrupts are received. The callback is passed a parameter which indicates the event as well as received data (if available).

Features

• Conforms to High Definition Multimedia Interface (HDMI) Consumer Electronics Control (CEC) standard Ver. 1.4b.
• Full range of local address settings (TV, Recording Device, Playback Device, etc.)
• Data filtering based on matching destination address and local address.
• Supports a user-callback function (required), invoked when transmit, receive, or error interrupts are received.

Configuration

Build Time Configurations for r_cec

The following build time configurations are defined in fsp_cfg/r_cec_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.
CEC Message Max Data Size	CEC message max data size must be a positive integer	14	Maximum Data Size for CEC Message Transmission/Reception.

Configurations for Connectivity > CEC (r_cec)

This module can be added to the Stacks tab via New Stack > Connectivity > CEC (r_cec). 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
General
Name	Name must be a valid C symbol	g_cec0	Module name
Control Configuration
Clock Select	PCLKB / 32 PCLKB / 64 PCLKB / 128 PCLKB / 256 PCLKB / 512 PCLKB / 1024 CECCLK CECCLK / 256	PCLKB / 1024	CEC Clock Select Configuration
Ack Bit Timing Error Enable	Disabled Enabled	Enabled	CEC Ack Bit Timing Error Enable
Signal-Free Time Bit Width	3-data bit width 5-data bit width 7-data bit width Does not detect signal-free time.	7-data bit width	Signal-Free Time Data Bit Width Select
Start Bit Error Detection Enable	Disabled Enabled	Enabled	Enable to detect timing errors during start bit reception.
Bus Lock Detection Enable	Disabled Enabled	Enabled	Enable to detect sticking of receive data to high or low.
Digital Filter Enable	Disabled Enabled	Enabled	Enable to use a digital filter.
Long Bit Width Error Pulse Output Enable	Disabled Enabled	Disabled	Enable to output an error handling pulse when a long bit width error is detected.
Start Detection Reception Restart Enable	Disabled Enabled	Enabled	Enable to restart reception after a start bit error is detected.
Bit Width Timing
Bit Width Timing > Transmit
Start Bit Low Time	CEC transmission start bit low width setting must be a positive integer.	180	CEC transmission start bit low width setting (CEC Clock Cycles).
Start Bit Width Time	CEC transmission start bit high width setting must be a positive integer.	220	CEC transmission start bit high width setting (CEC Clock Cycles).
Logical Zero Low Time	CEC transmission logical zero low width setting must be a positive integer.	73	CEC transmission logical zero low width setting (CEC Clock Cycles).
Logical One Low Time	CEC transmission logical one low width setting must be a positive integer.	29	CEC transmission logical one low width setting (CEC Clock Cycles).
Overall Bit Width Time	CEC transmission overall data bit width time setting must be a positive integer.	117	CEC transmission overall data bit width time setting (CEC Clock Cycles).
Bit Width Timing > Receive
Data Sample Time	CEC reception data sampling time must be a positive integer.	49	CEC reception data sampling time setting (CEC Clock Cycles).
Data Bit Reference Width	CEC reception data bit reference width must be a positive integer.	117	CEC data bit reference width setting (CEC Clock Cycles).
Start Bit Low Min Time	CEC reception start bit minimum low width setting must be a positive integer.	171	CEC reception start bit minimum low width setting (CEC Clock Cycles). Not used when Start Bit Error Detection and restart Rx on Error are not enabled.
Start Bit Low Max Time	CEC reception start bit maximum low width setting must be a positive integer.	190	CEC reception start bit maximum low width setting (CEC Clock Cycles). Not used when Start Bit Error Detection and restart Rx on Error are not enabled.
Start Bit Min Time	CEC start bit minimum time setting must be a positive integer.	210	CEC start bit minimum time setting (CEC Clock Cycles). Not used when Start Bit Error Detection and restart Rx on Error are not enabled.
Start Bit Max Time	CEC reception start bit maximum time setting must be a positive integer.	229	CEC start bit maximum time setting (CEC Clock Cycles). Not used when Start Bit Error Detection and restart Rx on Error are not enabled.
Logical Zero Low Min Time	CEC reception logical zero minimum low width setting must be a positive integer.	64	CEC reception logical zero minimum low width setting (CEC Clock Cycles).
Logical Zero Low Max Time	CEC reception locical zero maximum low width setting must be a positive integer.	83	CEC reception logical zero maximum low width setting (CEC Clock Cycles).
Logical One Low Min Time	CEC reception logical one minimum low width setting must be a positive integer.	20	CEC reception logical one minimum low width setting (CEC Clock Cycles).
Logical One Low Max Time	CEC reception logical one maximum low width setting must be a positive integer.	39	CEC reception logical one maximum low width (CEC Clock Cycles).
Overall Bit Width Min Time	CEC reception overall minimum bit width setting must be a positive integer.	100	CEC reception overall minimum bit width setting (CEC Clock Cycles).
Overall Bit Width Max Time	CEC reception overall maximum bit width setting must be a positive integer.	134	CEC reception overall maximum bit width setting (CEC Clock Cycles).
Interrupts
Interrupt Priority Level	MCU Specific Options		Error/Data/Message interrupt priority level.
Callback Function	Callback Function must be a valid C symbol	g_rm_cec0_callback	Callback function
Communication Complete Interrupt Timing	After Last Frame and Signal Free Time After Last Frame After Signal Free Time	After Last Frame and Signal Free Time	Communication Complete Interrupt (INTCE) Generation Timing Select
Address Mismatch Interrupt Enable	Disabled Enabled	Disabled	Enable to generate an interrupt when the addresses do not match.
Data Interrupt Timing Selection	EOM timing (9th bit of data) ACK Timing (10th bit of data)	EOM timing (9th bit of data)	INTDA reception interrupt timing selection (EOM or ACK).

Clock Configuration

The CEC peripheral uses the CECCLK or PCLKB as its clock source. To set the PCLKB frequency, use the Clocks tab of the RA Configuration editor.

Note

The selected clock and configured divider must be configured in the range of 23.4375 to 78.125 kHz.

Pin Configuration

A CEC channel uses one data pin - CECIO for data transmission and reception.

The output type for each pin should be set to n-ch open drain for most hardware designs. This can be configured in Pins tab of the RA Configuration editor by selecting the pin under Pin Selection->Ports.

Usage Notes

CEC Device Addresses

The CEC standard provides 13 device addresses that may be requested based on a device's primary function. Use R_CEC_MediaInit to request a specific address before starting communication with other devices.

Note

Address 0 is always the primary display (TV). Do not attempt to allocate this address unless your device is intended to function as a display.

Limitations

Developers should be aware of the following limitations when using the CEC module:

• R_CEC_MediaInit may return FSP_ERR_IN_USE for up to 45 milliseconds after R_CEC_Open while the hardware initializes.
• The CECIO pin must be set to n-ch open drain mode.

Examples

Basic Example

This is a basic example of minimal use of the CEC in an application.

/***********************************************************************************************************************
 * Application defined callback
 * - May be assigned at compile-time via the e2 studio configuration tool or set at run-time via R_CEC_CallbackSet()
 **********************************************************************************************************************/
void cec_callback (cec_callback_args_t * p_args)
{
    switch (p_args->event)
    {
        case CEC_EVENT_READY:
        {
            /* Application processing for address allocation success. */
            break;
        }

        case CEC_EVENT_TX_COMPLETE:
        {
            /* Any required processing after transmission has completed. */
            break;
        }

        case CEC_EVENT_ERR:
        {
            /* Error processing. See cec_error_t for possible errors. */
            break;
        }

        case CEC_EVENT_RX_DATA:
        {
            /* Application to store and process received data bytes. */
            break;
        }

        case CEC_EVENT_RX_COMPLETE:
        {
            /* Application processing for message reception complete. */
        }
    }
}

/***********************************************************************************************************************
 * Basic example
 **********************************************************************************************************************/
#define     CEC_TIMEOUT_MS     (50)
#define     CEC_MSG_STANDBY    (0X36)  /* See CEC Specification for message definitions */
void basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;


    /* Open the CEC module */
    err = R_CEC_Open(&g_cec0_ctrl, &g_cec0_cfg);
    assert(FSP_SUCCESS == err);


    /* Initialize the CEC module and allocate an address */
    uint32_t timeout_ms = CEC_TIMEOUT_MS;
    do
    {
        /* R_CEC_MediaInit may return FSP_ERR_IN_USE for up to 45 milliseconds after calling R_CEC_Open */
        err = R_CEC_MediaInit(&g_cec0_ctrl, CEC_ADDR_TV);
        R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_MILLISECONDS);
    } while ((FSP_ERR_IN_USE == err) && --timeout_ms);

    assert(timeout_ms);
    assert(FSP_SUCCESS == err);


    /* Wait for local address allocation and CEC bus to be free */
    cec_status_t status;
    err = R_CEC_StatusGet(&g_cec0_ctrl, &status);
    while ((FSP_SUCCESS == err) && (CEC_STATE_READY != status.state))
    {
        err = R_CEC_StatusGet(&g_cec0_ctrl, &status);
        assert(FSP_SUCCESS == err);
    }


    cec_message_t cec_msg;
    uint8_t       total_transmit_size;

    cec_msg.destination = CEC_ADDR_BROADCAST;       /* For this example, send message to all devices on the bus */
    cec_msg.opcode      = CEC_MSG_STANDBY;          /* Send Standby Request */
    memset(cec_msg.data, 0U, sizeof(cec_msg.data)); /* See CEC Specification for other message data structures */
    total_transmit_size = 2U;                       /* Total message size, including header, opcode, and data */

    /* Send asynchronous message.
     * - Application will then be free for other processing while message is being sent.
     * - Do not modify the message buffer until transmission has completed. */
    err = R_CEC_Write(&g_cec0_ctrl, &cec_msg, total_transmit_size);
    assert(FSP_SUCCESS == err);

}

Function Documentation

R_CEC_Open()

fsp_err_t R_CEC_Open	(	cec_ctrl_t *const	p_ctrl,
		cec_cfg_t const *const	p_cfg
	)

Open and configure the CEC module for operation.

Example:

    /* Open the CEC module */
    err = R_CEC_Open(&g_cec0_ctrl, &g_cec0_cfg);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	CEC Module opened successfully.
FSP_ERR_ALREADY_OPEN	Driver already open.
FSP_ERR_ASSERTION	An input argument is invalid.
FSP_ERR_IRQ_BSP_DISABLED	Interrupts are not enabled.

R_CEC_MediaInit()

fsp_err_t R_CEC_MediaInit	(	cec_ctrl_t *const	p_ctrl,
		cec_addr_t	local_address
	)

Allocate provided CEC Local Address and Initialize the CEC module for operation.

Note

After calling R_CEC_Open this function may return FSP_ERR_IN_USE for up to 45 milliseconds.

Example:

    /* Initialize the CEC module and allocate an address */
    uint32_t timeout_ms = CEC_TIMEOUT_MS;
    do
    {
        /* R_CEC_MediaInit may return FSP_ERR_IN_USE for up to 45 milliseconds after calling R_CEC_Open */
        err = R_CEC_MediaInit(&g_cec0_ctrl, CEC_ADDR_TV);
        R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_MILLISECONDS);
    } while ((FSP_ERR_IN_USE == err) && --timeout_ms);

    assert(timeout_ms);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	CEC Module Initialized successfully.
FSP_ERR_ASSERTION	An input argument is invalid or callback has not been set.
FSP_ERR_NOT_OPEN	Control block not open.
FSP_ERR_IN_USE	HDMI CEC Bus is currently in use. Try again later.

R_CEC_Close()

fsp_err_t R_CEC_Close

(

cec_ctrl_t *const

p_ctrl

)

Close the CEC module.

Return values

FSP_SUCCESS	CEC Module closed successfully.
FSP_ERR_ASSERTION	An input argument is invalid.

R_CEC_Write()

fsp_err_t R_CEC_Write	(	cec_ctrl_t *const	p_ctrl,
		cec_message_t const *const	p_message,
		uint32_t	message_size
	)

Write data to the CEC bus. Data transmission is asynchronous. Provided message buffer should not be modified until transmission is complete.

Data Transmission follows the pattern defined be the HDMI CEC Specification:

Data	Description	Size
Start Bit	Managed by Hardware, per config	N/A
Header Block	Source/Destination Identifier	1 Byte
Data Block 1	Opcode Value (Optional)	1 Byte
Data Block 2	Operands (Optional)	Variable (0-14 Bytes Typical)

Example:

    cec_message_t cec_msg;
    uint8_t       total_transmit_size;

    cec_msg.destination = CEC_ADDR_BROADCAST;       /* For this example, send message to all devices on the bus */
    cec_msg.opcode      = CEC_MSG_STANDBY;          /* Send Standby Request */
    memset(cec_msg.data, 0U, sizeof(cec_msg.data)); /* See CEC Specification for other message data structures */
    total_transmit_size = 2U;                       /* Total message size, including header, opcode, and data */

    /* Send asynchronous message.
     * - Application will then be free for other processing while message is being sent.
     * - Do not modify the message buffer until transmission has completed. */
    err = R_CEC_Write(&g_cec0_ctrl, &cec_msg, total_transmit_size);
    assert(FSP_SUCCESS == err);

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_NOT_OPEN	Control block not open.
FSP_ERR_NOT_INITIALIZED	Module has not been successfully initialized.
FSP_ERR_ASSERTION	An input argument is invalid.
FSP_ERR_INVALID_SIZE	Invalid message size.
FSP_ERR_IN_USE	HDMI CEC Bus is currently in use. Try again later.

R_CEC_StatusGet()

fsp_err_t R_CEC_StatusGet	(	cec_ctrl_t *const	p_ctrl,
		cec_status_t *const	p_status
	)

Provides the state and status information according to the provided CEC control instance.

Return values

FSP_SUCCESS	Operation succeeded.
FSP_ERR_NOT_OPEN	Control block not open.
FSP_ERR_ASSERTION	An input argument is invalid.

R_CEC_CallbackSet()

fsp_err_t R_CEC_CallbackSet	(	cec_ctrl_t *const	p_ctrl,
		void(*)(cec_callback_args_t *)	p_callback,
		void const *const	p_context,
		cec_callback_args_t *const	p_callback_memory
	)

Updates the user callback with the option to provide memory for the callback argument structure. Implements cec_api_t::callbackSet.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	An input argument is invalid.
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.