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.

uds.can.frame_fields.DEFAULT_FILLER_BYTE: int = 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).

class uds.can.frame_fields.CanIdHandler

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 bus supports two formats of CAN ID:

• Standard (11-bit Identifier)

• Extended (29-bit Identifier)

class CanIdAIAlias

Bases: TypedDict

Alias of Addressing Information that is carried by CAN Identifier.

Initialize self. See help(type(self)) for accurate signature.

addressing_type: uds.transmission_attributes.AddressingType | None

target_address: int | None

source_address: int | None

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: str = 'addressing_type'

Name of Addressing Type parameter in Addressing Information.

TARGET_ADDRESS_NAME: str = 'target_address'

Name of Target Address parameter in Addressing Information.

SOURCE_ADDRESS_NAME: str = 'source_address'

Name of Source Address parameter in Addressing Information.

classmethod decode_can_id(addressing_format, can_id)

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.CanAddressingFormat) – 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:

CanIdAIAlias

classmethod decode_normal_fixed_addressed_can_id(can_id)

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:

CanIdAIAlias

classmethod decode_mixed_addressed_29bit_can_id(can_id)

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:

CanIdAIAlias

classmethod encode_normal_fixed_addressed_can_id(addressing_type, target_address, source_address)

Generate CAN ID value for Normal Fixed CAN Addressing format.

Parameters:

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

• target_address (int) – Target address value to use.

• source_address (int) – 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(addressing_type, target_address, source_address)

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

Parameters:

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

• target_address (int) – Target address value to use.

• source_address (int) – 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(can_id, addressing_format, addressing_type=None)

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.CanAddressingFormat) – Addressing format used.

• addressing_type (Optional[uds.transmission_attributes.AddressingType]) – 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(can_id)

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(can_id, addressing_type=None)

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.AddressingType]) – 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(can_id)

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(can_id)

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(can_id, addressing_type=None)

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.AddressingType]) – 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(value)

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(can_id)

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(can_id)

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(value, extended_can_id=None)

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

Parameters:

• value (int) – 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

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(dlc)

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(data_bytes_number)

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(data_bytes_number)

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(dlc)

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(value)

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

Parameters:

value (int) – 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(value, exact_value=True)

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

Parameters:

• value (int) – 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