CAN HAL

CAN Hardware Abstraction Layer API Reference. More...

Functions list
void	hal_can_configure_default (hal_can_config_t *config)
	Configure CAN HAL configuration structure.
void	hal_can_filter_configure_default (hal_can_filter_config_t *filter_config)
	Configure CAN HAL filter configuration structure.
err_t	hal_can_open (handle_t *handle, bool hal_obj_open_state)
	Open the CAN HAL object.
err_t	hal_can_init (handle_t *handle, hal_can_config_t *config, hal_can_filter_config_t *filter_config)
	Initialize CAN module.
err_t	hal_can_set_filter (handle_t *handle, hal_can_config_t *config, hal_can_filter_config_t *filter_config)
	Initialize CAN module filter.
err_t	hal_can_set_frequency (handle_t *handle, hal_can_config_t *config, hal_can_filter_config_t *filter_config)
	Set CAN module frequency.
err_t	hal_can_get_frequency (handle_t *handle)
	Get CAN module frequency.
err_t	hal_can_set_mode (handle_t *handle, hal_can_config_t *config, hal_can_filter_config_t *filter_config)
	Set CAN module mode.
err_t	hal_can_get_mode (handle_t *handle)
	Get CAN module mode.
err_t	hal_can_transmit (handle_t *handle, hal_can_transmit_message_struct *transmit_message)
	Transmit data to the first free TX mailbox.
void	hal_can_transmission_stop (handle_t *handle)
	Stop transmit operation.
err_t	hal_can_receive (handle_t *handle, hal_can_receive_message_struct *receive_message)
	Get data from the RX FIFO.
err_t	hal_can_close (handle_t *handle)
	Close CAN HAL object.

Function Documentation

hal_can_close()

err_t hal_can_close

(

handle_t *

handle

)

De-allocates hardware resources for specific HAL object and de-initializes the module on a hardware level, resets pin AF to default values, clears all buffers used by object and disables module clock for lower power consumption.

Parameters

[in,out]

obj

CAN HAL object. See hal_can_t structure definition for detailed explanation.

Returns

The function hal_can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// Close the CAN module object handler.
if ( CAN_SUCCESS == hal_can_close( &hal_can ) ) {
    // No error
} else {
    // Handle the error.
}

hal_can_configure_default()

void hal_can_configure_default

(

hal_can_config_t *

config

)

Configures hal_can_config_t structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

config

configure CAN HAL configuration structure. See hal_can_config_t structure definition for detailed explanation.

Default values:

Function	Default value
Tx pin	0xFFFFFFFF (invalid pin)
Rx pin	0xFFFFFFFF (invalid pin)
Mode	HAL_CAN_MODE_NORMAL
Frequency	500000

Returns

Nothing.

Example

// CAN HAL configuration structure.
static hal_can_config_t hal_can_cfg;
 
// Fill structure with default values.
hal_can_configure_default( &hal_can_cfg );

hal_can_filter_configure_default()

void hal_can_filter_configure_default

(

hal_can_filter_config_t *

filter_config

)

Configures hal_can_filter_config_t structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

filter_config

configure CAN HAL filter configuration structure. See hal_can_filter_config_t structure definition for detailed explanation.

Default values:

Function	Default value
ID high	0x0000
ID low	0x0000
ID mask high	0x0000
ID mask low	0x0000
Filter mode	HAL_CAN_FILTER_MODE_IDMASK
Filter scale	HAL_CAN_FILTER_SCALE_16BIT
Filter enable	HAL_CAN_FILTER_DISABLE
Filter FIFO	HAL_CAN_FILTER_FIFO0
Filter bank	0

Returns

Nothing.

Example

// CAN HAL filter configuration structure.
static hal_can_filter_config_t hal_can_filter_cfg;
 
// Fill structure with default values.
hal_can_filter_configure_default( &hal_can_filter_cfg );

hal_can_get_frequency()

err_t hal_can_get_frequency

(

handle_t *

handle

)

Gets the currently configured CAN frequency.

Parameters

[in]

obj

CAN HAL object. See hal_can_t structure definition for detailed explanation.

Returns

The function can return the CAN_ERROR value defined by hal_can_err_t, which is size dependant on the architecture, or the actual frequency.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_can_open definition for detailed explanation.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// Get transmission rate.
int32_t frequency = hal_can_get_frequency( &hal_can );

hal_can_get_mode()

err_t hal_can_get_mode

(

handle_t *

handle

)

Gets the currently configured CAN mode.

Parameters

[in]

obj

CAN HAL object. See hal_can_t structure definition for detailed explanation.

Returns

The function can return the CAN_ERROR value defined by hal_can_err_t, which is size dependant on the architecture, or the actual mode.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_can_open definition for detailed explanation.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// Get mode.
hal_can_mode_t mode = hal_can_get_mode( &hal_can );

hal_can_init()

err_t hal_can_init	(	handle_t *	handle,
		hal_can_config_t *	config,
		hal_can_filter_config_t *	filter_config )

Sets CAN module parameters.

Parameters

[in]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	config	CAN config structure. See hal_can_config_t structure definition for detailed explanation.
[in]	filter_config	CAN filter config structure. See hal_can_filter_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call hal_can_open function.

Postcondition

This function initializes CAN module and sets adequate parameters.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// CAN HAL filter configuration structure.
static hal_can_filter_config_t hal_can_filter_cfg;
 
// CAN HAL configuration structure.
static hal_can_config_t hal_can_cfg;
 
// Call the function.
if ( hal_can_init( &hal_can, &hal_can_cfg, &hal_can_filter_cfg ) == HAL_CAN_ERROR )
{
    // Error handling strategy.
}

hal_can_open()

err_t hal_can_open	(	handle_t *	handle,
		bool	hal_obj_open_state )

