3 C Programming User API Documentation

Table of Contents

User API Documentation

The user application interface (user API) is a set of c-functions used to access helper, system and hardware functionality of MRS S32K modules. Each available function is listed and described in this document. If you require additional functionality please contact MRS.

Information

i

User API development is a steady and continuous process and will be extended and improved all the time. In case of outdated or occurred problems please contact support@mrs-electronic.com.

This document will give you a summary of the basic user API functionality and related examples. Each API feature is described with its functions, an overview of the parameters and a description of associated values like pin names and where they can be found as well as examples.

You can simply copy the example code here, make your adjustments and paste it into your code.

Inputs

Digital Input

    • Get state of digital input: 
uint8_t user_io_get_di( uint16_t pin );
Parameter Description
uint16_t pin Ports & Interfaces: Digital Input Pins:
return State of digital input pin
example uint8_t get_di_input;
get_di_input = user_io_get_di(DI_KL15);
execution Immediate
    • Get the corresponding Analog pin number from a regular pin number (supported pins only) 
enum_adc_pin_name user_di_find_adc_pin(uint16_t pin);
Parameter Description
uint16_t pin Ports & Interfaces: Digital Input Pins
return Analog Pin Number (CC16WP options [AI_A_IN0] - [AI_A_IN5])
example uint16_t voltage = 0;
voltage = user_ai_get_mv(user_di_find_adc_pin);
execution Immediate

Analog Input

    • Adjust the measuring range, for analog inputs, between 16V and 32V (supported pins only) 
void user_ai_set_measurement_range( enum_adc_pin_name pin, uint8_t range );
Parameter Description
enum_adc_pin_name pin Ports & Interfaces: Analog Input Pins (CC16WP options [AI_A_IN0] - [AI_A_IN5])
uint8_t range AI_RANGE_16V or AI_RANGE_32V
example user_ai_set_measurement_range(AI_A_IN0, AI_RANGE_32V)
execution Immediate
    • Brief information on the measuring range:
      Measuring range is set to 16V by default and must not be called first.

    • Get value in mV of analog input: 
uint16_t user_ai_get_mv( enum_adc_pin_name pin );
Parameter Description
enum_adc_pin_name pin Ports & Interfaces: Analog Input Pins:
return Value of analog input in mV
example uint16_t get_in0_value_mv;
get_in0_value_mv = user_ai_get_mv( AI_A_IN0 );
execution Immediate
    • Get value in digits of analog input: 
uint16_t user_ai_get_digits( enum_adc_pin_name pin );
Parameter Description
enum_adc_pin_name pin Ports & Interfaces: Analog Input Pins:
return Value of analog input
example uint16_t get_in0_value;
get_in0_value = user_ai_get_digits( AI_A_IN0 );
execution Immediate
    • Additional info about KL30_1 and KL30_2:
      In order to be able to read out the voltage values of KL30_1 and KL30_2, you must first set DO_POWER.
      The measuring range does not have to be set for this.
(void)user_io_set_do( DO_POWER, 1 );

Frequency Input

    • General info about Frequency measurement:
      Each channel of a FlexTimer Module (FTM) can measure a different frequency.
      FlexTimer Modules can have multiple channels.

Current composition of the Frequency measurement on the CC16WP

FTM PWM Channel
FTM3 FREQ_A_IN0
FREQ_A_IN1
FREQ_A_IN2
FREQ_A_IN3
FREQ_A_IN4
FREQ_A_IN5
    • Get measured frequency of frequency input pin: 
uint32_t user_freq_get_measured_freq( uint16_t pin );
Parameter Description
uint16_t pin From io_tables.h in enum_pwm_pin_name (FREQ_A_IN0, .. , FREQ_A_IN5)
return Measured frequency value in Hz (1Hz per count)
example uint32_t freq_ai_0;
freq_ai_0 = user_freq_get_measured_freq(FREQ_A_IN0);
execution Immediate
    • Get measured frequency of frequency input pin with high resolution: 
uint32_t user_freq_get_measured_freq_high_res( uint16_t pin );
Parameter Description
uint16_t pin From io_tables.h in enum_pwm_pin_name (FREQ_A_IN0, .. , FREQ_A_IN5)
return Measured frequency value in mHz (1mHz per count)
example uint32_t freq_ai_0;
freq_ai_0 = user_freq_get_measured_freq_high_res(FREQ_A_IN0);
execution Immediate
    • Get measured duty of frequency input pin: 
uint32_t user_freq_get_measured_duty( uint16_t pin );
Parameter Description
uint16_t pin From io_tables.h in enum_pwm_pin_name (FREQ_A_IN0, .. , FREQ_A_IN5)
return Measured duty value in percent (0.1% per count)
example uint32_t duty_ai_0;
duty_ai_0 = user_freq_get_measured_duty(FREQ_A_IN0);
execution Immediate
    • Get measured duty of frequency input pin with high resolution: 
uint32_t user_freq_get_measured_duty_high_res( uint16_t pin );
Parameter Description
uint16_t pin From io_tables.h in enum_pwm_pin_name (FREQ_A_IN0, .. , FREQ_A_IN5)
return Measured duty value in percent (0.01% per count)
example uint32_t duty_ai_0;
duty_ai_0 = user_freq_get_measured_duty_high_res(FREQ_A_IN0);
execution Immediate
    • Get measured edge count of frequency input pin: 
uint32_t user_freq_get_measured_edge_count( uint16_t pin );
Parameter Description
uint16_t pin From io_tables.h in enum_pwm_pin_name (FREQ_A_IN0, .. , FREQ_A_IN5)
return Number of detected edges
example uint32_t edges_ai_0;
edges_ai_0 = user_freq_get_measured_edge_count(FREQ_A_IN0);
execution Immediate

