uds.can.frame_fields

Implementation for CAN frame fields that are influenced by UDS.

Handlers for CAN Frame fields:

  • CAN Identifier

  • DLC

  • Data

Module Contents

Classes

CanIdHandler

Helper class that provides utilities for CAN Identifier field.

CanDlcHandler

Helper class that provides utilities for CAN Data Length Code field.

Attributes

DEFAULT_FILLER_BYTE

Default value of Filler Byte.

AICanIdAlias

Alias of Addressing Information that is carried in CAN Identifier.
uds.can.frame_fields.DEFAULT_FILLER_BYTE :uds.utilities.RawByte = 204

Default value of Filler Byte. Filler Bytes are used for CAN Frame Data Padding. .. note:: The value is specified by ISO 15765-2:2016 (chapter 10.4.2.1).

uds.can.frame_fields.AICanIdAlias

Alias of Addressing Information that is carried in CAN Identifier.

class uds.can.frame_fields.CanIdHandler[source]

Helper class that provides utilities for CAN Identifier field.

CAN Identifier (CAN ID) is a CAN frame field that informs about a sender and a content of CAN frames.

CAN supports two formats of CAN ID:

  • Standard (11-bit Identifier)

  • Extended (29-bit Identifier)

MIN_STANDARD_VALUE :int = 0

Minimum value of Standard (11-bit) CAN ID.

MAX_STANDARD_VALUE :int

Maximum value of Standard (11-bit) CAN ID.

MIN_EXTENDED_VALUE :int

Minimum value of Extended (29-bit) CAN ID.

MAX_EXTENDED_VALUE :int

Maximum value of Extended (29-bit) CAN ID.

NORMAL_FIXED_PHYSICAL_ADDRESSING_OFFSET :int = 416940032

Minimum value of physically addressed CAN ID in Normal Fixed Addressing format.

NORMAL_FIXED_FUNCTIONAL_ADDRESSING_OFFSET :int = 417005568

Minimum value of functionally addressed CAN ID in Normal Fixed Addressing format.

MIXED_29BIT_PHYSICAL_ADDRESSING_OFFSET :int = 416153600

Minimum value of physically addressed CAN ID in Mixed 29-bit Addressing format.

MIXED_29BIT_FUNCTIONAL_ADDRESSING_OFFSET :int = 416088064

Minimum value of functionally addressed CAN ID in Mixed 29-bit Addressing format.

ADDRESSING_TYPE_NAME = addressing_type

Name of Addressing Type parameter in Addressing Information.

TARGET_ADDRESS_NAME = target_address

Name of Target Address parameter in Addressing Information.

SOURCE_ADDRESS_NAME = source_address

Name of Source Address parameter in Addressing Information.

classmethod decode_can_id(cls, addressing_format, can_id)[source]

Extract Addressing Information out of CAN ID.

Warning

This methods might not extract any Addressing Information from the provided CAN ID as some of these information are system specific.

For example, Addressing Type (even though it always depends on CAN ID value) will not be decoded when either Normal 11bit, Extended or Mixed 11bit addressing format is used as the Addressing Type (in such case) depends on system specific behaviour.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – Addressing format used.

  • can_id (int) – CAN ID from which Addressing Information to be extracted.

Raises

NotImplementedError – There is missing implementation for the provided Addressing Format. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns

Dictionary with Addressing Information decoded out of the provided CAN ID.

Return type

AICanIdAlias

classmethod decode_normal_fixed_addressed_can_id(cls, can_id)[source]

Extract Addressing Information out of CAN ID for Normal Fixed CAN Addressing format.

Parameters

can_id (int) – CAN ID from which Addressing Information to be extracted.

Raises

  • ValueError – Provided CAN ID is not compatible with Normal Fixed Addressing format.

  • NotImplementedError –

    There is missing implementation for the provided CAN ID. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns

Dictionary with Addressing Information decoded out of the provided CAN ID.

Return type

AICanIdAlias

classmethod decode_mixed_addressed_29bit_can_id(cls, can_id)[source]

Extract Addressing Information out of CAN ID for Mixed 29-bit CAN Addressing format.

Parameters

can_id (int) – CAN ID from which Addressing Information to be extracted.

Raises

  • ValueError – Provided CAN ID is not compatible with Mixed 29-bit Addressing format.

  • NotImplementedError –

    There is missing implementation for the provided CAN ID. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns

