uds.can.transport_interface.common

Definition of UDS Transport Interface for CAN bus.

Classes

AbstractCanTransportInterface

Abstract definition of Transport Interface for managing Diagnostics on CAN.

Module Contents

class uds.can.transport_interface.common.AbstractCanTransportInterface(network_manager, addressing_information, n_as_timeout=N_AS_TIMEOUT, n_ar_timeout=N_AR_TIMEOUT, n_bs_timeout=N_BS_TIMEOUT, n_cr_timeout=N_CR_TIMEOUT, n_br=DEFAULT_N_BR, n_cs=DEFAULT_N_CS, flow_control_parameters_generator=DEFAULT_FLOW_CONTROL_PARAMETERS, can_version=CanVersion.CLASSIC_CAN, bitrate_switch=False, **segmenter_configuration)

Bases: uds.transport_interface.AbstractTransportInterface, abc.ABC

Abstract definition of Transport Interface for managing Diagnostics on CAN.

CAN Transport Interfaces are meant to handle UDS middle layers (Transport and Network) on CAN bus.

Create Transport Interface (an object for handling UDS Transport and Network layers).

Parameters:

• network_manager (Any) – An object that handles CAN bus (Physical and Data layers of OSI Model).

• addressing_information (uds.can.addressing.AbstractCanAddressingInformation) – Addressing Information configuration of a simulated node that is taking part in DoCAN communication.

• n_as_timeout (uds.utilities.TimeMillisecondsAlias) – Timeout value for N_As time parameter.

• n_ar_timeout (uds.utilities.TimeMillisecondsAlias) – Timeout value for N_Ar time parameter.

• n_bs_timeout (uds.utilities.TimeMillisecondsAlias) – Timeout value for N_Bs time parameter.

• n_cr_timeout (uds.utilities.TimeMillisecondsAlias) – Timeout value for N_Cr time parameter.

• n_br (uds.utilities.TimeMillisecondsAlias) – Value of N_Br time parameter to use in communication.

• n_cs (uds.utilities.TimeMillisecondsAlias | None) – Value of N_Cs time parameter to use in communication.

• flow_control_parameters_generator (uds.can.packet.AbstractFlowControlParametersGenerator) – Generator with Flow Control parameters to use.

• can_version (uds.can.frame.CanVersion) – Version of CAN protocol to be used for packets sending.

• bitrate_switch (bool) – Whether bitrate switch (BRS) shall be set in sent packets.

• segmenter_configuration (Any) –

  Configuration parameters for CAN Segmenter.

  • parameter dlc:

    Base CAN DLC value to use for CAN packets.

  • parameter min_dlc:

    Minimal CAN DLC to use for CAN Packets during Data Optimization.

  • parameter use_data_optimization:

    Information whether to use CAN Frame Data Optimization.

  • parameter filler_byte:

    Filler byte value to use for CAN Frame Data Padding.

N_AS_TIMEOUT: uds.utilities.TimeMillisecondsAlias = 1000

Timeout value of N_As time parameter according to ISO 15765-2.

N_AR_TIMEOUT: uds.utilities.TimeMillisecondsAlias = 1000

Timeout value of N_Ar time parameter according to ISO 15765-2.

N_BS_TIMEOUT: uds.utilities.TimeMillisecondsAlias = 1000

Timeout value of N_Bs time parameter according to ISO 15765-2.

N_CR_TIMEOUT: uds.utilities.TimeMillisecondsAlias = 1000

Timeout value of N_Cr time parameter according to ISO 15765-2.

DEFAULT_N_BR: uds.utilities.TimeMillisecondsAlias = 0

Default value for N_Br time parameter.

DEFAULT_N_CS: uds.utilities.TimeMillisecondsAlias | None = None

Default value for N_Cs time parameter.

DEFAULT_FLOW_CONTROL_PARAMETERS

Default values generator for Flow Control parameters (Flow Status, Block Size, Separation Time minimum).

addressing_information: uds.can.addressing.AbstractCanAddressingInformation

Get Addressing Information of UDS Entity simulated by this Transport Interface.

__n_ar_measured: uds.utilities.TimeMillisecondsAlias | None = None

__n_as_measured: uds.utilities.TimeMillisecondsAlias | None = None

__n_bs_measured: tuple[uds.utilities.TimeMillisecondsAlias, ...] | None = None

__n_cr_measured: tuple[uds.utilities.TimeMillisecondsAlias, ...] | None = None

