The latest development version of this page may be more current than this released 3.7.0 version.

ISO-TP Transport Protocol

Overview

ISO-TP is a transport protocol defined in the ISO-Standard ISO15765-2 Road vehicles - Diagnostic communication over Controller Area Network (DoCAN). Part2: Transport protocol and network layer services. As its name already implies, it is originally designed, and still used in road vehicle diagnostic over Controller Area Networks. Nevertheless, it’s not limited to applications in road vehicles or the automotive domain.

This transport protocol extends the limited payload data size for classical CAN (8 bytes) and CAN FD (64 bytes) to theoretically four gigabytes. Additionally, it adds a flow control mechanism to influence the sender’s behavior. ISO-TP segments packets into small fragments depending on the payload size of the CAN frame. The header of those segments is called Protocol Control Information (PCI).

Packets smaller or equal to seven bytes on Classical CAN are called single-frames (SF). They don’t need to fragment and do not have any flow-control.

Packets larger than that are segmented into a first-frame (FF) and as many consecutive-frames (CF) as required. The FF contains information about the length of the entire payload data and additionally, the first few bytes of payload data. The receiving peer sends back a flow-control-frame (FC) to either deny, postpone, or accept the following consecutive frames. The FC also defines the conditions of sending, namely the block-size (BS) and the minimum separation time between frames (STmin). The block size defines how many CF the sender is allowed to send, before he has to wait for another FC.

ISO-TP Sequence

API Reference

Related code samples

ISO-TP library

Use ISO-TP library to exchange messages between two boards.

group can_isotp

CAN ISO-TP Protocol.

ISO-TP message ID flags

ISOTP_MSG_EXT_ADDR

Message uses ISO-TP extended addressing (first payload byte of CAN frame)

ISOTP_MSG_FIXED_ADDR

Message uses ISO-TP fixed addressing (according to SAE J1939).

Only valid in combination with ISOTP_MSG_IDE.

ISOTP_MSG_IDE

Message uses extended (29-bit) CAN ID.

ISOTP_MSG_FDF

Message uses CAN FD format (FDF)

ISOTP_MSG_BRS

Message uses CAN FD Baud Rate Switch (BRS).

Only valid in combination with ISOTP_MSG_FDF.

Defines

ISOTP_N_OK

Completed successfully.

ISOTP_N_TIMEOUT_A

Ar/As has timed out.

ISOTP_N_TIMEOUT_BS

Reception of next FC has timed out.

ISOTP_N_TIMEOUT_CR

Cr has timed out.

ISOTP_N_WRONG_SN

Unexpected sequence number.

ISOTP_N_INVALID_FS

Invalid flow status received.

ISOTP_N_UNEXP_PDU

Unexpected PDU received.

ISOTP_N_WFT_OVRN

Maximum number of WAIT flowStatus PDUs exceeded.

ISOTP_N_BUFFER_OVERFLW

FlowStatus OVFLW PDU was received.

ISOTP_N_ERROR

General error.

ISOTP_NO_FREE_FILTER

Implementation specific errors.

Can’t bind or send because the CAN device has no filter left

ISOTP_NO_NET_BUF_LEFT

No net buffer left to allocate.

ISOTP_NO_BUF_DATA_LEFT

Not sufficient space in the buffer left for the data.

ISOTP_NO_CTX_LEFT

No context buffer left to allocate.

ISOTP_RECV_TIMEOUT

Timeout for recv.

ISOTP_FIXED_ADDR_SA_POS

Position of fixed source address (SA)

ISOTP_FIXED_ADDR_SA_MASK

Mask to obtain fixed source address (SA)

ISOTP_FIXED_ADDR_TA_POS

Position of fixed target address (TA)

ISOTP_FIXED_ADDR_TA_MASK

Mask to obtain fixed target address (TA)

ISOTP_FIXED_ADDR_PRIO_POS

Position of priority in fixed addressing mode.

ISOTP_FIXED_ADDR_PRIO_MASK

Mask for priority in fixed addressing mode.

ISOTP_FIXED_ADDR_RX_MASK

CAN filter RX mask to match any priority and source address (SA)

Typedefs

typedef void (*isotp_tx_callback_t)(int error_nr, void *arg)

Transmission callback.

This callback is called when a transmission is completed.

Param error_nr:

ISOTP_N_OK on success, ISOTP_N_* on error

Param arg:

Callback argument passed to the send function

Functions

int isotp_bind(struct isotp_recv_ctx *rctx, const struct device *can_dev, const struct isotp_msg_id *rx_addr, const struct isotp_msg_id *tx_addr, const struct isotp_fc_opts *opts, k_timeout_t timeout)

