uds.can.flow_control

Implementation specific for Flow Control CAN packets.

This module contains implementation of Flow Control packet attributes:

Module Contents

Classes

CanFlowStatus

Definition of Flow Status values.

CanSTminTranslator

Helper class that provides STmin values mapping.

CanFlowControlHandler

Helper class that provides utilities for Flow Control CAN Packets.

Attributes

CanFlowStatusAlias

Typing alias that describes CanFlowStatus member.
exception uds.can.flow_control.UnrecognizedSTminWarning[source]

Bases: Warning

Inheritance diagram of uds.can.flow_control.UnrecognizedSTminWarning

Warning about STmin value that is reserved and therefore not implemented.

Note

If you have a documentation that defines a meaning of STmin value for which this warning was raised, please create a request in issues management system and provide this documentation for us.

Initialize self. See help(type(self)) for accurate signature.

class uds.can.flow_control.CanFlowStatus[source]

Bases: uds.utilities.NibbleEnum, uds.utilities.ValidatedEnum

Inheritance diagram of uds.can.flow_control.CanFlowStatus

Definition of Flow Status values.

Flow Status (FS) is a 4-bit value that enables controlling Consecutive Frames transmission.

Initialize self. See help(type(self)) for accurate signature.

ContinueToSend = 0

Asks to resume Consecutive Frames transmission.

Wait = 1

Asks to pause Consecutive Frames transmission.

Overflow = 2

Asks to abort transmission of a diagnostic message.

uds.can.flow_control.CanFlowStatusAlias

Typing alias that describes CanFlowStatus member.

class uds.can.flow_control.CanSTminTranslator[source]

Helper class that provides STmin values mapping.

Separation Time minimum (STmin) informs about minimum time gap between a transmission of two following Consecutive Frames.

MAX_STMIN_TIME :uds.utilities.TimeMilliseconds = 127

Maximal time value (in milliseconds) of STmin.

MIN_VALUE_MS_RANGE :int = 0

Minimal value of STmin in milliseconds range (raw value and time value in milliseconds are equal).

MAX_VALUE_MS_RANGE :int = 127

Maximal value of STmin in milliseconds range (raw value and time value in milliseconds are equal).

MIN_RAW_VALUE_100US_RANGE :uds.utilities.RawByte = 241

Minimal raw value of STmin in 100 microseconds range.

MAX_RAW_VALUE_100US_RANGE :uds.utilities.RawByte = 249

Maximal raw value of STmin in 100 microseconds range.

MIN_TIME_VALUE_100US_RANGE :uds.utilities.TimeMilliseconds = 0.1

Minimal time value (in milliseconds) of STmin in 100 microseconds range.

MAX_TIME_VALUE_100US_RANGE :uds.utilities.TimeMilliseconds = 0.9

Maximal time value (in milliseconds) of STmin in 100 microseconds range.

__FLOATING_POINT_ACCURACY :int = 10

Accuracy used for floating point values (rounding is necessary due to float operation in python).

classmethod decode(cls, raw_value)[source]

Map raw value of STmin into time value.

Note

According to ISO 15765-2, if a raw value of STmin that is not recognized by its recipient, then the longest STmin time value (0x7F = 127 ms) shall be used instead.

Parameters

raw_value (uds.utilities.RawByte) – Raw value of STmin.

Returns

STmin time in milliseconds.

Return type

uds.utilities.TimeMilliseconds

classmethod encode(cls, time_value)[source]

Map time value of STmin into raw value.

Parameters

time_value (uds.utilities.TimeMilliseconds) – STmin time in milliseconds.

Raises

  • TypeError – Provided value is not time in milliseconds.

  • ValueError – Value out of supported range.

Returns

Raw value of STmin.

Return type

uds.utilities.RawByte

classmethod is_time_value(cls, value)[source]

Check if provided value is a valid time value of STmin.

Parameters

value (Any) – Value to check.

Returns

True if provided value is a valid time value of STmin, False otherwise.

Return type

bool

classmethod _is_ms_value(cls, value)[source]

Check if provided argument is STmin time value in milliseconds.

Parameters

value (uds.utilities.TimeMilliseconds) – Value to check.

Returns

True if provided valid value of STmin time in milliseconds, False otherwise.

Return type

bool

classmethod _is_100us_value(cls, value)[source]

Check if provided argument is STmin time value in 100 microseconds.

Parameters

value (uds.utilities.TimeMilliseconds) – Value to check.

Returns

True if provided valid value of STmin time in 100 microseconds, False otherwise.

Return type

bool

class uds.can.flow_control.CanFlowControlHandler[source]

Helper class that provides utilities for Flow Control CAN Packets.

FLOW_CONTROL_N_PCI :uds.utilities.Nibble = 3

N_PCI value of Flow Control.

FS_BYTES_USED :int = 3

Number of CAN Frame data bytes used to carry CAN Packet Type, Flow Status, Block Size and STmin.

BS_BYTE_POSITION :int = 1

Position of a data byte with Block Size parameter.

STMIN_BYTE_POSITION :int = 2

Position of a data byte with STmin parameter.