Outputs

Digital Output

    • Set digital output: 
void user_io_set_do( uint16_t pin, uint8_t state );
Parameter Description
uint16_t pin Ports & Interfaces: Digital Output Pins
uint8_t state boolean
example (void)user_io_set_do(DO_VREF_EN, 1);
execution Immediate
    • Brief information on the output pins:
      The eight output pins of the CC16WP module are internally configured as PWM.
      If you use user_io_set_do(..) the PWM output will be overwritten immediately - independent of the current PWM cycle. It is therefore recommended to use the individual pins only for one purpose, either as a digital output or a PWM.
      Please also note that PWM outputs are only updated after a PWM cycle is complete. E.g. with 100 Hz it will only change after 10 ms in the worst case (if a new cycle just started right before pwm_set..(..) was called).

    • Additional info about vref:
      When DO_VREF_EN is set, there is a standard voltage of 5V at the Vref output.
      You can also set Vref output to 8,5V or 10V by setting: (void)user_io_set_do(DCDC_8V5, 1); or (void)user_io_set_do(DCDC_10V, 1);

    • Readback digital output: 
uint8_t user_io_readback_do( uint16_t pin );
Parameter Description
uint16_t pin Ports & Interfaces: Digital Output Pins:
return State of digital output pin
example uint8_t get_do_rb;
get_do_rb = user_io_readback_do(DO_VREF_EN);
execution Immediate

PWM Output

    • General info about PWM:
      Duty can be set individually for each channel, but you can only set the frequency once per FlexTimer Module (FTM).
      FlexTimer Modules can have multiple channels.

Overview about the channels on the CC16WP

FTM PWM Channel
FTM0 PWM_HSD_OUT1
PWM_HSD_OUT2
PWM_HSD_OUT3
PWM_HSD_OUT7
FTM1 PWM_HSD_OUT6
FTM2 PWM_HSD_OUT0
PWM_HSD_OUT4
PWM_HSD_OUT5
    • Set PWM: 
uint32_t user_pwm_set_pwm( uint16_t pin,
                           uint16_t freq,
                           uint16_t duty );
Parameter Description
uint16_t pin From io_tables.h in struct_ftm_config_tbl (PWM_HSD1_OUT0... )
uint16_t freq uint16_t value, set the desired frequency here
uint16_t duty uint16_t value, 0 - 1000
return 0 if succes
example (void)user_pwm_set_pwm(PWM_HSD1_OUT0, 250, 500);
execution Immediate
    • Set PWM duty: 
uint32_t user_pwm_set_duty( uint16_t pin, uint16_t duty );
Parameter Description
uint16_t pin From io_tables.h in struct_ftm_config_tbl (PWM_HSD1_OUT0... )
uint16_t duty uint16_t value, 0 - 1000
return 0 if succes
example (void)user_pwm_set_duty(PWM_HSD1_OUT0, 500);
//set duty to 50%
execution Immediate
    • Set PWM frequency: 
uint32_t user_pwm_set_freq( uint16_t pin,
                            uint16_t freq );
Parameter Description
uint16_t pin From io_tables.h in struct_ftm_config_tbl (PWM_HSD1_OUT0... )
uint16_t freq Set the desired frequency here
return 0 if succes
example (void)user_pwm_set_freq(PWM_HSD1_OUT0, 1000);
//set frequency to 1kHz
execution Immediate
    • Set global PWM frequency: 
uint32_t user_pwm_set_global_freq( uint16_t freq );
Parameter Description
uint16_t freq Set the desired frequency globally for all modules here
return 0 if succes
example (void)user_pwm_set_global_freq(1000);
//set frequency to 1kHz
execution Immediate

CAN Bus

    • Changing the can fifo size:

The size of the RX and TX fifo are changeable with the Applics Studio and will be be generated into can_db_tables.h. The size of every TX or RX fifo can be changed seperately by changing the definition of the size.

#define CAN0_TX_FIFO_SIZE 40        // CAN 0 TX fifo size (1 entry = 16 byte)
#define CAN1_TX_FIFO_SIZE 40        // CAN 1 TX fifo size (1 entry = 16 byte)

#define CAN0_RX_FIFO_SIZE 40        // CAN 0 RX fifo size (1 entry = 16 byte)
#define CAN1_RX_FIFO_SIZE 40        // CAN 1 RX fifo size (1 entry = 16 byte)
    • Send message on CAN bus : 
enum_HAL_CAN_RETURN_VALUE user_can_send_msg( const uint8_t can_bus,
                                             const uint32_t can_id,
                                             const enum_CAN_ID_TYPE id_type,
                                             const uint8_t can_dlc,
                                             const uint8_t data_byte_0,
                                             const uint8_t data_byte_1,
                                             const uint8_t data_byte_2,
                                             const uint8_t data_byte_3,
                                             const uint8_t data_byte_4,
                                             const uint8_t data_byte_5,
                                             const uint8_t data_byte_6,
                                             const uint8_t data_byte_7 );
Parameter Description
uint16_t can_bus CAN BUS from enum in can_db_tables.h (can_bus_id)
uint8_t can_id Can ID for example 0x123
uint8_t id_type Type of CAN ID STANDARD_IDor EXTENDED_ID
uint8_t can_dlc Number of bytes in data field
uint8_t data_byte_(0-7) Message data with a data size of 1 byte each
return 0 = success, 1 = general error, 15 = wrong dlc, 8 = write error (fifo full)
example (void)user_can_send_msg(CAN_BUS_0, 0x123, STANDARD_ID, 8, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88);
execution Immediate
    • Send buffer on CAN bus: 