Dictionary with Addressing Information decoded out of the provided CAN ID.

Return type

AICanIdAlias

classmethod encode_normal_fixed_addressed_can_id(cls, addressing_type, target_address, source_address)[source]

Generate CAN ID value for Normal Fixed CAN Addressing format.

Parameters

  • addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type used.

  • target_address (uds.utilities.RawByte) – Target address value to use.

  • source_address (uds.utilities.RawByte) – Source address value to use.

Raises

NotImplementedError –

There is missing implementation for the provided Addressing Type. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns

Value of CAN ID (compatible with Normal Fixed Addressing Format) that was generated from the provided values.

Return type

int

classmethod encode_mixed_addressed_29bit_can_id(cls, addressing_type, target_address, source_address)[source]

Generate CAN ID value for Mixed 29-bit CAN Addressing format.

Parameters

  • addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type used.

  • target_address (uds.utilities.RawByte) – Target address value to use.

  • source_address (uds.utilities.RawByte) – Source address value to use.

Raises

NotImplementedError –

There is missing implementation for the provided Addressing Type. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns

Value of CAN ID (compatible with Mixed 29-bit Addressing Format) that was generated from the provided values.

Return type

int

classmethod is_compatible_can_id(cls, can_id, addressing_format, addressing_type=None)[source]

Check if the provided value of CAN ID is compatible with addressing format used.

Parameters

  • can_id (int) – Value to check.

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – Addressing format used.

  • addressing_type (Optional[uds.transmission_attributes.AddressingTypeAlias]) – Addressing type for which consistency check to be performed. Leave None to not perform consistency check with Addressing Type.

Raises

NotImplementedError –

There is missing implementation for the provided Addressing Format. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Returns

True if CAN ID value is compatible with provided addressing values, False otherwise.

Return type

bool

classmethod is_normal_11bit_addressed_can_id(cls, can_id)[source]

Check if the provided value of CAN ID is compatible with Normal 11-bit Addressing format.

Parameters

can_id (int) – Value to check.

Returns

True if value is a valid CAN ID for Normal 11-bit Addressing format, False otherwise.

Return type

bool

classmethod is_normal_fixed_addressed_can_id(cls, can_id, addressing_type=None)[source]

Check if the provided value of CAN ID is compatible with Normal Fixed Addressing format.

Parameters

  • can_id (int) – Value to check.

  • addressing_type (Optional[uds.transmission_attributes.AddressingTypeAlias]) – Addressing type for which consistency check to be performed. Leave None to not perform consistency check with Addressing Type.

Returns

True if value is a valid CAN ID for Normal Fixed Addressing format and consistent with the provided Addressing Type, False otherwise.

Return type

bool

classmethod is_extended_addressed_can_id(cls, can_id)[source]

Check if the provided value of CAN ID is compatible with Extended Addressing format.

Parameters

can_id (int) – Value to check.

Returns

True if value is a valid CAN ID for Extended Addressing format, False otherwise.

Return type

bool

classmethod is_mixed_11bit_addressed_can_id(cls, can_id)[source]

Check if the provided value of CAN ID is compatible with Mixed 11-bit Addressing format.

Parameters

can_id (int) – Value to check.

Returns

True if value is a valid CAN ID for Mixed 11-bit Addressing format, False otherwise.

Return type

bool

classmethod is_mixed_29bit_addressed_can_id(cls, can_id, addressing_type=None)[source]

Check if the provided value of CAN ID is compatible with Mixed 29-bit Addressing format.

Parameters

  • can_id (int) – Value to check.

  • addressing_type (Optional[uds.transmission_attributes.AddressingTypeAlias]) – Addressing type for which consistency check to be performed. Leave None to not perform consistency check with Addressing Type.

Returns

True if value is a valid CAN ID for Mixed 29-bit Addressing format and consistent with the provided Addressing Type, False otherwise.

Return type

bool

classmethod is_can_id(cls, value)[source]

Check if the provided value is either Standard (11-bit) or Extended (29-bit) CAN ID.

Parameters

value (int) – Value to check.

Returns

True if value is a valid CAN ID, False otherwise.

Return type

bool

classmethod is_standard_can_id(cls, can_id)[source]

Check if the provided value is Standard (11-bit) CAN ID.

Parameters

can_id (int) – Value to check.

Returns

