API Reference¶

The Liebherr CAN Slave API consist of differnet functions organaized by functionality.

Core¶

Functions¶

Init, Start and State¶

lcsa_errorcode_t lcsa_init(lcsa_bdr_t baudrate)¶

This function is used to initialize the stack.

Return

LCSA_ERROR_OK or LCSA_ERROR_XLOAD_INFO_BAD_CRC if LI_CAN_SLV_USE_ASYNC_DOWNLOAD is used.

Parameters

baudrate: Use one of the available baud rate defines: li_can_slv_api_defines_baudrate

lcsa_errorcode_t lcsa_start(void)¶

Use this function to start the general handling of the slave stack.

Attention

The function should be called at a point where the system is setup correctly and ready for normal operation. Because after that call the master is allowed to start the normal operation.

Return: LCSA_ERROR_OK

void lcsa_set_state(lcsa_state_t new_state)¶

Parameters

new_state: New lcsa_state_t to set

lcsa_state_t lcsa_get_state(void)¶

Return: the current lcsa_state_t

Mandatory Function¶

lcsa_trigger_5msec()¶

This function must be called every 5 milliseconds.

Return: LCSA_ERROR_OK

Configuration¶

lcsa_errorcode_t lcsa_add_module(const lcsa_module_config_t *module, lcsa_module_number_t module_nr, void *rx0, void *rx1, void *rx2, void *rx3, void *tx0, void *tx1, void *tx2, void *tx3)¶

add module to can configuration

Remark

In case of multiple usage of the module number the default module number is set and a according error is returned.

Return

LCSA_ERROR_OK if successful other send the error over CAN

Parameters

module: is the pointer to application module type configuration
module_nr: is the module number of the configured module
rx0: data pointer to application data of CAN receive object 0
rx1: data pointer to application data of CAN receive object 1
rx2: data pointer to application data of CAN receive object 2
rx3: data pointer to application data of CAN receive object 3
tx0: data pointer to application data of CAN transmit object 0
tx1: data pointer to application data of CAN transmit object 1
tx2: data pointer to application data of CAN transmit object 2
tx3: data pointer to application data of CAN transmit object 3

lcsa_set_module_critical(module_type)¶

With this function it is possible to set a module to a critical state.

That means if the module is added to li_can_slv master i will be in timeout after the call off this function.

Attention

After the module is in a critical state there is no way to bring the module back in a non critical state. The only possible solution is a reboot of the system.

Return

LCSA_ERROR_OK or LCSA_ERROR_CONFIG_MODULE_TYPE_NOT_FOUND

Parameters

module_type: module type which should be set critical

lcsa_is_module_valid(module_type, module_number, table_pos)¶

Return

LCSA_ERROR_OK or LCSA_ERROR_CONFIG_MODULE_NOT_FOUND

Parameters

module_type: module type of module
module_number: module number of module
table_pos: table position of the module

lcsa_get_main_module_number()¶

Return: the module number of the main module type

lcsa_set_baudrate(baudrate)¶

Return

LCSA_ERROR_OK or ERR_MSG_CAN_CONFIG_SET_INVALID_BAUDRATE

Parameters

baudrate: is the baud rate to set in kBaud

lcsa_bdr_t lcsa_get_baudrate(void)¶

get current configured CAN baud rate

Return: the current used baud rate

Enums¶

enum lcsa_state_t¶

defines the state of the stack

Values:

enumerator LI_CAN_SLV_STATE_RUNNING = 0¶: stack is in running mode

enumerator LI_CAN_SLV_STATE_DOWNLOAD¶: stack is in download or after download mode

enumerator LI_CAN_SLV_STATE_RECONNECT¶: stack is in reconnect mode

enumerator LI_CAN_SLV_STATE_INIT¶: stack is in init mode

enumerator LI_CAN_SLV_STATE_STOPPED¶: stack is stopped

enum lcsa_module_change_voter_state_t¶

