ISO15765 - DoCAN Protocol

DoCAN Overview

ISO 15765 (ISO-TP or DoCAN) is an international standard for sending data packets over a CAN-Bus that exceed the eight byte maximum payload of CAN frames. ISO-TP segments longer messages into multiple frames, adding metadata that allows the interpretation of individual frames and reassembly into a complete message packet by the recipient allowing up to 4GB of transfers.

Embien offers its implementation of the protocol via the RAPIDSEA DoCAN stack. Some of the major features of the stack are

  • Support for both SF, FF, CF and FC

  • Support for various timing configuration

  • Multi-message filtering

  • Up to 4095 bytes transfer support

  • MISRA-C compliant ANSI C source code

  • Can be used with or without RTOS

  • Can support 8, 16, 32, 64-bit CPUs

As captured in the below diagram, the DoCAN stack is typically accessed by the higher level application stack like UDS and this in-turn calls the lower level CAN HAL.

DoCAN Stack in UDS

Using DoCAN

This section covers the details of how to use the DoCAN stack. Essentially the DoCAN is responsible for framing of packets and de-framing of packets of large messages over smaller CAN frames. It employs frames such as SingleFrame (SF), FirstFrame(FF), ConsecutiveFrame(CF) and FlowControl(FC) packets to manage the message flow.

As it is message oriented, the RAPIDSEA DoCAN stack has to be provided with the buffers during initialization. The size of the buffers can be determined by the user based on their application requirement. For example, if 4096 message size has to be supported, each of the buffer must be of at least this size plus a few more.

When the higher level application layer wants to transfer a message, it should first request one from the DoCAN layer, fill it with data and queue it for transmission. Then the DoCAN stack sends the message over one or more frames and informs the caller of the status of the transfer. Similarly when an incoming message is received, DoCAN consolidates it over multiple frames in a single message and provides it to the application layer as a single message.

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

API Functions

Function

Description

rs_iso15765_open

To initialize the ISO15765 DoCAN stack

rs_iso15765_set_tx_msg_buf

To assign buffers for transmission

rs_iso15765_set_rx_msg_buf

To assign buffers for reception

rs_iso15765_release_transmit_msg

To release the transmit buffer of DoCAN message

rs_iso15765_rx_buffer_handled

To indicate successful processing of received message

rs_iso15765_register_callback

Registers callback function to be called on events

rs_iso15765_process

To be periodically called for internal processing

rs_iso15765_close

To free the DoCAN handle

The details of these functions are covered in the below sections.

The application logic should call the rs_can_init function and use the returned handle when initializing the DoCAN stack.

The below table captures the function that are called from the DoCAN Stack.

Called Functions

Function

Description

rs_can_register_callback

Registers the ISO15765 DoCAN stack call back with the CAN layer

rs_can_get_transmit_buf

To get CAN buffers for transmission

rs_can_transmit

To transmit CAN buffers

More details of these CAN related functions are available in the CAN Interface page.

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

DoCAN Sequence Diagram

Refer to the ISO14229 - UDS Protocol page for an example about how the RAPIDSEA UDS stack uses the DoCAN.

Dependency

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

DoCAN Header Details

Documentation from the relevant header as follows:

ISO15765 DoCAN Module.

This file contains the APIs for using ISO15765 defined DoCAN module used for UDS and OBD communication

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_ISO15765_SERVICE_COMM_DATA_REQ

N_USData.request.

RS_ISO15765_SERVICE_COMM_DATA_FF_INDICATION

N_USData_FF.indication.

RS_ISO15765_SERVICE_COMM_DATA_INDICATION

N_USData.indication.

RS_ISO15765_SERVICE_COMM_DATA_CONFIRM

N_USData.confirm.

RS_ISO15765_SERVICE_CHANGE_PARAM_REQ

N_ChangeParameter.request.

RS_ISO15765_SERVICE_CHANGE_PARAM_CONFIRM

N_ChangeParameter.confirm.

RS_ISO15765_SERVICE_COMM_N_ERROR

N_Error indication.

RS_ISO15765_SERVICE_COMM_N_TIMEOUT_A

N_TIMEOUT_A indication.

RS_ISO15765_SERVICE_COMM_N_TIMEOUT_BS

N_TIMEOUT_Bs indication.

RS_ISO15765_PCI_TYPE_MASK

PCI Mask.

RS_ISO15765_PCI_TYPE_SF

Single Frame.

RS_ISO15765_PCI_TYPE_FF

First Frame.

RS_ISO15765_PCI_TYPE_CF

Consecutive Frame.

RS_ISO15765_PCI_TYPE_FC

Flow Control Frame.

RS_ISO15765_FC_CTS

Continue to send.

RS_ISO15765_FC_WAIT

Wait till CTS.

RS_ISO15765_FC_OVERFLOW

Overflow Abort.

RS_ISO15765_RX_STATE_IDLE

Received message idle state.

RS_ISO15765_RX_STATE_TO_SEND_FC

Received message Ready to send flow control state.

RS_ISO15765_RX_STATE_FC_SENT

Received message flow control sent state.

RS_ISO15765_TX_STATE_IDLE

Transmit message idle state.

RS_ISO15765_TX_STATE_SF_SENT

Transmit message single frame sent state.

RS_ISO15765_TX_STATE_FF_SENT

Transmit message first frame sent state.

RS_ISO15765_TX_STATE_SEND_CF

Transmit message consecutive frame sent state.

RS_ISO15765_TX_STATE_WAIT_FOR_CTS

Transmit message wait for CTS state.

RS_ISO15765_MAX_DATA_PER_SF

Number of data bytes per SF.

Typedefs

typedef struct tag_rs_iso15765_config rs_iso15765_config_t

