DoIP (ISO13400) Client Stack

DoIP Client Overview

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

The below diagram captures the block level diagram of the DoIP client and how it interfaces with other modules.

DoIP Client Block Diagram

Application Interface

While the RAPIDSEA DoIP client stack can handle most of the functionality such as message validation,vehicle identification process, routing activation process, Diagnostic response messages handling etc, the business logic has to implement the application functionality. The RAPIDSEA DoIP client 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_iso13400_client_open

To initialize the DoIP client instance structure for both UDP and TCP process.

rs_iso13400_client_timer_init

To initialize the DoIP client timer

rs_iso13400_client_run

To be called to set the run state for state machine for both UDP and TCP process.

rs_iso13400_client_udp_set_tx_msg_buf

To set up the transmit buffers to be used for the DoIP client UDP communication

rs_iso13400_client_udp_set_rx_msg_buf

To set up the receive buffers to be used for the DoIP client UDP communication.

rs_iso13400_client_tcp_set_tx_msg_buf

To set up the transmit buffers to be used for the DoIP client TCP communication

rs_iso13400_client_tcp_set_rx_msg_buf

To set up the receive buffers to be used for the DoIP client TCP communication.

rs_iso13400_client_set_tx_msg_buf

To set up the transmit buffers to be used for the DoIP client and UDS communication.

rs_iso13400_client_set_rx_msg_buf

To set up the receive buffers to be used for the DoIP client and UDS communication.

rs_iso13400_client_comm_process

To be called periodically to process the incoming/outgoing messages of both UDP and TCP process.

rs_iso13400_client_process

To be called periodically to get the request from the UDS stack and frame doip layer on top of UDS request and sent to server.

rs_iso13400_client_close

To be called to release the DoIP client handle

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

Implementation Guide

This section explains how the DoIP client 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

  • Initialize the buffers necessary for the operation

  • Initialize the DoIP stack function.

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

High level flow chart is depicted below:

DoIP Client Flow Diagram

The below diagram captures the high level sequence of operations associated with the DoIP client stack.

DoIP Client High level Sequence 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 DoIP UDS Client Demo.

DoIP Client Header

Documentation from the relevant header as follows:

ISO13400 DoIP Module.

This file contains the APIs for using ISO13400 defined DOIP client Module

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Typedefs

typedef struct tag_rs_iso13400_client_config rs_iso13400_client_config_t

Contains information about ISO13400 client configuration.

typedef struct tag_rs_iso13400_udp_client_info rs_iso13400_udp_client_info_t

Contains information about ISO13400 UDP client information.

typedef struct tag_rs_iso13400_tcp_client_info rs_iso13400_tcp_client_info_t

Contains information about ISO13400 TCP client information.

typedef struct tag_rs_iso13400_client_instance rs_iso13400_client_instance_t

Contains information about ISO13400 client instance.

Functions

rs_handle_t rs_iso13400_client_open(rs_iso13400_client_instance_t *ptr_instance, rs_iso13400_client_config_t *ptr_config)

Initialize the DoIP client instance structure with initial values.

This function initialize the DoIP client instance structure with initial values.

Parameters:

  • ptr_instance – [in] - pointer to the DoIP client instance information

  • ptr_config – [in] - pointer to the DoIP configuration information

Returns:

Handle of the DoIP client instance information which include configuration information also

rs_ret_val_t rs_iso13400_client_timer_init(rs_handle_t doip_handle, rs_doip_timer_config_t *ptr_timer_cfg)

Initialize the DoIP client timer.

Initialize the DoIP client timer configuration

Parameters:

  • doip_handle – [in] - handle of the DOIP client instance

  • ptr_timer_cfg – [in] - Pointer to the timer configuration

Returns:

0 on success or error code on failure

rs_ret_val_t rs_iso13400_client_run(rs_handle_t doip_handle, uint32_t u32_run)

Assign the initial state of the state machine for both UDP and TCP.

This function assigns the initial state of the state machine for both UDP and TCP.

Parameters:

  • doip_handle – [in] - Handle of the DoIP client instance information

  • u32_run – [in] - state will be set according to this value.

Returns:

Zero on success or negative error code on failure.

rs_ret_val_t rs_iso13400_client_udp_set_tx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the transmit buffers to be used for the DoIP client UDP communication.

This function sets up the transmit buffers to be used for DoIP client UDP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP client instance information.

  • ptr_tx_msgs – [in] - Pointer to the array of DoIP transmit messages

  • u32_num_msg – [in] - Number of transmit messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_client_tcp_set_tx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the transmit buffers to be used for the DoIP client TCP communication.

This function sets up the transmit buffers to be used for DoIP client TCP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP client instance information.

  • ptr_tx_msgs – [in] - Pointer to the array of DoIP transmit messages

  • u32_num_msg – [in] - Number of transmit messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_client_udp_set_rx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_rx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the receive buffers to be used for the DoIP client UDP communication.

