9. UDS Auxiliary

9.1. uds_auxiliary

module

uds_auxiliary

synopsis

Auxiliary used to handle Unified Diagnostic Service protocol

class pykiso.lib.auxiliaries.udsaux.uds_auxiliary.UdsAuxiliary(com, config_ini_path=None, odx_file_path=None, request_id=None, response_id=None, tp_layer=None, uds_layer=None, **kwargs)

Auxiliary used to handle the UDS protocol on client (tester) side.

Initialize attributes. :type com: CChannel :param com: communication channel connector. :type config_ini_path: Union[Path, str, None] :param config_ini_path: UDS parameter file. :type odx_file_path: Union[Path, str, None] :param odx_file_path: ecu diagnostic definition file. :type request_id: Optional[int] :param request_id: optional CAN ID used for sending messages. :type response_id: Optional[int] :param response_id: optional CAN ID used for receiving messages. :type tp_layer: Optional[dict] :param tp_layer: isotp configuration given at yaml level :type uds_layer: Optional[dict] :param uds_layer: uds configuration given at yaml level

check_raw_response_negative(resp)

Check if the response is negative, raise an error if not

Parameters

resp (UdsResponse) – raw response of uds request

Raises

UnexpectedResponseError – raised when the answer is not the expected one

Return type

Optional[bool]

Returns

True if response is negative

check_raw_response_positive(resp)

Check if the response is positive, raise an error if not

Parameters

resp (UdsResponse) – raw response of uds request

Raises

UnexpectedResponseError – raised when the answer is not the expected one

Return type

Optional[bool]

Returns

True if response is positive

errors = <module 'pykiso.lib.auxiliaries.udsaux.common.uds_exceptions' from '/home/docs/checkouts/readthedocs.org/user_builds/kiso-testing/envs/0.19.2/lib/python3.7/site-packages/pykiso/lib/auxiliaries/udsaux/common/uds_exceptions.py'>

force_ecu_reset()

Allow power reset of the component

Return type

UdsResponse

Returns

response of the force ecu reset request

hard_reset()

Allow power reset of the component

Return type

Union[dict, UdsResponse]

Returns

response of the hard reset request

read_data(parameter)

UDS config command that allow data reading

Parameters

parameter (str) – data to be read

Return type

Union[dict, bool, None]

Returns

a dict with uds config response

send_uds_config(msg_to_send, timeout_in_s=6)

Send UDS config to the target ECU.

Parameters

• msg_to_send (dict) – uds config to be sent

• timeout_in_s (float) – not used

Return type

Union[dict, bool]

Returns

a dict containing the uds response, or True if a response is not expected and the command is properly sent otherwise False

send_uds_raw(msg_to_send, timeout_in_s=6, response_required=True)

Send a UDS diagnostic request to the target ECU and check response.

Parameters

• msg_to_send (Union[bytes, List[int], tuple]) – can uds raw bytes to be sent

• timeout_in_s (float) – not used, actual timeout in seconds for the response can be configured with the P2_CAN_Client parameter in the config.ini file (default value is 5s)

• response_required (bool) – Wait for a response if True

Raises

• ResponseNotReceivedError – raised when no answer has been received

• Exception – raised when the raw message could not be send properly

Return type

Union[UdsResponse, bool]

Returns

the raw uds response’s bytes, or True if a response is not expected and the command is properly sent otherwise False

soft_reset()

Perform soft reset of the component, equivalent to a restart of application

Return type

Union[dict, UdsResponse]

Returns

response of the soft reset request

start_tester_present_sender(period=4)

Start to continuously send tester present messages via UDS

stop_tester_present_sender()

Stop to continuously send tester present messages via UDS

tester_present_sender(period=4)

Context manager that continuously sends tester present messages via UDS

Parameters

period (int) – period in seconds to use for the cyclic sending of tester present

Return type

Iterator[None]

transmit(data, req_id, extended=False)

Transmit a message through ITF connector. This method is a substitute to transmit method present in python-uds package.

Parameters

• data (bytes) – data to send

• req_id (int) – CAN message identifier

• extended (bool) – True if addressing mode is extended otherwise False

Return type

None

write_data(parameter, value)

UDS config command that allow data writing

Parameters

• parameter (str) – data to be set

• value (Union[List[bytes], bytes]) – new content of the data

Return type

Union[dict, bool, None]

Returns

a dict with uds config response

10. UDS Server Auxiliary

10.1. UDS Auxiliary acting as a Server/ECU

module

uds_server_auxiliary

synopsis

Auxiliary used to handle Unified Diagnostic Service protocol as a Server. This auxiliary is meant to run in the background and replies to configured requests.

class pykiso.lib.auxiliaries.udsaux.uds_server_auxiliary.UdsServerAuxiliary(*args, **kwargs)

Auxiliary used to handle the UDS protocol on server (ECU) side.

Initialize attributes.

Parameters

• com – communication channel connector.

• config_ini_path – uds parameters file.

• request_id – optional CAN ID used for sending messages.

• response_id – optional CAN ID used for receiving messages.

• odx_file_path – ecu diagnostic definition file.

property callbacks

Access the callback dictionary in a thread-safe way.

Returns

the internal callbacks dictionary.

static encode_stmin(stmin)

Encode the provided minimum separation time according to the ISO TP specification.

Parameters

stmin (float) – minimum separation time in ms.

Raises

ValueError – if the provided value is not valid.

Return type

int

Returns

the encoded STmin to be sent in a flow control frame.

static format_data(uds_data)