classmethod create_valid_frame_data(cls, *, addressing_format, flow_status, block_size=None, st_min=None, 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 Flow Control 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 Flow Control with any (also incompatible with ISO 15765) parameters values.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format used by a considered Flow Control.

  • flow_status (CanFlowStatusAlias) – Value of Flow Status parameter.

  • block_size (Optional[uds.utilities.RawByte]) – Value of Block Size parameter. This parameter is only required with ContinueToSend Flow Status, leave None otherwise.

  • st_min (Optional[uds.utilities.RawByte]) – Value of Separation Time minimum (STmin) parameter. This parameter is only required with ContinueToSend Flow Status, leave None otherwise.

  • 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 – Invalid DLC value was provided.

Returns

Raw bytes of CAN frame data for the provided Flow Control packet information.

Return type

uds.utilities.RawBytesList

classmethod create_any_frame_data(cls, *, addressing_format, flow_status, dlc, block_size=None, st_min=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)[source]

Create a data field of a CAN frame that carries a Flow Control packet.

Note

You can use this method to create Flow Control 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 Flow Control with valid (compatible with ISO 15765) parameters values.

Parameters

  • addressing_format (uds.can.addressing_format.CanAddressingFormatAlias) – CAN addressing format used by a considered Flow Control.

  • flow_status (CanFlowStatusAlias) – Value of Flow Status parameter.

  • st_min (Optional[uds.utilities.RawByte]) – Value of Separation Time minimum (STmin) parameter. Leave None to not insert this parameter in a Flow Control data bytes.

  • block_size (Optional[uds.utilities.RawByte]) – Value of Block Size parameter. Leave None to not insert this parameter in a Flow Control data bytes.

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

  • 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 – DLC value is too small.

Returns

Raw bytes of CAN frame data for the provided Flow Control packet information.

Return type

uds.utilities.RawBytesList

classmethod is_flow_control(cls, addressing_format, raw_frame_data)[source]

Check if provided data bytes encodes a Flow Control packet.

Warning

The method does not validate the content of the provided frame data bytes. Only, CAN Packet Type (N_PCI) parameter is checked whether contain Flow Control 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 Flow Control, False otherwise.

Return type

bool

classmethod decode_flow_status(cls, addressing_format, raw_frame_data)[source]

Extract Flow Status value from Flow Control 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

ValueError – Provided frame data of a CAN frames does not carry a Flow Control CAN packet.

Returns

Flow Status value carried by a considered Flow Control.

Return type

CanFlowStatusAlias

classmethod decode_block_size(cls, addressing_format, raw_frame_data)[source]

Extract Block Size value from Flow Control 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

ValueError – Provided frame data of a CAN frames does not carry a Flow Control CAN packet with Continue To Send Flow Status.

Returns

Block Size value carried by a considered Flow Control.

Return type

uds.utilities.RawByte

classmethod decode_st_min(cls, addressing_format, raw_frame_data)[source]

Extract STmin value from Flow Control 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

ValueError – Provided frame data of a CAN frames does not carry a Flow Control CAN packet with Continue To Send Flow Status.

Returns

Separation Time minimum (STmin) value carried by a considered Flow Control.

Return type

uds.utilities.RawByte

classmethod get_min_dlc(cls, addressing_format)[source]

Get the minimum value of a CAN frame DLC to carry a Flow Control packet.

Parameters

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

Returns

The lowest value of DLC that enables to fit in provided Flow Control packet data.

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 Flow Control.

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 properly encoded Flow Control CAN packet.

Return type

None

classmethod __encode_valid_flow_status(cls, flow_status, block_size=None, st_min=None, filler_byte=DEFAULT_FILLER_BYTE)

Create Flow Control data bytes with CAN Packet Type and Flow Status, Block Size and STmin parameters.

Note

This method can only be used to create a valid (compatible with ISO 15765 - Diagnostic on CAN) output.

Parameters

  • flow_status (CanFlowStatusAlias) – Value of Flow Status parameter.

  • block_size (Optional[uds.utilities.RawByte]) – Value of Block Size parameter. This parameter is only required with ContinueToSend Flow Status, leave None otherwise.

  • st_min (Optional[uds.utilities.RawByte]) – Value of Separation Time minimum (STmin) parameter. This parameter is only required with ContinueToSend Flow Status, leave None otherwise.

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

Returns

Flow Control data bytes with CAN Packet Type and Flow Status, Block Size and STmin parameters.

Return type

uds.utilities.RawBytesList

classmethod __encode_any_flow_status(cls, flow_status, block_size=None, st_min=None)

Create Flow Control data bytes with CAN Packet Type and Flow Status, Block Size and STmin parameters.

Note

This method can be used to create any (also incompatible with ISO 15765 - Diagnostic on CAN) output.

Parameters

  • flow_status (uds.utilities.Nibble) – Value of Flow Status parameter.

  • block_size (Optional[uds.utilities.RawByte]) – Value of Block Size parameter. Leave None to skip the Block Size byte in the output.

  • st_min (Optional[uds.utilities.RawByte]) – Value of Separation Time minimum (STmin) parameter. Leave None to skip the STmin byte in the output.

Returns

Flow Control data bytes with CAN Packet Type and Flow Status, Block Size and STmin parameters. Some of the parameters might be missing if certain arguments were provided.

Return type

uds.utilities.RawBytesList