property n_as_timeout: uds.utilities.TimeMillisecondsAlias

Get timeout value for N_As time parameter.

Return type:

uds.utilities.TimeMillisecondsAlias

property n_ar_timeout: uds.utilities.TimeMillisecondsAlias

Get timeout value for N_Ar time parameter.

Return type:

uds.utilities.TimeMillisecondsAlias

property n_bs_timeout: uds.utilities.TimeMillisecondsAlias

Get timeout value for N_Bs time parameter.

Return type:

uds.utilities.TimeMillisecondsAlias

property n_cr_timeout: uds.utilities.TimeMillisecondsAlias

Get timeout value for N_Cr time parameter.

Return type:

uds.utilities.TimeMillisecondsAlias

property n_br: uds.utilities.TimeMillisecondsAlias

Get the value of N_Br time parameter which is currently set.

Note

The actual (observed on the bus) value will be slightly longer as it also includes computation and CAN Interface delays.

Return type:

uds.utilities.TimeMillisecondsAlias

property n_cs: uds.utilities.TimeMillisecondsAlias | None

Get the value of N_Cs time parameter which is currently set.

Note

The actual (observed on the bus) value will be slightly longer as it also includes computation and CAN Interface delays.

Return type:

uds.utilities.TimeMillisecondsAlias | None

property flow_control_parameters_generator: uds.can.packet.AbstractFlowControlParametersGenerator

Get generator of Flow Control parameters (Flow Status, Block Size, Separation Time minimum).

Return type:

uds.can.packet.AbstractFlowControlParametersGenerator

property segmenter: uds.can.segmenter.CanSegmenter

Get the segmenter used by this CAN Transport Interface.

Return type:

uds.can.segmenter.CanSegmenter

property can_version: uds.can.frame.CanVersion

Get version of CAN protocol to be used for packets sending.

Return type:

uds.can.frame.CanVersion

property bitrate_switch: bool

Get value of bitrate switch (BRS) to be used for packets sending.

Return type:

bool

property dlc: int

Value of base CAN DLC to use for output CAN packets.

Note

All output CAN packets will have this DLC value set unless CAN Frame Data Optimization is used.

Return type:

int

property min_dlc: int | None

Value of minimal CAN DLC to use for CAN Packets during Data Optimization.

Note

Output CAN Packets (created by segmentation()) will never have DLC smaller than this value even if CAN Frame Data Optimization is used.

Return type:

int | None

property use_data_optimization: bool

Information whether to use CAN Frame Data Optimization during CAN packets creation.

See also

CAN Frame Data Optimization

Return type:

bool

property filler_byte: int

Filler byte value to use for output CAN Frame Data Padding during segmentation.

See also

CAN Frame Data Padding

Return type:

int

property n_as_measured: uds.utilities.TimeMillisecondsAlias | None

Get the last measured value of N_As time parameter.

Note

The last measurement comes from the last transmission of Single Frame or First Fame CAN Packet using either send_packet() or async_send_packet() method.

Returns:

Time in milliseconds or None if the value was never measured.

Return type:

uds.utilities.TimeMillisecondsAlias | None

property n_ar_measured: uds.utilities.TimeMillisecondsAlias | None

Get the last measured value of N_Ar time parameter.

Note

The last measurement comes from the last transmission of Flow Control CAN Packet using either receive_packet() or async_receive_packet() method.

Returns:

Time in milliseconds or None if the value was never measured.

Return type:

uds.utilities.TimeMillisecondsAlias | None

property n_bs_measured: tuple[uds.utilities.TimeMillisecondsAlias, ...] | None

Get the last measured values of N_Bs time parameter.

Note

The last measurement comes from the last transmission of UDS message using either send_message() or async_send_message() method.

Returns:

Tuple with times in milliseconds or None if the values could not be measured.

Return type:

tuple[uds.utilities.TimeMillisecondsAlias, …] | None

property n_br_max: uds.utilities.TimeMillisecondsAlias

Get the maximum valid value of N_Br time parameter.

Warning

To assess maximal value of N_Br, the actual value of N_Ar time parameter is required. Either the latest measured value of N_Ar would be used, or 0ms would be assumed (if there are no measurement result).

Return type:

uds.utilities.TimeMillisecondsAlias

property n_cs_max: uds.utilities.TimeMillisecondsAlias

Get the maximum valid value of N_Cs time parameter.

Warning

To assess maximal value of N_Cs, the actual value of N_As time parameter is required. Either the latest measured value of N_As would be used, or 0ms would be assumed (if there are no measurement result).

