uds.packet.can_packet

CAN bus specific implementation of UDS packets.

Module Contents

Classes

CanPacket	Definition of a CAN packet.
AnyCanPacket	Definition of a CAN packet in any format.

class uds.packet.can_packet.CanPacket(*, packet_type, addressing_format, addressing_type, can_id=None, target_address=None, source_address=None, address_extension=None, dlc=None, **packet_type_specific_kwargs)

Bases: uds.packet.abstract_packet.AbstractUdsPacket

Definition of a CAN packet.

Objects of this class act as a storage for all relevant attributes of a CAN packet.

Create a storage for a single CAN packet.

Parameters

• packet_type (uds.packet.can_packet_type.CanPacketTypeAlias) – Type of this CAN packet.

• addressing_format (uds.can.CanAddressingFormatAlias) – CAN addressing format that this CAN packet uses.

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (Optional[int]) – CAN Identifier value that is used by this packet. Leave None if other arguments unambiguously determine CAN ID value.

• target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. Leave None if provided addressing_format does not use Target Address parameter or the value of Target Address was provided in can_id parameter.

• source_address (Optional[uds.utilities.RawByte]) – Source Address value carried by this CAN packet. Leave None if provided addressing_format does not use Source Address parameter or the value of Source Address was provided in can_id parameter.

• address_extension (Optional[uds.utilities.RawByte]) – Address Extension value carried by this CAN packet. Leave None if provided addressing_format does not use Address Extension parameter.

• dlc (Optional[int]) –

  DLC value of a CAN frame that carries this 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 unused data bytes.

  Warning

  You have to provide DLC value for packets of First Frame type.

• packet_type_specific_kwargs (Any) –

  Arguments that are specific for provided CAN Packet Type.

  • parameter filler_byte

    (optional for: SF, CF and FC) Filler Byte value to use for CAN Frame Data Padding.

  • parameter payload

    (required for: SF, FF and CF) Payload of a diagnostic message that is carried by this CAN packet.

  • parameter data_length

    (required for: FF) Number of payload bytes of a diagnostic message initiated by this First Frame packet.

  • parameter sequence_number

    (required for: CF) Sequence number value of this Consecutive Frame.

  • parameter flow_status

    (required for: FC) Flow status information carried by this Flow Control frame.

  • parameter block_size

    (required for: FC with ContinueToSend Flow Status) Block size information carried by this Flow Control frame.

  • parameter st_min

    (required for: FC with ContinueToSend Flow Status) Separation Time minimum information carried by this Flow Control frame.

set_address_information(self, *, addressing_format, addressing_type, can_id=None, target_address=None, source_address=None, address_extension=None)

Change addressing information for this CAN packet.

This function enables to change an entire Network Address Information for a CAN packet.

Parameters

• addressing_format (uds.can.CanAddressingFormatAlias) – CAN addressing format that this CAN packet uses.

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (Optional[int]) – CAN Identifier value that is used by this packet. Leave None if other arguments unambiguously determine CAN ID value.

• target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. Leave None if provided addressing_format does not use Target Address parameter or the value of Target Address was provided in can_id parameter.

• source_address (Optional[uds.utilities.RawByte]) – Source Address value carried by this CAN packet. Leave None if provided addressing_format does not use Source Address parameter or the value of Source Address was provided in can_id parameter.

• address_extension (Optional[uds.utilities.RawByte]) – Address Extension value carried by this CAN packet. Leave None if provided addressing_format does not use Address Extension parameter.

Raises

NotImplementedError – There is missing implementation for the provided Addressing Format. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Return type

None

set_address_information_normal_11bit(self, addressing_type, can_id)

Change addressing information for this CAN packet to use Normal 11-bit Addressing format.

Parameters

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (int) – CAN Identifier value that is used by this packet.

Return type

None

set_address_information_normal_fixed(self, addressing_type, can_id=None, target_address=None, source_address=None)

Change addressing information for this CAN packet to use Normal Fixed Addressing format.

Parameters

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (Optional[int]) – CAN Identifier value that is used by this packet. Leave None if the values of target_address and source_address parameters are provided.

• target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. Leave None if the value of can_id parameter is provided.

• source_address (Optional[uds.utilities.RawByte]) – Source Address value carried by this CAN packet. Leave None if the value of can_id parameter is provided.

Return type

None

set_address_information_extended(self, addressing_type, can_id, target_address)

Change addressing information for this CAN packet to use Extended Addressing format.

