{"id":10326,"library":"udsoncan","title":"udsoncan: Unified Diagnostic Services (UDS) Protocol","description":"udsoncan is a Python library that implements the Unified Diagnostic Service (UDS) protocol (ISO-14229), widely used in the automotive industry for vehicle diagnostics and programming. It provides client and server capabilities, support for various communication connections (CAN, ISO-TP, J2534, DoIP), and tools for managing Data Identifiers (DIDs) and Diagnostic Trouble Codes (DTCs). The library is actively maintained, with version 1.25.2 being the latest, and typically sees several minor releases per year to add features and address bug fixes.","status":"active","version":"1.25.2","language":"en","source_language":"en","source_url":"https://github.com/pylessard/python-udsoncan","tags":["automotive","uds","can","iso-14229","diagnostics","obd","ecu","j2534"],"install":[{"cmd":"pip install udsoncan","lang":"bash","label":"Install udsoncan"},{"cmd":"pip install udsoncan[can]","lang":"bash","label":"Install with python-can (for CAN/ISO-TP)"}],"dependencies":[{"reason":"Required for CAN bus communication via IsoTPSocketConnection or other CAN-based connections. Not strictly required for the core library if using other connection types (e.g., LoopbackConnection, DoIPConnection).","package":"python-can","optional":true}],"imports":[{"symbol":"Client","correct":"from udsoncan.client import Client"},{"symbol":"Server","correct":"from udsoncan.server import Server"},{"symbol":"IsoTPSocketConnection","correct":"from udsoncan.connections import IsoTPSocketConnection"},{"symbol":"LoopbackConnection","correct":"from udsoncan.connections import LoopbackConnection"},{"symbol":"services","correct":"import udsoncan.services as services"},{"symbol":"Dtc","correct":"from udsoncan import Dtc"},{"symbol":"NegativeResponseException","correct":"from udsoncan.exceptions import NegativeResponseException"},{"symbol":"TimeoutException","correct":"from udsoncan.exceptions import TimeoutException"}],"quickstart":{"code":"import udsoncan\nfrom udsoncan.client import Client\nfrom udsoncan.server import Server\nfrom udsoncan.connections import LoopbackConnection\nfrom udsoncan.services import ReadDataByIdentifier, DiagnosticSessionControl\nfrom udsoncan.exceptions import NegativeResponseException\n\n# Define a simple UDS server application logic\nclass MyServerApplication:\n    def __init__(self):\n        self.data_store = {\n            0xF190: b'PythonUDS',  # Example VIN\n            0xF180: b'v1.0'        # Example Software version\n        }\n        self.current_session = 1  # Default session\n\n    def read_data_by_identifier(self, did, access_level=None):\n        if did in self.data_store:\n            return self.data_store[did]\n        raise NegativeResponseException(0x10) # SubFunction Not Supported if DID is unknown\n\n    def diagnostic_session_control(self, session_id, access_level=None):\n        if session_id in [1, 2, 3]:  # Default, Programming, Extended\n            self.current_session = session_id\n            return b''\n        raise NegativeResponseException(0x10) # SubFunction Not Supported if session is unknown\n\n    def get_did_config(self):\n        # Define how DIDs are encoded/decoded for the server\n        return {\n            0xF190: {'data_size': 9, 'codec': udsoncan.AsciiCodec},\n            0xF180: {'data_size': 4, 'codec': udsoncan.AsciiCodec},\n        }\n\n# Configure client and server to use an in-memory loopback connection\nconn = LoopbackConnection(name='test_bus')\n\n# Server setup\nserver_app = MyServerApplication()\nserver_config = udsoncan.ServerConfiguration()\nserver_config.default_response_pending_timeout = 200 # ms\nserver_config.set_did_config(server_app.get_did_config())\n\n# Link server services to the application methods\nserver_config.request_handler = {\n    ReadDataByIdentifier: server_app.read_data_by_identifier,\n    DiagnosticSessionControl: server_app.diagnostic_session_control\n}\n\nserver = Server(conn, server_config)\nserver.start()\n\n# Client setup\nclient = Client(conn, request_timeout=2) # 2 seconds timeout\n\ntry:\n    client.open()\n\n    # Example 1: Read VIN (DID F190)\n    response = client.read_data_by_identifier([0xF190])\n    vin = response.values[0xF190]\n    print(f\"VIN: {vin.decode('ascii')}\")\n\n    # Example 2: Change diagnostic session to Extended Diagnostic Session (ID 0x03)\n    response = client.diagnostic_session_control(3)\n    print(f\"Session changed to: {response.service_data.session_id} (Success)\")\n\n    # Example 3: Try reading an unsupported DID (will raise NegativeResponseException)\n    try:\n        client.read_data_by_identifier([0x1234])\n    except NegativeResponseException as e:\n        print(f\"Tried reading unsupported DID 0x1234: Received NRC {hex(e.response.code)}\")\n\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    client.close()\n    server.stop()\n    print(\"Client and server stopped.\")","lang":"python","description":"This quickstart demonstrates setting up a UDS client and server using `udsoncan` with a `LoopbackConnection`. This allows for in-process communication without needing external hardware or `python-can`. The server implements basic handlers for `ReadDataByIdentifier` and `DiagnosticSessionControl`. The client then interacts with this server to read a VIN, change a session, and handle an unsupported DID request."},"warnings":[{"fix":"Consult the latest `udsoncan` documentation and examples for J2534 usage. Review your J2534 connection and device initialization code.","message":"The J2534 module has undergone significant refactoring and improvements across versions (v1.23.2, v1.24.0, v1.25.2). If you are using `J2534Connection`, code written for older versions (e.g., prior to v1.23.2) may require adjustments to adapt to the updated API and internal workings.","severity":"breaking","affected_versions":"<1.25.2"},{"fix":"Upgrade to `udsoncan` version 1.24.0 or newer to benefit from the concurrency fixes, especially when dealing with multiple threads or asynchronous operations.","message":"When using `J2534Connection` or other connections with high concurrency, versions prior to 1.24.0 had a known concurrency issue that could lead to unstable behavior. This was addressed in v1.24.0.","severity":"gotcha","affected_versions":"<1.24.0"},{"fix":"Upgrade to `udsoncan` version 1.24.0 or newer for improved NRC 0x78 handling and clearer timeout messages. Consider implementing the `nrc_78_received_callback` in your client configuration for custom logic.","message":"Versions of `udsoncan` prior to 1.23.1 provided less informative error messages when a timeout occurred after an NRC 0x78 (Response Pending) was received. Version 1.24.0 further introduced a callback mechanism for handling NRC 0x78.","severity":"gotcha","affected_versions":"<1.24.0"},{"fix":"If using Python 3.7, ensure you are running `udsoncan` version 1.22.1 or newer. Avoid version 1.22.0.","message":"Version 1.22.0 introduced a bug that broke compatibility with Python 3.7. This was quickly fixed in version 1.22.1.","severity":"gotcha","affected_versions":"1.22.0"},{"fix":"If your application experiences slow DID requests with many configurations and you are on version 1.21, upgrade to `udsoncan` version 1.22.0 or newer.","message":"A performance degradation was introduced in v1.21 when requesting Data Identifiers (DIDs) with a large configuration. This issue was resolved in v1.22.0.","severity":"gotcha","affected_versions":"1.21.x"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the `python-can` library: `pip install python-can` (or `pip install udsoncan[can]` to install `udsoncan` with its `can` extras).","cause":"You are attempting to use a CAN-based connection (e.g., `IsoTPSocketConnection`) but the `python-can` library is not installed.","error":"ModuleNotFoundError: No module named 'can'"},{"fix":"Verify the UDS server is active and accessible. Double-check CAN IDs, physical wiring, and baud rates. If the server is genuinely slow, increase `client.request_timeout` or the P2/P2* timeout settings in the client configuration.","cause":"The UDS server did not respond within the client's configured request timeout (P2 or P2* timeout). This can be due to an inactive server, incorrect CAN IDs, a physical connection issue, or an overloaded/slow server.","error":"udsoncan.exceptions.TimeoutException: No response received from the server (request=...) (timeout=...s)"},{"fix":"Check the `udsoncan.services` module for the correct class name for the UDS service you intend to use. Ensure your import statement and class reference match the library's API (e.g., `from udsoncan.services import ReadDataByIdentifier`).","cause":"You are trying to import or reference a UDS service class that does not exist in the `udsoncan.services` module or is misspelled. Services like `ReadDataByIdentifier`, `DiagnosticSessionControl` are defined there.","error":"AttributeError: module 'udsoncan.services' has no attribute 'MyCustomService'"},{"fix":"Increase the `P2_star_timeout` in the client's configuration if the server is known to take a long time to process. Investigate the server-side behavior if it consistently fails to respond after 0x78. For `udsoncan` v1.24.0+, you can use `nrc_78_received_callback` for specific handling.","cause":"The UDS server sent a 'Response Pending' NRC (0x78) but then failed to send a final positive response or another NRC within the P2* timeout. This often indicates a server processing delay exceeding the client's tolerance, or a server internal issue.","error":"udsoncan.exceptions.NegativeResponseException: Server responded with negative response code 0x78 (Response Pending)"}]}