enum_HAL_CAN_RETURN_VALUE user_can_send_msg_buffer( const uint8_t can_bus,
                                                    const uint32_t can_id,
                                                    const enum_CAN_ID_TYPE id_type,
                                                    const uint8_t can_dlc,
                                                    const uint8_t *const data_buffer );
Parameter Description
uint16_t can_bus CAN BUS from enum in can_db_tables.h (can_bus_id)
uint8_t can_id Can ID for example 0x123
uint8_t id_type Type of CAN ID STANDARD_IDor EXTENDED_ID
uint8_t can_dlc Number of bytes in data field
uint8_t *const data_buffer Data buffer to be transmitted
return 0 = success, 1 = general error, 15 = wrong dlc, 8 = write error (fifo full)
example uint16_t can_tx_msg;
can_tx_msg = 0xAABB;
(void)user_can_send_msg_buffer(CAN_BUS_0, 0x123, STANDARD_ID, 2, &can_tx_msg);
execution Immediate
    • Receive messages on CAN bus: 
void user_can_receive_msg_callback(uint8_t bus_id, bios_can_msg_typ* msg)
Parameter Description
uint8_t bus_id CAN BUS from enum in can_db_tables.h (can_bus_id)
bios_can_msg_typ msg* Pointer to structure CAN message typ:
msg->id // Can ID for example 0x123
msg->id_ext // Type of CAN ID STANDARD_IDor EXTENDED_ID
msg->len // Number of bytes in data field
msg->data[] //Message data with a data size of 1 byte each
example below
execution Immediate
precondition set #define SET_CALLBACK_CAN_MSG_RECEIVE in user_code.h 
// Send an acknowledge message when CAN-ID 0x400 is received on CAN bus 0 as standard format and the value of byte 0 is equal 33.
void user_can_receive_msg_callback(uint8_t bus_id, bios_can_msg_typ* msg)
{
if( ( bus_id == CAN_BUS_0 ) && ( msg->id == 0x400 ) && ( msg->id_ext == STANDARD_ID ) )
   {
       if( msg->data[0] == 0x33 )
       {
           user_can_send_msg(CAN_BUS_0, 0x720, STANDARD_ID, 8, 0x66, 0x33, 0x11, 0, 0, 0, 0, msg->data[7]);
       }
       else
       {
           // do nothing
       }
   }
}

CAN DB

    • Get message in the CAN RX fifo and handle them: 
void user_can_db_clear_rx_buff();
Parameter Description
example user_can_db_clear_rx_buff();
execution Immediate
    • Output the message in the CAN DB and CAN TX fifo manually: 
void user_can_db_process_tx();

This function is only needed when the code in usercode() runs for a long time, or when you want to manually process massages in can_db. Otherwise the messages in can_db will automatically be processed and send out at the end of the usercode() cycle.

Parameter Description
example user_can_db_process_tx();
execution Immediate
    • Set value of CAN datapoint: 
void user_can_db_set_signal_value( const uint32_t id, uint32_t value_int );
Parameter Description
uint16_t id Data point name which you have defined in CAN DB Editor, also in can_db_tables.h (can_datenpunkt_db_const)
uint32_t value_int Message to be transmitted via can
example user_can_db_set_signal_value(MY_CAN_DP_0, get_in0_value);
execution Cyclical processing
    • Get value of CAN datapoint: 
uint32_t user_can_db_get_signal_value( const uint32_t id );
Parameter Description
uint16_t id Data point name which you have defined in CAN DB Editor, also in can_db_tables.h (can_datenpunkt_db_const)
return Return message for the associated data point
example: uint32_t get_can_msg;
get_can_msg = user_can_db_get_signal_value(MY_CAN_DP_0);
execution Cyclical processing
    • Check if the CAN block was received: 
uint8_t user_can_db_block_received(const uint32_t can_block_id, const uint8_t reset);
Parameter Description
uint32_t can_telegram_id Data block name which you have defined in CAN DB Editor, also in can_db_tables.h (can_block_db_const)
uint8_t reset Reset the "received" status of the given CAN DB block to "0".
reset = 1, do not reset = 0
return 0 = message not received,1 = message received
example: uint8_t message_received = 0;
message_received = user_can_db_block_received(MY_CAN_BLOCK_0, 1);
if(message_received)
// do something
execution Cyclical processing
    • Check the CAN datapoint value: 
uint8_t user_can_db_test_dp_value(const uint32_t can_dp_id);
Parameter Description
uint32_t can_dp_id Data point name which you have defined in CAN DB Editor, also in can_db_tables.h (can_datenpunkt_db_const)
return 0 = no message received, 1 = message received, datapoint has same value, 2 = message received, datapoint has another value
example: user_can_db_test_dp_value(MY_CAN_DP_0);
execution Cyclical processing
    • Send CAN datapoint: 
void user_can_db_send_dp(const uint32_t can_dp_id);
Parameter Description
uint32_t can_dp_id Data point name which you have defined in CAN DB Editor, also in can_db_tables.h (can_datenpunkt_db_const)
Associated CAN block must be configured to transmit.
example: user_can_db_send_dp(MY_CAN_DP_0);
execution Cyclical processing
    • Get CAN datapoint value on change: 
uint8_t user_can_db_get_value_on_change(const uint32_t can_dp_id, uint32_t* const buffer_dp_value);
Parameter Description
uint32_t can_dp_id Data point name which you have defined in CAN DB Editor, also in can_db_tables.h (can_datenpunkt_db_const)
uint32_t* buffer_dp_value the variable(buffer) in which the value should be saved in.
If the datapoint doesn't change, the current value will be returned
return
example: uint8_t changed_value = 0;
uint32_t value_MY_CAN_DP_0 = 0;
changed_value = user_can_db_get_value_on_change(MY_CAN_DP_0, &value_MY_CAN_DP_0);
if (changed_value)
// do something
execution Cyclical processing
    • Stop can_db transmission for a specific CAN bus: 