Parameters

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (int) – CAN Identifier value that is used by this packet.

• target_address (uds.utilities.RawByte) – Target Address value carried by this CAN Packet.

Return type

None

set_address_information_mixed_11bit(self, addressing_type, can_id, address_extension)

Change addressing information for this CAN packet to use Mixed 11-bit Addressing format.

Parameters

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (int) – CAN Identifier value that is used by this packet.

• address_extension (uds.utilities.RawByte) – Address Extension value carried by this CAN packet.

Return type

None

set_address_information_mixed_29bit(self, addressing_type, address_extension, can_id=None, target_address=None, source_address=None)

Change addressing information for this CAN packet to use Mixed 29-bit Addressing format.

Parameters

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (Optional[int]) – CAN Identifier value that is used by this packet. Leave None if the values of target_address and source_address parameters are provided.

• target_address (Optional[uds.utilities.RawByte]) – Target Address value carried by this CAN Packet. Leave None if the value of can_id parameter is provided.

• source_address (Optional[uds.utilities.RawByte]) – Source Address value carried by this CAN packet. Leave None if the value of can_id parameter is provided.

• address_extension (uds.utilities.RawByte) – Address Extension value carried by this CAN packet.

Return type

None

set_packet_data(self, *, packet_type, dlc=None, **packet_type_specific_kwargs)

Change packet type and data field of this CAN packet.

This function enables to change an entire Network Data Field and Network Protocol Control Information for a CAN packet.

Parameters

• packet_type (uds.packet.can_packet_type.CanPacketTypeAlias) – Type of this CAN packet.

• dlc (Optional[int]) –

  DLC value of a CAN frame that carries this 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 unused data bytes.

  Warning

  You have to provide DLC value for packets of First Frame type.

• packet_type_specific_kwargs (Any) –

  Arguments that are specific for provided CAN Packet Type.

  • parameter filler_byte

    (optional for: SF, CF and FC) Filler Byte value to use for CAN Frame Data Padding.

  • parameter payload

    (required for: SF, FF and CF) Payload of a diagnostic message that is carried by this CAN packet.

  • parameter data_length

    (required for: FF) Number of payload bytes of a diagnostic message initiated by this First Frame packet.

  • parameter sequence_number

    (required for: CF) Sequence number value of this Consecutive Frame.

  • parameter flow_status

    (required for: FC) Flow status information carried by this Flow Control frame.

  • parameter block_size

    (required for: FC with ContinueToSend Flow Status) Block size information carried by this Flow Control frame.

  • parameter st_min

    (required for: FC with ContinueToSend Flow Status) Separation Time minimum information carried by this Flow Control frame.

Raises

NotImplementedError –

There is missing implementation for the provided CAN Packet Type. Please create an issue in our Issues Tracking System with detailed description if you face this error.

Return type

None

set_single_frame_data(self, payload, dlc=None, filler_byte=DEFAULT_FILLER_BYTE)

Change packet type (to Single Frame) and data field of this CAN packet.

This function enables to change an entire Network Data Field and Network Protocol Control Information for a Single Frame.

Parameters

• payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by this CAN packet.

• dlc (Optional[int]) –

  DLC value of a CAN frame that carries this 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 unused data bytes.

• filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.

Return type

None

set_first_frame_data(self, dlc, payload, data_length)

Change packet type (to First Frame) and data field of this CAN packet.

This function enables to change an entire Network Data Field and Network Protocol Control Information for a First Frame.

Parameters

• dlc (int) – DLC value of a CAN frame that carries this CAN Packet.

• payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by this CAN packet.

• data_length (int) – Number of payload bytes of a diagnostic message initiated by this First Frame packet.

Return type

None

set_consecutive_frame_data(self, payload, sequence_number, dlc=None, filler_byte=DEFAULT_FILLER_BYTE)

Change packet type (to Consecutive Frame) and data field of this CAN packet.

This function enables to change an entire Network Data Field and Network Protocol Control Information for a Consecutive Frame.

Parameters

• payload (uds.utilities.RawBytes) – Payload of a diagnostic message that is carried by this CAN packet.

• sequence_number (int) – Sequence number value of this Consecutive Frame.

• dlc (Optional[int]) –

  DLC value of a CAN frame that carries this 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 unused data bytes.

• filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.

Return type

None

set_flow_control_data(self, flow_status, block_size=None, st_min=None, dlc=None, filler_byte=DEFAULT_FILLER_BYTE)

