uds.can.frame_fields ==================== .. py:module:: uds.can.frame_fields .. 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_fields.DEFAULT_FILLER_BYTE Classes ------- .. autoapisummary:: uds.can.frame_fields.CanIdHandler uds.can.frame_fields.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:: 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 Maximum value of Standard (11-bit) CAN ID. .. py:attribute:: MIN_EXTENDED_VALUE :type: int Minimum value of Extended (29-bit) CAN ID. .. py:attribute:: MAX_EXTENDED_VALUE :type: int 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:: 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:attribute:: ADDRESSING_TYPE_NAME :type: str :value: 'addressing_type' Name of :ref:`Addressing Type ` parameter in Addressing Information. .. py:attribute:: TARGET_ADDRESS_NAME :type: str :value: 'target_address' Name of Target Address parameter in Addressing Information. .. py:attribute:: SOURCE_ADDRESS_NAME :type: str :value: 'source_address' Name of Source Address parameter in Addressing Information. .. py:class:: CanIdAIAlias Bases: :py:obj:`TypedDict` .. autoapi-inheritance-diagram:: uds.can.frame_fields.CanIdHandler.CanIdAIAlias :parts: 1 :private-bases: Alias of :ref:`Addressing Information ` that is carried by CAN Identifier. Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: addressing_type :type: Optional[uds.transmission_attributes.AddressingType] .. py:attribute:: target_address :type: Optional[int] .. py:attribute:: source_address :type: Optional[int] .. py:method:: decode_can_id(addressing_format, can_id) :classmethod: 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, Extended or Mixed 11bit addressing format is used as the Addressing Type (in such case) depends on system specific behaviour. :param addressing_format: Addressing format used. :param can_id: CAN ID from which Addressing Information to be extracted. :raise 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. :return: Dictionary with Addressing Information decoded out of the provided CAN ID. .. py:method:: decode_normal_fixed_addressed_can_id(can_id) :classmethod: Extract Addressing Information out of CAN ID for Normal Fixed CAN Addressing format. :param can_id: CAN ID from which Addressing Information to be extracted. :raise ValueError: Provided CAN ID is not compatible with Normal Fixed Addressing format. :raise 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. :return: Dictionary with Addressing Information decoded out of the provided CAN ID. .. py:method:: decode_mixed_addressed_29bit_can_id(can_id) :classmethod: Extract Addressing Information out of CAN ID for Mixed 29-bit CAN Addressing format. :param can_id: CAN ID from which Addressing Information to be extracted. :raise ValueError: Provided CAN ID is not compatible with Mixed 29-bit Addressing format. :raise 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. :return: Dictionary with Addressing Information decoded out of the provided CAN ID. .. py:method:: encode_normal_fixed_addressed_can_id(addressing_type, target_address, source_address, priority = DEFAULT_PRIORITY_VALUE) :classmethod: Generate CAN ID value for Normal Fixed CAN Addressing format. :param addressing_type: Addressing type used. :param target_address: Target Address value to use. :param source_address: Source Address value to use. :param priority: Priority parameter value to use. :raise 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. :return: Value of CAN ID (compatible with Normal Fixed Addressing Format) that was generated from the provided values. .. py:method:: encode_mixed_addressed_29bit_can_id(addressing_type, target_address, source_address, priority = DEFAULT_PRIORITY_VALUE) :classmethod: Generate CAN ID value for Mixed 29-bit CAN Addressing format. :param addressing_type: Addressing type used. :param target_address: Target Address value to use. :param source_address: Source Address value to use. :param priority: Priority parameter value to use. :raise 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. :return: Value of CAN ID (compatible with Mixed 29-bit Addressing Format) that was generated from the provided values. .. py:method:: is_compatible_can_id(can_id, addressing_format, addressing_type = None) :classmethod: Check if the provided value of CAN ID is compatible with addressing format used. :param can_id: Value to check. :param addressing_format: Addressing format used. :param addressing_type: Addressing type for which consistency check to be performed. Leave None to not perform consistency check with Addressing Type. :raise 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. :return: True if CAN ID value is compatible with provided addressing values, False otherwise. .. py:method:: is_normal_addressed_can_id(can_id) :classmethod: Check if the provided value of CAN ID is compatible with Normal Addressing format. :param can_id: Value to check. :return: True if value is a valid CAN ID for Normal 11-bit Addressing format, False otherwise. .. py:method:: is_normal_fixed_addressed_can_id(can_id, addressing_type = None) :classmethod: Check if the provided value of CAN ID is compatible with Normal Fixed Addressing format. :param can_id: Value to check. :param addressing_type: Addressing type for which consistency check to be performed. Leave None to not perform consistency check with Addressing Type. :return: True if value is a valid CAN ID for Normal Fixed Addressing format and consistent with the provided Addressing Type, False otherwise. .. py:method:: is_extended_addressed_can_id(can_id) :classmethod: Check if the provided value of CAN ID is compatible with Extended Addressing format. :param can_id: Value to check. :return: True if value is a valid CAN ID for Extended Addressing format, False otherwise. .. py:method:: is_mixed_11bit_addressed_can_id(can_id) :classmethod: Check if the provided value of CAN ID is compatible with Mixed 11-bit Addressing format. :param can_id: Value to check. :return: True if value is a valid CAN ID for Mixed 11-bit Addressing format, False otherwise. .. py:method:: is_mixed_29bit_addressed_can_id(can_id, addressing_type = None) :classmethod: Check if the provided value of CAN ID is compatible with Mixed 29-bit Addressing format. :param can_id: Value to check. :param addressing_type: Addressing type for which consistency check to be performed. Leave None to not perform consistency check with Addressing Type. :return: True if value is a valid CAN ID for Mixed 29-bit Addressing format and consistent with the provided Addressing Type, False otherwise. .. 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 provided value is a valid number of data bytes that might be carried 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.