return type for the module change callback voter

Values:

enumerator LCSA_MODULE_CHANGE_VALID = 0¶: change will proceed and change the identifiers for rx and tx messages accordingly

enumerator LCSA_MODULE_CHANGE_ERROR¶: change will be skipped and an error send

enumerator LCSA_MODULE_CHANGE_FORBIDDEN¶: change will be skipped and an error send

enumerator LCSA_MODULE_CHANGE_VALID_BUT_SET_SILENT¶: change will be proceeded the identifiers changed but the module will not respond to any message until an reboot or an AWAKE command

Types¶

group li_can_slv_api_types

Typedefs

typedef li_can_slv_config_module_t lcsa_module_config_t¶: module configuration type

typedef li_can_slv_module_nr_t lcsa_module_number_t¶: module number type

typedef li_can_slv_module_type_t lcsa_module_type_t¶: module type type

typedef li_can_slv_config_bdr_t lcsa_bdr_t¶: baud rate type

typedef can_config_module_silent_t lcsa_module_response_sate_t¶: state if an module is responsive or silent on CAN messages

Defines¶

Configuration¶

LCSA_DEF_MODULE_NR1¶: default module for can module 1

LCSA_DEF_MODULE_NR2¶: default module for can module 2

LCSA_DEF_MODULE_NR3¶: default module for can module 3

LCSA_DEF_MODULE_NR4¶: default module for can module 4

LCSA_DEF_MODULE_NR5¶: default module for can module 5

LCSA_DEF_MODULE_NR6¶: default module for can module 6

LCSA_DEF_MODULE_NR7¶: default module for can module 7

LCSA_DEF_MODULE_NR8¶: default module for can module 8

LCSA_CONFIG_OBJ_USED_NOT¶: message objects not used

LCSA_CONFIG_OBJ_USED_0¶: number of message objects used 0

LCSA_CONFIG_OBJ_USED_1¶: number of message objects used 1

LCSA_CONFIG_OBJ_USED_2¶: number of message objects used 2

LCSA_CONFIG_OBJ_USED_3¶: number of message objects used 3

LCSA_CONFIG_OBJ_USED_4¶: number of message objects used 4

LCSA_CONFIG_DLC_USED_0¶: used data length 0

LCSA_CONFIG_DLC_USED_1¶: used data length 1

LCSA_CONFIG_DLC_USED_2¶: used data length 2

LCSA_CONFIG_DLC_USED_3¶: used data length 3

LCSA_CONFIG_DLC_USED_4¶: used data length 4

LCSA_CONFIG_DLC_USED_5¶: used data length 5

LCSA_CONFIG_DLC_USED_6¶: used data length 6

LCSA_CONFIG_DLC_USED_7¶: used data length 7

LCSA_CONFIG_DLC_USED_8¶: used data length 8

LCSA_CONFIG_MODULE_TYPE_LENGTH¶: max module type length

Baud Rate¶

LCSA_BAUD_RATE_DEFAULT¶: default baud rate (250kBaud)

LCSA_BAUD_RATE_125K¶: 125 kBaud

LCSA_BAUD_RATE_250K¶: 250 kBaud

LCSA_BAUD_RATE_500k¶: 500 kBaud

LCSA_BAUD_RATE_1M¶: 1000 kBaud

Synchronous Protocol Handling¶

Functions¶

lcsa_sync_trigger_process_periode()¶: lcsa_sync_trigger_process_periode

lcsa_sync_get_process_periode()¶

lcsa_sync_get_process_periode

Return: lcsa_errorcode_t or LCSA_ERROR_OK if successful

lcsa_sync_get_process_cycle_time()¶

lcsa_sync_get_process_cycle_time

Return: lcsa_errorcode_t or LCSA_ERROR_OK if successful

lcsa_sync_set_process_time_valid_fnc(module_type, pfnc)¶

Set function pointer to read the valid process time for this module type.

