uds.can.packet.consecutive_frame

Implementation of handlers for Consecutive Frame CAN packet.

Attributes

CONSECUTIVE_FRAME_N_PCI

N_PCI value of Consecutive Frame.

SN_BYTES_USED

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

Functions

is_consecutive_frame(addressing_format, raw_frame_data)

Check if provided data bytes contain a Consecutive Frame packet.

validate_consecutive_frame_data(addressing_format, ...)

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

create_consecutive_frame_data(addressing_format, ...)

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

generate_consecutive_frame_data(addressing_format, ...)

Generate CAN frame data field that carries any combination of Consecutive Frame packet data parameters.

extract_consecutive_frame_payload(addressing_format, ...)

Extract diagnostic message payload from Consecutive Frame data bytes.

get_consecutive_frame_min_dlc(addressing_format[, ...])

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

get_consecutive_frame_max_payload_size(addressing_format)

Get the maximum payload size that could be carried by a Consecutive Frame.

extract_sequence_number(addressing_format, raw_frame_data)

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

encode_sequence_number(sequence_number)

Create valid Consecutive Frame data bytes that contain Sequence Number and N_PCI values.

Module Contents

uds.can.packet.consecutive_frame.CONSECUTIVE_FRAME_N_PCI: int = 2

N_PCI value of Consecutive Frame.

uds.can.packet.consecutive_frame.SN_BYTES_USED: int = 1

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

uds.can.packet.consecutive_frame.is_consecutive_frame(addressing_format, raw_frame_data)[source]

Check if provided data bytes contain a Consecutive Frame packet.

Warning

The method does not validate the content of the provided frame data bytes. It only checks CAN Packet Type (N_PCI) parameter for Consecutive Frame N_PCI value.

Parameters:

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

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

Returns:

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

Return type:

bool

uds.can.packet.consecutive_frame.validate_consecutive_frame_data(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.CanAddressingFormat) – CAN Addressing Format used.

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

Raises:

  • ValueError – The value of N_PCI in provided data is not Consecutive Frame N_PCI.

  • InconsistencyError – Provided data does not carry any payload.

Return type:

None

uds.can.packet.consecutive_frame.create_consecutive_frame_data(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 generate_consecutive_frame_data() to generate data bytes with any (also incompatible with ISO 15765) parameters values.

Parameters:

  • addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.

  • payload (uds.utilities.RawBytesAlias) – Payload to carry.

  • sequence_number (int) – Sequence Number value to set.

  • dlc (Optional[int]) –

    DLC value of a CAN frame.

    • 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 (int) – Filler Byte value to use for CAN Frame Data Padding.

  • target_address (Optional[int]) – Target Address value carried by this CAN Packet. The value must only be provided if addressing_format requires CAN frame data field to contain Target Address parameter.

  • address_extension (Optional[int]) – Address Extension value carried by this CAN packet. The value must only be provided if addressing_format requires CAN frame data field to contain Address Extension parameter.

Raises:

InconsistencyError – Provided parameters cannot be used together to create a valid Consecutive Frame data.

Returns:

Raw data bytes of a CAN frame.

Return type:

bytearray

uds.can.packet.consecutive_frame.generate_consecutive_frame_data(addressing_format, payload, sequence_number, dlc, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]

Generate CAN frame data field that carries any combination of Consecutive Frame packet data parameters.

Note

Crosscheck of provided values is not performed so you might use this function to create data fields that are not compatible with Diagnostic on CAN standard (ISO 15765).

Parameters:

  • addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.

  • payload (uds.utilities.RawBytesAlias) – Payload to carry.

  • dlc (int) – DLC value of a CAN frame.

  • sequence_number (int) – Sequence Number value to set.

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

  • target_address (Optional[int]) – Target Address value carried by this CAN Packet. The value must only be provided if addressing_format requires CAN frame data field to contain Target Address parameter.

  • address_extension (Optional[int]) – Address Extension value carried by this CAN packet. The value must only be provided if addressing_format requires CAN frame data field to contain Address Extension parameter.

Raises:

InconsistencyError – Provided payload contains invalid number of bytes.

Returns:

Raw data bytes of a CAN frame.

Return type:

bytearray

uds.can.packet.consecutive_frame.extract_consecutive_frame_payload(addressing_format, raw_frame_data)[source]

Extract diagnostic message payload from Consecutive Frame data bytes.

Warning

The output might contain 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.CanAddressingFormat) – CAN Addressing Format used.

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

Returns:

Payload bytes (with potential Filler Bytes) carried by the provided Consecutive Frame data.

Return type:

bytearray

uds.can.packet.consecutive_frame.get_consecutive_frame_min_dlc(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.CanAddressingFormat) – CAN addressing format used.

  • payload_length (int) – Number of payload bytes to carry.

Raises:

  • TypeError – Provided value of Payload Length is not int type.

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

Returns:

The lowest value of DLC for a Consecutive Frame that would carry provided payload size.

Return type:

int

uds.can.packet.consecutive_frame.get_consecutive_frame_max_payload_size(addressing_format, dlc=None)[source]

Get the maximum payload size that could be carried by a Consecutive Frame.

Parameters:

  • addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.

  • 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:

InconsistencyError – Provided dlc cannot be used for Consecutive Frame with in the provided CAN Addressing Format.

Returns:

The maximum number of payload bytes that could be carried in a Consecutive Frame.

Return type:

int

uds.can.packet.consecutive_frame.extract_sequence_number(addressing_format, raw_frame_data)[source]

Extract the 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.CanAddressingFormat) – CAN Addressing Format used.

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

Returns:

Extracted value of Sequence Number.

Return type:

int

uds.can.packet.consecutive_frame.encode_sequence_number(sequence_number)[source]

Create valid Consecutive Frame data bytes that contain Sequence Number and N_PCI values.

Parameters:

sequence_number (int) – Order value of a Consecutive Frame.

Returns:

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

Return type:

bytearray