uint8_t user_can_db_stop_transmission(const uint8_t can_bus, const uint8_t status);
Parameter Description
const uint8_t can_bus CAN BUS from enum in can_db_tables.h (can_bus_id)
const uint8_t status Status of the function. stop = 1, start = 0
return Return value, 0 = success
example: (void)user_can_db_stop_transmission(CAN_BUS_1, 1);
execution Immediate
    • Stop can_db transmission for all CAN bus: 
uint8_t user_can_db_transmit_deactivate(const uint8_t status);
Parameter Description
const uint8_t status Status of the function. stop = 1, start = 0
return Return value, 0 = success
example: (void)user_can_db_transmit_deactivate(1);
execution Immediate
    • Stop can_db gateway functionality for known ids for a specific CAN bus: 
uint8_t user_can_db_stop_gateway_for_known_ids( const uint8_t can_bus, const uint8_t status );
Parameter Description
const uint8_t can_bus CAN BUS from enum in can_db_tables.h (can_bus_id)
const uint8_t status Status of the function. stop = 1, start = 0
return Return value, 0 = success
example: (void)user_can_db_stop_gateway_for_known_ids(0,1);
execution Immediate
    • Stop can_db gateway functionality for unknown ids for a specific CAN bus 
uint8_t user_can_db_stop_gateway_for_unknown_ids(const uint8_t can_bus, const uint8_t status);
Parameter Description
const uint8_t can_bus CAN BUS from enum in can_db_tables.h (can_bus_id)
const uint8_t status Status of the function. stop = 1, start = 0
return Return value, 0 = success
example: (void)user_can_db_stop_gateway_for_unknown_ids(0,1);
execution Immediate

LIN Bus

    • Get value of LIN datapoint: 
uint32_t lin_db_get_value( uint32_t datapoint_id );
Parameter Description
ovverview Get the value of a signal/datapoint from the LIN database
uint32_t datapoint_id From lin_db_tables.h (index of the LIN datapoint)
uint32_t return Return message for the associated data point
example uint32_t value;
value = lin_db_get_value(LIN0_RX_SIGNAL_NAME_15);
execution Cyclical processing
    • Set value of LIN datapoint: 
void lin_db_set_value( uint32_t datapoint_id, uint32_t set_value );
Parameter Description
ovverview Set the value of a signal/datapoint from the LIN database
uint32_t datapoint_id From lin_db_tables.h (index of the LIN datapoint)
uint32_t set_value Message to be transmitted via lin
uint32_t example lin_db_set_value(LIN0_TX_SIGNAL_NAME_1, 0x0F);
execution Cyclical processing
    • Check for received LIN frame: 
uint8_t lin_check_for_received_frame( uint8_t lin_module, 
                                      uint8_t frame_index,
                                      uint8_t reset );
Parameter Description
ovverview Universal function for checking if a LIN frame (or also frame header only in slave mode) was received without knowing about request or response frame on master or slave.
NOTE 1: This currently does not enable frame transmission in slave mode even though the "reset" parameter is TRUE. => additionally use lin_enable_frame_transmission() to clear the flag and enable transmission.
NOTE 2: For most use cases, the parameter "reset" can be set to be TRUE.
For more details concerning the flag handling, see descriptions of the following functions:
- lin_check_for_received_response_frame()
- lin_check_for_received_request_frame()
uint8_t lin_module LIN index number. See options at #enum_lin_bus_id in lin_db_tables.h.(enum_lin_bus_id)
uint8_t frame_index Frame index number or name from enum_lin_frame_id
NOTE: be sure to use FRAME index only, NOT signal/datapoint index (enum_lin_frame_id)
uint8_t reset boolean - TRUE (1) clear the flag to detect a new receive, FALSE (0) don't clear the flag to reset it manual
uint8_t return 0 = nothing received
1 = received
example if( lin_check_for_received_frame(LIN_BUS_0, LIN0_FRM_RX_INDEX_NAME_01, TRUE) == TRUE )
{
// complete frame / frame header was received
// do something
}
execution Cyclical processing
    • Check for received LIN frame: 
uint8_t lin_check_for_received_header( uint8_t frame_index );
Parameter Description
ovverview SLAVE only: Check if a frame header from the master was received that requires transmission of a response by the slave (published frame)
NOTE 1: The corresponding flag has to be cleared manually to enable transmission of the response. This way, the data to be sent can be safely updated before it is actually transmitted.
NOTE 2: This is just an "alias" for lin_check_for_received_response_frame() with a more descriptive name.()
uint8_t lin_module LIN index number. See options at #enum_lin_bus_id in lin_db_tables.h.(enum_lin_bus_id)
uint8_t frame_index Frame index number or name from enum_lin_frame_id in lin_db_tables.h
NOTE: be sure to use FRAME index only, NOT signal/datapoint index! (enum_lin_frame_id)
uint8_t reset boolean - TRUE (1) clear the flag to detect a new receive, FALSE (0) don't clear the flag to reset it manual
uint8_t return 0 = nothing received
1 = received
example if (lin_check_for_received_header( frame_index )) // TRUE if a header (without payload) was received
{
lin_db_set_value(LIN0_TX_SIGNAL_NAME_1, 0x0F); // update a certain value within the frame to be transmitted
lin_enable_frame_transmission( frame_index ); // enable frame transmission
}
execution Cyclical processing
    • Check for received LIN response frame: 
