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.

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_get_version_info	To get docan version information
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_get_transmit_msg_buf	Retrieves a free transmit message buffer for preparing a new DoCAN frame.
rs_iso15765_queue_transmit_msg	Queues a prepared message for transmission through the DoCAN stack.
rs_iso15765_change_param	Allows updating configurable parameters such as block size and STmin parameters.
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

There are several callback functions through which the DoCAN stack retrieves dynamic parameters or notifies the application about specific events. These functions are captured in the below table.

Callback Functions
Function	Description
rcb_iso15765_get_dynamic_bs	Provides the application-defined dynamic Block Size (BS) for flow control.
rcb_iso15765_get_dynamic_stmin	Provides the dynamic Separation Time (STmin) value required for flow control.
rcb_iso15765_param_changed	Notifies the application when the DoCAN communication parameters (BS and STmin) have been updated.
rcb_iso15765_rx_seg_msg_started	Called when segmented reception begins (First Frame received).
rcb_iso15765_msg_rxed	Indicates that a complete DoCAN message has been received and is ready for application processing.
rcb_iso15765_msg_txed	Indicates that the message transmission is completed (Single Frame or the last Consecutive Frame).

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 functions that are called by the DoCAN stack to interface with the CAN Data Link Layer, as well as the callback functions used by the CAN layer to notify the DoCAN stack about transmit and receive events.

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
rs_can_put_transmit_buf	Releases or returns the CAN transmit buffer after use.
rcb_iso15765_can_tx_done	Callback invoked by the CAN layer to notify that a CAN frame transmission is complete.
rcb_iso15765_can_frame_rxed	Callback invoked by the CAN layer when a new CAN frame is received, passing it to the DoCAN stack for processing.

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.

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.

CAN Interface

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_SERVICE_COMM_N_TIMEOUT_CR: N_TIMEOUT_Cr indication.

RS_ISO15765_SERVICE_COMM_N_TIMEOUT_BR: N_TIMEOUT_Br indication.

RS_ISO15765_SERVICE_COMM_N_TIMEOUT_CS: N_TIMEOUT_CS indication.

RS_ISO15765_SERVICE_COMM_WFT_OVRN: N_WFT_OVRN: Too many consecutive FlowControl(WAIT) frames received.

RS_ISO15765_SERVICE_COMM_BUFFER_OVFLW: N_BUFFER_OVFLW: Receiver buffer overflow, cannot accept more CFs.

RS_ISO15765_SERVICE_COMM_UNEXP_PDU: N_UNEXP_PDU: Unexpected or invalid PDU sequence detected.

RS_ISO15765_SERVICE_COMM_WRONG_SN: N_WRONG_SN : receved CF has worng sequence number.

RS_ISO15765_SERVICE_COMM_INVALID_FS: N_INVALID_FS : receved FC value are invalid.

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_TX_DL(mode): Total number of data bytes available in the CAN (or CAN FD) frame.

RS_ISO15765_MAX_WFT: MAX FC wait count.

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_RX_STATE_WAIT_FC: Received message flow control sent wait fc.

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_NORMAL_ADDRESSING: Address format.

RS_ISO15765_NORMAL_FIXED_ADDRESSING

RS_ISO15765_EXTENDED_ADDRESSING

RS_ISO15765_MIXED_ADDRESSING

RS_ISO15765_ROLE_CLIENT: Role config.

RS_ISO15765_ROLE_SERVER

RS_ISO15765_MASK_ADD_BIT: DoCan mask config.

RS_ISO15765_MASK_LOW_NIBBLE

RS_ISO15765_MASK_FIRST_BYTE

RS_ISO15765_MAX_DATA_PER_SF(TX_DL, addr_fmt): Number of data bytes per SF Single Frame (SF): entire data fits into one frame

RS_ISO15765_MAX_DATA_PER_FF(TX_DL, addr_fmt): First Frame.

RS_ISO15765_MAX_DATA_PER_CF(TX_DL, addr_fmt): Consecutive Frame.

RS_ISO15765_N_TATYPE_1

Address type.

Classical CAN, 11-bit, Physical

RS_ISO15765_N_TATYPE_2: Classical CAN, 11-bit, Functional.

RS_ISO15765_N_TATYPE_3: CAN FD, 11-bit, Physical.

RS_ISO15765_N_TATYPE_4: CAN FD, 11-bit, Functional.

RS_ISO15765_N_TATYPE_5: Classical CAN, 29-bit, Physical.

RS_ISO15765_N_TATYPE_6: Classical CAN, 29-bit, Functional.

RS_ISO15765_N_TATYPE_7: CAN FD, 29-bit, Physical.

RS_ISO15765_N_TATYPE_8: CAN FD, 29-bit, Functional.

RS_ISO15765_N_AI_PRIORITY: N_AI config.

RS_ISO15765_TARGET_ADDR_MASK