Bind an address to a receiving context.

This function binds an RX and TX address combination to an RX context. When data arrives from the specified address, it is buffered and can be read by calling isotp_recv. When calling this routine, a filter is applied in the CAN device, and the context is initialized. The context must be valid until calling unbind.

Parameters:

  • rctx – Context to store the internal states.

  • can_dev – The CAN device to be used for sending and receiving.

  • rx_addr – Identifier for incoming data.

  • tx_addr – Identifier for FC frames.

  • opts – Flow control options.

  • timeout – Timeout for FF SF buffer allocation.

Return values:

  • ISOTP_N_OK – on success

  • ISOTP_NO_FREE_FILTER – if CAN device has no filters left.

void isotp_unbind(struct isotp_recv_ctx *rctx)

Unbind a context from the interface.

This function removes the binding from isotp_bind. The filter is detached from the CAN device, and if a transmission is ongoing, buffers are freed. The context can be discarded safely after calling this function.

Parameters:

  • rctx – Context that should be unbound.

int isotp_recv(struct isotp_recv_ctx *rctx, uint8_t *data, size_t len, k_timeout_t timeout)

Read out received data from fifo.

This function reads the data from the receive FIFO of the context. It blocks if the FIFO is empty. If an error occurs, the function returns a negative number and leaves the data buffer unchanged.

Parameters:

  • rctx – Context that is already bound.

  • data – Pointer to a buffer where the data is copied to.

  • len – Size of the buffer.

  • timeout – Timeout for incoming data.

Return values:

  • Number – of bytes copied on success

  • ISOTP_RECV_TIMEOUT – when “timeout” timed out

  • ISOTP_N_* – on error

int isotp_recv_net(struct isotp_recv_ctx *rctx, struct net_buf **buffer, k_timeout_t timeout)

Get the net buffer on data reception.

This function reads incoming data into net-buffers. It blocks until the entire packet is received, BS is reached, or an error occurred. If BS was zero, the data is in a single net_buf. Otherwise, the data is fragmented in chunks of BS size. The net-buffers are referenced and must be freed with net_buf_unref after the data is processed.

Parameters:

  • rctx – Context that is already bound.

  • buffer – Pointer where the net_buf pointer is written to.

  • timeout – Timeout for incoming data.

Return values:

  • Remaining – data length for this transfer if BS > 0, 0 for BS = 0

  • ISOTP_RECV_TIMEOUT – when “timeout” timed out

  • ISOTP_N_* – on error

int isotp_send(struct isotp_send_ctx *sctx, const struct device *can_dev, const uint8_t *data, size_t len, const struct isotp_msg_id *tx_addr, const struct isotp_msg_id *rx_addr, isotp_tx_callback_t complete_cb, void *cb_arg)

Send data.

This function is used to send data to a peer that listens to the tx_addr. An internal work-queue is used to transfer the segmented data. Data and context must be valid until the transmission has finished. If a complete_cb is given, this function is non-blocking, and the callback is called on completion with the return value as a parameter.

Parameters:

  • sctx – Context to store the internal states.

  • can_dev – The CAN device to be used for sending and receiving.

  • data – Data to be sent.

  • len – Length of the data to be sent.

  • rx_addr – Identifier for FC frames.

  • tx_addr – Identifier for outgoing frames the receiver listens on.

  • complete_cb – Function called on completion or NULL.

  • cb_arg – Argument passed to the complete callback.

Return values:

  • ISOTP_N_OK – on success

  • ISOTP_N_* – on error

struct isotp_msg_id
#include <isotp.h>

ISO-TP message id struct.

Used to pass addresses to the bind and send functions.

Public Members

union isotp_msg_id.[anonymous] [anonymous]

CAN identifier.

If ISO-TP fixed addressing is used, isotp_bind ignores SA and priority sections and modifies TA section in flow control frames.

uint8_t ext_addr

ISO-TP extended address (if used)

uint8_t dl

ISO-TP frame data length (TX_DL for TX address or RX_DL for RX address).

Valid values are 8 for classical CAN or 8, 12, 16, 20, 24, 32, 48 and 64 for CAN FD.

0 will be interpreted as 8 or 64 (if ISOTP_MSG_FDF is set).

The value for incoming transmissions (RX_DL) is determined automatically based on the received first frame and does not need to be set during initialization.

uint8_t flags

Flags.

See also

ISOTP_MSG_FLAGS.

struct isotp_fc_opts
#include <isotp.h>

ISO-TP frame control options struct.

Used to pass the options to the bind and send functions.

Public Members

uint8_t bs

Block size.

Number of CF PDUs before next CF is sent

uint8_t stmin

Minimum separation time.

Min time between frames