Return type:

uds.utilities.TimeMillisecondsAlias

property n_cr_measured: tuple[uds.utilities.TimeMillisecondsAlias, ...] | None

Get the last measured values of N_Cr time parameter.

Note

The last measurement comes from the last reception of UDS message using either receive_message() or async_receive_message() method.

Returns:

Tuple with times in milliseconds or None if the values could not be measured.

Return type:

tuple[uds.utilities.TimeMillisecondsAlias, …] | None

_update_n_ar_measured(value)

Update measured values of N_Ar.

Parameters:

value (uds.utilities.TimeMillisecondsAlias) – Value to set.

Return type:

None

_update_n_as_measured(value)

Update measured values of N_As.

Parameters:

value (uds.utilities.TimeMillisecondsAlias) – Value to set.

Return type:

None

_update_n_bs_measured(message_record)

Update measured values of N_Bs according to timestamps of CAN packet records.

Parameters:

message_record (uds.message.UdsMessageRecord) – Record of UDS message transmitted over CAN.

Raises:

• TypeError – Provided value is not UDS message record.

• ValueError – Provided UDS message record was not transmitted.

Return type:

None

_update_n_cr_measured(message_record)

Update measured values of N_Cr according to timestamps of CAN packet records.

Parameters:

message_record (uds.message.UdsMessageRecord) – Record of UDS message received over CAN.

Raises:

• TypeError – Provided value is not UDS message record.

• ValueError – Provided UDS message record was not received.

Return type:

None

clear_measurements()

Clear measured values of Network Layer CAN communication parameters.

Return type:

None

_send_cf_packets_block(cf_packets_block, delay, fc_transmission_timestamp)

Send a block of Consecutive Frame CAN packets.

Parameters:

• cf_packets_block (list[uds.can.packet.CanPacket]) – Consecutive Frame CAN packets to send.

• delay (uds.utilities.TimeMillisecondsAlias) – Minimum delay between sending following Consecutive Frame packets [ms].

• fc_transmission_timestamp (float) – Transmission timestamp of the preceding Flow Control packet.

Returns:

Records containing historical information about the transmitted Consecutive Frame CAN packets.

Return type:

tuple[uds.can.packet.CanPacketRecord, …]

async _async_send_cf_packets_block(cf_packets_block, delay, fc_transmission_timestamp, loop)

Asynchronously send a block of Consecutive Frame CAN packets.

Parameters:

• cf_packets_block (list[uds.can.packet.CanPacket]) – Consecutive Frame CAN packets to send.

• delay (uds.utilities.TimeMillisecondsAlias) – Minimum delay between sending following Consecutive Frame packets [ms].

• fc_transmission_timestamp (float) – Transmission timestamp of the preceding Flow Control packet.

• loop (asyncio.AbstractEventLoop) – The asyncio event loop to use for scheduling this task.

Returns:

Records containing historical information about the transmitted Consecutive Frame CAN packets.

Return type:

tuple[uds.can.packet.CanPacketRecord, …]

_receive_cf_packets_block(sequence_number, block_size, remaining_data_length, timestamp_end)

Receive block of Consecutive Frames.

Parameters:

• sequence_number (int) – Current Sequence Number (next Consecutive Frame shall have this value set).

• block_size (int) – Block Size value sent in the last Flow Control CAN packet.

• remaining_data_length (int) – Number of remaining data bytes to receive in UDS message.

• timestamp_end (uds.utilities.TimestampAlias | None) – The final timestamp till when the reception must be completed.

Raises:

• TimeoutError – Timeout was reached. Either: - Consecutive Frame did not arrive before reaching N_Cr timeout - diagnostic message was not fully received on time

• CanUnexpectedSequenceNumber – Consecutive Frame with unexpected Sequence Number value was received.

Returns:

Either: - Record of UDS message if reception was interrupted by a new UDS message transmission. - Tuple with records of received Consecutive Frames.

Return type:

uds.message.UdsMessageRecord | tuple[uds.can.packet.CanPacketRecord, …]

async _async_receive_cf_packets_block(sequence_number, block_size, remaining_data_length, timestamp_end, loop)

Receive asynchronously block of Consecutive Frames.

Parameters:

• sequence_number (int) – Current Sequence Number (next Consecutive Frame shall have this value set).

• block_size (int) – Block Size value sent in the last Flow Control CAN packet.

• remaining_data_length (int) – Number of remaining data bytes to receive in UDS message.

