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)[source]
Auxiliary used to handle the UDS protocol on client (tester) side.
Initialize attributes.
- Parameters
com (
CChannel
) – communication channel connector.config_ini_path (
Union
[Path
,str
,None
]) – UDS parameter file.odx_file_path (
Union
[Path
,str
,None
]) – ecu diagnostic definition file.request_id (
Optional
[int
]) – optional CAN ID used for sending messages.response_id (
Optional
[int
]) – optional CAN ID used for receiving messages.
- check_raw_response_negative(resp)[source]
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)[source]
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.0/lib/python3.7/site-packages/pykiso/lib/auxiliaries/udsaux/common/uds_exceptions.py'>
- force_ecu_reset()[source]
Allow power reset of the component
- Return type
UdsResponse
- Returns
response of the force ecu reset request
- hard_reset()[source]
Allow power reset of the component
- Return type
Union
[dict
,UdsResponse
]- Returns
response of the hard reset request
- read_data(parameter)[source]
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)[source]
Send UDS config to the target ECU.
- Parameters
msg_to_send (
dict
) – uds config to be senttimeout_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)[source]
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 senttimeout_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()[source]
Perform soft reset of the component, equivalent to a restart of application
- Return type
Union
[dict
,UdsResponse
]- Returns
response of the soft reset request
- tester_present_sender(period=4)[source]
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)[source]
Transmit a message through ITF connector. This method is a substitute to transmit method present in python-uds package.
- Parameters
data (
bytes
) – data to sendreq_id (
int
) – CAN message identifierextended (
bool
) – True if addressing mode is extended otherwise False
- Return type
None
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)[source]
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)[source]
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)[source]
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()[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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.