Return

lcsa_errorcode_t or LCSA_ERROR_OK if successful

Parameters

module_type:
pfnc: function pointer to the valid function

Set Callback Functions¶

lcsa_set_first_status_request_cbk(pfnc)¶

Set the callback function pointer for the function which should be called on the first status request.

Return

LCSA_ERROR_OK if successful

Parameters

pfnc: function pointer to the callback

lcsa_sync_set_first_process_request_cbk(pfnc)¶

Set the callback function pointer for the function which should be called on every first received process request.

Return

LCSA_ERROR_OK if successful

Parameters

pfnc: function pointer to the callback

lcsa_sync_set_process_request_cbk(module_type, module_number, pfnc)¶

Set the callback function pointer for the function which should be called on every received process request.

Return

LCSA_ERROR_OK if successful

Parameters

module_type: the module type for which the callback is set
module_number: the module number for which the callback is set
pfnc: function pointer to the callback

lcsa_sync_set_process_image_valid_cbk(module_type, module_number, pfnc)¶

Set the callback function pointer for the function which should be called on every valid process image.

Tip

The callback will be called if the image for the current module is valid. Here is an example of a possible implementation:

// add the callback
err = lcsa_sync_set_process_image_valid_cbk(module_type, module_number, &app_my_module_process_image_valid_cbk);
if (err == LCSA_ERROR_OK)
{
        return(err);
}

// callback implementation
static void app_my_module_process_image_valid_cbk(void)
{

}

Return

LCSA_ERROR_OK if successful

Parameters

module_type: the module type for which the callback is set
module_number: the module number for which the callback is set
pfnc: function pointer to the callback

lcsa_sync_set_process_image_not_valid_cbk(module_type, module_number, pfnc)¶

Set the callback function pointer for the function which should be called on every not valid process image.

Return

LCSA_ERROR_OK if successful

Parameters

module_type: the module type for which the callback is set
module_number: the module number for which the callback is set
pfnc: function pointer to the callback

lcsa_sync_set_whole_process_image_valid_cbk(pfnc)¶

Set the callback function pointer for the function which should be called if the whole image was received valid.

Return

LCSA_ERROR_OK if successful

Parameters

pfnc: function pointer to the callback

Download / Upload¶

Set Handle Functions¶

lcsa_dload_set_start_handle(hdl)¶

Return

LCSA_ERROR_DLOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for download start

lcsa_dload_set_version_request_handle(hdl)¶

Return

LCSA_ERROR_DLOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for download version request

lcsa_dload_set_start_request_handle(hdl)¶

Return

LCSA_ERROR_DLOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for download start request

lcsa_dload_set_data_block_end_handle(hdl)¶

Return

LCSA_ERROR_DLOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for data block end

lcsa_dload_set_end_handle(hdl)¶

Return

LCSA_ERROR_DLOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for download end

lcsa_uload_set_info_request_handle(hdl)¶

Return

LCSA_ERROR_ULOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for upload info request

lcsa_uload_set_start_request_handle(hdl)¶

Return

LCSA_ERROR_ULOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for upload start request

lcsa_uload_set_uload_block_ack_handle(hdl)¶

Return

LCSA_ERROR_ULOAD_ADD_HANDLE or LCSA_ERROR_OK

Parameters

hdl: handle function for upload block acknowledge

Error and Message¶

Functions¶

lcsa_send_module_error(msg_code, priority, group, subgroup, module_nr)¶

Return

LCSA_ERROR_OK if successful

Parameters

msg_code: message code of the error
priority: the priority used for this message. Usage of LCSA_ERROR_MSG_PRIO_INFO, LCSA_ERROR_MSG_PRIO_WARNING or LCSA_ERROR_MSG_PRIO_ERROR is possible.
group: group definition of the message for example use LCSA_ERROR_GROUP_CAN for group CAN
subgroup: subgroup definition of the message for example use LCSA_ERROR_SUBGROUP_CAN_APPLICATION for subgroup CAN application
module_nr: logical CAN module number that caused the error