• timestamp_end (uds.utilities.TimestampAlias | None) – The final timestamp till when the reception must be completed.

• loop (asyncio.AbstractEventLoop) – An asyncio event loop used for observing messages.

Raises:

• TimeoutError – Timeout was reached. Either: - Consecutive Frame did not arrive before reaching N_Cr timeout - diagnostic message was not fully received on time

• CanUnexpectedSequenceNumber – Consecutive Frame with unexpected Sequence Number value was received.

Returns:

Either: - Record of UDS message if reception was interrupted by a new UDS message transmission. - Tuple with records of received Consecutive Frames.

Return type:

uds.message.UdsMessageRecord | tuple[uds.can.packet.CanPacketRecord, …]

_receive_consecutive_frames(first_frame, timestamp_end)

Receive Consecutive Frames after reception of First Frame.

Parameters:

• first_frame (uds.can.packet.CanPacketRecord) – First Frame that was received.

• timestamp_end (uds.utilities.TimestampAlias | None) – The final timestamp till when the reception must be completed.

Raises:

• TimeoutError – Message was not fully received on time.

• CanOverflowFlowStatus – Flow Control packet with Flow Status equal to OVERFLOW was sent.

Returns:

Record of UDS message that was formed provided First Frame and received Consecutive Frames.

Return type:

uds.message.UdsMessageRecord

async _async_receive_consecutive_frames(first_frame, timestamp_end, loop)

Receive asynchronously Consecutive Frames after reception of First Frame.

Parameters:

• first_frame (uds.can.packet.CanPacketRecord) – First Frame that was received.

• timestamp_end (uds.utilities.TimestampAlias | None) – The final timestamp till when the reception must be completed.

• loop (asyncio.AbstractEventLoop) – An asyncio event loop used for observing messages.

Raises:

• TimeoutError – Message was not fully received on time.

• CanOverflowFlowStatus – Flow Control packet with Flow Status equal to OVERFLOW was sent.

Returns:

Record of UDS message that was formed provided First Frame and received Consecutive Frames.

Return type:

uds.message.UdsMessageRecord

_message_receive_start(initial_packet, timestamp_end)

Continue to receive message after receiving initial packet.

Parameters:

• initial_packet (uds.can.packet.CanPacketRecord) – Record of a packet initiating UDS message reception.

• timestamp_end (uds.utilities.TimestampAlias | None) – The final timestamp till when the reception must be completed.

Raises:

NotImplementedError – Unhandled CAN packet starting a new CAN message transmission was received.

Returns:

Record of UDS message received.

Return type:

uds.message.UdsMessageRecord

async _async_message_receive_start(initial_packet, timestamp_end, loop)

Continue to receive message asynchronously after receiving initial packet.

Parameters:

• initial_packet (uds.can.packet.CanPacketRecord) – Record of a packet initiating UDS message reception.

• timestamp_end (uds.utilities.TimestampAlias | None) – The final timestamp till when the reception must be completed.

• loop (asyncio.AbstractEventLoop) – An asyncio event loop used for observing messages.

Raises:

NotImplementedError – Unhandled CAN packet starting a new CAN message transmission was received.

Returns:

Record of UDS message received.

Return type:

uds.message.UdsMessageRecord

abstractmethod _wait_for_flow_control(timeout_timestamp)

Wait until a Flow Control CAN packet is received.

Parameters:

timeout_timestamp (float) – Deadline for receiving the Flow Control CAN packet, expressed as a time.perf_counter() timestamp.

Returns:

Record containing historical information about the received Flow Control CAN packet.

Return type:

uds.can.packet.CanPacketRecord

abstractmethod _async_wait_for_flow_control(timeout_timestamp)

Async:

Parameters:

timeout_timestamp (float)

Return type:

uds.can.packet.CanPacketRecord

Asynchronously wait until a Flow Control CAN packet is received.

Parameters:

timeout_timestamp (float) – Deadline for receiving the Flow Control CAN packet, expressed as a time.perf_counter() timestamp.

Returns:

Record containing historical information about the received Flow Control CAN packet.

Return type:

uds.can.packet.CanPacketRecord

abstractmethod clear_received_frame_buffers()

Clear buffers for storing received CAN frames.

Warning

This makes all previously received CAN packets inaccessible.

Return type:

None

abstractmethod clear_transmitted_frame_buffers()

Clear buffers for storing transmitted CAN frames.

Return type:

None

abstractmethod clear_flow_control_frame_buffers()

