uds.can.first_frame

Implementation specific for First Frame CAN packets.

This module contains implementation specific for First Frame packets - that includes First Frame Data Length (FF_DL) parameter.

Module Contents

Classes

CanFirstFrameHandler

Helper class that provides utilities for First Frame CAN Packets.
class uds.can.first_frame.CanFirstFrameHandler[source]

Helper class that provides utilities for First Frame CAN Packets.

FIRST_FRAME_N_PCI: int = 1

First Frame N_PCI value.

MAX_SHORT_FF_DL_VALUE: int = 4095

Maximum value of First Frame Data Length (FF_DL) for which short format of FF_DL is used.

MAX_LONG_FF_DL_VALUE: int = 4294967295

Maximum value of First Frame Data Length (FF_DL).

SHORT_FF_DL_BYTES_USED: int = 2

Number of CAN Frame data bytes used to carry CAN Packet Type and First Frame Data Length (FF_DL). This value is valid only for the short format using FF_DL <= 4095.

LONG_FF_DL_BYTES_USED: int = 6

Number of CAN Frame data bytes used to carry CAN Packet Type and First Frame Data Length (FF_DL). This value is valid only for the long format using FF_DL > 4095.

classmethod create_valid_frame_data(*, addressing_format, payload, dlc, ff_dl, target_address=None, address_extension=None)[source]

Create a data field of a CAN frame that carries a valid First 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 First Frame with any (also incompatible with ISO 15765) parameters values.

Parameters:

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

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

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

  • ff_dl (int) – Value of First Frame Data Length parameter that is carried by a considered CAN packet.

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

  • address_extension (Optional[int]) – 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 incorrect number of bytes to fit them into a First Frame data field using provided parameters.

Returns:

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

Return type:

uds.utilities.RawBytesListAlias

classmethod create_any_frame_data(*, addressing_format, payload, dlc, ff_dl, long_ff_dl_format=False, target_address=None, address_extension=None)[source]

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

Note

You can use this method to create First 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 First Frame with valid (compatible with ISO 15765) parameters values.

Parameters:

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

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

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

  • ff_dl (int) – Value of First Frame Data Length parameter that is carried by a considered CAN packet.

  • long_ff_dl_format (bool) – Information whether to use long or short format of First Frame Data Length.

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

  • address_extension (Optional[int]) – 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 incorrect number of bytes to fit them into a First Frame data field using provided parameters.

Returns:

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

Return type:

uds.utilities.RawBytesListAlias

classmethod is_first_frame(addressing_format, raw_frame_data)[source]

Check if provided data bytes encodes a First Frame packet.

Warning

The method does not validate the content (e.g. FF_DL parameter) of the packet.

Parameters:
Returns:

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

Return type:

bool

classmethod decode_payload(addressing_format, raw_frame_data)[source]

Extract a value of payload from First 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:
Returns:

Payload bytes of a diagnostic message carried by a considered First Frame.

Return type:

uds.utilities.RawBytesListAlias

classmethod decode_ff_dl(addressing_format, raw_frame_data)[source]

Extract a value of First Frame Data Length from First 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:
Raises:

NotImplementedError – There is missing implementation for the provided First Frame Data Length format. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns:

Extracted value of First Frame Data Length.

Return type:

int

classmethod get_payload_size(addressing_format, dlc, long_ff_dl_format=False)[source]

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

Parameters:

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

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

  • long_ff_dl_format (bool) – Information whether to use long or short format of First Frame Data Length.

Raises:

ValueError – First Frame packet cannot use provided attributes according to ISO 15765.

Returns:

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

Return type:

int

classmethod validate_frame_data(addressing_format, raw_frame_data)[source]

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

Parameters:
Raises:

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

Return type:

None

classmethod validate_ff_dl(ff_dl, long_ff_dl_format=None, dlc=None, addressing_format=None)[source]

Validate a value of First Frame Data Length.

Parameters:

  • ff_dl (int) – First Frame Data Length value to validate.

  • long_ff_dl_format (Optional[bool]) –

    Information whether long or short format of First Frame Data Length is used.

    • None - do not perform compatibility check with the FF_DL format

    • True - perform compatibility check with long FF_DL format

    • False - perform compatibility check with short FF_DL format

  • dlc (Optional[int]) – Value of DLC to use for First Frame Data Length value validation. Leave None if you do not want to validate whether First Frame shall be used in this case.

  • addressing_format (Optional[uds.can.addressing_format.CanAddressingFormat]) – Value of CAN Addressing Format to use for First Frame Data Length value validation. Leave None if you do not want to validate whether First Frame shall be used in this case.

Raises:

  • TypeError – Provided value of First Frame Data Length is not integer.

  • ValueError – Provided value of First Frame Data Length is out of range.

  • InconsistentArgumentsError – Single Frame shall be used instead of First Frame to transmit provided number of payload bytes represented by FF_DL value.

Return type:

None

classmethod __extract_ff_dl_data_bytes(addressing_format, raw_frame_data)

Extract data bytes that carries CAN Packet Type and First Frame Data Length parameters.

Warning

This method does not check whether provided raw_frame_data actually contains First Frame.

Parameters:
Returns:

Extracted data bytes with CAN Packet Type and First Frame Data Length parameters.

Return type:

uds.utilities.RawBytesListAlias

classmethod __encode_valid_ff_dl(ff_dl, dlc, addressing_format)

Create First Frame data bytes with CAN Packet Type and First Frame Data Length parameters.

Note

This method can only be used to create a valid (compatible with ISO 15765 - Diagnostic on CAN) output. First Frame Data Length value validation (whether it is too low according to ISO 15765) is not performed though.

Parameters:

  • ff_dl (int) – Value to put into a slot of First Frame Data Length.

  • dlc (int) – Value of DLC to use for First Frame Data Length value validation.

  • addressing_format (uds.can.addressing_format.CanAddressingFormat) – Value of CAN Addressing Format to use for First Frame Data Length value validation.

Returns:

First Frame data bytes containing CAN Packet Type and First Frame Data Length parameters.

Return type:

uds.utilities.RawBytesListAlias

classmethod __encode_any_ff_dl(ff_dl, long_ff_dl_format=False)

Create First Frame data bytes with CAN Packet Type and First Frame Data Length parameters.

Note

This method can be used to create any (also incompatible with ISO 15765 - Diagnostic on CAN) output.

Parameters:

  • ff_dl (int) – Value to put into a slot of First Frame Data Length.

  • long_ff_dl_format (bool) – Information whether to use long or short format of First Frame Data Length.

Raises:

  • ValueError – Provided First Frame Data Length value is out of the parameter values range.

  • InconsistentArgumentsError – Provided First Frame Data Length value cannot fit into the short format.

Returns:

First Frame data bytes containing CAN Packet Type and First Frame Data Length parameters.

Return type:

uds.utilities.RawBytesListAlias