lcsa_send_module_error_short(msg_code, priority, module_nr)¶

Return

LCSA_ERROR_OK if successful

Parameters

msg_code: message code of the error
priority: the priority used for this message. Usage of LCSA_ERROR_MSG_PRIO_INFO, LCSA_ERROR_MSG_PRIO_WARNING or LCSA_ERROR_MSG_PRIO_ERROR is possible.
module_nr: logical CAN module number that caused the error

lcsa_send_module_error_with_add_info(msg_code, add_info, priority, group, subgroup, module_nr)¶

send module error with info

Return

lcsa_errorcode_t or LCSA_ERROR_OK if successful

Return

lcsa_errorcode_t or LCSA_ERROR_OK if successful

Parameters

msg_code: message code of the error
add_info: additional signed info byte
priority: the priority used for this message. Usage of LCSA_ERROR_MSG_PRIO_INFO, LCSA_ERROR_MSG_PRIO_WARNING or LCSA_ERROR_MSG_PRIO_ERROR is possible.
group: group definition of the message for example use LCSA_ERROR_GROUP_CAN for group CAN
subgroup: subgroup definition of the message for example use LCSA_ERROR_SUBGROUP_CAN_APPLICATION for subgroup CAN application
module_nr: logical CAN module number that caused the error.

Parameters

msg_code: message code of the error
add_info: additional signed info byte
priority: the priority used for this message. Usage of LCSA_ERROR_MSG_PRIO_INFO, LCSA_ERROR_MSG_PRIO_WARNING or LCSA_ERROR_MSG_PRIO_ERROR is possible.
module_nr: logical CAN module number that caused the error.

lcsa_send_module_error_short_with_add_info(msg_code, add_info, priority, module_nr)¶

lcsa_send_sensor_error(msg_code, priority, module_nr)¶

send sensor error

Return

lcsa_errorcode_t or LCSA_ERROR_OK if successful

Parameters

msg_code: message code of the error
priority: the priority used for this message. Usage of LCSA_ERROR_MSG_PRIO_INFO, LCSA_ERROR_MSG_PRIO_WARNING or LCSA_ERROR_MSG_PRIO_ERROR is possible.
module_nr: logical CAN module number that caused the error.

Defines¶

Error Code¶

LCSA_ERROR_OK¶

LCSA_ERROR_CONFIG_MODULE_TYPE_NOT_FOUND¶

LCSA_ERROR_CONFIG_MODULE_NOT_FOUND¶

LCSA_ERROR_XLOAD_INFO_BAD_CRC¶

LCSA_ERROR_CONIFG_REDECLARED_MODULE_NR¶

LCSA_ERROR_DLOAD_ADD_HANDLE¶

LCSA_ERROR_DLOAD_UNKNOWN_COMPONENT¶

LCSA_ERROR_ULOAD_ADD_HANDLE¶

LCSA_ERROR_ULOAD_UNKNOWN_COMPONENT¶

Priority¶

LCSA_ERROR_MSG_PRIO_INFO¶: message priority info

LCSA_ERROR_MSG_PRIO_WARNING¶: message priority warning

LCSA_ERROR_MSG_PRIO_ERROR¶: message priority error

LCSA_ERROR_MSG_PRIO_CRITICAL¶: message priority critical

LCSA_ERROR_MSG_PRIO_FATAL¶: message priority fatal

Group¶

LCSA_ERROR_GROUP_CAN¶: group definition: CAN bus

LCSA_ERROR_GROUP_SMALLSYSTEM¶: group definition: small system

SubGroup¶

LCSA_ERROR_SUBGROUP_CAN_APPLICATION¶: application

LCSA_ERROR_SUBGROUP_CAN_SENSOR¶: sensor

LCSA_ERROR_SUBGROUP_SMALLSYSTEM_FREQUENCYCONVERTER¶: freqeuncyconverter

