repository·master·Indexed 20 days ago
https://github.com/pylessard/python-udsoncanA Python 3 implementation of the Unified Diagnostic Services (UDS) protocol as defined by ISO-14229. It provides tools to interact with vehicle ECUs via transport layers like ISO-TP, allowing developers to build and interpret UDS payloads, manage diagnostic sessions, and detect malformed messages. The library includes a synchronous Client for handling request/response cycles, support for custom security algorithms, and configurable codecs for Data Identifiers (DID) and Input/Output Control (IOC).
Unified Diagnostic Services (UDS), defined by the ISO-14229 standard, is an application protocol interface used for diagnostics, debugging, and configuration of Electronic Control Units (ECUs) in road vehicles.
Key roles in a UDS communication:
UDS defines message formatting and the interface for services, but the specific implementation of how a server responds to a request is left to the ECU manufacturer.
python-udsoncan, the library is not limited to CAN bus. The library abstracts the transport protocol through the Connection class. You can implement or use connections for other transport layers as long as they satisfy the Connection interface.While UDS does not define the specific mathematical algorithm used for security, it defines the protocol for the key exchange. The process follows a request/response pattern consisting of two main exchanges:
UDS communication involves managing both the current session and the current security level.
When a client connects, the server typically assigns it a default session. In this session, only a limited set of services (like reading DTCs) are available.
DiagnosticSessionControl service.A security level is a status that grants access to restricted features (services, subfunctions, or specific values) by providing a security key.
SecurityAccess service.TesterPresent service.The udsoncan.client.Client is a synchronous client designed to handle a single request/response cycle at a time. It simplifies interaction with the Services object by automating repetitive tasks and providing error handling.
When you request a service, the client automatically performs the following sequence:
empty_rxqueue method to clear stale messages.This abstraction allows the client to detect usage errors and malformed server responses automatically.
The udsoncan.Dtc class and its associated components are used to manage Diagnostic Trouble Codes.
Key sub-components include:
udsoncan.Dtc.Status: Represents the status of a DTC.udsoncan.Dtc.DtcClass: Represents the class of a DTC.udsoncan.Dtc.Severity: Represents the severity level of a DTC.udsoncan.Dtc.Format: Handles the formatting of DTCs.udsoncan.Dtc.FunctionalGroupIdentifiers: Manages functional group identifiers related to DTCs.The python-udsoncan library allows you to interact with UDS (Unified Diagnostic Services) at different levels of abstraction, ranging from raw byte manipulation to high-level client methods:
Request and Response objects to wrap payloads, providing basic service and code identification.services.RoutineControl) to generate requests and interpret responses, including automatic parsing of service-specific data (like control_type_echo).Client class, which provides named methods (e.g., client.start_routine()) and handles validation of echoed data automatically.# Level 4: High-level Client usage
try:
response = client.start_routine(routine_id=0x1234)
print('Success!')
except Exception:
print('Start of routine 0x1234 failed')Since UDS is an application layer protocol, it requires a data transport protocol (like ISO-TP over CAN) to function. python-udsoncan does not implement the underlying communication protocols itself, but instead provides a standard Connection interface to interact with them.
Users interact with the underlying protocol through a Connection object. This abstraction allows the Client object to remain agnostic of whether you are using a CAN bus, a socket, or a custom transport layer.
Each UDS service is represented by a class extending BaseService. Services follow a two-step pattern for communication:
make_request method. This returns a Request instance containing the payload. You then send this payload via your Connection object.Response object using Response.from_payload(payload). Then, call the service's interpret_response method. This parses the raw response.data and populates the response.service_data property with an instance of the service's nested ResponseData class.This pattern ensures that raw byte payloads are converted into structured, typed Python objects.
# Crafting a request
req = SomeService.make_request(param1, param2)
my_connection.send(req.get_payload())
# Parsing a response
payload = my_connection.wait_frame(timeout=1)
response = Response.from_payload(payload)
print('Raw data : %s' % response.data)
SomeService.interpret_response(response, param1, param2)
print('Interpreted data : field1 : %s, field2 : %s' % (response.service_data.field1, response.service_data.field2))Functionality in UDS is organized into services. A service is a type of request that includes specific parameters.
Common examples of services include:
Subfunctions:
Many services include subfunctions, which are identified by the first byte of the service payload. For example, the ECUReset service uses a subfunction to specify the type of reset requested, such as a 'hard reset' (power cycle) or a 'soft reset' (firmware restart).
To use the SecurityAccess service, you must provide a security_algo callable in the client configuration. This function implements the specific security logic required by your ECU.
Signature Requirements: Starting from v1.12, parameters are passed by name. The function must accept:
level (int): The requested security level.seed (bytes): The seed provided by the server.params (any): The value provided via the security_algo_params configuration key.Returns:
bytes: The calculated security key.Example configuration:
config = {
'security_algo': my_algorithm_function,
'security_algo_params': {'key': 'some_value'}
}