Opens the CAN HAL object on selected pins. Allocates memory and pins for specified object.

Parameters

[in,out]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	hal_obj_open_state	CAN state, is it open or not.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
// CAN HAL configuration structure.
static hal_can_t hal_can_cfg;
 
// Specify desired TX pin.
hal_can_cfg.tx_pin = CAN_TX;
 
// Specify desired RX pin.
hal_can_cfg.rx_pin = CAN_RX;
 
// Allocate resources for CAN module.
if ( hal_can_open( &hal_can, &hal_can_cfg ) == HAL_CAN_ERROR )
{
    // Error handling strategy.
}

hal_can_receive()

err_t hal_can_receive	(	handle_t *	handle,
		hal_can_receive_message_struct *	receive_message )

Function stores previously transmitted data into the rx_data in receive_message structure.

Parameters

[in]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	receive_message	Structure designed to store received information and data retrieved from the CAN registers. See #hal_can_message_struct structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand, and the module has been initialized to adequate CAN frequency. See hal_can_open definition and hal_can_set_frequency for detailed explanation.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// CAN receive structure.
hal_can_receive_message_struct *rx_message;
 
if ( hal_can_receive( &hal_can, &rx_message ) == CAN_ERROR )
{
    // Error handling strategy.
}

hal_can_set_filter()

err_t hal_can_set_filter	(	handle_t *	handle,
		hal_can_config_t *	config,
		hal_can_filter_config_t *	filter_config )

Sets CAN module filter parameters.

Parameters

[in]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	config	CAN config structure. See hal_can_config_t structure definition for detailed explanation.
[in]	filter_config	CAN filter config structure. See hal_can_filter_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Precondition

Make sure that hal_can_filter_config_t structure has been adequately filled out.

Postcondition

This function initializes CAN filter and sets adequate parameters.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// CAN HAL filter config structure.
static hal_can_filter_config_t hal_can_filter_cfg;
 
// CAN HAL configuration structure.
static hal_can_config_t hal_can_cfg;
 
// Configure CAN filter.
if ( hal_can_set_filter( &hal_can, &hal_can_cfg, &hal_can_filter_cfg ) == HAL_CAN_ERROR )
{
    // Error handling strategy.
}

hal_can_set_frequency()

err_t hal_can_set_frequency	(	handle_t *	handle,
		hal_can_config_t *	config,
		hal_can_filter_config_t *	filter_config )

Sets CAN module frequency to frequency value if possible. Frequency must be set to exact amount as requested, otherwise error is returned.

Parameters

[in]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	config	CAN config structure. See hal_can_config_t structure definition for detailed explanation.
[in]	filter_config	CAN filter config structure. See hal_can_filter_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_can_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// CAN HAL filter config structure.
static hal_can_filter_config_t hal_can_filter_cfg;
 
// CAN HAL configuration structure.
static hal_can_config_t hal_can_cfg;
 
// Set transmission rate.
if ( hal_can_set_frequency( &hal_can, &hal_can_cfg, &hal_can_filter_cfg ) == HAL_CAN_ERROR )
{
    // Error handling strategy.
}

hal_can_set_mode()

err_t hal_can_set_mode	(	handle_t *	handle,
		hal_can_config_t *	config,
		hal_can_filter_config_t *	filter_config )

Sets CAN module mode to mode if possible.

Parameters

[in]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	config	CAN config structure. See hal_can_config_t structure definition for detailed explanation.
[in]	filter_config	CAN filter config structure. See hal_can_filter_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_can_open definition for detailed explanation.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// CAN HAL filter config structure.
static hal_can_filter_config_t hal_can_filter_cfg;
 
// CAN HAL configuration structure.
static hal_can_config_t hal_can_cfg;
 
// Set mode.
if ( hal_can_set_mode( &hal_can, &hal_can_cfg, &hal_can_filter_cfg ) == HAL_CAN_ERROR )
{
    // Error handling strategy.
}

hal_can_transmission_stop()

void hal_can_transmission_stop

(

handle_t *

handle

)

Function accesses hardware transmit registers, finds the transmit mailbox that has message transmission request in progress and stops data transmission.

Parameters

[in]

obj

CAN HAL object.

Returns

void None.

Precondition

Make sure that there is transmission in progress. See hal_can_transmit definition for detailed explanation.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// Stop transmission.
hal_can_transmission_stop( &hal_can );

hal_can_transmit()

err_t hal_can_transmit	(	handle_t *	handle,
		hal_can_transmit_message_struct *	transmit_message )

Function sets parameters from the transmit message structure in the appropriate registers and then sends out the data.

Parameters

[in]	obj	CAN HAL object. See hal_can_t structure definition for detailed explanation.
[in]	transmit_message	Structure containing necessary information about the message being transmitted. See #hal_can_message_struct structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_can_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand, and the module has been initialized to adequate CAN frequency. See hal_can_open definition and hal_can_set_frequency for detailed explanation.

Note

It is recommended to check return value for error.

Example

// CAN HAL context structure.
static hal_can_t hal_can;
 
// CAN transmit structure.
can_transmit_message_struct *tx_message;
 
// Set the ID type.
tx_message.tx_id_type = HAL_CAN_FRAME_FORMAT_STANDARD_11BITS;
 
// Set a unique standard ID.
tx_message.tx_std_id = 0x321;
 
// Set the length of the message in bytes.
tx_message.tx_data_len = 3;
 
// Set the data.
tx_message.tx_data[0] = 0xAA;
tx_message.tx_data[1] = 0xBB;
tx_message.tx_data[2] = 0xCC;
 
if ( hal_can_transmit( &hal_can, &tx_message ) == HAL_CAN_ERROR )
{
    // Error handling strategy.
}