Client

The UDS client is a simple client that works synchronously and can handle a single request/response at a time. When requesting a service, the client executes these tasks:

Builds a payload

Calls the connection empty_rxqueue method.

Sends the request

Waits for a response, with timeout

Interprets the response data

Validates the response content

Returns the response

The goal of this client is to simplify the usage of the Services object by exposing only useful arguments, hiding repetitive values, handling exceptions and logging. It can detect usage errors as well as malformed server responses.

The client will raise a NegativeResponseException when the server responds with a negative response.

The client may raise InvalidResponseException if the payload is incomplete or if the underlying service raises this exception while parsing the response data.

The client may raise UnexpectedResponseException if the response from the server does not match the last request sent. For example, if the service number in the response is different from the service number in the request. Another case would be if the echo of a parameter for a specific service does not match the request. For instance, if an ECUReset subfunction is the reset type, a valid server response will include an echo of the reset type in its payload.

class udsoncan.client.Client(self, conn, config=default_client_config, request_timeout=None)[source]

Object that interacts with a UDS server. It builds a service request, sends it to the server, receives and parses its response, detects communication anomalies and logs what it is doing for further debugging.

Parameters:

conn (Connection) – The underlying protocol interface.
config (dict) – The client configuration
request_timeout (int) – Maximum amount of time to wait for a response. This parameter exists for backward compatibility only. For detailed timeout handling, see Client configuration

Configuration

The client configuration must be a dictionary with the following keys defined:

exception_on_negative_response (bool): When set to True, the client will raise a NegativeResponseException when the server responds with a negative response. When set to False, the returned Response will have its property positive set to False

exception_on_invalid_response (bool): When set to True, the client will raise a InvalidResponseException when the underlying service interpret_response raises the same exception. When set to False, the returned Response will have its property valid set to False

exception_on_unexpected_response (bool): When set to True, the client will raise a UnexpectedResponseException when the server returns a response that is not expected. For instance, a response for a different service or when the subfunction echo doesn’t match the request. When set to False, the returned Response will have its property unexpected set to True in the same case.

security_algo (callable)

The implementation of the security algorithm necessary for the SecurityAccess service. This function must have the following signatures:

SomeAlgorithm(level, seed, params)

Parameters:

level (int) – The requested security level.

seed (bytes) – The seed given by the server

params – The value provided by the client configuration security_algo_params

Returns:

The security key

Return type:

bytes

Warning

Starting from v1.12, parameters are passed by name, so their order is not important, but their name is. Also, for backward compatibility, Python reflection is used to pass only arguments present in the signature. So a signature such as SomeAlgorithm() would be accepted.

See an example

security_algo_params (...): This value will be given to the security algorithm defined in config['security_algo']. This value can be any Python object, including a dictionary.

data_identifiers (dict)

This configuration is a dictionary that is mapping an integer (the data identifier) with a DidCodec. These codecs will be used to convert values to byte payload and vice-versa when sending/receiving data for a service that needs a DID, i.e.:

ReadDataByIdentifier

WriteDataByIdentifier

ReadDTCInformation with subfunction reportDTCSnapshotRecordByDTCNumber and reportDTCSnapshotRecordByRecordNumber

Possible configuration values are

string : The string will be used as a pack/unpack string when processing the data

DidCodec (class or instance) : The encode/decode method will be used to process the data

The special dictionnary key ‘default’ can be used to specify a fallback codec if an operation is done on a codec not part of the configuration. Useful for scanning a range of DID

input_output (dict)

This configuration is a dictionary that is mapping an integer (the IO data identifier) with a DidCodec specifically for the InputOutputControlByIdentifier service. Just like config[data_identifers], these codecs will be used to convert values to byte payload and vice-versa when sending/receiving data.

Since InputOutputControlByIdentifier supports composite codecs, it is possible to provide a sub-dictionary as a codec specifying the bitmasks.

Possible configuration values are:

string : The string will be used as a pack/unpack string when processing the data

DidCodec (class or instance) : The encode/decode method will be used to process the data

dict : The dictionary entry indicates a composite DID. Three subkeys must be defined as:

codec : The codec, a string or a DidCodec class/instance

mask : A dictionary mapping the mask name with a bit