Format UDS data as a list of integers to a hexadecimal string.

Parameters

uds_data (List[int]) – UDS data as a list of integers.

Return type

str

Returns

the UDS data as a hexadecimal string.

receive()

Receive a message through ITF connector. Called inside a thread, this method is a substitute to the reception method used in the python-uds package.

Return type

Optional[bytes]

Returns

the received message or None.

register_callback(request, response=None, response_data=None, data_length=None, callback=None)

Register an automatic response to send if the specified request is received from the client.

The callback is stored inside the callbacks dictionary under the format `{"0x2EC4": UdsCallback()}`_, where the keys are case-sensitive and correspond to the registered requests.

Parameters

• request (Union[int, List[int], UdsCallback]) – UDS request to be responded to.

• response (Union[int, List[int], None]) – full UDS response to send. If not set, respond with a basic positive response with the specified response_data.

• response_data (Union[int, bytes, None]) – UDS data to send. If not set, respond with a basic positive response containing no data.

• data_length (Optional[int]) – optional length of the data to send if it is supposed to have a fixed length (zero-padded).

• callback (Optional[Callable]) – custom callback to register

Return type

None

send_flow_control(flow_status=0, block_size=0, stmin=0)

Send an ISO TP flow control frame to the client.

Parameters

• flow_status (int) – status of the flow control, defaults to 0 (continue to send).

• block_size (int) – size of the data block to send, defaults to 0 (infinitely large).

• stmin (float) – minimum separation time between 2 consecutive frames in ms, defaults to 0 ms.

Return type

None

send_response(response_data)

Encode and transmit a UDS response.

Parameters

response_data (List[int]) – the UDS response to send.

Return type

None

services

alias of uds.uds_config_tool.ISOStandard.ISOStandard.IsoServices

transmit(data, req_id=None, extended=False)

Pad and transmit a message through ITF connector. This method is also used as a substitute to the transmit method present in python-uds package.

Parameters

• data (List[int]) – data to send.

• req_id (Optional[int]) – CAN message identifier. If not set use the one configured.

• extended (bool) – True if addressing mode is extended otherwise False.

Return type

None

unregister_callback(request)

Unregister previously registered callback.

The callback is stored inside the callbacks dictionary under the format `{"0x2E01": UdsCallback()}`_, where the keys are case-sensitive and correspond to the registered requests.

Parameters

request (Union[str, int, List[int]]) – request for which the callback was registered as a string (“0x2E01”), an integer (0x2e01) or a list ([0x2e, 0x01]).

Return type

None

10.2. Helper classes for UDS callback registration

module

uds_callback

synopsis

This module defines classes for the definition of UDS callbacks to be registered by the :py:class:`~pykiso.lib.auxiliaries.uds_aux.uds_server_auxiliary.UdsServerAuxiliary`_ along with callbacks for functional requests (TransferData service).

class pykiso.lib.auxiliaries.udsaux.common.uds_callback.UdsCallback(request, response=None, response_data=None, data_length=None, callback=None)

Class used to store information in order to configure and send a response to the specified UDS request.

Parameters

• request (Union[int, List[int]]) – request from the client that should be responded to.

• response (Optional[Union[int, List[int]]]) – full UDS response to send. If not set, respond with a basic positive response with the specified response_data.

• response_data (Optional[Union[int, bytes]]) – UDS data to send. If not set, respond with a basic positive response containing no data.

• data_length (Optional[int]) – optional length of the data to send in the response if the data has a fixed length (zero-padded).

• callback (Optional[Callable[[List[int], UdsServerAuxiliary], None]]) – custom callback function to register. The callback function must have two positional arguments: the received request as a list of integers and the UdsServerAuxiliary instance.

class pykiso.lib.auxiliaries.udsaux.common.uds_callback.UdsDownloadCallback(request=IsoServices.RequestDownload, response=None, response_data=None, data_length=None, callback=None, stmin=0)

UDS Callback for DownloadData handling on server-side.

In comparison to the base UdsCallback, this callback fixes the request tu 0x34 (RequestDownload) and the custom callback to execute in order to handle the data transfer.

Parameters

stmin (float) – minimum separation time between two received consecutive frames.

static get_first_frame_data_length(first_frame)

Extract the expected data size to receive from a first frame (ISO TP) and the start index of the contained UDS request.

Parameters

first_frame (List[int]) – received first frame.

Return type

Tuple[int, int]

Returns

tuple of two integers corresponding to the expected data length to receive and the resulting start index of the UDS request.

static get_transfer_size(download_request)

Extract the size of the data to download from the passed DownloadData request.

Parameters

download_request (List[int]) – the received DownloadData request.

Return type

int

Returns

the expected download size.

handle_data_download(download_request, aux)

Handle a download request from the client.

This method handles the entire download functional unit composed of:

• sending the appropriate RequestDownload response to the received request

• waiting for the initial TransferData request and sending the ISO TP

  flow control frame

• receiving the data blocks until the transfer is finished

• sending the resulting TransferData positive response

Parameters

• download_request (List[int]) – DownloadData request received from the client.

• aux (UdsServerAuxiliary) – UdsServerAuxiliary instance used by the callback to handle data reception and transmission.

Return type

None

make_request_download_response(max_transfer_size=None)

Build a positive response for a RequestDownload request based on the maximum transfer size.

Parameters

max_transfer_size (Optional[int]) – maximum transfer size. If not set, use the default one configured inside the callback class (0xFFFF).

Returns

the UDS RequestDownload positive response.