OBD-II Server Stack

Overview

RAPIDSEA supports ISO15031 protocol as explained in the ISO15031 - OBD Protocol page. This page explains the server architecture and details how the user should interface the stack with their custom logic and realize the ECU implementation quickly. It also provides guidelines on adopting the stack for different systems.

The below diagram captures the block level diagram of the DoCAN OBD server and how it interfaces with other modules.

DoCAN OBD Stack Block Diagram

DoCAN Interface

The OBD server communicates over the CAN network through the underlying DoCAN stack (ISO15765). This DoCAN stack is also available as part of the RAPIDSEA components. All the functions that are needed are available as part of the DoCAN stack and has to be compiled together.

DoCAN Interface

Mode

Description

rs_iso15765_*

Set of functions called by OBD server to perform operation such as initialize, transmit messages etc

rs_obd_server_docan_callback

Callback function called by the DoCAN layer to inform of Data Indication, error etc

These details with respect to the DoCAN interface are covered in detail in the ISO15765 - DoCAN Protocol page.

Application Interface

While the RAPIDSEA OBD server stack can handle most of the functionality such as message validation, session management, timing control etc, the business logic has to implement the application functionality. the RAPIDSEA OBD server clearly defines API and callback functions that are essential for the user to use/implement.

The below table captures the function that are to be called from the application logic.

API Functions

Function

Description

rs_obd_server_open

To initialize the OBD server stack

rs_obd_server_set_p2_timing

To setup the P2 timing associated with the server

rs_obd_server_process

To be called periodically to process the incoming/outgoing messages

There are many functions through which the OBD server stack retrieves information from the application logic or indicate actions to be performed. These functions are captured in the below table.

Callback Functions

Function

Description

rcb_obd_server_01h_req_current_diag_data

Called to indicate request Current Diagnostic Data

rcb_obd_server_02h_request_freeze_frame_data

Called to indicate request Freeze Frame Data

rcb_obd_server_03h_req_diag_trouble_code

Called to indicate request Diagnostic Trouble Codes

rcb_obd_server_04h_clear_dtc

Called to Clear/Reset Diagnostic Trouble Codes and information

rcb_obd_server_05h_req_oxygen_sensor_monitoring

Called to indicate request Oxygen Sensor Monitoring Test Results

rcb_obd_server_06h_req_on_board_monitoring

Called to indicate request On-Board Monitoring Test Results for Specific Monitored Systems

rcb_obd_server_07h_req_emission_diag_trouble_code

Called to indicate request Emission-Related Diagnostic Trouble Codes Detected During Current or Last Completed Driving Cycle

rcb_obd_server_08h_req_ctrl_of_on_board_system

Called to indicate request Control of On-Board System, Test or Component

rcb_obd_server_09h_req_vehicle_information

Called to indicate request vehicle information

These functions are documented in detail in the below sections. It is important for the server to implement these functions correct for proper operation of the system.

Implementation Guide

This section explains how the OBD server can be implemented using the RAPIDSEA stack. Whether the stack is available in source form or in binary form, the steps to be followed are

  • Implement the Callback functions mentioned above

  • Implement the underlying rs_can_* functions for DoCAN as per the underlying hardware design as described in the CAN Interface page.

  • Initialize the buffers necessary for the operation

  • Initialize the CAN, ISO15765 and ISO15031 stack function for DoCAN.

  • Periodically call the process functions so that internal timeouts are handled.

High level flow chart is depicted below for DoCAN:

DoCAN OBD Server Flow Diagram

This can be implemented in a bare-metal system or over RTOS or over full fledged OS such as Linux etc.

Dependency

This stack depends on the below RAPIDSEA interfaces that can be obtained or custom implemented.

Example demo

An example implementation is available along with the release and is described in DoCAN OBD-II Server Demo.

OBD Header Details

Documentation from the relevant header as follows:

ISO15031 OBD Server Module.

This file contains the APIs for using ISO15031 defined obd server module

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_OBD_SERVER_MAX_NUM_RX_MSGS

Number of receive messages that can be buffered during reception.

Typedefs

typedef struct tag_rs_obd_server_config rs_obd_server_config_t

Contains information about server configuration.

typedef struct tag_rs_obd_server_instance rs_obd_server_instance_t

Contains information about server instance.

Functions

rs_handle_t rs_obd_server_open(rs_obd_server_instance_t *ptr_instance, rs_obd_server_config_t *ptr_config)

