uds.can.packet.single_frame =========================== .. py:module:: uds.can.packet.single_frame .. autoapi-nested-parse:: Implementation of handlers for :ref:`Single Frame ` CAN packet. Attributes ---------- .. autoapisummary:: uds.can.packet.single_frame.SINGLE_FRAME_N_PCI uds.can.packet.single_frame.MAX_DLC_VALUE_SHORT_SF_DL uds.can.packet.single_frame.SHORT_SF_DL_BYTES_USED uds.can.packet.single_frame.LONG_SF_DL_BYTES_USED Functions --------- .. autoapisummary:: uds.can.packet.single_frame.is_single_frame uds.can.packet.single_frame.validate_single_frame_data uds.can.packet.single_frame.create_single_frame_data uds.can.packet.single_frame.generate_single_frame_data uds.can.packet.single_frame.extract_single_frame_payload uds.can.packet.single_frame.extract_sf_dl uds.can.packet.single_frame.get_max_sf_dl uds.can.packet.single_frame.get_single_frame_min_dlc uds.can.packet.single_frame.extract_sf_dl_data_bytes uds.can.packet.single_frame.get_sf_dl_bytes_number uds.can.packet.single_frame.encode_sf_dl uds.can.packet.single_frame.generate_sf_dl_bytes uds.can.packet.single_frame.validate_sf_dl Module Contents --------------- .. py:data:: SINGLE_FRAME_N_PCI :type: int :value: 0 :ref:`N_PCI ` value of :ref:`Single Frame `. .. py:data:: MAX_DLC_VALUE_SHORT_SF_DL :type: int :value: 8 Maximum value of DLC for which short :ref:`Single Frame Data Length ` format shall be used. .. py:data:: SHORT_SF_DL_BYTES_USED :type: int :value: 1 Number of CAN Frame data bytes used to carry CAN Packet Type and Single Frame Data Length (SF_DL). This value is valid only for the short format (used when DLC <= 8). .. py:data:: LONG_SF_DL_BYTES_USED :type: int :value: 2 Number of CAN Frame data bytes used to carry CAN Packet Type and Single Frame Data Length (SF_DL). This value is valid only for the long format (used when DLC > 8). .. py:function:: is_single_frame(addressing_format, raw_frame_data) Check if provided data bytes contain a Single Frame packet. .. warning:: The method does not validate the content (e.g. SF_DL parameter) of the provided frame data bytes. It only checks :ref:`CAN Packet Type (N_PCI) ` parameter for Single 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 Single Frame, False otherwise. .. py:function:: validate_single_frame_data(addressing_format, raw_frame_data) Validate whether data field of a CAN Packet carries a properly encoded Single 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 Single Frame N_PCI. :raise InconsistencyError: Provided frame data of a CAN frames does not carry a properly encoded Single Frame CAN packet. .. py:function:: create_single_frame_data(addressing_format, payload, dlc = None, filler_byte = DEFAULT_FILLER_BYTE, target_address = None, address_extension = None) Create data field of a CAN frame that carries a valid Single 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.single_frame.generate_single_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. - None - use CAN Data Frame Optimization (CAN DLC value will be automatically determined) - int type value - DLC value to use. CAN Data Padding will be used to fill the unused data bytes. :param filler_byte: Filler Byte value to use for CAN Frame Data Padding. :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 invalid number of bytes. :return: Raw data bytes of a CAN frame. .. py:function:: generate_single_frame_data(addressing_format, payload, dlc, sf_dl_short, sf_dl_long = None, filler_byte = DEFAULT_FILLER_BYTE, target_address = None, address_extension = None) Generate CAN frame data field that carries any combination of Single 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 sf_dl_short: Value to put into a slot of Single Frame Data Length in short format. :param sf_dl_long: Value to put into a slot of Single Frame Data Length in long format. Leave None to use short (1-byte-long) format of Single Frame Data Length. :param filler_byte: Filler Byte value to use for CAN Frame Data Padding. :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 invalid number of bytes. :return: Raw data bytes of a CAN frame. .. py:function:: extract_single_frame_payload(addressing_format, raw_frame_data) Extract payload from Single 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 CAN frame. :return: Payload bytes carried by the provided Single Frame data. .. py:function:: extract_sf_dl(addressing_format, raw_frame_data) Extract the value of Single Frame Data Length from Single 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 CAN frame. :raise NotImplementedError: There is missing implementation for the provided Single Frame Data Length format. :return: Extracted value of Single Frame Data Length. .. py:function:: get_max_sf_dl(addressing_format, dlc = None) Get the maximum value Single Frame Data Length. .. note:: The maximal value of SF_DL reflects maximal number of payload bytes that would fit into a Single Frame. :param addressing_format: CAN addressing format used. :param dlc: DLC value to use. Leave None to get the result for the greatest possible DLC value. :raise InconsistencyError: Single Frame packet cannot use provided attributes. :return: The maximum number value of SF_DL for the provided DLC and CAN Addressing Format. .. py:function:: get_single_frame_min_dlc(addressing_format, payload_length) Get the minimum value of a CAN frame DLC to carry a Single Frame packet. :param addressing_format: CAN addressing format used. :param payload_length: Number of payload bytes to carry. :return: The lowest value of DLC for a Single Frame that would carry provided payload size. .. py:function:: extract_sf_dl_data_bytes(addressing_format, raw_frame_data) Extract data bytes that carry CAN Packet Type and Single Frame Data Length parameters. .. warning:: This method does not check whether provided `raw_frame_data` actually contains Single 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 Single Frame Data Length parameters. .. py:function:: get_sf_dl_bytes_number(dlc) Get number of data bytes used for carrying CAN Packet Type and Single Frame Data Length parameters. :param dlc: DLC value of a CAN frame. :return: The number of bytes used for CAN Packet Type and Single Frame Data Length parameters. .. py:function:: encode_sf_dl(addressing_format, dlc, sf_dl) Create valid Single Frame data bytes that contain Single 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 addressing_format: CAN Addressing Format used. :param dlc: DLC value of a CAN Frame to carry this information. :param sf_dl: Number of payload bytes carried by a Single Frame. :return: Single Frame data bytes containing CAN Packet Type and Single Frame Data Length parameters. .. py:function:: generate_sf_dl_bytes(sf_dl_short = 0, sf_dl_long = None) Create Single Frame bytes containing Single Frame Data Length and N_PCI values. .. note:: This method can be used to create any (also incompatible with ISO 15765 - Diagnostic on CAN) output. :param sf_dl_short: Value to put into a slot of Single Frame Data Length in short format. :param sf_dl_long: Value to put into a slot of Single Frame Data Length in long format. Leave None to use short (1-byte-long) format of Single Frame Data Length./ :return: CAN frame data bytes containing CAN Packet Type and Single Frame Data Length parameters. .. py:function:: validate_sf_dl(addressing_format, dlc, sf_dl) Validate a value of Single Frame Data Length. :param addressing_format: CAN Addressing Format used. :param dlc: DLC value used. :param sf_dl: Single Frame Data Length value to validate. :raise TypeError: Provided value of Single Frame Data Length is not int type. :raise ValueError: Provided value of Single Frame Data Length is too small. :raise InconsistencyError: It is impossible for a Single Frame with provided DLC to contain as many payload bytes as the provided value of Single Frame Data Length.