Change packet type (to Flow Control) and data field of this CAN packet.

This function enables to change an entire Network Data Field and Network Protocol Control Information for a Flow Control.

Parameters

• flow_status (uds.can.CanFlowStatusAlias) – Flow status information carried by this Flow Control frame.

• block_size (Optional[uds.utilities.RawByte]) – Block size information carried by this Flow Control frame.

• st_min (Optional[uds.utilities.RawByte]) – Separation Time minimum information carried by this Flow Control frame.

• dlc (Optional[int]) –

  DLC value of a CAN frame that carries this 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 unused data bytes.

• filler_byte (uds.utilities.RawByte) – Filler Byte value to use for CAN Frame Data Padding.

Return type

None

property raw_frame_data(self)

Raw data bytes of a CAN frame that carries this CAN packet.

Return type

uds.utilities.RawBytesTuple

property addressing_type(self)

Addressing type for which this CAN packet is relevant.

Return type

uds.transmission_attributes.AddressingTypeAlias

property addressing_format(self)

CAN addressing format used by this CAN packet.

Return type

uds.can.CanAddressingFormatAlias

property packet_type(self)

Type (N_PCI value) of this CAN packet.

Return type

uds.packet.can_packet_type.CanPacketTypeAlias

property can_id(self)

CAN Identifier (CAN ID) of a CAN Frame that carries this CAN packet.

Return type

int

property dlc(self)

Value of Data Length Code (DLC) of a CAN Frame that carries this CAN packet.

Return type

int

property target_address(self)

Target Address (TA) value of this CAN Packet.

Target Address value is used with following addressing formats:

• Normal Fixed Addressing

• Extended Addressing

• Mixed 29-bit Addressing

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property source_address(self)

Source Address (SA) value of this CAN Packet.

Source Address value is used with following addressing formats:

• Normal Fixed Addressing

• Mixed 29-bit Addressing

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property address_extension(self)

Address Extension (AE) value of this CAN Packet.

Address Extension is used with following addressing formats:

• Mixed Addressing - either: - Mixed 11-bit Addressing - Mixed 29-bit Addressing

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property payload(self)

Diagnostic message payload carried by this CAN packet.

Payload is only provided by packets of following types:

• Single Frame

• First Frame

• Consecutive Frame

None in other cases.

Warning

For Consecutive Frames this value might contain additional filler bytes (they are not part of diagnostic message payload) that were added during CAN Frame Data Padding. The presence of filler bytes in Consecutive Frame cannot be determined basing solely on the information contained in this packet object.

Return type

Optional[uds.utilities.RawBytesTuple]

property data_length(self)

Payload bytes number of a diagnostic message that is carried by this CAN packet.

Data length is only provided by packets of following types:

• Single Frame - Single Frame Data Length

• First Frame - First Frame Data Length

None in other cases.

Return type

Optional[int]

property sequence_number(self)

Sequence Number carried by this CAN packet.

Sequence Number is only provided by packets of following types:

• Consecutive Frame

None in other cases.

Return type

Optional[int]

property flow_status(self)

Flow Status carried by this CAN packet.

Flow Status is only provided by packets of following types:

• Flow Control

None in other cases.

Return type

Optional[uds.can.CanFlowStatusAlias]

property block_size(self)

Block Size value carried by this CAN packet.

Block Size is only provided by packets of following types:

• Flow Control

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property st_min(self)

Separation Time minimum (STmin) value carried by this CAN packet.

STmin is only provided by packets of following types:

• Flow Control

None in other cases.

Return type

Optional[uds.utilities.RawByte]

__validate_unambiguous_ai_change(self, addressing_format)

Validate whether CAN Addressing Format change to provided value is ambiguous.

Parameters

addressing_format (uds.can.CanAddressingFormatAlias) – Desired value of CAN Addressing Format.

Raises

AmbiguityError – Cannot change value because the operation is ambiguous.

Return type

None

__update_ai_data_byte(self)

Update the value of raw_frame_data attribute after Addressing Information change.

Return type

None

class uds.packet.can_packet.AnyCanPacket(*, raw_frame_data, addressing_format, addressing_type, can_id)

Bases: uds.packet.abstract_packet.AbstractUdsPacket

Definition of a CAN packet in any format.

Objects of this class act as a storage for all relevant attributes of a CAN packet.

Note

This class is meant to provide option to create CAN Packets that are incompatible with with ISO 15765 (Diagnostic on CAN) standard.

