uds.can.packet.first_frame ========================== .. py:module:: uds.can.packet.first_frame .. autoapi-nested-parse:: Implementation of handlers for :ref:`First Frame ` CAN packet. Attributes ---------- .. autoapisummary:: uds.can.packet.first_frame.FIRST_FRAME_N_PCI uds.can.packet.first_frame.MAX_SHORT_FF_DL_VALUE uds.can.packet.first_frame.MAX_LONG_FF_DL_VALUE uds.can.packet.first_frame.SHORT_FF_DL_BYTES_USED uds.can.packet.first_frame.LONG_FF_DL_BYTES_USED Functions --------- .. autoapisummary:: uds.can.packet.first_frame.is_first_frame uds.can.packet.first_frame.validate_first_frame_data uds.can.packet.first_frame.create_first_frame_data uds.can.packet.first_frame.generate_first_frame_data uds.can.packet.first_frame.extract_first_frame_payload uds.can.packet.first_frame.extract_ff_dl uds.can.packet.first_frame.get_first_frame_payload_size uds.can.packet.first_frame.extract_ff_dl_data_bytes uds.can.packet.first_frame.encode_ff_dl uds.can.packet.first_frame.generate_ff_dl_bytes uds.can.packet.first_frame.validate_ff_dl Module Contents --------------- .. py:data:: FIRST_FRAME_N_PCI :type: int :value: 1 :ref:`N_PCI ` value of :ref:`First Frame `. .. py:data:: MAX_SHORT_FF_DL_VALUE :type: int :value: 4095 Maximum value of :ref:`First Frame Data Length (FF_DL) ` for which short can be used. .. py:data:: MAX_LONG_FF_DL_VALUE :type: int :value: 4294967295 Maximum value of :ref:`First Frame Data Length (FF_DL) `. .. py:data:: SHORT_FF_DL_BYTES_USED :type: int :value: 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 with FF_DL <= 4095. .. py:data:: LONG_FF_DL_BYTES_USED :type: int :value: 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 with FF_DL > 4095. .. py:function:: is_first_frame(addressing_format, raw_frame_data) Check if provided data bytes contain a First Frame packet. .. warning:: The method does not validate the content (e.g. FF_DL parameter) of the provided frame data bytes. It only checks :ref:`CAN Packet Type (N_PCI) ` parameter for First Frame N_PCI value. :param addressing_format: CAN Addressing Format used. :param raw_frame_data: Raw data bytes of a CAN frame to check. :return: True if provided data bytes carries First Frame, False otherwise. .. py:function:: validate_first_frame_data(addressing_format, raw_frame_data) Validate whether data field of a CAN Packet carries a properly encoded First Frame. :param addressing_format: CAN Addressing Format used. :param raw_frame_data: Raw data bytes of a CAN frame to validate. :raise ValueError: The value of N_PCI in provided data is not First Frame N_PCI. .. py:function:: create_first_frame_data(addressing_format, payload, dlc, data_length, target_address = None, address_extension = None) 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 :func:`~uds.can.packet.first_frame.generate_first_frame_data` to generate data bytes with any (also incompatible with ISO 15765) parameters values. :param addressing_format: CAN addressing format used. :param payload: Payload to carry. :param dlc: DLC value of a CAN frame. :param data_length: Total payload bytes number of a diagnostic message. :param target_address: Target Address value carried by this CAN Packet. The value must only be provided if `addressing_format` requires CAN frame data field to contain Target Address parameter. :param address_extension: Address Extension value carried by this CAN packet. The value must only be provided if `addressing_format` requires CAN frame data field to contain Address Extension parameter. :raise InconsistencyError: Provided `payload` contains incorrect number of bytes to fit them into a First Frame data field using provided parameters. :return: Raw bytes of CAN frame data for the provided First Frame packet information. .. py:function:: generate_first_frame_data(addressing_format, payload, dlc, ff_dl, long_ff_dl_format = False, target_address = None, address_extension = None) Generate CAN frame data field that carries any combination of First Frame packet data parameters. .. note:: Crosscheck of provided values is not performed so you might use this function to create data fields that are not compatible with Diagnostic on CAN standard (ISO 15765). :param addressing_format: CAN addressing format used. :param payload: Payload to carry. :param dlc: DLC value of a CAN frame. :param ff_dl: Total payload bytes number of a diagnostic message. :param long_ff_dl_format: Information whether long or short format of First Frame Data Length is used. :param target_address: Target Address value carried by this CAN Packet. The value must only be provided if `addressing_format` requires CAN frame data field to contain Target Address parameter. :param address_extension: Address Extension value carried by this CAN packet. The value must only be provided if `addressing_format` requires CAN frame data field to contain Address Extension parameter. :raise InconsistencyError: Provided `payload` contains incorrect number of bytes to fit them into a First Frame data field using provided parameters. :return: Raw bytes of CAN frame data for the provided First Frame packet information. .. py:function:: extract_first_frame_payload(addressing_format, raw_frame_data) Extract 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. :param addressing_format: CAN Addressing Format used. :param raw_frame_data: Raw data bytes of a considered CAN frame. :return: Payload bytes carried by the provided Single Frame data. .. py:function:: extract_ff_dl(addressing_format, raw_frame_data) Extract the 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. :param addressing_format: CAN Addressing Format used. :param raw_frame_data: Raw data bytes of a considered CAN frame. :raise NotImplementedError: There is missing implementation for the provided First Frame Data Length format. :return: Extracted value of First Frame Data Length. .. py:function:: get_first_frame_payload_size(addressing_format, dlc, long_ff_dl_format) Get the number of payload bytes that could be carried by First Frame. :param addressing_format: CAN addressing format used. :param dlc: DLC value used. :param long_ff_dl_format: Information whether long or short format of First Frame Data Length is used. :raise ValueError: Invalid DLC value. :return: The number of payload bytes that shall be carried in a First Frame. .. py:function:: extract_ff_dl_data_bytes(addressing_format, raw_frame_data) Extract data bytes that carry CAN Packet Type and First Frame Data Length parameters. .. warning:: This method does not check whether provided `raw_frame_data` actually contains First Frame. :param addressing_format: CAN Addressing Format used. :param raw_frame_data: Raw data bytes of a CAN frame. :return: Extracted data bytes with CAN Packet Type and First Frame Data Length parameters. .. py:function:: encode_ff_dl(addressing_format, dlc, ff_dl) Create valid First Frame data bytes that contain First Frame Data Length and N_PCI values. .. note:: This method can only be used to create a valid (compatible with ISO 15765 - Diagnostic on CAN) output. :param ff_dl: Value to put into a slot of First Frame Data Length. :param dlc: Value of DLC to use for First Frame Data Length value validation. :param addressing_format: Value of CAN Addressing Format to use for First Frame Data Length value validation. :return: First Frame data bytes containing CAN Packet Type and First Frame Data Length parameters. .. py:function:: generate_ff_dl_bytes(ff_dl, long_ff_dl_format) 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. :param ff_dl: Value to put into a slot of First Frame Data Length. :param long_ff_dl_format: Information whether to use long or short format of First Frame Data Length. :raise ValueError: Provided First Frame Data Length value is out of the parameter values range. :return: First Frame data bytes containing CAN Packet Type and First Frame Data Length parameters. .. py:function:: validate_ff_dl(ff_dl, ff_dl_bytes_number = None, dlc = None, addressing_format = None) Validate a value of First Frame Data Length. :param ff_dl: First Frame Data Length value to validate. :param ff_dl_bytes_number: Information how many bytes are used to carry FF_DL. - None - do not perform compatibility check with the FF_DL format - LONG_FF_DL_BYTES_USED - perform compatibility check with long FF_DL format - SHORT_FF_DL_BYTES_USED - perform compatibility check with short FF_DL format - any other value will lead to raising an exception :param dlc: 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. :param addressing_format: 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. :raise TypeError: Provided value of First Frame Data Length is not int type. :raise ValueError: Provided value of First Frame Data Length is out of range (0 <= value <= MAX FF_DL). :raise InconsistencyError: Single Frame shall be used instead of First Frame to transmit provided number of payload bytes represented by FF_DL value.