mask_size : An integer indicating on how many bytes must the mask be encoded

The special dictionnary key ‘default’ can be used to specify a fallback codec if an operation is done on a codec not part of the configuration. Useful for scanning a range of DID

See this example to see how IO codecs are defined.

tolerate_zero_padding (bool): This value will be passed to the services ‘interpret_response’ when the parameter is supported as in ReadDataByIdentifier, ReadDTCInformation. It has to ignore trailing zeros in the response data to avoid falsely raising InvalidResponseException if the underlying protocol uses some zero-padding.

ignore_all_zero_dtc (bool)

This value is used with the ReadDTCInformation service when reading DTCs. It will skip any DTC that has an ID of 0x000000. If the underlying protocol uses zero-padding, it may generate a valid response data of all zeros. This parameter is different from config['tolerate_zero_padding'].

Consider a server response that contains a list of DTCs where all DTCs must be 4 bytes long (ID and status). Say that the server returns a single DTC of value 0x123456, with status 0x78 over a transport protocol that uses zero-padding. Let’s study 5 different payloads.

1234567800 (invalid)

123456780000 (invalid)

12345678000000 (invalid)

1234567800000000 (valid)

123456780000000000 (invalid)

In this situation, all cases except case 4 would raise a InvalidResponseException because of their incorrect lengths (unless config['tolerate_zero_padding'] is set to True). Case 4 would return 2 DTCs, the second DTC with an ID of 0x000000 and a status of 0x00. Setting config['ignore_all_zero_dtc'] to True will make the functions return only the first valid DTC.

server_address_format (int)

The MemoryLocation server_address_format is the value to use when none is specified explicitly for methods expecting a parameter of type MemoryLocation.

See an example

server_memorysize_format (int)

The MemoryLocation server_memorysize_format is the value to use when none is specified explicitly for methods expecting a parameter of type MemoryLocation

See an example

extended_data_size (dict[int] = int): This is the description of all the DTC extended data record sizes. This value is used to decode the server response when requesting a DTC extended data. The value must be specified as follows:

config['extended_data_size'] = {
   0x123456 : 45, # Extended data for DTC 0x123456 is 45 bytes long
   0x123457 : 23 # Extended data for DTC 0x123457 is 23 bytes long
}

dtc_snapshot_did_size (int): The number of bytes used to encode a data identifier specifically for ReadDTCInformation subfunction reportDTCSnapshotRecordByDTCNumber and reportDTCSnapshotRecordByRecordNumber. The UDS standard does not specify a DID size although all other services expect a DID encoded over 2 bytes (16 bits). Default value of 2

standard_version (int): The standard version to use, valid values are : 2006, 2013, 2020. Default value is 2020

request_timeout (float)

Maximum amount of time in seconds to wait for a response of any kind, positive or negative, after sending a request. After this time is elapsed, a TimeoutException will be raised regardless of other timeouts value or previous client responses. In particular even if the server requests that the client wait, by returning response requestCorrectlyReceived-ResponsePending (0x78), this timeout will still trigger.

If you wish to disable this behaviour and have your server wait for as long as it takes for the ECU to finish whatever activity you have requested, set this value to None.

Default value of 5

p2_timeout (float): Maximum amount of time in seconds to wait for a first response (positive, negative, or NRC 0x78). After this time is elapsed, a TimeoutException will be raised if no response has been received. See ISO 14229-2:2013 (UDS Session Layer Services) for more details. Default value of 1

p2_star_timeout (float): Maximum amount of time in seconds to wait for a response (positive, negative, or NRC0x78) after the reception of a negative response with code 0x78 (requestCorrectlyReceived-ResponsePending). After this time is elapsed, a TimeoutException will be raised if no response has been received. See ISO 14229-2:2013 (UDS Session Layer Services) for more details. Default value of 5

use_server_timing (bool)

When using 2013 standard or above, the server is required to provide its P2 and P2* timing values with a DiagnosticSessionControl request. By setting this parameter to True, the value received from the server will be used. When False, these timing values will be ignored and local configuration timing will be used. Note that no timeout value can exceed the config['request_timeout'] as it is meant to avoid the client from hanging for too long.

This parameter has no effect when config['standard_version'] is set to 2006.

Default value is True