True if value is a valid 11-bit CAN ID, False otherwise.

Return type

bool

classmethod is_extended_can_id(cls, can_id)[source]

Check if the provided value is Extended (29-bit) CAN ID.

Parameters

can_id (int) – Value to check.

Returns

True if value is a valid 29-bit CAN ID, False otherwise.

Return type

bool

classmethod validate_can_id(cls, value, extended_can_id=None)[source]

Validate whether provided value is either Standard or Extended CAN ID.

Parameters

  • value (Any) – Value to validate.

  • extended_can_id (Optional[bool]) –

    Flag whether to perform consistency check with CAN ID format.

    • None - does not check the format of the value

    • True - verify that the value uses Extended (29-bit) CAN ID format

    • False - verify that the value uses Standard (11-bit) CAN ID format

Raises

  • TypeError – Provided value is not int type.

  • ValueError – Provided value is out of CAN Identifier values range.

Return type

None

class uds.can.frame_fields.CanDlcHandler[source]

Helper class that provides utilities for CAN Data Length Code field.

CAN Data Length Code (DLC) is a CAN frame field that informs about number of data bytes carried by CAN frames.

CAN DLC supports two values ranges:

  • 0x0-0x8 - linear range which is supported by CLASSICAL CAN and CAN FD

  • 0x9-0xF - discrete range which is supported by CAN FD only

__DLC_VALUES :Tuple[int, Ellipsis]
__DATA_BYTES_NUMBERS :Tuple[int, Ellipsis] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 16, 20, 24, 32, 48, 64]
__DLC_MAPPING :Dict[int, int]
__DATA_BYTES_NUMBER_MAPPING :Dict[int, int]
__DLC_SPECIFIC_FOR_CAN_FD :Set[int]
MIN_DATA_BYTES_NUMBER :int

Minimum number of data bytes in a CAN frame.

MAX_DATA_BYTES_NUMBER :int

Maximum number of data bytes in a CAN frame.

MIN_DLC_VALUE :int

Minimum value of DLC parameter.

MAX_DLC_VALUE :int

Maximum value of DLC parameter.

MIN_BASE_UDS_DLC :int = 8

Minimum CAN DLC value that can be used for UDS communication. Lower values of DLC are only allowed when CAN Frame Data Optimization is used.

classmethod decode_dlc(cls, dlc)[source]

Map a value of CAN DLC into a number of data bytes.

Parameters

dlc (int) – Value of CAN DLC.

Returns

Number of data bytes in a CAN frame that is represented by provided DLC value.

Return type

int

classmethod encode_dlc(cls, data_bytes_number)[source]

Map a number of data bytes in a CAN frame into DLC value.

Parameters

data_bytes_number (int) – Number of data bytes in a CAN frame.

Returns

DLC value of a CAN frame that represents provided number of data bytes.

Return type

int

classmethod get_min_dlc(cls, data_bytes_number)[source]

Get a minimum value of CAN DLC that is required to carry the provided number of data bytes in a CAN frame.

Parameters

data_bytes_number (int) – Number of data bytes in a CAN frame.

Returns

Minimum CAN DLC value that is required to carry provided number of data bytes in a CAN frame.

Return type

int

classmethod is_can_fd_specific_dlc(cls, dlc)[source]

Check whether the provided DLC value is CAN FD specific.

Parameters

dlc (int) – Value of DLC to check.

Returns

True if provided DLC value is CAN FD specific, False otherwise.

Return type

bool

classmethod validate_dlc(cls, value)[source]

Validate whether the provided value is a valid value of CAN DLC.

Parameters

value (Any) – Value to validate.

Raises

  • TypeError – Provided values is not int type.

  • ValueError – Provided value is not a valid DLC value.

Return type

None

classmethod validate_data_bytes_number(cls, value, exact_value=True)[source]

Validate whether provided value is a valid number of data bytes that might be carried a CAN frame.

Parameters

  • value (Any) – Value to validate.

  • exact_value (bool) –

    Informs whether the value must be the exact number of data bytes in a CAN frame.

    • True - provided value must be the exact number of data bytes to be carried by a CAN frame.

    • False - provided value must be a number of data bytes that could be carried by a CAN frame (CAN Frame Data Padding is allowed).

Raises

  • TypeError – Provided values is not int type.

  • ValueError – Provided value is not number of data bytes that matches the criteria.

Return type

None