This class is not a replacer to CanPacket and it is recommended to use CanPacket for all valid cases as it provides proper format validation and other features that this class is missing.

Create a storage for a single CAN packet.

Note

Intention of this of this method is to create a CAN Packet that is incompatible with ISO 15765, therefore any parameter validation is restricted to sanity check (whether the data can be converted into a CAN Frame). If you want to create a valid CAN Packet, use CanPacket instead.

Parameters

• raw_frame_data (uds.utilities.RawBytes) –

  Raw data bytes of a CAN frame that carries this CAN packet.

  Note

  One can use uds.can.single_frame.CanSingleFrameHandler.create_any_frame_data(), uds.can.first_frame.CanFirstFrameHandler.create_any_frame_data(), uds.can.consecutive_frame.CanConsecutiveFrameHandler.create_any_frame_data() or uds.can.flow_control.CanFlowControlHandler.create_any_frame_data() to create input (also incompatible with ISO 15765) for this parameter.

• addressing_format (uds.can.CanAddressingFormatAlias) – CAN addressing format that this CAN packet uses.

• addressing_type (uds.transmission_attributes.AddressingTypeAlias) – Addressing type for which this CAN packet is relevant.

• can_id (int) – CAN Identifier value that is used by this packet.

property raw_frame_data(self)

Raw data bytes of a CAN frame that carries this CAN packet.

Return type

uds.utilities.RawBytesTuple

property addressing_type(self)

Addressing type for which this CAN packet is relevant.

Return type

uds.transmission_attributes.AddressingTypeAlias

property addressing_format(self)

CAN addressing format used by this CAN packet.

Return type

uds.can.CanAddressingFormatAlias

property can_id(self)

CAN Identifier (CAN ID) of a CAN Frame that carries this CAN packet.

Return type

int

property packet_type(self)

Type (N_PCI value) of this CAN packet.

Return type

Optional[uds.utilities.Nibble]

property dlc(self)

Value of Data Length Code (DLC) of a CAN Frame that carries this CAN packet.

Return type

int

property target_address(self)

Target Address (TA) value of this CAN Packet.

Target Address value is used with following addressing formats:

• Normal Fixed Addressing

• Extended Addressing

• Mixed 29-bit Addressing

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property source_address(self)

Source Address (SA) value of this CAN Packet.

Source Address value is used with following addressing formats:

• Normal Fixed Addressing

• Mixed 29-bit Addressing

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property address_extension(self)

Address Extension (AE) value of this CAN Packet.

Address Extension is used with following addressing formats:

• Mixed Addressing - either: - Mixed 11-bit Addressing - Mixed 29-bit Addressing

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property payload(self)

Diagnostic message payload carried by this CAN packet.

Payload is only provided by packets of following types:

• Single Frame

• First Frame

• Consecutive Frame

None in other cases.

Warning

For Consecutive Frames this value might contain additional filler bytes (they are not part of diagnostic message payload) that were added during CAN Frame Data Padding. The presence of filler bytes in Consecutive Frame cannot be determined basing solely on the information contained in this packet object.

Return type

Optional[uds.utilities.RawBytesTuple]

property data_length(self)

Payload bytes number of a diagnostic message that is carried by this CAN packet.

Data length is only provided by packets of following types:

• Single Frame - Single Frame Data Length

• First Frame - First Frame Data Length

None in other cases.

Return type

Optional[int]

property sequence_number(self)

Sequence Number carried by this CAN packet.

Sequence Number is only provided by packets of following types:

• Consecutive Frame

None in other cases.

Return type

Optional[int]

property flow_status(self)

Flow Status carried by this CAN packet.

Flow Status is only provided by packets of following types:

• Flow Control

None in other cases.

Return type

Optional[uds.utilities.Nibble]

property block_size(self)

Block Size value carried by this CAN packet.

Block Size is only provided by packets of following types:

• Flow Control

None in other cases.

Return type

Optional[uds.utilities.RawByte]

property st_min(self)

Separation Time minimum (STmin) value carried by this CAN packet.

STmin is only provided by packets of following types:

• Flow Control

None in other cases.

Return type

Optional[uds.utilities.RawByte]

__get_addressing_info(self)

Get Addressing Information carried by this packet.

Returns

Addressing Information decoded from CAN ID and CAN Frame data of this packet. None if Addressing Information cannot be decoded (invalid format of the CAN Packet).

Return type

Optional[dict]