Suppress positive response

The UDS standard proposes a mechanism to avoid treating useless positive responses. For all services using a subfunction byte, the client can set bit 7 of the subfunction byte to signal that no response is necessary if the response is positive. This bit is called the suppressPosRspMsgIndicationBit

The Client object lets you use that feature by using suppress_positive_response into a with statement. See the following example:

with client.suppress_positive_response(wait_nrc=False):
    client.tester_present()   # Will not wait for a response and always return None

with client.suppress_positive_response(wait_nrc=True):
    client.tester_present()   # Will wait in case an NRC is returned.

When suppress_positive_response is askied for a service using a subfunction byte, the client will set suppressPosRspMsgIndicationBit before sending the request. If wait_nrc is False (default value), the client will not wait for any response and will disregard positive and negative responses if they happen. The response returned by the client function will always be None in that case.

If wait_nrc is True, the client will wait to see if a negative response is returned. In that scenario

No timeout will be raised if no response is received
If a positive response is received, it will not be validated and None will be returned
If a negative response is received, the normal processing will happen. Meaning either the response will be returned or a NegativeResponseException
will be raised, depending on exception_on_negative_response parameter.

If suppress_positive_response is askied for a service with no subfunction byte, the directive will be ignored and a warning message will be logged.

Overriding the output

For mean of testing, it may be useful to send invalid payloads to the server and still want the Client object to parse the response of the server.

It is possible to do so by using the payload_override property into a with statement. See the following example:

with client.payload_override(b'\x11\x22\x33'): # Client will send 112233 (hex) in every call within this "with" statement
   client.tester_present()

It is also possible to override with a function that modify the original output

def my_func(payload):
   return payload + b'\x00'  # Add extra 00 to the payload

with client.payload_override(my_func): # Client will append 00 to its output
   client.tester_present()

When using that feature, the client will process the response from the server just like if a valid request was sent. The response may be Invalid, Unexpected or Negative.

Note

It is possible to change the behaviour of the client on failing requests. See the client parameters exception_on_invalid_response, exception_on_unexpected_response and exception_on_negative_response

Methods by services

AccessTimingParameter 

Client.read_extended_timing_parameters()[source]

Reads the timing parameters from the server with AccessTimingParameter service with subfunction readExtendedTimingParameterSet (0x01).

Effective configuration:: exception_on_<type>_response
Returns:: The server response parsed by AccessTimingParameter.interpret_response
Return type:: Response

Client.reset_default_timing_parameters()[source]

Resets the server timing parameters to their default value with AccessTimingParameter service with subfunction setTimingParametersToDefaultValues (0x02).

Effective configuration:: exception_on_<type>_response
Returns:: The server response parsed by AccessTimingParameter.interpret_response
Return type:: Response

Client.read_active_timing_parameters()[source]

Reads the currently active timing parameters from the server with AccessTimingParameter service with subfunction readCurrentlyActiveTimingParameters (0x03).

Effective configuration:: exception_on_<type>_response
Returns:: The server response parsed by AccessTimingParameter.interpret_response
Return type:: Response

Client.set_timing_parameters(params)[source]

Sets the timing parameters into the server with AccessTimingParameter service with subfunction setTimingParametersToGivenValues (0x04).

Effective configuration:: exception_on_<type>_response
Parameters:: params (bytes) – The parameters data. Specific to each ECU.
Returns:: The server response parsed by AccessTimingParameter.interpret_response
Return type:: Response

ClearDiagnosticInformation 

Client.clear_dtc(group=16777215, memory_selection=None)[source]

Requests the server to clear its active Diagnostic Trouble Codes with the ClearDiagnosticInformation service.

Effective configuration:

exception_on_<type>_response. standard_version

Parameters:

group (int) –
The group of DTCs to clear. It may refer to Powertrain DTCs, Chassis DTCs, etc. Values are defined by the ECU manufacturer except for two specific values
- 0x000000 : Emissions-related systems
- 0xFFFFFF : All DTCs
memory_selection (int) – MemorySelection byte (0-0xFF). This value is user defined and introduced in 2020 version of ISO-14229-1. Only added to the request payload when different from None. Default : None

Returns:

The server response parsed by ClearDiagnosticInformation.interpret_response

Return type: