uds.can.packet.flow_control

Implementation specific for Flow Control CAN packets.

This module contains implementation of Flow Control CAN packet attributes:

• Flow Status

• Block Size

• Separation Time minimum (STmin)

Attributes

FLOW_CONTROL_N_PCI	N_PCI value of Flow Control.
FS_BYTES_USED	Number of CAN Frame data bytes used to carry CAN Packet Type, Flow Status, Block Size and STmin.
BS_BYTE_POSITION	Position of a data byte with Block Size parameter.
ST_MIN_BYTE_POSITION	Position of a data byte with STmin parameter.
FlowControlParametersAlias	Alias of Flow Control parameters which contain:

Exceptions

UnrecognizedSTminWarning

Warning about STmin value that is reserved for future definition in ISO 15765 and therefore not implemented.

Classes

CanFlowStatus	Definition of Flow Status values.
CanSTminTranslator	Helper class that provides STmin values mapping.
AbstractFlowControlParametersGenerator	Definition of Flow Control parameters generator.
DefaultFlowControlParametersGenerator	Default (recommended to use) Flow Control parameters generator.

Functions

is_flow_control(addressing_format, raw_frame_data)	Check if provided data bytes contain a Flow Control packet.
validate_flow_control_data(addressing_format, ...)	Validate whether data field of a CAN Packet carries a properly encoded Flow Control.
create_flow_control_data(addressing_format, flow_status)	Create a data field of a CAN frame that carries a valid Flow Control packet.
generate_flow_control_data(addressing_format, ...[, ...])	Generate CAN frame data field that carries any combination of Flow Control packet data parameters.
extract_flow_status(addressing_format, raw_frame_data)	Extract Flow Status value from Flow Control data bytes.
extract_block_size(addressing_format, raw_frame_data)	Extract Block Size value from Flow Control data bytes.
extract_st_min(addressing_format, raw_frame_data)	Extract STmin value from Flow Control data bytes.
get_flow_control_min_dlc(addressing_format)	Get the minimum value of a CAN frame DLC to carry a Flow Control packet.
encode_flow_status(flow_status)	Create valid Flow Control data bytes that contain Flow Status and N_PCI values.
generate_flow_status(flow_status)	Create Flow Control bytes containing Flow Status and N_PCI values.

Module Contents

uds.can.packet.flow_control.FLOW_CONTROL_N_PCI: int = 3

N_PCI value of Flow Control.

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

uds.can.packet.flow_control.BS_BYTE_POSITION: int = 1

Position of a data byte with Block Size parameter.

uds.can.packet.flow_control.ST_MIN_BYTE_POSITION: int = 2

Position of a data byte with STmin parameter.

exception uds.can.packet.flow_control.UnrecognizedSTminWarning

Bases: Warning

Warning about STmin value that is reserved for future definition in ISO 15765 and therefore not implemented.

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

class uds.can.packet.flow_control.CanFlowStatus

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

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: CanFlowStatus = 0

Asks to resume Consecutive Frames transmission.

Wait: CanFlowStatus = 1

Asks to pause Consecutive Frames transmission.

Overflow: CanFlowStatus = 2

Asks to abort transmission of a diagnostic message.

class uds.can.packet.flow_control.CanSTminTranslator

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.TimeMillisecondsAlias = 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: int = 241

Minimal raw value of STmin in 100 microseconds range.

MAX_RAW_VALUE_100US_RANGE: int = 249

Maximal raw value of STmin in 100 microseconds range.

MIN_TIME_VALUE_100US_RANGE: uds.utilities.TimeMillisecondsAlias = 0.1

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

MAX_TIME_VALUE_100US_RANGE: uds.utilities.TimeMillisecondsAlias = 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(raw_value)

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 (int) – Raw value of STmin.

Returns:

STmin time in milliseconds.

Return type:

uds.utilities.TimeMillisecondsAlias

classmethod encode(time_value)

Map time value of STmin into raw value.

Parameters:

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

Raises:

• TypeError – Provided value is not int or float type.

• ValueError – Value out of supported range.

Returns:

Raw value of STmin.

Return type:

int

classmethod is_time_value(value)

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

Parameters:

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

Returns:

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

Return type:

bool

classmethod _is_ms_value(value)

Check if provided argument is STmin time value in milliseconds.

Parameters:

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

Returns:

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

Return type:

bool

classmethod _is_100us_value(value)

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

Parameters:

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

Returns:

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

Return type:

bool

uds.can.packet.flow_control.is_flow_control(addressing_format, raw_frame_data)

Check if provided data bytes contain a Flow Control packet.

Warning

The method does not validate the content of the provided frame data bytes. It only checks CAN Packet Type (N_PCI) parameter for Flow Control 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 Flow Control, False otherwise.

Return type:

bool

uds.can.packet.flow_control.validate_flow_control_data(addressing_format, raw_frame_data)

Validate whether data field of a CAN Packet carries a properly encoded Flow Control.

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

• InconsistencyError – Provided data does not carry all Flow Control parameters.

Return type:

None