Types¶

typedef li_can_slv_errorcode_t lcsa_errorcode_t¶: error code type

typedef li_can_slv_msg_code_t lcsa_msg_code_t¶: message code type

typedef li_can_slv_msg_add_info_t lcsa_msg_add_info_t¶: message additional info type

typedef li_can_slv_msg_priority_t lcsa_msg_priority_t¶: message priority type

typedef li_can_slv_msg_group_t lcsa_msg_group_t¶: message group type

typedef li_can_slv_msg_subgroup_t lcsa_msg_subgroup_t¶: message subgroup type

CAN reconnect (Autobaud)¶

Set Callback Functions¶

group li_can_slv_api_reconnect_online

Defines

lcsa_reconnect_set_online_change_baudrate_start_cbk(pfnc)¶

This function sets the reconnect online change baud rate start callback.

Parameters

pfnc: function to handle the reconnect online change baud rate start callback

lcsa_reconnect_set_online_change_baudrate_stop_cbk(pfnc)¶

This function sets the reconnect online change baud rate stop callback.

Tip

This function can be used to save the baud rate as an example:

static void reconnect_online_change_baudrate_stop(lcsa_bdr_t baudrate)
{
  // save the baud rate here or do what ever you want to do...
}

Now this callback can be set that way:

lcsa_reconnect_set_online_change_baudrate_stop_cbk(reconnect_online_change_baudrate_stop);

Parameters

pfnc: function to handle the reconnect online change baud rate stop callback

group li_can_slv_api_reconnect_startup

Defines

lcsa_reconnect_set_startup_change_baudrate_start_cbk(pfnc)¶

This function sets the reconnect startup change baud rate start callback.

Parameters

pfnc: function to handle the reconnect startup change baud rate start callback

lcsa_reconnect_set_startup_change_baudrate_stop_cbk(pfnc)¶

This function sets the reconnect startup change baud rate stop callback.

Attention

Do not use this function to save the baud rate.

Parameters

pfnc: function to handle the reconnect startup change baud rate stop callback

Change Module Number Handling¶

group lcsa_api_change_module_nr

Defines

lcsa_change_module_nr_and_identifiers(module_type, new_module_number, actual_module_number)¶

Return

LCSA_ERROR_OK or too many messages to specify

Parameters

module_type: CAN module type as char_t
new_module_number: the new module number where the identifier is calculated from
actual_module_number: the actual module number of the module to identify the exact module if two of the same modules are on the line

lsca_set_module_nr_change_cbk_voter(pfnc)¶

Parameters

pfnc: function pointer to the voter which has to return an state of type lcsa_module_change_voter_state_t and will get the parameters of the module_type, the desired new number and the actual module number

Tip

The callback as function pointer will be called on each change module number command and can be used to store the new module number information in an persistent storage for example.

lcsa_module_change_voter_state_t vote_module_change_valid(char_t *module_type, lcsa_module_number_t new_module_nr, lcsa_module_number_t act_module_nr)
{
        if((new_module_nr < MODULE_NR_MAX) && (new_module_nr > MODULE_NR_MIN))
        {
                // ...store new module number in persistent storage for next start up
                // ...or do any special handling
                return(LI_CAN_SLV_MODULE_CHANGE_VALID);
        }
        else
        {
                return(LI_CAN_SLV_MODULE_CHANGE_FORBIDDEN);
        }
}

lcsa_set_module_silent_awake_from_type_and_nr(module_type, module_number, state)¶

Return

LCSA_ERROR_OK or ERR_MSG_CAN_CONFIG_MODULE_NOT_FOUND or ERR_MSG_CAN_CONFIG_INVALID_SILENT_AWAKE_STATE

Parameters

module_type: CAN module type as char_t
module_number: module number of the module to identify the exact module if two of the same modules are on the line
state: in type of lcsa_module_response_sate_t