RS_ISO15765_ADDR_INDIC_MASK

RS_ISO15765_N_AI_PRIORITY_MASK

RS_ISO15765_MIXED_ADDR_PHY_INDIC

RS_ISO15765_MIXED_ADDR_FUN_INDIC

RS_ISO15765_NORMAL_FIXED_ADDR_PHY_INDIC

RS_ISO15765_NORMAL_FIXED_ADDR_FUN_INDIC

RS_ISO15765_DEFAULT_PAD_VALUE: DoCAN Param configuration.

RS_ISO15765_STMIN_MIN_VALUE_FD

RS_ISO15765_STMIN_MAX_VALUE_FD

RS_ISO15765_STMIN_MAX_VALUE

RS_ISO15765_MAX_MSG_CTX: MAX message context.

RS_ISO15765_CTX_FREE: Message context state.

RS_ISO15765_CTX_IN_USE

RS_ISO15765_CTX_QUEUED

RS_ISO15765_2_RSVD_ID_RANGE1_START: ISO 15765-2 Reserved CAN Identifier Ranges.

RS_ISO15765_2_RSVD_ID_RANGE1_END

RS_ISO15765_2_RSVD_ID_RANGE2_START

RS_ISO15765_2_RSVD_ID_RANGE2_END

RS_ISO15765_STMIN_US(stmin): DoCAN Stmin converter.

Typedefs

typedef struct tag_rs_iso15765_config rs_iso15765_config_t: Contains information about DoCAN configuration.

typedef struct tag_rs_iso15765_tp_ctx rs_iso15765_msg_ctx_t

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

Enums

enum rs_iso15765_msg_type

Enum for Message type.

Values:

enumerator RS_ISO15765_MSG_TYPE_DIAGNOSTICS

enumerator RS_ISO15765_MSG_TYPE_REMOTE_DIAGNOSTICS

enum rs_iso15765_param_config_t

Enum for change param.

Values:

enumerator RS_ISO15765_PARAM_BS

enumerator RS_ISO15765_PARAM_STMIN

enum rs_iso15765_param_result_t

Enum for change param result.

Values:

enumerator RS_ISO15765_N_OK

enumerator RS_ISO15765_N_RX_ON

enumerator RS_ISO15765_N_WRONG_PARAMETER

enumerator RS_ISO15765_N_WRONG_VALUE

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_get_version_info(uint32_t *ptr_maj_ver, uint32_t *ptr_min_ver, uint32_t *ptr_build_ver)

Get DoCAN version information.

This function use to get DoCAN version information

Parameters:

ptr_maj_ver – [in] - pointer to the major version
ptr_min_ver – [in] - pointer to the minor version
ptr_build_ver – [in] - pointer to the build version

Returns:

Return Zero or negative error code

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_ret_val_t rs_iso15765_get_transmit_msg_buf(rs_handle_t docan_handle, rs_an_tp_msg_t **ptr_tx_msg)

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
ptr_tx_msg – [in] - Pointer to a free transmit buffer if available or NULL

Returns:

Return 0 on success or negative on failure

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

void rcb_iso15765_rx_seg_msg_started(rs_an_tp_msg_t *ptr_msg)

Callback invoked when reception of a segmented message starts.

This function is called after a valid First Frame (FF) is received. It notifies the upper layer that a segmented message is incoming, allocates buffers, and initializes the receive state machine.

Parameters:: ptr_msg – [in] - pointer to the message being received
Returns:: None

void rcb_iso15765_msg_txed(rs_an_tp_instance_t *ptr_tp_instance, rs_ret_val_t result, rs_an_tp_msg_t *ptr_msg)

Callback invoked when a message has been fully transmitted.

This function is called after a message (single or segmented) transmission is completed. It informs the upper layer about transmission success or failure, cleans up transmit buffers, and resets the transport protocol state.

Parameters:

ptr_tp_instance – [in] - pointer to the transport protocol instance
result – [in] - result of the transmission (success or failure)
ptr_msg – [in] - pointer to the message that was transmitted

Returns:

None

void rcb_iso15765_msg_rxed(rs_an_tp_instance_t *ptr_tp_instance, rs_ret_val_t reason, rs_an_tp_msg_t *ptr_msg)

Callback invoked when a message has been fully received or reception failed.

This function is called after a message (single or segmented) reception is complete. It delivers the received message or error to the upper layer, updates the receive state, and releases message buffers.

Parameters:

ptr_tp_instance – [in] - pointer to the transport protocol instance
reason – [in] - reason code indicating success or failure of reception
ptr_msg – [in] - pointer to the received message (NULL if reception failed)

Returns:

None

void rcb_iso15765_param_changed(rs_iso15765_param_config_t param_config, rs_iso15765_param_result_t param_result)

Callback invoked when a configuration parameter is changed.