uint8_t lin_check_for_received_response_frame( uint8_t frame_index );
Parameter Description
ovverview MASTER: Check if a response from a slave was received (subscribed frame).
SLAVE: Check if a frame header from the MASTER was received that requires transmission of a response by the slave (published frame).
NOTE: The corresponding flag has to be cleared manually to enable transmission of the response.This way, the data to be sent can be safely updated before it is actually transmitted.
uint8_t frame_index Frame index number or name from enum_lin_frame_id in lin_db_tables.h
NOTE: be sure to use FRAME index only, NOT signal/datapoint index!
uint8_t return 0 = nothing received
1 = received
example if (lin_check_for_received_response_frame(uint8_t frame_index)) // TRUE if a header (without payload) was received (published frame)
{
lin_db_set_value(LIN0_TX_SIGNAL_NAME_1, 0x0F); // update a certain value within the frame to be transmitted
lin_clear_response_frame_flag(uint8_t frame_index); // clear the flag to enable transmission of the response
}
execution Cyclical processing
    • Check for received LIN request frame: 
uint8_t lin_check_for_received_request_frame( uint8_t frame_index );
Parameter Description
ovverview SLAVE: Check if a complete frame from the MASTER was received.
NOTE: The corresponding flag (request frame flag) has to be cleared manually in some scenarios (see lin_clear_request_frame_flag()).transmitted.
For most applications, using lin_check_for_received_frame( ..., TRUE ) is more convenient for this use case.
uint8_t frame_index Frame index number or name from enum_lin_frame_id in lin_db_tables.h
NOTE: be sure to use FRAME index only, NOT signal/datapoint index!
uint8_t return 0 = nothing received
1 = received
example //SLAVE Mode:
if (lin_check_for_received_request_frame(uint8_t frame_index)) // TRUE if a frame with payload was received (subscribed frame)
{
received_data = lin_db_get_value(LIN0_RX_SIGNAL_NAME_1); // get a value from the received frame
lin_clear
}
execution Cyclical processing
    • Enable LIN transmission: 
uint8_t lin_enable_frame_transmission( uint8_t frame_index );
Parameter Description
ovverview SLAVE: Enable transmission of the slave response data field
NOTE: This just an "alias" for lin_clear_response_frame_flag() with a more descriptive name.
uint8_t frame_index Frame index number or name from enum_lin_frame_id in lin_db_tables.h
NOTE: be sure to use FRAME index only, NOT signal/datapoint index!
uint8_t return 0 = nothing received
1 = received
example lin_enable_frame_transmission(LIN0_FRM_RESP_INDEX_NAME_01);
execution Cyclical processing
    • Clear LIN response frame flag: 
void lin_clear_response_frame_flag( uint8_t frame_index );     // slave mode: after a positive response you need to clear the flag to enable frame transmission
Parameter Description
ovverview MASTER: In master mode, resetting the flag is not strictly necessary.
SLAVE: The response frame flag needs to be cleared to enable transmission of the response data field.
uint8_t frame_index frame index number or name from enum_lin_frame_id in lin_db_tables.h
NOTE: be sure to use FRAME index only, NOT signal/datapoint index!
example lin_clear_response_frame_flag(LIN0_FRM_RESP_INDEX_NAME_01);
execution Cyclical processing
    • Clear LIN request frame flag: 
