uds.can.consecutive_frame

Implementation specific for Consecutive Frame CAN packets.

This module contains implementation specific for Consecutive Frame packets - that includes Sequence Number (SN) parameter.

Module Contents

Classes

CanConsecutiveFrameHandler

Helper class that provides utilities for Consecutive Frame CAN Packets.
class uds.can.consecutive_frame.CanConsecutiveFrameHandler[source]

Helper class that provides utilities for Consecutive Frame CAN Packets.

CONSECUTIVE_FRAME_N_PCI :uds.utilities.Nibble = 2

Consecutive Frame N_PCI value.

SN_BYTES_USED :int = 1

Number of CAN Frame data bytes used to carry CAN Packet Type and Sequence Number in Consecutive Frame.

classmethod create_valid_frame_data(cls, *, addressing_format, payload, sequence_number, dlc=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]

Create a data field of a CAN frame that carries a valid Consecutive Frame packet.

Note

This method can only be used to create a valid (compatible with ISO 15765 - Diagnostic on CAN) output. Use create_any_frame_data() to create data bytes for a Consecutive Frame with any (also incompatible with ISO 15765) parameters values.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format used by a considered Consecutive Frame.

  • payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by a considered CAN packet.

  • sequence_number (uds.utilities.Nibble) – Value of Sequence Number parameter.

  • dlc (Optional[int]) –

    DLC value of a CAN frame that carries a considered CAN Packet.

    • None - use CAN Data Frame Optimization (CAN ID value will be automatically determined)

    • int type value - DLC value to set. CAN Data Padding will be used to fill the unused data bytes.

  • filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.

  • target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. The value must only be provided if addressing_format uses Target Address parameter.

  • address_extension (Optional[uds.utilities.RawByte]) – Address Extension value carried by this CAN packet. The value must only be provided if addressing_format uses Address Extension parameter.

Raises

InconsistentArgumentsError – Provided payload contains invalid number of bytes to fit it into a properly defined Consecutive Frame data field.

Returns

Raw bytes of CAN frame data for the provided Consecutive Frame packet information.

Return type

uds.utilities.RawBytesList

classmethod create_any_frame_data(cls, *, addressing_format, payload, sequence_number, dlc, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]

Create a data field of a CAN frame that carries a Consecutive Frame packet.

Note

You can use this method to create Consecutive Frame data bytes with any (also inconsistent with ISO 15765) parameters values. It is recommended to use create_valid_frame_data() to create data bytes for a Consecutive Frame with valid (compatible with ISO 15765) parameters values.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format used by a considered Consecutive Frame.

  • payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by a considered CAN packet.

  • sequence_number (uds.utilities.Nibble) – Value of Sequence Number parameter.

  • dlc (int) – DLC value of a CAN frame that carries a considered CAN Packet.

  • filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.

  • target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. The value must only be provided if addressing_format uses Target Address parameter.

  • address_extension (Optional[uds.utilities.RawByte]) – Address Extension value carried by this CAN packet. The value must only be provided if addressing_format uses Address Extension parameter.

Raises

InconsistentArgumentsError – Provided payload contains too many bytes to fit it into a Consecutive Frame data field.

Returns

Raw bytes of CAN frame data for the provided Consecutive Frame packet information.

Return type

uds.utilities.RawBytesList

classmethod is_consecutive_frame(cls, addressing_format, raw_frame_data)[source]

Check if provided data bytes encodes a Consecutive Frame packet.

Warning

The method does not validate the content of the provided frame data bytes. Only, CAN Packet Type (N_PCI) parameter is checked whether contain Consecutive Frame N_PCI value.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.

  • raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a CAN frame to check.

Returns

True if provided data bytes carries Consecutive Frame, False otherwise.

Return type

bool

classmethod decode_payload(cls, addressing_format, raw_frame_data)[source]

Extract diagnostic message payload from Consecutive Frame data bytes.

Warning

The output might contain additional filler bytes (they are not part of diagnostic message payload) that were added during CAN Frame Data Padding. The presence of filler bytes in Consecutive Frame cannot be determined basing solely on the information contained in a Consecutive Frame data bytes.

Warning

The method does not validate the content of the provided frame data bytes. There is no guarantee of the proper output when frame data in invalid format (incompatible with ISO 15765) is provided.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.

  • raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a considered CAN frame.

Raises

ValueError – Provided frame data of a CAN frames does not carry a Consecutive Frame CAN packet.

Returns

Payload bytes (with potential Filler Bytes) of a diagnostic message carried by a considered Consecutive Frame.

Return type

uds.utilities.RawBytesList

classmethod decode_sequence_number(cls, addressing_format, raw_frame_data)[source]

Extract a value of Sequence Number from Consecutive Frame data bytes.

Warning

The method does not validate the content of the provided frame data bytes. There is no guarantee of the proper output when frame data in invalid format (incompatible with ISO 15765) is provided.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.

  • raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a considered CAN frame.

Raises

ValueError – Provided frame data of a CAN frames does not carry a Consecutive Frame CAN packet.

Returns

Extracted value of Sequence Number.

Return type

int

classmethod get_min_dlc(cls, addressing_format, payload_length=1)[source]

Get the minimum value of a CAN frame DLC to carry a Consecutive Frame packet.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format that considered CAN packet uses.

  • payload_length (int) – Number of payload bytes that considered CAN packet carries.

Raises

  • TypeError – Provided value of Payload Length is not integer value.

  • ValueError – Provided value of Payload Length is out of range.

  • InconsistentArgumentsError – Provided Addressing Format and Payload Length values cannot be used together.

Returns

The lowest value of DLC that enables to fit in provided Consecutive Frame packet data.

Return type

int

classmethod get_max_payload_size(cls, addressing_format=None, dlc=None)[source]

Get the maximum size of a payload that can fit into Consecutive Frame data bytes.

Parameters

  • addressing_format (Optional[uds.can.addressing_format.CanAddressingFormatAlias]) – CAN addressing format that considered CAN packet uses. Leave None to get the result for CAN addressing format that does not use data bytes for carrying addressing information.

  • dlc (Optional[int]) – DLC value of a CAN frame that carries a considered CAN Packet. Leave None to get the result for the greatest possible DLC value.

Raises

InconsistentArgumentsError – Consecutive Frame packet cannot use provided attributes according to ISO 15765.

Returns

The maximum number of payload bytes that could fit into a considered Consecutive Frame.

Return type

int

classmethod validate_frame_data(cls, addressing_format, raw_frame_data)[source]

Validate whether data field of a CAN Packet carries a properly encoded Consecutive Frame.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.

  • raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a CAN frame to validate.

Raises

  • ValueError – Provided frame data of a CAN frames does not carry a Consecutive Frame CAN packet.

  • InconsistentArgumentsError – Provided frame data of a CAN frames does not carry a properly encoded Consecutive Frame CAN packet.

Return type

None

classmethod __encode_sn(cls, sequence_number)

Create Consecutive Frame data bytes with CAN Packet Type and Sequence Number parameters.

Parameters

sequence_number (uds.utilities.Nibble) – Value of the sequence number parameter.

Returns

Consecutive Frame data bytes containing CAN Packet Type and Sequence Number parameters.

Return type

uds.utilities.RawBytesList