uds.can.packet.flow_control.create_flow_control_data(addressing_format, flow_status, block_size=None, st_min=None, dlc=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)

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

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

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

• st_min (Optional[int]) – 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 (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 – Invalid DLC value was provided.

Returns:

Raw data bytes of a CAN frame.

Return type:

bytearray

uds.can.packet.flow_control.generate_flow_control_data(addressing_format, flow_status, dlc, block_size=None, st_min=None, filler_byte=DEFAULT_FILLER_BYTE, target_address=None, address_extension=None)

Generate CAN frame data field that carries any combination of Flow Control 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.

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

• dlc (int) – DLC value of a CAN frame.

• block_size (Optional[int]) – Value of Block Size parameter. Leave None to skip this parameter in a Flow Control data bytes.

• st_min (Optional[int]) – Value of Separation Time minimum (STmin) parameter. Leave None to skip this parameter in a Flow Control 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 DLC value is too small.

Returns:

Raw data bytes of a CAN frame.

Return type:

bytearray

uds.can.packet.flow_control.extract_flow_status(addressing_format, raw_frame_data)

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.CanAddressingFormat) – CAN Addressing Format used.

• raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame.

Returns:

Flow Status value carried by the provided Flow Control data.

Return type:

CanFlowStatus

uds.can.packet.flow_control.extract_block_size(addressing_format, raw_frame_data)

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.CanAddressingFormat) – CAN Addressing Format used.

• raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame.

Returns:

Block Size value carried by the provided Flow Control data.

Return type:

int

uds.can.packet.flow_control.extract_st_min(addressing_format, raw_frame_data)

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.CanAddressingFormat) – CAN Addressing Format used.

• raw_frame_data (uds.utilities.RawBytesAlias) – Raw data bytes of a CAN frame.

Returns:

Separation Time minimum (STmin) value carried by the provided Flow Control data.

Return type:

int

uds.can.packet.flow_control.get_flow_control_min_dlc(addressing_format)

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

Parameters:

addressing_format (uds.can.addressing.CanAddressingFormat) – CAN addressing format used.

Returns:

The lowest value of DLC for a Flow Control.

Return type:

int

uds.can.packet.flow_control.encode_flow_status(flow_status)

Create valid Flow Control data bytes that contain Flow Status and N_PCI values.

Parameters:

flow_status (CanFlowStatus) – Value of Flow Status parameter.

Returns:

Flow Control data bytes containing CAN Packet Type and Flow Status parameters.

Return type:

bytearray

uds.can.packet.flow_control.generate_flow_status(flow_status)

Create Flow Control bytes containing Flow Status and N_PCI values.

Note

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

Parameters:

flow_status (int) – Value of Flow Status parameter.

Returns:

Flow Control data bytes containing CAN Packet Type and Flow Status parameters.

Return type:

bytearray

uds.can.packet.flow_control.FlowControlParametersAlias

Alias of Flow Control parameters which contain: - Flow Status - Block Size - Separation Time minimum

class uds.can.packet.flow_control.AbstractFlowControlParametersGenerator

Bases: abc.ABC

Definition of Flow Control parameters generator.

__iter__()

Get iterator object - called on each First Frame reception.

Return type:

AbstractFlowControlParametersGenerator

abstractmethod __next__()

Generate next set of Flow Control parameters - called on each Flow Control message building.

Returns:

Tuple with values of Flow Control parameters (Flow Status, Block Size, ST min).

Return type:

FlowControlParametersAlias

class uds.can.packet.flow_control.DefaultFlowControlParametersGenerator(block_size=0, st_min=0, wait_count=0, repeat_wait=False)

Bases: AbstractFlowControlParametersGenerator

Default (recommended to use) Flow Control parameters generator.

Every generated Flow Control parameters will contain the same (valid) values.

Set values of Block Size and Separation Time minimum parameters to use.

Parameters:

• block_size (int) – Value of Block Size parameter to use.

• st_min (int) – Value of Separation Time minimum parameter to use.

• wait_count (int) – Number of Flow Control packets to send with Flow Status equal 1 (wait).

• repeat_wait (bool) –

  How to send Flow Control packets with WAIT Flow Status:

  • True - send them before every Flow Control packet with Flow Status=0 (continue to send)

  • False - send them only once before the first Flow Control packet with Flow Status=0 (continue to send)

property block_size: int

Value of Block Size parameter.

Return type:

int

property st_min: int

Value of Separation Time minimum parameter.

Return type:

int

property wait_count: int

Get number of Flow Control packets to send with WAIT Flow Status.

Return type:

int

property repeat_wait: bool

Flag informing how to send Flow Control packets with WAIT Flow Status.

• True - send them before every Flow Control packet with Flow Status=0 (continue to send)

• False - send them only once before the first Flow Control packet with Flow Status=0 (continue to send)

Return type:

bool

_remaining_wait: int | None = None

__iter__()

Get iterator object.

Return type:

DefaultFlowControlParametersGenerator

__next__()

Generate next set of Flow Control parameters.

Returns:

Tuple with values of Flow Control parameters: - Flow Status - Block Size - Separation Time minimum

Return type:

FlowControlParametersAlias