This function sets up the receive buffers to be used for DoIP client UDP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP instance information

  • ptr_rx_msgs – [in] - Pointer to the array of DoIP receive messages

  • u32_num_msg – [in] - Number of receive messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_client_tcp_set_rx_msg_buf(rs_handle_t doip_handle, rs_doip_msg_t *ptr_rx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the receive buffers to be used for the DoIP client TCP communication.

This function sets up the receive buffers to be used for DoIP client TCP communication.

Parameters:

  • doip_handle – [in] - handle of DoIP instance information

  • ptr_rx_msgs – [in] - Pointer to the array of DoIP receive messages

  • u32_num_msg – [in] - Number of receive messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_client_set_tx_msg_buf(rs_handle_t doip_handle, rs_an_tp_msg_t *ptr_tx_msgs, uint32_t u32_num_msg, void *ptr_msg_ptr_buf)

Set up the transmit buffers to be used for the DoIP client and UDS communication.

This function sets up the transmit buffers to be used for DoIP client and UDS communication.

Parameters:

  • doip_handle – [in] - handle of DoIP client instance information.

  • ptr_tx_msgs – [in] - Pointer to the array of DoIP transmit messages

  • u32_num_msg – [in] - Number of transmit messages that the DoIP stack can use from the above array

  • ptr_msg_ptr_buf – [in] - Pointer to the message pointer buffer

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_client_set_rx_msg_buf(rs_handle_t doip_handle, rs_an_tp_msg_t *ptr_rx_msgs, uint32_t u32_num_msg)

Set up the receive buffers to be used for the DoIP client stack.

This function sets up the receive buffers to be used for DoIP client stack

Parameters:

  • doip_handle – [in] - handle of DoIP client instance information.

  • ptr_rx_msgs – [in] - Pointer to the array of DoIP receive messages

  • u32_num_msg – [in] - Number of receive messages that the DoIP stack can use from the above array

Returns:

Zero or negative error code

rs_ret_val_t rs_iso13400_client_process(rs_handle_t doip_handle)

Frame and sent request messages to DoIP server.

This function frame and sent request messages to DoIP server.

Parameters:

doip_handle – [in] - handle of DoIP client instance information.

Returns:

None

rs_ret_val_t rs_iso13400_client_comm_process(rs_handle_t doip_handle)

Called to call the UDP and TCP’s state machine and process respectively.

This function called to call the UDP and TCP’s state machine and process respectively.

Parameters:

doip_handle – [in] - Handle of the DoIP instance information

Returns:

Return 0 if success or negative value if failure.

rs_ret_val_t rs_iso13400_client_close(rs_handle_t doip_handle)

Called to free the DoIP client handle.

This function called to free the DoIP client handle.

Parameters:

doip_handle – [in] - Handle of the DoIP instance information

Returns:

Return 0 if success or negative value if failure.

struct tag_rs_iso13400_client_config
#include <rs_iso13400_client.h>

Contains information about ISO13400 client configuration.

Public Members

uint16_t port_num

Port number of server.

uint8_t ip_addr[RS_13400_MAX_BUFFER_LENGTH]

IP address of server.

uint8_t broadcast_addr[RS_13400_MAX_BUFFER_LENGTH]

IP address for broadcast.

uint16_t broadcast_port_num

Port number for broadcast.

uint16_t client_src_addr

Client’s source address.

uint8_t vin[RS_ISO13400_VIN_LEN]

Vehicle identification number.

uint16_t logical_addr

Logical Address.

uint64_t eid

Entity identification number (6bytes only)

uint64_t gid

Group identification number (6bytes only)

uint8_t far_val

further action required

uint8_t vehic_identy_req_type

vehicle identification request type (with VIN or EID or nothing)

uint16_t cli_target_addr

DoIP client’s target address.

struct tag_rs_iso13400_udp_client_info
#include <rs_iso13400_client.h>

Contains information about ISO13400 UDP client information.

Public Members

rs_socket_config_t udp_socket_config

UDP socket configuration.

rs_udp_instance_t udp_socket_instance

UDP socket instance(information)

uint32_t data_len

Data length of RX/TX packet.

uint8_t state

UDP process state.

uint8_t data_buff[RS_13400_BUF_SIZE]

Buffer for RX/TX.

rs_buffer_mgr_t tx_buf_mgr

Transmit buffer manager.

rs_buffer_mgr_t rx_buf_mgr

Receive buffer manager.

rs_buffer_mgr_t rx_msg_queue_mgr

RX message FIFO.

rs_buffer_mgr_t tx_msg_queue_mgr

TX message FIFO.

struct tag_rs_iso13400_tcp_client_info
#include <rs_iso13400_client.h>

Contains information about ISO13400 TCP client information.

Public Members

rs_socket_config_t tcp_socket_config

TCP socket configuration.

rs_tcp_conn_instance_t tcp_socket_instance

TCP socket instance(information)

uint32_t data_len

Data length of RX/TX packet.

uint8_t state

TCP process state.

uint8_t data_buff[RS_13400_BUF_SIZE]

Buffer for RX/TX.

uint8_t run_state

TCP run state.

rs_buffer_mgr_t tx_buf_mgr

Transmit buffer manager.

rs_buffer_mgr_t rx_buf_mgr

Receive buffer manager.

rs_buffer_mgr_t rx_msg_queue_mgr

RX message FIFO.

rs_buffer_mgr_t tx_msg_queue_mgr

TX message FIFO.

struct tag_rs_iso13400_client_instance
#include <rs_iso13400_client.h>

Contains information about ISO13400 client instance.

Public Members

rs_an_tp_instance_t an_tp_instance

Common instance DoCAN/DoIP(Information)

rs_iso13400_client_config_t *ptr_doip_client_config

Pointer to the DoIP client configuration.

rs_iso13400_udp_client_info_t iso13400_udp_client_info

DoIP UDP client information.

rs_iso13400_tcp_client_info_t iso13400_tcp_client_info

DoIP TCP server information.

rs_handle_t tcp_comm_handle

Transport interface handle for TCP.

rs_handle_t udp_comm_handle

Transport interface handle for UDP.

uint8_t run_state

DoIP client run state.

rs_doip_timer_config_t *ptr_doip_timer

pointer to the DoIP timer configuration

rs_doip_data_t *ptr_cur_tx_data

DoIP Data being transmitted.

uint8_t diag_pow_mode_state

DoIP Diagnostics power mode state.