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

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:

LI_CAN_SLV_STATE_RUNNING = 0
LI_CAN_SLV_STATE_DOWNLOAD
LI_CAN_SLV_STATE_RECONNECT
LI_CAN_SLV_STATE_INIT
enum lcsa_module_change_voter_state_t

return type for the module change callback voter

Values:

LCSA_MODULE_CHANGE_VALID = 0

change will proceed and change the identifiers for rx and tx messages accordingly

LCSA_MODULE_CHANGE_ERORR

change will be skipped and an error send

LCSA_MODULE_CHANGE_FORBIDDEN

change will be skipped and an error send

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_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

li_can_slv_sync_get_process_periode

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 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.

Set the callback function pointer for the function which should be called on every not 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

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)
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

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

Error and Message

Functions

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

Return
LCSA_ERROR_OK if successful
Parameters

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
Parameters

lcsa_send_sensor_error(msg_code, priority, module_nr)

send sensor error

Return
lcsa_errorcode_t or LCSA_ERROR_OK if successful
Parameters

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

subgroup definition for group CAN bus: application layer

LCSA_ERROR_SUBGROUP_CAN_SENSOR

subgroup definition for group CAN bus: sensors on CAN bus

LCSA_ERROR_SUBGROUP_SMALLSYSTEM_FREQUENCYCONVERTER

subgroup definition for group smallsystem: 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