uds.can.packet.single_frame

Implementation of handlers for Single Frame CAN packet.

Attributes

`SINGLE_FRAME_N_PCI`	N_PCI value of Single Frame.
`MAX_DLC_VALUE_SHORT_SF_DL`	Maximum value of DLC for which short
`SHORT_SF_DL_BYTES_USED`	Number of CAN Frame data bytes used to carry CAN Packet Type and Single Frame Data Length (SF_DL).
`LONG_SF_DL_BYTES_USED`	Number of CAN Frame data bytes used to carry CAN Packet Type and Single Frame Data Length (SF_DL).

Functions

`is_single_frame`(addressing_format, raw_frame_data)	Check if provided data bytes contain a Single Frame packet.
`validate_single_frame_data`(addressing_format, ...)	Validate whether data field of a CAN Packet carries a properly encoded Single Frame.
`create_single_frame_data`(addressing_format, payload[, ...])	Create data field of a CAN frame that carries a valid Single Frame packet.
`generate_single_frame_data`(addressing_format, payload, ...)	Generate CAN frame data field that carries any combination of Single Frame packet data parameters.
`extract_single_frame_payload`(addressing_format, ...)	Extract payload from Single Frame data bytes.
`extract_sf_dl`(addressing_format, raw_frame_data)	Extract the value of Single Frame Data Length from Single Frame data bytes.
`get_max_sf_dl`(addressing_format[, dlc])	Get the maximum value Single Frame Data Length.
`get_single_frame_min_dlc`(addressing_format, payload_length)	Get the minimum value of a CAN frame DLC to carry a Single Frame packet.
`extract_sf_dl_data_bytes`(addressing_format, raw_frame_data)	Extract data bytes that carry CAN Packet Type and Single Frame Data Length parameters.
`get_sf_dl_bytes_number`(dlc)	Get number of data bytes used for carrying CAN Packet Type and Single Frame Data Length parameters.
`encode_sf_dl`(addressing_format, dlc, sf_dl)	Create valid Single Frame data bytes that contain Single Frame Data Length and N_PCI values.
`generate_sf_dl_bytes`([sf_dl_short, sf_dl_long])	Create Single Frame bytes containing Single Frame Data Length and N_PCI values.
`validate_sf_dl`(addressing_format, dlc, sf_dl)	Validate a value of Single Frame Data Length.

Module Contents

uds.can.packet.single_frame.SINGLE_FRAME_N_PCI: int = 0: N_PCI value of Single Frame.

uds.can.packet.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.

uds.can.packet.single_frame.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 (used when DLC <= 8).

uds.can.packet.single_frame.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 (used when DLC > 8).

uds.can.packet.single_frame.is_single_frame(addressing_format, raw_frame_data)[source]

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 CAN Packet Type (N_PCI) parameter for Single Frame N_PCI value.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame to check.

Returns:

True if provided data bytes carries Single Frame, False otherwise.

Return type:

bool

uds.can.packet.single_frame.validate_single_frame_data(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.CanAddressingFormat) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame to validate.

Raises:

ValueError – The value of N_PCI in provided data is not Single Frame N_PCI.
InconsistencyError – Provided frame data of a CAN frames does not carry a properly encoded Single Frame CAN packet.

Return type:

None

uds.can.packet.single_frame.create_single_frame_data(addressing_format, payload, dlc=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]

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 generate_single_frame_data() to generate data bytes with any (also incompatible with ISO 15765) parameters values.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.
payload (uds.utilities.RawBytesAlias) – Payload to carry.
dlc (Optional[int]) –
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.
filler_byte (int) – Filler Byte value to use for CAN Frame Data Padding.
target_address (Optional[int]) – 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.
address_extension (Optional[int]) – 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.

Raises:

InconsistencyError – Provided payload contains invalid number of bytes.

Returns:

Raw data bytes of a CAN frame.

Return type:

bytearray

uds.can.packet.single_frame.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)[source]

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).

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.
payload (uds.utilities.RawBytesAlias) – Payload to carry.
dlc (int) – DLC value of a CAN frame.
sf_dl_short (int) – Value to put into a slot of Single Frame Data Length in short format.
sf_dl_long (Optional[int]) – 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 (int) – Filler Byte value to use for CAN Frame Data Padding.
target_address (Optional[int]) – 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.
address_extension (Optional[int]) – 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.

Raises:

InconsistencyError – Provided payload contains invalid number of bytes.

Returns:

Raw data bytes of a CAN frame.

Return type:

bytearray

uds.can.packet.single_frame.extract_single_frame_payload(addressing_format, raw_frame_data)[source]

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.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame.

Returns:

Payload bytes carried by the provided Single Frame data.

Return type:

bytearray

uds.can.packet.single_frame.extract_sf_dl(addressing_format, raw_frame_data)[source]

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.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame.

Raises:

NotImplementedError – There is missing implementation for the provided Single Frame Data Length format.

Returns:

Extracted value of Single Frame Data Length.

Return type:

int

uds.can.packet.single_frame.get_max_sf_dl(addressing_format, dlc=None)[source]

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.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.
dlc (Optional[int]) – DLC value to use. Leave None to get the result for the greatest possible DLC value.

Raises:

InconsistencyError – Single Frame packet cannot use provided attributes.

Returns:

The maximum number value of SF_DL for the provided DLC and CAN Addressing Format.

Return type:

int

uds.can.packet.single_frame.get_single_frame_min_dlc(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.CanAddressingFormat) – CAN addressing format used.
payload_length (int) – Number of payload bytes to carry.

Returns:

The lowest value of DLC for a Single Frame that would carry provided payload size.

Return type:

int

uds.can.packet.single_frame.extract_sf_dl_data_bytes(addressing_format, raw_frame_data)[source]

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.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN Addressing Format used.
raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame.

Returns:

Extracted data bytes with CAN Packet Type and Single Frame Data Length parameters.

Return type:

bytearray

uds.can.packet.single_frame.get_sf_dl_bytes_number(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 CAN frame.
Returns:: The number of bytes used for CAN Packet Type and Single Frame Data Length parameters.
Return type:: int

uds.can.packet.single_frame.encode_sf_dl(addressing_format, dlc, sf_dl)[source]

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.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN Addressing Format used.
dlc (int) – DLC value of a CAN Frame to carry this information.
sf_dl (int) – Number of payload bytes carried by a Single Frame.

Returns:

Single Frame data bytes containing CAN Packet Type and Single Frame Data Length parameters.

Return type:

bytearray

uds.can.packet.single_frame.generate_sf_dl_bytes(sf_dl_short=0, sf_dl_long=None)[source]

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.

Parameters:

sf_dl_short (int) – Value to put into a slot of Single Frame Data Length in short format.
sf_dl_long (Optional[int]) – 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:

CAN frame data bytes containing CAN Packet Type and Single Frame Data Length parameters.

Return type:

bytearray

uds.can.packet.single_frame.validate_sf_dl(addressing_format, dlc, sf_dl)[source]

Validate a value of Single Frame Data Length.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN Addressing Format used.
dlc (int) – DLC value used.
sf_dl (int) – Single Frame Data Length value to validate.

Raises:

TypeError – Provided value of Single Frame Data Length is not int type.
ValueError – Provided value of Single Frame Data Length is too small.
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.

Return type:

None