Group isotp_protocol¶

Pure functions that translate between CAN frames and ISO-TP PDUs. More...

Classes¶

Type	Name
struct	isotp_pdu One decoded ISO-TP frame (protocol data unit).

Public Functions¶

Type	Name
int	isotp_decode (const uint8_t * frame, size_t length, struct isotp_pdu * pdu) Validate one received CAN frame and describe it.
int	isotp_encode_consecutive (uint8_t * frame, size_t capacity, uint8_t sequence_number, const uint8_t * data, uint32_t length) Encode a Consecutive Frame.
int	isotp_encode_first (uint8_t * frame, size_t capacity, const uint8_t * payload, uint32_t message_length) Encode a First Frame and its first payload bytes.
int	isotp_encode_flow_control (uint8_t * frame, size_t capacity, uint8_t flow_status, uint8_t block_size, uint8_t st_min) Encode a Flow Control frame.
int	isotp_encode_single (uint8_t * frame, size_t capacity, const uint8_t * payload, uint32_t length) Encode a Single Frame.
int	isotp_frame_pad (uint8_t * frame, size_t capacity, size_t length, uint8_t value) Fill a frame with a padding byte up to 8 data bytes.
uint32_t	isotp_st_min_decode (uint8_t st_min) Decode a received STmin byte.
uint8_t	isotp_st_min_encode (uint32_t us) Encode a separation time for a Flow Control frame.

Detailed Description¶

The codec holds no state. isotp_decode validates one received CAN frame and describes it in a isotp_pdu; the encoders write one frame into a caller buffer and return its length. Frames are classical CAN (up to 8 data bytes) with normal addressing. The encoders produce the shortest frame; isotp_frame_pad fills it up to 8 bytes when the bus requires padding.

** **

Decoding: isotp_decode.
Encoding: isotp_encode_single, isotp_encode_first, isotp_encode_consecutive, isotp_encode_flow_control, isotp_frame_pad.
Separation time: isotp_st_min_encode, isotp_st_min_decode.

Public Functions Documentation¶

function isotp_decode¶

Validate one received CAN frame and describe it.

int isotp_decode (
    const uint8_t * frame,
    size_t length,
    struct isotp_pdu * pdu
)

Rejects frames that ISO 15765-2 tells a receiver to ignore: unknown frame type, SF_DL of 0 or longer than the frame, a First Frame that is not 8 bytes long or announces a message that would fit a Single Frame (or, with the 32-bit FF_DL, fits the 12-bit field), a Consecutive Frame without data, a Flow Control frame shorter than 3 bytes. The flow status is not checked here: an unknown value is an N_INVALID_FS condition the sender has to report.

Parameters:

frame CAN frame data.
length CAN data length, 1..8.
pdu Receives the description.

Return value:

ISOTP_OK pdu describes a valid frame.
ISOTP_ERROR NULL argument, invalid length or malformed frame.

function isotp_encode_consecutive¶

Encode a Consecutive Frame.

int isotp_encode_consecutive (
    uint8_t * frame,
    size_t capacity,
    uint8_t sequence_number,
    const uint8_t * data,
    uint32_t length
)

Parameters:

frame Output buffer.
capacity Size of frame, at least length + 1.
sequence_number SN, 0..15.
data Segment bytes.
length Segment length, 1..7.

Returns:

Frame length (length + 1), or ISOTP_ERROR.

function isotp_encode_first¶

Encode a First Frame and its first payload bytes.

int isotp_encode_first (
    uint8_t * frame,
    size_t capacity,
    const uint8_t * payload,
    uint32_t message_length
)

Messages up to 4095 bytes use the 12-bit FF_DL and carry 6 payload bytes; longer messages use the escape sequence with a 32-bit FF_DL and carry 2 payload bytes.

Parameters:

frame Output buffer.
capacity Size of frame, at least 8.
payload Start of the message; at least 6 (or 2) bytes are read.
message_length Length of the whole message, at least 8.

Returns:

Frame length (8), or ISOTP_ERROR.

function isotp_encode_flow_control¶

Encode a Flow Control frame.

int isotp_encode_flow_control (
    uint8_t * frame,
    size_t capacity,
    uint8_t flow_status,
    uint8_t block_size,
    uint8_t st_min
)

Parameters:

frame Output buffer.
capacity Size of frame, at least 3.
flow_status ISOTP_FS_CONTINUE, ISOTP_FS_WAIT or ISOTP_FS_OVERFLOW.
block_size BS, 0 = no further Flow Control.
st_min Raw STmin byte, see isotp_st_min_encode.

Returns:

Frame length (3), or ISOTP_ERROR.

function isotp_encode_single¶

Encode a Single Frame.

int isotp_encode_single (
    uint8_t * frame,
    size_t capacity,
    const uint8_t * payload,
    uint32_t length
)

Parameters:

frame Output buffer.
capacity Size of frame, at least length + 1.
payload Message bytes.
length Message length, 1..7.

Returns:

Frame length (length + 1), or ISOTP_ERROR.

function isotp_frame_pad¶

Fill a frame with a padding byte up to 8 data bytes.

int isotp_frame_pad (
    uint8_t * frame,
    size_t capacity,
    size_t length,
    uint8_t value
)

Parameters:

frame Frame buffer.
capacity Size of frame, at least 8.
length Current frame length, 1..8.
value Padding byte.

Returns:

New frame length (8), or ISOTP_ERROR.

function isotp_st_min_decode¶

Decode a received STmin byte.

uint32_t isotp_st_min_decode (
    uint8_t st_min
)

0x00..0x7F are milliseconds, 0xF1..0xF9 are 100..900 us. ISO 15765-2 tells the sender to treat the reserved values as 0x7F (127 ms).

Parameters:

st_min Raw STmin byte.

Returns:

Separation time in microseconds.

function isotp_st_min_encode¶

Encode a separation time for a Flow Control frame.

uint8_t isotp_st_min_encode (
    uint32_t us
)

Rounds up, so the sender never sends faster than requested: 0 us gives 0x00, 1..900 us give 0xF1..0xF9 (100 us steps), 901..127000 us give 0x01..0x7F (1 ms steps), larger values 0x7F.

Parameters:

us Separation time in microseconds.

Returns:

Raw STmin byte.