Initializes the obd server stack.

This function initializes the obd stack for server operation

Parameters:

  • ptr_instance – [in] - Pointer to the OBD server instance information

  • ptr_config – [in] - Pointer to the OBD server configuration

Returns:

Handle of the OBD server instance information which include configuration information also

rs_ret_val_t rs_obd_server_process(rs_handle_t obd_server_handle)

Function to be called periodically to process underlying obd server state machines.

This function is to be called at not more than 5 ms interval

Parameters:

obd_server_handle – [in] - Handle to the OBD server instance

Returns:

None

rs_ret_val_t rs_obd_server_set_p2_timing(rs_obd_server_config_t *ptr_config, uint16_t u16_p2_server, uint16_t u16_p2_ext_server)

Configures the obd server stack P2 timings.

This function sets the P2 timings for the obd server stack

Parameters:

  • ptr_config – [in] - Pointer to the obd server configuration

  • u16_p2_server – [in] - P2 server time

  • u16_p2_ext_server – [in] - P2 extended server time

Returns:

Return code

rs_ret_val_t rcb_obd_server_01h_req_current_diag_data(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request Current Diagnostic Data.

This function Request the Current Diagnostic Data

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_PID_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_02h_request_freeze_frame_data(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request Freeze Frame Data.

This function Request Freeze Frame Data

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_PID_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_03h_req_diag_trouble_code(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request Diagnostic Trouble Codes.

This function Request Diagnostic Trouble Codes

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_04h_clear_dtc(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Clear/Reset Diagnostic Trouble Codes and information.

This function Clear/Reset Diagnostic Trouble Codes and information

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_05h_req_oxygen_sensor_monitoring(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request Oxygen Sensor Monitoring Test Results.

This function Request Oxygen Sensor Monitoring Test Results

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_06h_req_on_board_monitoring(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request On-Board Monitoring Test Results for Specific Monitored Systems.

This function On-Board Monitoring Test Results for Specific Monitored Systems

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_07h_req_emission_diag_trouble_code(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request Emission-Related Diagnostic Trouble Codes Detected During Current or Last Completed Driving Cycle.

This function Request Emission-Related Diagnostic Trouble Codes Detected During Current or Last Completed Driving Cycle

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_08h_req_ctrl_of_on_board_system(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_resp_data, uint8_t *ptr_resp_len)

Request Control of On-Board System, Test or Component.

This function Request Control of On-Board System, Test or Component

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rcb_obd_server_09h_req_vehicle_information(rs_handle_t obd_server_handle, uint8_t u8_pid_num, uint8_t *ptr_data, uint16_t *ptr_data_len)

Request the vehicle information.

This function Request the vehicle information

Parameters:

  • obd_server_handle – [in] - Handle to the OBD server instance

  • u8_pid_num – [in] - Requested PID number

  • ptr_resp_data – [out] - Pointer to response buffer

  • ptr_resp_len – [out] - Pointer to response length

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rs_obd_server_close(rs_handle_t obd_handle)

Function to free the OBD handle.

This function used to free the OBD handle

Parameters:

obd_handle – [in] - Handle of the server instance information

Returns:

Return 0 on success or error code on failure

struct tag_rs_obd_server_config
#include <rs_obd_server.h>

Contains information about server configuration.

Public Members

uint16_t p2_server

Server Response time.

uint16_t p2_ext_server

Server Extended Response time.

uint32_t session_timeout

Session timeout.

uint8_t session_id

Active Session.

struct tag_rs_obd_server_instance
#include <rs_obd_server.h>

Contains information about server instance.

Public Members

rs_handle_t tp_handle

Transport Handle with corresponding type (DoIP/ DoCAN)

rs_obd_server_config_t *ptr_obd_server_config

Contains information about server configuration.

rs_buffer_mgr_t rx_msg_mgr

RX message FIFO.

void *arr_rx_msgs[RS_OBD_SERVER_MAX_NUM_RX_MSGS]

Pointer array to hold incoming messages.

rs_search_mgr_t si_search_mgr

Search manager for service handlers lookup.

rs_an_tp_msg_t *ptr_cur_proc_msg

For P2 handling.

uint32_t last_active_time

Session activity timer.

uint32_t last_resp_time

Time last resp was sent to track P2.

uint8_t extend_timing

P2 Extension mode.