Clear buffers for storing received Flow Control CAN frames.

Return type:

None

abstractmethod send_packet(packet)

Transmit CAN packet.

Parameters:

packet (uds.can.packet.CanPacket) – CAN packet to send.

Returns:

Record with historic information about transmitted packet.

Return type:

uds.can.packet.CanPacketRecord

abstractmethod async_send_packet(packet, loop=None)

Async:

Parameters:

• packet (uds.can.packet.CanPacket)

• loop (asyncio.AbstractEventLoop | None)

Return type:

uds.can.packet.CanPacketRecord

Transmit CAN packet asynchronously.

Parameters:

• packet (uds.can.packet.CanPacket) – CAN packet to send.

• loop (asyncio.AbstractEventLoop | None) – An asyncio event loop to use for scheduling this task.

Returns:

Record with historic information about transmitted packet.

Return type:

uds.can.packet.CanPacketRecord

abstractmethod receive_packet(timeout=None)

Receive CAN packet.

Parameters:

timeout (uds.utilities.TimeMillisecondsAlias | None) – Maximal time (in milliseconds) to wait. Leave None to wait forever.

Raises:

TimeoutError – Timeout was reached.

Returns:

Record with historic information about received packet.

Return type:

uds.can.packet.CanPacketRecord

abstractmethod async_receive_packet(timeout=None, loop=None)

Async:

Parameters:

• timeout (uds.utilities.TimeMillisecondsAlias | None)

• loop (asyncio.AbstractEventLoop | None)

Return type:

uds.can.packet.CanPacketRecord

Receive CAN packet asynchronously.

Parameters:

• timeout (uds.utilities.TimeMillisecondsAlias | None) – Maximal time (in milliseconds) to wait. Leave None to wait forever.

• loop (asyncio.AbstractEventLoop | None) – An asyncio event loop to use for scheduling this task.

Raises:

• TimeoutError – Timeout was reached.

• asyncio.TimeoutError – Timeout was reached.

Returns:

Record with historic information about received packet.

Return type:

uds.can.packet.CanPacketRecord

send_message(message)

Transmit UDS message over CAN.

Warning

Must not be called within an asynchronous function.

Parameters:

message (uds.message.UdsMessage) – A message to send.

Raises:

• CanOverflowFlowStatus – Flow Control packet with Flow Status equal to OVERFLOW was received.

• NotImplementedError – Flow Control CAN packet with unknown Flow Status was received.

Returns:

Record with historic information about transmitted UDS message.

Return type:

uds.message.UdsMessageRecord

async async_send_message(message, loop=None)

Transmit asynchronously UDS message over CAN.

Parameters:

• message (uds.message.UdsMessage) – A message to send.

• loop (asyncio.AbstractEventLoop | None) – An asyncio event loop to use for scheduling this task.

Raises:

• CanOverflowFlowStatus – Flow Control packet with Flow Status equal to OVERFLOW was received.

• NotImplementedError – Flow Control CAN packet with unknown Flow Status was received.

Returns:

Record with historic information about transmitted UDS message.

Return type:

uds.message.UdsMessageRecord

receive_message(start_timeout=None, end_timeout=None)

Receive UDS message over CAN.

Parameters:

• start_timeout (uds.utilities.TimeMillisecondsAlias | None) – Maximal time (in milliseconds) to wait for the start of a message transmission. Leave None to wait forever.

• end_timeout (uds.utilities.TimeMillisecondsAlias | None) – Maximal time (in milliseconds) to wait for a message transmission to finish. Leave None to wait forever.

Raises:

MessageTransmissionNotStartedError – Timeout was exceeded before message reception started.

Returns:

Record with historic information about received UDS message.

Return type:

uds.message.UdsMessageRecord

async async_receive_message(start_timeout=None, end_timeout=None, loop=None)

Receive asynchronously UDS message over CAN.

Parameters:

• start_timeout (uds.utilities.TimeMillisecondsAlias | None) – Maximal time (in milliseconds) to wait for the start of a message transmission. Leave None to wait forever.

• end_timeout (uds.utilities.TimeMillisecondsAlias | None) – Maximal time (in milliseconds) to wait for a message transmission to finish. Leave None to wait forever.

• loop (asyncio.AbstractEventLoop | None) – An asyncio event loop to use for scheduling this task.

Raises:

MessageTransmissionNotStartedError – Timeout was exceeded before message reception started.

Returns:

Record with historic information about received UDS message.

Return type:

uds.message.UdsMessageRecord