This function is called whenever an ISO15765 parameter (e.g., STmin, Block Size, timeouts) is changed. It notifies the application or upper layer about the parameter change result.

Parameters:

param_config – [in] - configuration parameter that was changed
param_result – [in] - result of the parameter change (success or failure)

Returns:

None

rs_ret_val_t rs_iso15765_change_param(rs_handle_t docan_handle, rs_an_tp_addr_config_t *ptr_msg_addr, rs_iso15765_param_config_t param_config, uint8_t param_value)

Changes an ISO15765 network layer parameter at runtime.

This function updates a parameter such as STmin, Block Size, or timeout values for a specific ISO15765 instance. It validates the new parameter and triggers a callback to notify the result of the change.

Parameters:

docan_handle – [in] - handle to the ISO15765 instance
ptr_msg_addr – [in] - pointer to the address configuration for which the parameter applies
param_config – [in] - type of parameter to change (STmin, BS, NA timeout, NB timeout, etc.)
param_value – [in] - new value for the parameter

Returns:

RS_ERR_OK if the parameter is successfully updated, otherwise an error code

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

uint8_t rcb_iso15765_get_dynamic_stmin(rs_an_tp_addr_config_t *ptr_tp_addr_config)

Retrieves the dynamically calculated STmin value.

This function returns the dynamically computed Separation Time Minimum (STmin) value for the given ISO15765 transport protocol instance. The STmin value is typically updated during multi-frame communication based on network conditions or flow control requirements.

Parameters:: ptr_tp_addr_config – [in] - Pointer to the ISO15765 transport protocol address config.
Returns:: Returns the dynamic STmin value in milliseconds

uint8_t rcb_iso15765_get_dynamic_bs(rs_an_tp_addr_config_t *ptr_tp_addr_config)

Retrieves the dynamically calculated block size value.

This function returns the dynamic Block Size (BS) for the given ISO15765 transport protocol instance. The BS value determines how many Consecutive Frames (CF) can be received before a new Flow Control (FC) frame is required. It may be updated during runtime based on protocol negotiation or internal logic.

Parameters:: ptr_tp_addr_config – [in] - Pointer to the ISO15765 transport protocol address config.
Returns:: Returns the dynamic block size value

struct tag_rs_iso15765_config

#include <rs_iso15765.h>

Contains information about DoCAN configuration.

Public Members

uint32_t na_timeout: Na Timeout value.

uint32_t nb_timeout: Nb Timeout value.

uint32_t nc_timeout: Nc timeout value.

uint32_t tx_can_id: Transmit Can ID.

uint32_t rx_can_id: Receive Can ID.

uint16_t address_format: address formate (Normal / Normal Fixed / Extended / Mixed)

uint8_t st_min: STmin value.

uint8_t block_size: Block size per transfer.

uint8_t pad_active

uint8_t padding_value

uint8_t docan_role: Client or Server.

rs_an_tp_addr_config_t *ptr_addr_config: config the address

struct tag_rs_iso15765_tp_ctx

Public Members

uint32_t rx_can_id: Receive CAN ID.

uint32_t tx_can_id: Transmit CAN ID.

uint32_t exp_rx_len: Num frame bytes expected.

uint32_t tx_fc_req_time: Flow control request time.

uint32_t tx_next_cf_time: Next CF frame transmit time1.

uint32_t fc_start_time: FC start time.

uint32_t cf_wait_time: CF wait time.

uint32_t last_cf_tx_time: Last CF frame transmit time.

uint32_t fc_resend_start_time: FC frame transmit ,after FC with WAIT.

uint8_t next_sn: Next serial num expected.

uint8_t next_tx_sn: Next serial number to be transmitted.

uint8_t rx_fc_bs: Received BS from the FC.

uint8_t tx_fc_bs: Received BS from the FC.

uint8_t rx_fc_stmin: Received STmin from the FC.

uint8_t tx_fc_stmin: Received STmin from the FC.

uint8_t tx_fc_status: FC status to send.

uint8_t wait_frame_count: CF frame wait count.

uint8_t seg_msg_process: a segmented message reception.

uint8_t rx_cf_rece_in_block: CFs received block count.

uint8_t cf_sent_in_block: CF block number.

uint8_t cur_rx_state: Current Receive state.

uint8_t cur_tx_state: Current Transmit state.

void *ptr_cur_rx_msg: Current RX msg in progress.

void *ptr_cur_tx_msg: Current RX msg in progress.

uint16_t curr_tx_len: Length of current transmit message.

rs_can_tx_data_t *ptr_cur_tx_data: CAN Data being transmitted.

uint32_t tx_data_req_time: Transmit data requested time.

uint8_t state: Flags.

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 can_mode: Indicate CAN mode (i.e classic or FD)

rs_iso15765_msg_ctx_t msg_ctx[RS_ISO15765_MAX_MSG_CTX]