uds.can.packet.first_frame

Implementation of handlers for First Frame CAN packet.

Attributes

`FIRST_FRAME_N_PCI`	N_PCI value of First Frame.
`MAX_SHORT_FF_DL_VALUE`	Maximum value of First Frame Data Length (FF_DL)
`MAX_LONG_FF_DL_VALUE`	Maximum value of First Frame Data Length (FF_DL).
`SHORT_FF_DL_BYTES_USED`	Number of CAN Frame data bytes used to carry CAN Packet Type and First Frame Data Length (FF_DL).
`LONG_FF_DL_BYTES_USED`	Number of CAN Frame data bytes used to carry CAN Packet Type and First Frame Data Length (FF_DL).

Functions

`is_first_frame`(addressing_format, raw_frame_data)	Check if provided data bytes contain a First Frame packet.
`validate_first_frame_data`(addressing_format, ...)	Validate whether data field of a CAN Packet carries a properly encoded First Frame.
`create_first_frame_data`(addressing_format, payload, ...)	Create a data field of a CAN frame that carries a valid First Frame packet.
`generate_first_frame_data`(addressing_format, payload, ...)	Generate CAN frame data field that carries any combination of First Frame packet data parameters.
`extract_first_frame_payload`(addressing_format, ...)	Extract payload from First Frame data bytes.
`extract_ff_dl`(addressing_format, raw_frame_data)	Extract the value of First Frame Data Length from First Frame data bytes.
`get_first_frame_payload_size`(addressing_format, dlc, ...)	Get the number of payload bytes that could be carried by First Frame.
`extract_ff_dl_data_bytes`(addressing_format, raw_frame_data)	Extract data bytes that carry CAN Packet Type and First Frame Data Length parameters.
`encode_ff_dl`(addressing_format, dlc, ff_dl)	Create valid First Frame data bytes that contain First Frame Data Length and N_PCI values.
`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.
`validate_ff_dl`(ff_dl[, ff_dl_bytes_number, dlc, ...])	Validate a value of First Frame Data Length.

Module Contents

uds.can.packet.first_frame.FIRST_FRAME_N_PCI: int = 1: N_PCI value of First Frame.

uds.can.packet.first_frame.MAX_SHORT_FF_DL_VALUE: int = 4095: Maximum value of First Frame Data Length (FF_DL) for which short can be used.

uds.can.packet.first_frame.MAX_LONG_FF_DL_VALUE: int = 4294967295: Maximum value of First Frame Data Length (FF_DL).

uds.can.packet.first_frame.SHORT_FF_DL_BYTES_USED: int = 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.

uds.can.packet.first_frame.LONG_FF_DL_BYTES_USED: int = 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.

uds.can.packet.first_frame.is_first_frame(addressing_format, raw_frame_data)[source]

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 CAN Packet Type (N_PCI) parameter for First 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 First Frame, False otherwise.

Return type:

bool

uds.can.packet.first_frame.validate_first_frame_data(addressing_format, raw_frame_data)[source]

Validate whether data field of a CAN Packet carries a properly encoded First 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.

raise ValueError:

The value of N_PCI in provided data is not First Frame N_PCI.

Return type:

None

uds.can.packet.first_frame.create_first_frame_data(addressing_format, payload, dlc, data_length, target_address=None, address_extension=None)[source]

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 generate_first_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 (int) – DLC value of a CAN frame.
data_length (int) – Total payload bytes number of a diagnostic message.
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 incorrect number of bytes to fit them into a First Frame data field using provided parameters.

Returns:

Raw bytes of CAN frame data for the provided First Frame packet information.

Return type:

bytearray

uds.can.packet.first_frame.generate_first_frame_data(addressing_format, payload, dlc, ff_dl, long_ff_dl_format=False, target_address=None, address_extension=None)[source]

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

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.
ff_dl (int) – Total payload bytes number of a diagnostic message.
long_ff_dl_format (bool) – Information whether long or short format of First Frame Data Length is used.
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 incorrect number of bytes to fit them into a First Frame data field using provided parameters.

Returns:

Raw bytes of CAN frame data for the provided First Frame packet information.

Return type:

bytearray

uds.can.packet.first_frame.extract_first_frame_payload(addressing_format, raw_frame_data)[source]

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.

Parameters:

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

Returns:

Payload bytes carried by the provided Single Frame data.

Return type:

bytearray

uds.can.packet.first_frame.extract_ff_dl(addressing_format, raw_frame_data)[source]

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.

Parameters:

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

Raises:

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

Returns:

Extracted value of First Frame Data Length.

Return type:

int

uds.can.packet.first_frame.get_first_frame_payload_size(addressing_format, dlc, long_ff_dl_format)[source]

Get the number of payload bytes that could be carried by First Frame.

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.
dlc (int) – DLC value used.
long_ff_dl_format (bool) – Information whether long or short format of First Frame Data Length is used.

Raises:

ValueError – Invalid DLC value.

Returns:

The number of payload bytes that shall be carried in a First Frame.

Return type:

int

uds.can.packet.first_frame.extract_ff_dl_data_bytes(addressing_format, raw_frame_data)[source]

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.

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 First Frame Data Length parameters.

Return type:

bytearray

uds.can.packet.first_frame.encode_ff_dl(addressing_format, dlc, ff_dl)[source]

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.

Parameters:

ff_dl (int) – Value to put into a slot of First Frame Data Length.
dlc (int) – Value of DLC to use for First Frame Data Length value validation.
addressing_format (uds.can.addressing.CanAddressingFormat) – Value of CAN Addressing Format to use for First Frame Data Length value validation.

Returns:

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

Return type:

bytearray

uds.can.packet.first_frame.generate_ff_dl_bytes(ff_dl, long_ff_dl_format)[source]

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.

Parameters:

ff_dl (int) – Value to put into a slot of First Frame Data Length.
long_ff_dl_format (bool) – Information whether to use long or short format of First Frame Data Length.

Raises:

ValueError – Provided First Frame Data Length value is out of the parameter values range.

Returns:

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

Return type:

bytearray

uds.can.packet.first_frame.validate_ff_dl(ff_dl, ff_dl_bytes_number=None, dlc=None, addressing_format=None)[source]

Validate a value of First Frame Data Length.

Parameters:

ff_dl (int) – First Frame Data Length value to validate.
ff_dl_bytes_number (Optional[int]) –
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
dlc (Optional[int]) – 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.
addressing_format (Optional[uds.can.addressing.CanAddressingFormat]) – 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.

Raises:

TypeError – Provided value of First Frame Data Length is not int type.
ValueError – Provided value of First Frame Data Length is out of range (0 <= value <= MAX FF_DL).
InconsistencyError – Single Frame shall be used instead of First Frame to transmit provided number of payload bytes represented by FF_DL value.

Return type:

None