Contains information about DoCAN configuration.

typedef struct tag_rs_iso15765_instance rs_iso15765_instance_t

Contains information about DoCAN.

typedef void (*rs_iso15765_callback)(void *ptr_arg, rs_ret_val_t reason, rs_an_tp_msg_t *ptr_msg)

Callback function format.

This callback function is called on completion of given activity

Param ptr_arg:

[in] - Pointer to the UDS client instance structure.

Param reason:

[in] - Result of the last operation requested in non-blocking mode

Param ptr_msg:

[in] - Pointer to receive buffer on reception or NULL

Return:

None

Functions

rs_handle_t rs_iso15765_open(rs_iso15765_instance_t *ptr_instance, rs_iso15765_config_t *ptr_config)

Initialize the DoCAN instance structure with initial values.

This function initialize the DoCAN instance structure with initial values.

Parameters:
  • ptr_instance[in] - pointer to the ISO15765 instance information

  • ptr_config[in] - pointer to the DoCAN configuration information

Returns:

Handle of the DoCAN instance information which include configuration information also

rs_ret_val_t rs_iso15765_set_tx_msg_buf(rs_handle_t docan_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 DoCAN stack.

This function sets up the transmit buffers to be used for DoCAN stack

Parameters:
  • docan_handle[in] - Handle of the ISO15765 instance information

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

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

  • ptr_msg_ptr_buf[in] - Pointer to the pointer FIFO buffer

Returns:

Return Zero or negative error code

rs_ret_val_t rs_iso15765_set_rx_msg_buf(rs_handle_t docan_handle, rs_an_tp_msg_t *ptr_rx_msgs, uint32_t u32_num_msg)

Set up the receive buffers to be used for the DoCAN stack.

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

Parameters:
  • docan_handle[in] - Handle of the ISO15765 instance information

  • ptr_tx_msgs[in] - Pointer to the array of DoCAN receive messages

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

Returns:

Return Zero or negative error code

rs_ret_val_t rs_iso15765_queue_transmit_msg(rs_handle_t docan_handle, rs_an_tp_msg_t *ptr_msg)

Transmits the given message.

This function transmits the given message over one or more frames

Parameters:
  • docan_handle[in] - Handle of the ISO15765 instance information

  • ptr_msg[in] - Pointer to the message to be transmitted

Returns:

Return Zero or negative error code

rs_an_tp_msg_t *rs_iso15765_get_transmit_msg_buf(rs_handle_t docan_handle)

Requests a transmit buffer for sending DoCAN message.

This function return a transmit buffer for sending DoCAN message

Parameters:

docan_handle[in] - Handle of the ISO15765 instance information

Returns:

Pointer to a free transmit buffer if available or NULL

rs_ret_val_t rs_iso15765_release_transmit_msg(rs_handle_t docan_handle, rs_an_tp_msg_t *ptr_msg)

Release the transmit buffer of DoCAN message.

This function release the transmit buffer of DoCAN message

Parameters:
  • docan_handle[in] - Handle of the ISO15765 instance information

  • ptr_msg[in] - Pointer to the message to be released

Returns:

Return 0 on success or negative on failure

rs_ret_val_t rs_iso15765_rx_buffer_handled(rs_handle_t docan_handle, rs_an_tp_msg_t *ptr_msg)

Indicates the receive buffer is handled.

This function indicates the received buffer is handled and can be freed

Parameters:
  • docan_handle[in] - Handle of the ISO15765 instance information

  • ptr_msg[in] - Pointer to the message received

Returns:

Return 0 on success or negative on failure

rs_ret_val_t rs_iso15765_register_callback(rs_handle_t docan_handle, rs_iso15765_callback ptr_func, void *ptr_arg)

Registers the given callback function for ISO15765 operation.

This function registers the given callback function for various reasons

Parameters:
  • docan_handle[in] - Handle of the ISO15765 instance information

  • ptr_func[in] - Callback function to call to

  • ptr_arg[in] - Pointer to the UDS or OBD instance information

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rs_iso15765_process(rs_handle_t docan_handle)

Function to be called periodically to process underlying state machines.

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

Parameters:

docan_handle[in] - Handle of the ISO15765 instance information

Returns:

Return 0 on success or error code on failure

rs_ret_val_t rs_iso15765_close(rs_handle_t docan_handle)

Function to free the DoCAN handle.

This function used to free the DoCAN handle

Parameters:

docan_handle[in] - Handle of the ISO15765 instance information

Returns:

Return 0 on success or error code on failure

struct tag_rs_iso15765_config
#include <rs_iso15765.h>

Contains information about DoCAN configuration.

Public Members

uint32_t block_size

Block size per transfer.

uint32_t na_timeout

Na Timeout value.

uint32_t nb_timeout

Nb Timeout value.

uint32_t nc_timeout

Nc timeout value.

uint32_t can_id

Can ID.

struct tag_rs_iso15765_instance
#include <rs_iso15765.h>

Contains information about DoCAN.

Public Members

rs_an_tp_instance_t an_tp_instance

Common instance DoCAN/DoIP(Information)

rs_iso15765_config_t *ptr_docan_config

Pointer to the DoCAN configuration.

rs_handle_t can_handle

Can Handle.

uint8_t next_sn

Next serial num expected.

uint32_t exp_rx_len

Num frame bytes expected.

uint32_t total_tx_frames

Num frame bytes transmitted.

rs_can_data_t *ptr_cur_tx_data

CAN Data being transmitted.

uint32_t tx_fc_req_time

Flow control request time.

uint32_t tx_next_cf_time

Next CF frame transmit time1.

uint32_t last_rx_time

Last Receive Data time.

uint8_t next_tx_sn

Next serial number to be transmitted.