void lin_clear_request_frame_flag( uint8_t frame_index );
Parameter Description
ovverview This flag needs to be cleared if the detection of newly received frames within a usercode() cycle is required (see example below).
NOTE: Alternatively lin_check_for_received_frame(..., TRUE) can be used for frame reception check and combined automatic clearing of the flag (recommended for most applications).
uint8_t frame_index Frame index number or name from enum_lin_frame_id in lin_db_tables.h
NOTE: be sure to use FRAME index only, NOT signal/datapoint index!
example below
execution Cyclical processing 
// With clearing the flag
void usercode()
{
	// Check #1
	if (lin_check_for_received_request_frame(LIN0_FRM_REQ_INDEX_NAME_01))
	{
		// this is entered if the frame LIN0_FRM_REQ_INDEX_NAME_01 was actually rece
		// clear the flag to re-enable detection of newly received frames
		lin_clear_request_frame_flag(LIN0_FRM_REQ_INDEX_NAME_01);
	// [...]
	// Check #2 (same frame)
	if (lin_check_for_received_request_frame(LIN0_FRM_REQ_INDEX_NAME_01))
	{
		// this is only entered if the frame LIN0_FRM_REQ_INDEX_NAME_01 has been
		// received again between Check #1 and Check #2

// Without clearing the flag
void usercode()
{
	// Check #1
	if (lin_check_for_received_request_frame(LIN0_FRM_REQ_INDEX_NAME_01))
	{
		// this is entered if the frame LIN0_FRM_REQ_INDEX_NAME_01 was actually received
	// [...]
	// Check #2 (same frame)
	if (lin_check_for_received_request_frame(LIN0_FRM_REQ_INDEX_NAME_01))
	{
		// if the flag has not been cleared before, this will be entered even though
		// no new frame has been received between Check #1 and Check #2
	}
}
    • LIN schedule handling: 
void lin_schedule_handling( uint8_t lin_schedule_table_index, uint8_t lin_st_active );     // only as master
Parameter Description
ovverview MASTER only: Schedule the LIN frames as defined in the selected schedule table
uint8_t lin_schedule_table_index The schedule table affected by the reset (lin_db_tables.h)
uint8_t lin_st_active (TRUE/FALSE) - use TRUE to activate the scheduling
NOTE: Only one schedule table may be active at a time! Otherwise the behaviour is undefined.
example lin_schedule_handling(LIN0_SCHEDULE_TABLE_NR1, TRUE);
execution Cyclical processing
    • Reset LIN schedule handling: 
void lin_schedule_handling_reset( uint8_t lin_schedule_table_index );     // only as master
Parameter Description
ovverview MASTER only: Reset the LIN schedule handling (set schedule table index to 0)
uint8_t lin_schedule_table_index The schedule table affected by the reset (lin_db_tables.h)
example lin_schedule_handling_reset(LIN0_SCHEDULE_TABLE_NR1);
execution Cyclical processing
    • Check LIN frame response timeout: 
uint8_t lin_ma_check_frame_resp_timeout( uint8_t frame_index );       // only as master
Parameter Description
ovverview MASTER only: check frame response timeout
uint8_t frame_index Frame index number or name from lin_db_tables.h (enum_lin_frame_id)
return 0 = not timeout reachedTRUE
1 = Slave not responding (timeout)
example if( lin_ma_check_frame_resp_timeout(LIN0_FRM_INDEX_NAME_01) == TRUE )
{
// timeout reached - Slave not responding
}
execution Cyclical processing

UART

    • Send UART buffer: 
enum_HAL_SCI_RETURN_VALUE user_uart_send_buffer( uint8_t *send_buffer[], uint8_t send_lenght );
Parameter Description
uint8_t send_buffer uint8_t buffer
uint8_t send_lenght Number of bytes to send
return 0 if succes
example: uint8_t my_uart_buffer[3];
my_uart_buffer[0] = 0xAB;
my_uart_buffer[1] = 0xBC;
my_uart_buffer[2] = 0xCD;
user_uart_send_buffer(my_uart_buffer, 3);
//or
user_uart_send_buffer(my_uart_buffer, sizeof(my_uart_buffer));
execution Immediate
    • Read UART buffer: 
void user_int_rx_sci( uint8_t instance, uint8_t data );
Parameter Description
instance Device instance
data Receiving data
example void user_int_rx_sci(uint8_t instance, uint8_t data)
{
static uint8_t byte_array[32] = {0};
static uint8_t byte_cnt = 0;
byte_array[byte_cnt] = data;
byte_cnt++;
}
execution Immediate
    • Brief information on read UART buffer:
      The function reads the received bytes from the RX buffer of SCI0, it is called, byte by byte.
    • Change UART baudrate: 
enum_HAL_SCI_RETURN_VALUE user_uart_set_baudrate(uint8_t uart_interface, enum_HAL_SCI_BAUD baudrate);
Parameter Description
uart_interface uart instance
baudrate Receiving data
example enum_HAL_SCI_RETURN_VALUE err;
{
uint8_t uart_interface = 2;
enum_HAL_SCI_BAUD baudrate = HAL_SCI_BAUD_19200;
err = user_uart_set_baudrate(uart_interface, baudrate);
}
execution Immediate
    • Change UART parameter: 
enum_HAL_SCI_RETURN_VALUE user_uart_set_config_parameter(uint8_t uart_interface, lpuart_parity_mode_t parity, lpuart_stop_bit_count_t stop_bit, lpuart_bit_count_per_char_t bit_per_char );
Parameter Description
uart_interface Device instance
parity parity mode
stop_bit amount of bits per stop bit
bit_per_char amount of bits per char
example enum_HAL_SCI_RETURN_VALUE err;
{
uint8_t uart_interface = 2;
lpuart_parity_mode_t parity = LPUART_PARITY_DISABLED;
lpuart_stop_bit_count_t stop_bit = LPUART_ONE_STOP_BIT;
lpuart_bit_count_per_char_t bit_per_char = LPUART_8_BITS_PER_CHAR
err = user_uart_set_config_parameter(uart_interface, parity, stop_bit, bit_per_char );
}
execution Immediate

Time Behaviour

    • Set timestamp: 
uint8_t user_timer_set_timestamp( uint32_t *timestamp, enum_PRECISION precision );
Parameter Description
uint32_t* timestamp Pointer to uint32_t user timestamp
enum_PRECISION precision Precision from user_api_timer.c s (enum_PRECISION).
Only values greater than 1ms are supported.
return 0 if success
example uint32_t my_timestamp_0;
user_timer_set_timestamp(&my_timestamp_0, PRECISION_1MS);
execution Immediate
    • Get passed time: 
uint8_t user_timer_time_elapsed( uint32_t timestamp_t0, 
                                 uint32_t span,
                                 enum_PRECISION precision );
Parameter Description
uint32_t timestamp_t0 user timestamp
span Period of time
enum_PRECISION precision Precision from user_api_timer.c s (enum_PRECISION)
Precision should be the same as in user_timer_set_timestamp(...)
Only values greater than 1ms are supported.
return 1 when time has passed
example if(user_timer_time_elapsed(my_timestamp_0, 500, PRECISION_1MS))
{
// do something ...
user_timer_set_timestamp(&my_timestamp_0, PRECISION_1MS); // reset timestamp
}
execution Immediate
    • Get roundtrip time: 
uint8_t user_timer_get_prog_cycletime( uint32_t *roundtrip_time,
                                       enum_PRECISION precision,
                                       uint8_t reset_start );
Parameter Description
uint32_t* timestamp_t0 Pointer to uint32_t user timestamp
enum_PRECISION precision Precision from user_api_timer.c s (enum_PRECISION)
Precision should be the same as in user_timer_set_timestamp(...)
Only values greater than 1ms are supported.
reset_start boolean
return 1 when time has passed
example uint32_t roundtrip_time;
user_timer_get_prog_cycletime(&roundtrip_time, PRECISION_1MS, 0);
//.. code ..
user_timer_get_prog_cycletime(&roundtrip_time, PRECISION_1MS, 1);
execution Immediate

EEPROM

  1. General info on the EEPROM: The EEPROM size of the S32K MCU is 4096 bytes in total. The EEPROM is split in half to manage the factory data of the module and the user data. The first 2048 bytes are reserved for factory data, module data, configuration data and calibration data. This EEPROM area is read only. The second part, byte 2048 to byte 4095, is reserved for user data. Only this area is available for the customer to use (read/write).

To use the user area of the EEPROM the two functions below are provided. To access any given area of the user EEPROM the parameter "address" can be set to a value between 0 and 2047. This relative address value is then converted to the absolute value of the user EEPROM space by adding the resembling offset. The calculating of the offset as well as the verification of accessing the EEPROM within its limits is performed by the user_api functions.

You can transfer the data as dec or as hex value for writing to the EEPROM. In the EEPROM itself, these are saved as hex.


    • Write data to the EEPROM user area: 
uint8_t user_eeprom_write( uint32_t addr, 
                           uint32_t len, 
                           const uint8_t *ptr_data );
Parameter Description
uint32_t addr Address from which is written. Value between 0 and 2047.
uint32_t len How many bytes will be written
const uint8_t* ptr_data Pointer to the data for writing
return 0 if success
example uint8_t write_val[2];
write_val[0] = 4;
write_val[1] = 2;
user_eeprom_write(0, 2, &write_val[0]);
execution Immediate
    • Read data from the EEPROM user area: 
uint8_t user_eeprom_read( uint32_t addr, 
                          uint32_t len, 
                          uint8_t *ptr_data);
Parameter Description
uint32_t addr Address from which is read. Value between 0 and 2047.
uint32_t len How many bytes will be read.
const uint8_t* ptr_data Pointer to the data which will be read.
return 0 if success
example uint8_t read_val[2];
user_eeprom_read(0, 2, &read_val[0]);
execution Immediate
    • Read EEPROM version 
uint16_t user_eeprom_read_module_eeprom_version();
Parameter Description
return EEPROM version number
example uint16_t eeprom_version;
eeprom_version = user_eeprom_read_module_eeprom_version();
execution Immediate
    • Read module id

NOTE: Currently unsupported. Reserved for future use.

uint16_t user_eeprom_read_module_uuid();
Parameter Description
return the id of the module
example uint16_t module_uuid;
module_uuid = user_eeprom_read_module_uuid();
execution Immediate
    • Read serial number 
uint32_t user_eeprom_read_module_serial_nr();
Parameter Description
return the serial number of the module
example uint32_t serial_nr;
serial_nr = user_eeprom_read_module_serial_nr();
execution Immediate
    • Read part number 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_module_part_nr(uint8_t buffer[], 
                                                          uint8_t size_buffer, 
                                                          bool filter);
Parameter Description
uint8_t buffer[] buffer for the part number, coded as ASCII
uint8_t size_buffer The length of the buffer, must be at least 21 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t part_nr[21];
user_eeprom_read_module_part_nr(part_nr, sizeof(part_nr), true);
execution Immediate
    • Read drawing number 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_module_drawing_nr(uint8_t buffer[], 
                                                             uint8_t size_buffer, 
                                                             bool filter);
Parameter Description
uint8_t buffer[] buffer for the drawing number, coded as ASCII
uint8_t size_buffer The length of the buffer, must be at least 21 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t draw_nr[21];
user_eeprom_read_module_drawing_nr(draw_nr, sizeof(draw_nr), true);
execution Immediate
    • Read module name of the device 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_module_name(uint8_t buffer[], 
                                                             uint8_t size_buffer, 
                                                             bool filter);
Parameter Description
uint8_t buffer[] buffer for the device name, coded as ASCII
uint8_t size_buffer The length of the buffer, must be at least 41 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t device_name[41];
user_eeprom_read_module_name(device_name, sizeof(device_name), true);
execution Immediate
    • Read production order number of the module 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_module_order_nr(uint8_t buffer[], 
                                                           uint8_t size_buffer, 
                                                           bool filter);
Parameter Description
uint8_t buffer[] buffer for the order number, coded as ASCII
uint8_t size_buffer The length of the buffer, must be at least 21 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t order_nr[21];
user_eeprom_read_module_order_nr(order_nr, sizeof(order_nr), true);
execution Immediate
    • Read test date of the module 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_module_test_date(uint8_t buffer[], 
                                                            uint8_t size_buffer, 
                                                            bool filter);
Parameter Description
uint8_t buffer[] buffer for the test date, coded as ASCII. DD.MM.YYYY
uint8_t size_buffer The length of the buffer, must be at least 13 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t test_date[13];
user_eeprom_read_module_test_date(test_date, sizeof(test_date), true);
execution Immediate
    • Read MCU type

Note: Used for internal reference

uint16_t user_eeprom_read_module_mcu_type();
Parameter Description
return mcu type number
example uint16_t mcu_type;
mcu_type = user_eeprom_read_module_mcu_type();
execution Immediate
    • Read hardware version 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_module_hw_version(uint8_t buffer[], 
                                                             uint8_t size_buffer, 
                                                             bool filter);
Parameter Description
uint8_t buffer[] Buffer to write the data into, coded as ASCII
uint8_t size_buffer The length of the buffer, must be at least 3 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t hw_version[3];
user_eeprom_read_module_hw_version(hw_version, sizeof(hw_version), true);
execution Immediate
    • Read available can interfaces 
uint16_t user_eeprom_read_module_hw_can_active();
Parameter Description
return Returns the available can interfaces of the module
0x00 oder 0xFF = invalid
0x01 = CAN0 available
0x03 = CAN0+1 available
example uint16_t can_interfaces;
can_interfaces = user_eeprom_read_module_hw_can_active();
execution Immediate
    • Read bootloader version 
uint16_t user_eeprom_read_module_bootloader_version();
Parameter Description
return Bootloader version of the module
example uint16_t bl_version;
bl_version = user_eeprom_read_module_bootloader_version();
execution Immediate
    • Read reset counter

Note: Only for internal use

uint16_t user_eeprom_read_module_reset_counter();
Parameter Description
return reset counter of the
behavior will differ between modules and so the counter can also behave different module to module
example uint16_t reset_counter;
reset_counter = user_eeprom_read_module_reset_counter();
execution Immediate
    • Read the reset reason

Note: Currently unsupported. Reserved for future use.

uint16_t user_eeprom_read_module_reset_reason();
Parameter Description
return reset reason of the module (coded in binary).
meaning of bytes:
0: Low-Voltage Detect count
1: Loss of Clock count
2: Illegal Address count
3: Illegal Opcode count
4: COP count
example uint16_t reset_reason;
reset_reason = user_eeprom_read_module_reset_reason();
execution Immediate
    • Read the program status 
uint16_t user_eeprom_read_module_prog_status();
Parameter Description
return program status of the module
0 = OK,
1 = parameter error,
2 = error reset,
3 = stopped by user,
4 = stopped by MRS master
example uint16_t prog_state;
reset_reason = user_eeprom_read_module_prog_status();
execution Immediate
    • Read application name 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_app_name(uint8_t* buffer,
                                                    uint8_t size_buffer, 
                                                    bool filter);
Parameter Description
uint8_t buffer[] buffer for the application name, coded as ASCII chars
uint8_t size_buffer The length of the buffer, must be at least 21 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t app_name[21];
user_eeprom_read_app_name(app_name, sizeof(app_name), true);
execution Immediate
    • Read application version 
enum_HAL_NVM_RETURN_VALUE user_eeprom_read_app_version(uint8_t* buffer,
                                                       uint8_t size_buffer, 
                                                       bool filter);
Parameter Description
uint8_t buffer[] buffer for the application version, coded as ASCII chars
uint8_t size_buffer The length of the buffer, must be at least 31 bytes
bool filter "false" to read the raw data or set to "true" to filter unnecessary characters (whitespace)
return 0 = success, 3 = error during read operation., 8 = data length invalid
example uint8_t app_version[31];
user_eeprom_read_app_version(app_version, sizeof(app_version), true);
execution Immediate
    • Write application name and version 
enum_HAL_NVM_RETURN_VALUE user_eeprom_write_app_info(const uint8_t *app_name, 
                                                     const uint8_t *app_version);
Parameter Description
const uint8_t *app_name pointer for the application name
const uint8_t *app_version pointer for the application version
return 0 = success
example uint8_t app_name[21] = {"test_application"}; uint8_t app_version[31] = {"V1.0.0"}
user_eeprom_write_app_info(app_name, app_version);
execution Immediate
    • Read the cop watchdog timeout value

Note: Only for internal use

uint16_t user_eeprom_read_module_cop_wd_timeout();
Parameter Description
return cop watchdog timeout value
example uint16_t cop;
cop = user_eeprom_read_module_prog_status();
execution Immediate

Look Up Table

    • 1D lookup table: 
uint16_t user_util_get_lookup_value_1D_16( int16_t *table_x, 
                                           int16_t *table_y,
                                           uint8_t count,
                                           int16_t val,
                                           uint8_t mode );
uint32_t user_util_get_lookup_value_1D_32( int32_t *table_x,
                                           int32_t *table_y,
                                           uint8_t count,
                                           int32_t val,
                                           uint8_t mode );
Parameter Description
*table_x Pointer x-array (1D)
*table_y Pointer y-array (1D)
count Counts of x-array elements
val x-value
mode LUT_MODE_EXTRAPOLATION (Standard): away from the array extrapolate
LUT_MODE_LIMIT: away from the array not extrapolate
LUT_MODE_KALIBRATION: y-value always >= 0, extrapolating upwards with difference (y_max - x_max)
return uint16_t y-value
uint32_t y-value
example uint16_t ret_val_1d;
int16_t arr_x_1d[] = {136,200,311,444,666};
int16_t arr_y_1d[] = {-10,5,16,27,39};
ret_val_1d = user_util_get_lookup_value_1D_16(arr_x_1d, arr_y_1d, 5, 250, LUT_MODE_EXTRAPOLATION);
execution Immediate
    • 2D lookup table: 
uint16_t user_util_get_lookup_value_2D_16( int16_t *table_x,
                                           int16_t *table_y,
                                           uint8_t count_x,
                                           uint8_t count_y,
                                           int16_t *table_z,
                                           int16_t val_x,
                                           int16_t val_y );
uint32_t user_util_get_lookup_value_2D_32( int32_t *table_x,
                                           int32_t *table_y,
                                           uint8_t count_x,
                                           uint8_t count_y,
                                           int32_t *table_z,
                                           int32_t val_x,
                                           int32_t val_y );
Parameter Description
*table_x Pointer x-array (1D)
*table_y Pointer y-array (1D)
count_x [in] Counts of x-array elements
count_y [in] Counts of y-array elements
*table_z [in] Pointer z-array (1D with (count_y * count_x) elements)
val_x [in] x-value (away from the x-array => extrapolation)
val_y [in] y-value (away from the y-array => extrapolation)
return uint16_t z-value
uint32_t z-value
example uint16_t ret_val_2d;
int16_t arr_x_2d[] = {10,20,30,40,50};
int16_t arr_y_2d[] = {100,200,300};
int16_t arr_z_2d[] = {10, 20, 50, 90,150,
25, 70, 150,250,400,
50, 120, 240,400,860};
ret_val_2d = user_util_get_lookup_value_2D_16(arr_x_2d, arr_y_2d, 5, 3, arr_z_2d, 25, 270);
execution Immediate

System

    • System soft reset: 
void user_system_soft_reset();
Parameter Description
return void
example user_system_soft_reset();
execution Immediate

This function is used to initiate a system reset