uds.can.single_frame
Implementation specific for Single Frame CAN packets.
This module contains implementation specific for Single Frame packets - that includes Single Frame Data Length (SF_DL) parameter.
Module Contents
Classes
Helper class that provides utilities for Single Frame CAN Packets. |
- class uds.can.single_frame.CanSingleFrameHandler[source]
Helper class that provides utilities for Single Frame CAN Packets.
- SINGLE_FRAME_N_PCI :uds.utilities.Nibble = 0
N_PCI value of Single Frame.
- MAX_DLC_VALUE_SHORT_SF_DL :int = 8
Maximum value of DLC for which short Single Frame Data Length format shall be used.
- SHORT_SF_DL_BYTES_USED :int = 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 using DLC <= 8.
- LONG_SF_DL_BYTES_USED :int = 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 using DLC > 8.
- classmethod create_valid_frame_data(cls, *, addressing_format, payload, dlc=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]
Create a 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
create_any_frame_data()
to create data bytes for a Single Frame with any (also incompatible with ISO 15765) parameters values.- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format used by a considered Single Frame.
payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by a considered CAN packet.
dlc (Optional[int]) –
DLC value of a CAN frame that carries a considered CAN Packet.
None - use CAN Data Frame Optimization (CAN ID value will be automatically determined)
int type value - DLC value to set. CAN Data Padding will be used to fill the unused data bytes.
filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.
target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. The value must only be provided if addressing_format uses Target Address parameter.
address_extension (Optional[uds.utilities.RawByte]) – Address Extension value carried by this CAN packet. The value must only be provided if addressing_format uses Address Extension parameter.
- Raises
InconsistentArgumentsError – Provided payload contains invalid number of bytes to fit it into a properly defined Single Frame data field.
- Returns
Raw bytes of CAN frame data for the provided Single Frame packet information.
- Return type
uds.utilities.RawBytesList
- classmethod create_any_frame_data(cls, *, addressing_format, payload, dlc, sf_dl_short, sf_dl_long=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]
Create a data field of a CAN frame that carries a Single Frame packet.
Note
You can use this method to create Single Frame data bytes with any (also inconsistent with ISO 15765) parameters values. It is recommended to use
create_valid_frame_data()
to create data bytes for a Single Frame with valid (compatible with ISO 15765) parameters values.- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format used by a considered Single Frame.
payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by a considered CAN packet.
dlc (int) – DLC value of a CAN frame that carries a considered CAN Packet.
sf_dl_short (uds.utilities.Nibble) – Value to put into a slot of Single Frame Data Length in short format.
sf_dl_long (Optional[uds.utilities.RawByte]) – 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.
filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.
target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. The value must only be provided if addressing_format uses Target Address parameter.
address_extension (Optional[uds.utilities.RawByte]) – Address Extension value carried by this CAN packet. The value must only be provided if addressing_format uses Address Extension parameter.
- Raises
InconsistentArgumentsError – Provided payload contains too many bytes to fit it into a Single Frame data field.
- Returns
Raw bytes of CAN frame data for the provided Single Frame packet information.
- Return type
uds.utilities.RawBytesList
- classmethod is_single_frame(cls, addressing_format, raw_frame_data)[source]
Check if provided data bytes encodes a Single Frame packet.
Warning
The method does not validate the content (e.g. SF_DL parameter) of the provided frame data bytes. Only, CAN Packet Type (N_PCI) parameter is checked whether contain Single Frame N_PCI value.
- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a CAN frame to check.
- Returns
True if provided data bytes carries Single Frame, False otherwise.
- Return type
bool
- classmethod decode_payload(cls, addressing_format, raw_frame_data)[source]
Extract diagnostic message 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.
- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a considered CAN frame.
- Returns
Payload bytes of a diagnostic message carried by a considered Single Frame.
- Return type
uds.utilities.RawBytesList
- classmethod decode_sf_dl(cls, addressing_format, raw_frame_data)[source]
Extract a 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.
- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a considered CAN frame.
- Raises
NotImplementedError – There is missing implementation for the provided Single Frame Data Length format. Please create an issue in our Issues Tracking System with detailed description if you face this error.
- Returns
Extracted value of Single Frame Data Length.
- Return type
int
- classmethod get_min_dlc(cls, addressing_format, payload_length)[source]
Get the minimum value of a CAN frame DLC to carry a Single Frame packet.
- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format that considered CAN packet uses.
payload_length (int) – Number of payload bytes that considered CAN packet carries.
- Returns
The lowest value of DLC that enables to fit in provided Single Frame packet data.
- Return type
int
- classmethod get_max_payload_size(cls, addressing_format=None, dlc=None)[source]
Get the maximum size of a payload that can fit into Single Frame data bytes.
- Parameters
addressing_format (Optional[uds.can.addressing_format.CanAddressingFormatAlias]) – CAN addressing format that considered CAN packet uses. Leave None to get the result for CAN addressing format that does not use data bytes for carrying addressing information.
dlc (Optional[int]) – DLC value of a CAN frame that carries a considered CAN Packet. Leave None to get the result for the greatest possible DLC value.
- Raises
InconsistentArgumentsError – Single Frame packet cannot use provided attributes according to ISO 15765.
- Returns
The maximum number of payload bytes that could fit into a considered Single Frame.
- Return type
int
- classmethod get_sf_dl_bytes_number(cls, dlc)[source]
Get number of data bytes used for carrying CAN Packet Type and Single Frame Data Length parameters.
- Parameters
dlc (int) – DLC value of a considered CAN frame.
- Returns
The number of bytes used for carrying CAN Packet Type and Single Frame Data Length parameters.
- Return type
int
- classmethod validate_frame_data(cls, addressing_format, raw_frame_data)[source]
Validate whether data field of a CAN Packet carries a properly encoded Single Frame.
- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a CAN frame to validate.
- Raises
ValueError – Provided frame data of a CAN frames does not carry a Single Frame CAN packet.
InconsistentArgumentsError – Provided frame data of a CAN frames does not carry a properly encoded Single Frame CAN packet.
- Return type
None
- classmethod validate_sf_dl(cls, sf_dl, dlc, addressing_format=None)[source]
Validate a value of Single Frame Data Length.
- Parameters
sf_dl (int) – Single Frame Data Length value to validate.
dlc (int) – DLC value to validate.
addressing_format (Optional[uds.can.addressing_format.CanAddressingFormatAlias]) – Value of CAN Addressing Format to use for Single Frame Data Length value validation. Leave None if you do not want to validate whether payload can fit into a CAN Frame with considered DLC.
- Raises
TypeError – Provided value of Single Frame Data Length is not integer.
ValueError – Provided value of Single Frame Data Length is too small.
InconsistentArgumentsError – 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.
- Return type
None
- classmethod __validate_payload_length(cls, payload_length, ai_data_bytes_number)
Validate value of payload length.
- Parameters
payload_length (int) – Value to validate.
ai_data_bytes_number (int) – Number of data byte that carry Addressing Information.
- Raises
TypeError – Provided value of payload length is not integer.
ValueError – Provided value of payload length is less or equal to 0.
InconsistentArgumentsError – Provided value of payload length is greater than maximum value.
- Return type
None
- classmethod __extract_sf_dl_data_bytes(cls, addressing_format, raw_frame_data)
Extract data bytes that carries CAN Packet Type and Single Frame Data Length parameters.
Warning
This method does not check whether provided raw_frame_data actually contains Single Frame.
- Parameters
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytes) – Raw data bytes of a considered CAN frame.
- Returns
Extracted data bytes with CAN Packet Type and Single Frame Data Length parameters.
- Return type
uds.utilities.RawBytesList
- classmethod __encode_valid_sf_dl(cls, sf_dl, dlc, addressing_format)
Create Single Frame data bytes with CAN Packet Type and Single Frame Data Length parameters.
Note
This method can only be used to create a valid (compatible with ISO 15765 - Diagnostic on CAN) output.
- Parameters
sf_dl (int) – Number of payload bytes carried by a considered Single Frame.
dlc (int) – DLC value of a CAN Frame to carry this information.
addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – Value of CAN Addressing Format to use for Single Frame Data Length value validation.
- Returns
Single Frame data bytes containing CAN Packet Type and Single Frame Data Length parameters.
- Return type
uds.utilities.RawBytesList
- classmethod __encode_any_sf_dl(cls, sf_dl_short=0, sf_dl_long=None)
Create Single Frame data bytes with CAN Packet Type and Single Frame Data Length parameters.
Note
This method can be used to create any (also incompatible with ISO 15765 - Diagnostic on CAN) output.
- Parameters
sf_dl_short (uds.utilities.Nibble) – Value to put into a slot of Single Frame Data Length in short format.
sf_dl_long (Optional[uds.utilities.RawByte]) – 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.
- Returns
Single Frame data bytes containing CAN Packet Type and Single Frame Data Length parameters.
- Return type
uds.utilities.RawBytesList