uds.can.frame ============= .. py:module:: uds.can.frame .. autoapi-nested-parse:: Implementation for CAN frame fields that are influenced by UDS. Handlers for :ref:`CAN Frame ` fields: - CAN Identifier - DLC - Data Attributes ---------- .. autoapisummary:: uds.can.frame.DEFAULT_FILLER_BYTE Classes ------- .. autoapisummary:: uds.can.frame.CanVersion uds.can.frame.CanIdHandler uds.can.frame.CanDlcHandler Module Contents --------------- .. py:data:: DEFAULT_FILLER_BYTE :type: int :value: 204 Default value of Filler Byte. Filler Bytes are used for :ref:`CAN Frame Data Padding `. .. note:: The value is specified by ISO 15765-2:2016 (chapter 10.4.2.1). .. py:class:: CanVersion Bases: :py:obj:`uds.utilities.ValidatedEnum` .. autoapi-inheritance-diagram:: uds.can.frame.CanVersion :parts: 1 :private-bases: :ref:`Versions of CAN bus `. .. py:attribute:: CLASSIC_CAN :type: CanVersion :value: 'Classic CAN' Classic CAN 2.0 .. py:attribute:: CAN_FD :type: CanVersion :value: 'CAN FD' `CAN FD `_ .. py:class:: 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) .. py:attribute:: MIN_STANDARD_VALUE :type: int :value: 0 Minimum value of Standard (11-bit) CAN ID. .. py:attribute:: MAX_STANDARD_VALUE :type: int :value: 2047 Maximum value of Standard (11-bit) CAN ID. .. py:attribute:: MIN_EXTENDED_VALUE :type: int :value: 2048 Minimum value of Extended (29-bit) CAN ID. .. py:attribute:: MAX_EXTENDED_VALUE :type: int :value: 536870911 Maximum value of Extended (29-bit) CAN ID. .. py:attribute:: ADDRESSING_MASK :type: int :value: 67043328 CAN ID mask for bits enforced by SAE J1939 (Normal Fixed of Mixed 29bit addressing formats). .. py:attribute:: NORMAL_FIXED_PHYSICAL_ADDRESSING_MASKED_VALUE :type: int :value: 14286848 Masked value of physically addressed CAN ID in Normal Fixed Addressing format. .. py:attribute:: NORMAL_FIXED_FUNCTIONAL_ADDRESSING_MASKED_VALUE :type: int :value: 14352384 Masked value of functionally addressed CAN ID in Normal Fixed Addressing format. .. py:attribute:: MIXED_29BIT_PHYSICAL_ADDRESSING_MASKED_VALUE :type: int :value: 13500416 Masked value of physically addressed CAN ID in Mixed 29-bit Addressing format. .. py:attribute:: MIXED_29BIT_FUNCTIONAL_ADDRESSING_MASKED_VALUE :type: int :value: 13434880 Masked value of functionally addressed CAN ID in Mixed 29-bit Addressing format. .. py:attribute:: TARGET_ADDRESS_BIT_OFFSET :type: int :value: 8 Bit offset of Target Address parameter in CAN Identifier. .. py:attribute:: SOURCE_ADDRESS_BIT_OFFSET :type: int :value: 0 Bit offset of Source Address parameter. .. py:attribute:: PRIORITY_BIT_OFFSET :type: int :value: 26 Bit offset of Priority parameter defined by SAE J1939. .. py:attribute:: DEFAULT_PRIORITY_VALUE :type: int :value: 6 Default value of Priority parameter defined by SAE J1939. .. py:attribute:: MIN_PRIORITY_VALUE :type: int :value: 0 Minimal value of Priority parameter defined by SAE J1939. .. py:attribute:: MAX_PRIORITY_VALUE :type: int :value: 7 Maximal value of Priority parameter defined by SAE J1939. .. py:method:: is_can_id(value) :classmethod: Check if the provided value is either Standard (11-bit) or Extended (29-bit) CAN ID. :param value: Value to check. :return: True if value is a valid CAN ID, False otherwise. .. py:method:: is_standard_can_id(can_id) :classmethod: Check if the provided value is Standard (11-bit) CAN ID. :param can_id: Value to check. :return: True if value is a valid 11-bit CAN ID, False otherwise. .. py:method:: is_extended_can_id(can_id) :classmethod: Check if the provided value is Extended (29-bit) CAN ID. :param can_id: Value to check. :return: True if value is a valid 29-bit CAN ID, False otherwise. .. py:method:: validate_can_id(value, extended_can_id = None) :classmethod: Validate whether provided value is either Standard or Extended CAN ID. :param value: Value to validate. :param extended_can_id: 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 :raise TypeError: Provided value is not int type. :raise ValueError: Provided value is out of CAN Identifier values range. .. py:method:: validate_priority(value) :classmethod: Validate whether provided priority value is in line with SAE J1939 definition. :param value: Value to validate. :raise TypeError: Provided value is not int type. :raise ValueError: Provided value is out of Priority values range. .. py:class:: 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 .. py:attribute:: __DLC_VALUES :type: Tuple[int, Ellipsis] .. py:attribute:: __DATA_BYTES_NUMBERS :type: Tuple[int, Ellipsis] :value: (0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 16, 20, 24, 32, 48, 64) .. py:attribute:: __DLC_MAPPING :type: Dict[int, int] .. py:attribute:: __DATA_BYTES_NUMBER_MAPPING :type: Dict[int, int] .. py:attribute:: __DLC_SPECIFIC_FOR_CAN_FD :type: Set[int] .. py:attribute:: MIN_DATA_BYTES_NUMBER :type: int Minimum number of data bytes in a CAN frame. .. py:attribute:: MAX_DATA_BYTES_NUMBER :type: int Maximum number of data bytes in a CAN frame. .. py:attribute:: MIN_DLC_VALUE :type: int Minimum value of DLC parameter. .. py:attribute:: MAX_DLC_VALUE :type: int Maximum value of DLC parameter. .. py:attribute:: MIN_BASE_UDS_DLC :type: int :value: 8 Minimum CAN DLC value that can be used for UDS communication. Lower values of DLC are only allowed when :ref:`CAN Frame Data Optimization ` is used. .. py:method:: decode_dlc(dlc) :classmethod: Map a value of CAN DLC into a number of data bytes. :param dlc: Value of CAN DLC. :return: Number of data bytes in a CAN frame that is represented by provided DLC value. .. py:method:: encode_dlc(data_bytes_number) :classmethod: Map a number of data bytes in a CAN frame into DLC value. :param data_bytes_number: Number of data bytes in a CAN frame. :return: DLC value of a CAN frame that represents provided number of data bytes. .. py:method:: get_min_dlc(data_bytes_number) :classmethod: Get a minimum value of CAN DLC that is required to carry the provided number of data bytes in a CAN frame. :param data_bytes_number: Number of data bytes in a CAN frame. :return: Minimum CAN DLC value that is required to carry provided number of data bytes in a CAN frame. .. py:method:: is_can_fd_specific_dlc(dlc) :classmethod: Check whether the provided DLC value is CAN FD specific. :param dlc: Value of DLC to check. :return: True if provided DLC value is CAN FD specific, False otherwise. .. py:method:: validate_dlc(value) :classmethod: Validate whether the provided value is a valid value of CAN DLC. :param value: Value to validate. :raise TypeError: Provided values is not int type. :raise ValueError: Provided value is not a valid DLC value. .. py:method:: validate_data_bytes_number(value, exact_value = True) :classmethod: Validate whether the provided number of data bytes might be carried in a CAN frame. :param value: Value to validate. :param exact_value: 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 (:ref:`CAN Frame Data Padding ` is allowed). :raise TypeError: Provided values is not int type. :raise ValueError: Provided value is not number of data bytes that matches the criteria.