udsoncan DocumentationRelease 0
Pier-Yves Lessard
July 28, 2020
Contents
1 Introduction to UDS 11.1 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Sessions and security levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Security algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 Underlying protocol (Connections) 32.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 How to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.3 Available Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.4 Defining a new Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Request and Response 73.1 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4 Services 114.1 AccessTimingParameter (0x83) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 ClearDiagnosticInformation (0x14) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.3 CommunicationControl (0x28) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.4 ControlDTCSetting (0x85) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.5 DiagnosticSessionControl (0x10) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.6 ECUReset (0x11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.7 InputOutputControlByIdentifier (0x2F) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.8 LinkControl (0x87) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.9 ReadDataByIdentifier (0x22) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.10 RequestFileTransfer (0x38) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.11 ReadDTCInformation (0x19) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.12 ReadMemoryByAddress (0x23) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.13 RequestDownload (0x34) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244.14 RequestTransferExit (0x37) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.15 RequestUpload (0x35) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.16 RoutineControl (0x31) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264.17 SecurityAccess (0x27) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264.18 TesterPresent (0x3E) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.19 TransferData (0x36) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284.20 WriteDataByIdentifier (0x2E) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284.21 WriteMemoryByAddress (0x3D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294.22 DynamicallyDefineDataIdentifier (0x2C) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
i
4.23 SecuredDataTransmission (0x84) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.24 ResponseOnEvent (0x86) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.25 ReadScalingDataByIdentifier (0x24) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304.26 ReadDataByPeriodicIdentifier (0x2A) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5 Client 315.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325.2 Suppress positive response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345.3 Overriding the output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355.4 Methods by services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6 Helper classes 516.1 CommunicationType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516.2 MemoryLocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516.3 DidCodec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526.4 Baudrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526.5 DataFormatIdentifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536.6 AddressAndLengthFormatIdentifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536.7 Filesize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536.8 DTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546.9 DTC.Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546.10 DTC.Severity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546.11 DTC.Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556.12 IOValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556.13 IOMasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556.14 Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566.15 DataIdentifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7 Exceptions 597.1 NegativeResponseException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597.2 InvalidResponseException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597.3 UnexpectedResponseException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597.4 TimeoutException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597.5 ConfigError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
8 Examples 618.1 Different layers of intelligence (1 to 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618.2 Using UDS over python-can . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628.3 Server default address and size format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628.4 Security algorithm implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638.5 Reading a DID with ReadDataByIdentifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638.6 InputOutputControlByIdentifier Composite DID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
9 Questions and answers 659.1 What version of the standard has been used? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659.2 Can we expect an update for the 2020 version? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659.3 How reliable is this code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659.4 Why is there unimplemented services? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659.5 I have a CAN transceiver, how do I use this project now? . . . . . . . . . . . . . . . . . . . . . . . . 669.6 What is the DTC mirror memory? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669.7 What makes a DTC permanent? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669.8 How can I contribute? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
10 Purpose 67
ii
11 Example 69
iii
iv
CHAPTER 1
Introduction to UDS
The Unified Diagnostic Services (UDS) standard also known as ISO-14229 is an application protocol interface usedin road vehicles for diagnostics, debugging and configuration of ECUs.
UDS defines how messages should be formatted but not how they should be implemented (although the standardsuggests some good practices); that’s why it is an interface.
The UDS client is usually a tester unit meant to be connected to a vehicle diagnostic port. The UDS server is usually adevice within the vehicle that is connected to the CAN bus (accessible by the diagnostic port). This device is referredto as an Electronic Control Unit (ECU).
1.1 Services
Each functionality of the standard is grouped within the concept of a service. A service is basically a type of requestthat has some parameters. Here’s some examples of how functionalities are grouped within services :
• Reading the Diagnostic Trouble Codes known as DTCs (ReadDTCInformation)
• Setting vehicle-specific configuration (WriteDataByIdentifier)
• Overriding IOs (InputOutputControlByIdentifier)
• Requesting a reset (ECUReset)
• Etc.
These services can have subfunctions that are specific to them. For instance, the ECUReset service has a subfunctionthat describes the type of reset that the client wants to perform. It can be a hard reset (power cycle) or a soft reset(restarting the firmware). The subfunction is the first byte of the service payload and its value is defined by UDS. Theway the server triggers a reset is not defined by UDS and is left to the discretion of the server programmer.
1.2 Sessions and security levels
When connecting to a server, the client has a session and a security level.
By default, the server greets a new client by assigning it the “default session” in which only a few specific services areaccessible like reading the DTCs. UDS defines 4 sessions types but defines the list of available services only for thedefault session. In other words, the ECU manufacturer decides what services are available for each session, exclud-ing the default session. A client may switch to any session without restrictions (with the DiagnosticSessionControlservice), it is not a security mechanism. The ECU manufacturer can define 32 additional sessions.
1
udsoncan Documentation, Release 0
The security level is a status that the client gains by unlocking features within the server by providing a security key.UDS is designed to allow up to 64 security levels that are, in the end, boolean flags set in the server. These securitylevels, as well as what they unlock, are not defined by UDS but will be by the ECU manufacturer. A security level canunlock a whole service, a subfunction or the access to a specific value. For instance, writing the Vehicle IdentificationNumber (VIN) may require a specific security level that is different from what is needed to write the maximum speedor override the vehicle IOs.
Unlocking security levels is not allowed in the default session. To gain some privileges, the client must first switch to anon-default session that enables the SecurityAccess service. Only then may the client execute the handshake that willunlock the wanted feature. Usually, when privileges are gained, they will expire after a short period of time definedby the ECU manufacturer. A keepalive message will keep the security level unlocked and the session active; thesekeepalive messages are sent with service TesterPresent
1.3 Security algorithm
The payload that must be sent to unlock a security level is not defined by UDS; UDS defines how to proceed with thekey exchange. This process consists of 2 exchanges of request/response between the client and the server. It goes asfollows:
1. First, the client requests for a seed to unlock a specific security level (identified by a number). Thisseed is usually a random value that the client must use in order to compute the key. It is meantto prevent someone from recording the CAN bus message exchange and then gaining privileges byblindly sending what was recorded. In cryptography terms, the seed is a nonce used to avoid replayattacks.
2. Once the client gets the seed, it must compute a key using an algorithm that is defined by the ECUmanufacturer and known by the server.
3. The client then sends the key to the server, the server verifies it and, if it matches the server’s value,the security level is unlocked and a positive message is responded to the client.
The security algorithm can be any algorithm. The lack of algorithm definition in the UDS standard leavessome room for good security design, but also for poor design - it’s up to the manufacturer. Yes, somemanufacturers implement security through obscurity while some others will go for a more robust pre-shared key scheme.
2 Chapter 1. Introduction to UDS
CHAPTER 2
Underlying protocol (Connections)
2.1 Basics
Since UDS is an application layer protocol, it must be used over a data transport protocol. The current industry mostlyuses ISO-TP protocol (ISO-15765) over CAN bus (ISO-11898).
Controller Area Network (CAN) protocol is a link layer protocol that sends data over small chunks of 8 bytes. ISO-TPis a transport protocol that allow the transmission of larger frames, usually 4095 bytes maximum although the 2016version of the standard uses sizes defined over 32bits, which would theoretically allow frames of 4GB.
ISO-TP has been designed to be used for UDS. The current ISO-15765 protocol comes in 4 parts. ISO-15765-2 tellshow to transmit large frames and ISO-15765-3 defines how to map the ISO-TP fields to a UDS message.
This project does not implement any communication protocol below the UDS layer, but provides a standard interfaceto interact with them.
2.2 How to
Access to the underlying protocol is done through a Connection object. A user can define his own Connectionobject by inheriting the BaseConnection object and implementing the abstract method.
The main interfaces to use with the Connection object are:
BaseConnection.send(data)Sends data to the underlying transport protocol
Parameters data (bytes, Request, Response) – The data or object to send. If a Requestor Response is given, the value returned by get_payload() will be sent.
Returns None
BaseConnection.wait_frame(timeout=2, exception=False)Waits for the reception of a frame of data from the underlying transport protocol
Parameters
• timeout (int) – The maximum amount of time to wait before giving up in seconds
• exception (bool) – Boolean value indicating if this function may return excep-tions. When True, all exceptions may be raised, including TimeoutException WhenFalse, all exceptions will be logged as DEBUG and None will be returned.
3
udsoncan Documentation, Release 0
Returns Received data
Return type bytes or None
2.3 Available Connections
Some connections are already avaialble and can be imported from the udsoncan.connections modules. Eachof these connections are meant to address a specific use case.
2.3.1 PythonIsoTpConnection
class udsoncan.connections.PythonIsoTpConnection(isotp_layer, name=None)Sends and receives data using a can-isotp Python module which is a Python implementation of the IsoTp trans-port protocol which can be coupled with python-can module to interract with CAN hardware
can-isotp must be installed in order to use this connection.
See an example
Parameters
• isotp_layer (isotp.TransportLayer) – The IsoTP Transport layer object com-ing from the isotp module.
• name (string) – This name is included in the logger name so that its output can beredirected. The logger name will be Connection[<name>]
2.3.2 SocketConnection
class udsoncan.connections.SocketConnection(sock, bufsize=4095, name=None)Sends and receives data through a socket.
Parameters
• sock (socket.socket) – The socket to use. This socket must be bound and ready touse. Only send() and recv() will be called by this Connection
• bufsize (int) – Maximum buffer size of the socket, this value is passed to recv()
• name (string) – This name is included in the logger name so that its output can beredirected. The logger name will be Connection[<name>]
2.3.3 IsoTPSocketConnection
class udsoncan.connections.IsoTPSocketConnection(interface, rxid, txid, name=None, tp-sock=None, *args, **kwargs)
Sends and receives data through an ISO-TP socket. Makes cleaner code than SocketConnection but offers noadditional functionality. The can-isotp module must be installed in order to use this connection
Parameters
• interface (string) – The can interface to use (example: can0)
• rxid (int) – The reception CAN id
4 Chapter 2. Underlying protocol (Connections)
udsoncan Documentation, Release 0
• txid (int) – The transmission CAN id
• name (string) – This name is included in the logger name so that its output can beredirected. The logger name will be Connection[<name>]
• tpsock (isotp.socket) – An optional ISO-TP socket to use instead of creating one.
• args (list) – Optional parameters list passed to ISO-TP socket binding method.
• kwargs (dict) – Optional parameters dictionary passed to ISO-TP socket bindingmethod.
2.3.4 QueueConnection
class udsoncan.connections.QueueConnection(name=None, mtu=4095)Sends and receives data using 2 Python native queues.
•MyConnection.fromuserqueue : Data read from this queue when wait_frame is called
•MyConnection.touserqueue : Data written to this queue when send is called
Parameters
• mtu (int) – Optional maximum frame size. Messages will be truncated to this size
• name (string) – This name is included in the logger name so that its output can beredirected. The logger name will be Connection[<name>]
2.4 Defining a new Connection
If all of the above Connection does not suits your needs, you can always implement your own Connection.
In order to define a new connection, 5 methods must be implemented as they will be called by the Client object.
BaseConnection.open()Set up the connection object.
Returns None
BaseConnection.close()Close the connection object
Returns None
BaseConnection.specific_send(payload)The implementation of the send method.
Parameters payload (bytes) – Data to send
Returns None
BaseConnection.specific_wait_frame(timeout=2)The implementation of the wait_frame method.
Parameters timeout (int) – The maximum amount of time to wait before giving up
Returns Received data
Return type bytes or None
2.4. Defining a new Connection 5
udsoncan Documentation, Release 0
BaseConnection.empty_rxqueue()Empty all unread data in the reception buffer.
Returns None
6 Chapter 2. Underlying protocol (Connections)
CHAPTER 3
Request and Response
Messages exchanged by the client and the server are represented by a Request and a Response.
The client sends Requests to the server that include a service number, an optional subfunction and some data. Theserver processes the request and answers with a Response that contains an echo of the service number, a responsecode and some additional data.
The following classes provides the necessary interface to manipulate UDS requests and responses.
3.1 Request
req = Request(service=ECUReset, subfunction=1, data=b'\x99\x88')payload = req.get_payload()print(payload) # b'\x11\x01\x99\x88'req2 = Request.from_payload(payload)print(req2) # <Request: [ECUReset] (subfunction=1) - 2 data bytes at 0x12345678>
class udsoncan.Request(service=None, subfunction=None, suppress_positive_response=False,data=None)
Represents a UDS Request.
Parameters
• service (class) – The service for which to make the request. This parameter must be aclass that extends udsoncan.services.BaseService
• subfunction (int or None) – The service subfunction. This value may be ignoredif the given service does not supports subfunctions
• suppress_positive_response (bool) – Indicates that the server should not senda response if the response code is positive. This parameter has effect only when the givenservice supports subfunctions
• data (bytes) – The service data appended after service ID and payload
Request.get_payload(suppress_positive_response=None)Generates a payload to be given to the underlying protocol. This method is meant to be used by a UDS client
Returns A payload to be sent through the underlying protocol
Return type bytes
7
udsoncan Documentation, Release 0
classmethod Request.from_payload(payload)Creates a Request object from a payload coming from the underlying protocols. This method is meant to beused by a UDS server
Parameters payload (bytes) – The payload of data to parse
Returns A Request object with populated fields
Return type Request
3.2 Response
response = Response(service=ECUReset, code=Response.Code.PositiveResponse, data=b'\x11\x22')payload = response.get_payload()print(payload) # b'\x51\x11\x22'response2 = Response.from_payload(payload)print(response2) # <PositiveResponse: [ECUReset] - 2 data bytes at 0x7f9367e619b0>
class udsoncan.Response(service=None, code=None, data=None)Represents a server Response to a client Request
Parameters
• service (class) – The service implied by this response.
• code (int) – The response code
• data (bytes) – The response data encoded after the service and response code
valid(boolean) True if the response content is valid. Only invalid_reason is guaranteed to have a mean-ingful value if this value is False
invalid_reason(string) String explaining why the response is invalid.
service(class) The response target service class
positive(boolean) True if the response code is 0 (PositiveResponse), False otherwise
code(int) The response code.
code_name(string) The response code name.
data(bytes) The response data. All the payload content, except the service number and the response code
service_data(object) The content of data interpreted by a service; can be any type of content.
original_payload(bytes) When the response is built with Response.from_payload, this property contains a copy of the pay-load used. None otherwise.
unexpected(boolean) Indicates that the response was unexpected. Set by an external source such as the Client object
8 Chapter 3. Request and Response
udsoncan Documentation, Release 0
Response.get_payload()Generates a payload to be given to the underlying protocol. This method is meant to be used by a UDS server
Returns A payload to be sent through the underlying protocol
Return type bytes
classmethod Response.from_payload(payload)Creates a Response object from a payload coming from the underlying protocol. This method is meant to beused by a UDS client
Parameters payload (bytes) – The payload of data to parse
Returns A Response object with populated fields
Return type Response
3.2.1 Response Codes
class Response.Code
PositiveResponse = 0
GeneralReject = 16
ServiceNotSupported = 17
SubFunctionNotSupported = 18
IncorrectMessageLengthOrInvalidFormat = 19
ResponseTooLong = 20
BusyRepeatRequest = 33
ConditionsNotCorrect = 34
RequestSequenceError = 36
NoResponseFromSubnetComponent = 37
FailurePreventsExecutionOfRequestedAction = 38
RequestOutOfRange = 49
SecurityAccessDenied = 51
InvalidKey = 53
ExceedNumberOfAttempts = 54
RequiredTimeDelayNotExpired = 55
UploadDownloadNotAccepted = 112
TransferDataSuspended = 113
GeneralProgrammingFailure = 114
WrongBlockSequenceCounter = 115
RequestCorrectlyReceived_ResponsePending = 120
SubFunctionNotSupportedInActiveSession = 126
ServiceNotSupportedInActiveSession = 127
3.2. Response 9
udsoncan Documentation, Release 0
RpmTooHigh = 129
RpmTooLow = 130
EngineIsRunning = 131
EngineIsNotRunning = 132
EngineRunTimeTooLow = 133
TemperatureTooHigh = 134
TemperatureTooLow = 135
VehicleSpeedTooHigh = 136
VehicleSpeedTooLow = 137
ThrottlePedalTooHigh = 138
ThrottlePedalTooLow = 139
TransmissionRangeNotInNeutral = 140
TransmissionRangeNotInGear = 141
ISOSAEReserved = 142
BrakeSwitchNotClosed = 143
ShifterLeverNotInPark = 144
TorqueConverterClutchLocked = 145
VoltageTooHigh = 146
VoltageTooLow = 147
GeneralSecurityViolation = 56
SecuredModeRequested = 57
InsufficientProtection = 58
TerminationWithSignatureRequested = 59
AccessDenied = 60
VersionNotSupported = 61
SecuredLinkNotSupported = 62
CertificateNotAvailable = 63
AuditTrailInformationNotAvailable = 64
10 Chapter 3. Request and Response
CHAPTER 4
Services
Each service is represented by a class that extends the BaseService class. They all implement 2 methods :make_request and interpret_response.
• make_request will return a Request instance ready to be sent to the Connection
• interpret_response will parse the data property inside a Response instance and populate anotherproperty named service_data. This service_data property will be an instance of the ResponseDataclass that is nested within the service class.
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))
4.1 AccessTimingParameter (0x83)
classmethod AccessTimingParameter.make_request(access_type, timing_param_record=None)Generates a request for AccessTimingParameter
Parameters
• access_type (int) – Service subfunction. Allowed values are from 0 to 0x7F
• timing_param_record (bytes) – Data associated with request. Must be present onlywhen access_type=‘‘AccessType.setTimingParametersToGivenValues‘‘ (4)
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod AccessTimingParameter.interpret_response(response)Populates the response service_data property with an instance ofAccessTimingParameter.ResponseData
Parameters response (Response) – The received response to interpret
11
udsoncan Documentation, Release 0
Raises InvalidResponseException – If length of response.data is too short
class AccessTimingParameter.ResponseData
access_type_echoRequest subfunction echoed back by the server
timing_param_recordAdditional data associated with the response.
class AccessTimingParameter.AccessTypeAccessTimingParameter defined subfunctions
readExtendedTimingParameterSet = 1
setTimingParametersToDefaultValues = 2
readCurrentlyActiveTimingParameters = 3
setTimingParametersToGivenValues = 4
4.2 ClearDiagnosticInformation (0x14)
classmethod ClearDiagnosticInformation.make_request(group=16777215)Generates a request for ClearDiagnosticInformation
Parameters group (int) – DTC mask ranging from 0 to 0xFFFFFF. 0xFFFFFF means all DTCs
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod ClearDiagnosticInformation.interpret_response(response)Populates the response service_data property with an instance ofClearDiagnosticInformation.ResponseData
Parameters response (Response) – The received response to interpret
Note: This service have empty response data
Note: This service does not have subfunctions
4.3 CommunicationControl (0x28)
classmethod CommunicationControl.make_request(control_type, communication_type)Generates a request for CommunicationControl
Parameters
• control_type (int) – Service subfunction. Allowed values are from 0 to 0x7F
• communication_type (CommunicationType, int, bytes) – The communication type re-quested.
12 Chapter 4. Services
udsoncan Documentation, Release 0
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod CommunicationControl.interpret_response(response)Populates the response service_data property with an instance ofCommunicationControl.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class CommunicationControl.ResponseData
control_type_echoRequest subfunction echoed back by the server
class CommunicationControl.ControlTypeCommunicationControl defined subfunctions
enableRxAndTx = 0
enableRxAndDisableTx = 1
disableRxAndEnableTx = 2
disableRxAndTx = 3
4.4 ControlDTCSetting (0x85)
classmethod ControlDTCSetting.make_request(setting_type, data=None)Generates a request for ControlDTCSetting
Parameters
• setting_type (int) – Service subfunction. Allowed values are from 0 to 0x7F
• data (bytes) – Optional additional data sent with the request called DTCSettingCon-trolOptionRecord
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod ControlDTCSetting.interpret_response(response)Populates the response service_data property with an instance ofControlDTCSetting.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class ControlDTCSetting.ResponseData
setting_type_echoRequest subfunction echoed back by the server
class ControlDTCSetting.SettingTypeControlDTCSetting defined subfunctions
on = 1
off = 2
4.4. ControlDTCSetting (0x85) 13
udsoncan Documentation, Release 0
4.5 DiagnosticSessionControl (0x10)
classmethod DiagnosticSessionControl.make_request(session)Generates a request for DiagnosticSessionControl service
Parameters session (int) – Service subfunction. Allowed values are from 0 to 0x7F
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod DiagnosticSessionControl.interpret_response(response, stan-dard_version=2020)
Populates the response service_data property with an instance ofDiagnosticSessionControl.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class DiagnosticSessionControl.ResponseData
session_echoRequest subfunction echoed back by the server
session_param_recordsRaw session parameter records. Data given by the server. For 2006 configurations, this data can is manu-facturer specific. For 2013 version and above, this data correspond to P2 and P2* timing requirement.
p2_server_maxDefault P2 max timing supported by the server for the activated diagnostic session. Applicable for 2013version and above. Value in seconds.
p2_star_server_maxDefault P2* (NRC 0x78) max timing supported by the server for the activated diagnostic session. Appli-cable for 2013 version and above. Value in seconds
class DiagnosticSessionControl.SessionDiagnosticSessionControl defined subfunctions
defaultSession = 1
programmingSession = 2
extendedDiagnosticSession = 3
safetySystemDiagnosticSession = 4
4.6 ECUReset (0x11)
classmethod ECUReset.make_request(reset_type)Generates a request for ECUReset
Parameters reset_type (int) – Service subfunction. Allowed values are from 0 to 0x7F
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod ECUReset.interpret_response(response)Populates the response service_data property with an instance of ECUReset.ResponseData
Parameters response (Response) – The received response to interpret
14 Chapter 4. Services
udsoncan Documentation, Release 0
Raises InvalidResponseException – If length of response.data is too short
class ECUReset.ResponseData
reset_type_echoRequest subfunction echoed back by the server
powerdown_timeAmount of time, in seconds, before the power down sequence is executed. Should be provided only whenreset type is enableRapidPowerShutDown
class ECUReset.ResetTypeECUReset defined subfunctions
hardReset = 1
keyOffOnReset = 2
softReset = 3
enableRapidPowerShutDown = 4
disableRapidPowerShutDown = 5
4.7 InputOutputControlByIdentifier (0x2F)
classmethod InputOutputControlByIdentifier.make_request(did, control_param=None, val-ues=None, masks=None, io-config=None)
Generates a request for InputOutputControlByIdentifier
Parameters
• did (int) – Data identifier to represent the IO
• control_param (int) – Optional parameter that can be a value defined inInputOutputControlByIdentifier.ControlParam
• values (list, dict, IOValues) – Optional values to send to the server. This parameter willbe given to DidCodec.encode() method. It can be:
– A list for positional arguments
– A dict for named arguments
– An instance of IOValues for mixed arguments
• masks (list, dict, IOMask, bool) – Optional mask record for composite values. The maskdefinition must be included in ioconfig It can be:
– A list naming the bit mask to set
– A dict with the mask name as a key and a boolean as the value (True to set the mask,False to clear it)
– An instance of IOMask
– A boolean value to set all masks to the same value.
4.7. InputOutputControlByIdentifier (0x2F) 15
udsoncan Documentation, Release 0
• ioconfig (dict[int] = DidCodec, dict) – Definition of DID codecs. Dictionary mapping aDID (int) to a valid DidCodec class or pack/unpack string. It is possible to use compositeDidCodec by specifying a dict with entries : codec, mask, mask_size.
Raises
• ValueError – If parameters are out of range, missing or wrong type
• ConfigError – If given DID is not defined within ioconfig
classmethod InputOutputControlByIdentifier.interpret_response(response, con-trol_param=None,toler-ate_zero_padding=True,ioconfig=None)
Populates the response service_data property with an instance ofInputOutputControlByIdentifier.ResponseData
Parameters
• response (Response) – The received response to interpret
• control_param (int) – Same optional control parameter value given to make_request()
• tolerate_zero_padding (bool) – Ignore trailing zeros in the response data avoidingraising false InvalidResponseException.
• ioconfig (dict[int] = DidCodec, dict) – Definition of DID codecs. Dictionary mapping aDID (int) to a valid DidCodec class or pack/unpack string. It is possible to use compositeDidCodec by specifying a dict with entries : codec, mask, mask_size.
Raises
• ValueError – If parameters are out of range, missing or wrong type
• ConfigError – If DID echoed back by the server is not in the ioconfig definition
• InvalidResponseException – If response data is incomplete or if DID data does notmatch codec length.
class InputOutputControlByIdentifier.ResponseData
did_echoDID echoed back by the server
control_param_echocontrol_param echoed back by the server
decoded_dataValue processed by the DidCodec.decode() method
Note: This service does not have subfunctions
Note: Example available here
16 Chapter 4. Services
udsoncan Documentation, Release 0
4.8 LinkControl (0x87)
classmethod LinkControl.make_request(control_type, baudrate=None)Generates a request for LinkControl
Parameters
• control_type (int) – Service subfunction. Allowed values are from 0 to 0x7F
• baudrate (Baudrate) – Required baudrate value when control_typeis either verifyBaudrateTransitionWithFixedBaudrate (1) orverifyBaudrateTransitionWithSpecificBaudrate (2)
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod LinkControl.interpret_response(response)Populates the response service_data property with an instance of LinkControl.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class LinkControl.ResponseData
control_type_echoRequest subfunction echoed back by the server
class LinkControl.ControlTypeLinkControl defined subfunctions
verifyBaudrateTransitionWithFixedBaudrate = 1
verifyBaudrateTransitionWithSpecificBaudrate = 2
transitionBaudrate = 3
4.9 ReadDataByIdentifier (0x22)
classmethod ReadDataByIdentifier.make_request(didlist, didconfig)Generates a request for ReadDataByIdentifier
Parameters
• didlist (list[int]) – List of data identifier to read.
• didconfig (dict[int] = DidCodec) – Definition of DID codecs. Dictionary mapping aDID (int) to a valid DidCodec class or pack/unpack string
Raises
• ValueError – If parameters are out of range, missing or wrong type
• ConfigError – If didlist contains a DID not defined in didconfig
classmethod ReadDataByIdentifier.interpret_response(response, didlist, didconfig, toler-ate_zero_padding=True)
Populates the response service_data property with an instance ofReadDataByIdentifier.ResponseData
Parameters
4.8. LinkControl (0x87) 17
udsoncan Documentation, Release 0
• response (Response) – The received response to interpret
• didlist (list[int]) – List of data identifiers used for the request.
• didconfig (dict[int] = DidCodec) – Definition of DID codecs. Dictionary mapping aDID (int) to a valid DidCodec class or pack/unpack string
• tolerate_zero_padding (bool) – Ignore trailing zeros in the response data avoidingraising false InvalidResponseException.
Raises
• ValueError – If parameters are out of range, missing or wrong type
• ConfigError – If didlist parameter or response contains a DID not defined indidconfig.
• InvalidResponseException – If response data is incomplete or if DID data does notmatch codec length.
class ReadDataByIdentifier.ResponseData
valuesDictionary mapping the DID (int) with the value returned by the associated DidCodec.decode method
Note: This service does not have subfunctions
Example of DidConfig
didconfig = {0x1111 : '<H', # Strings are processed by struct.unpack0x2222 : MyCustomDidCodec, # Inherits the udsoncan.DidCodec,0x3333 : MyCustomDidCodec(param1='hello') # Instance can also be provided0x4444 : dict(key1='val1', key2='val2', codec=MyCustomDidCodec} # If dict is given, a key named "codec" will be searched for
}
4.10 RequestFileTransfer (0x38)
classmethod RequestFileTransfer.make_request(moop, path, dfi=None, filesize=None)Generates a request for RequestFileTransfer
Parameters
• moop (int) – Mode of operation. Can be AddFile(1), DeleteFile(2), ReplaceFile(3), Read-File(4), ReadDir(5). See RequestFileTransfer.ModeOfOperation
• path (string) – String representing the path to the target file or directory.
• dfi (DataFormatIdentifier) – DataFormatIdentifier defining the compression and encryp-tion scheme of the data. If not specified, the default value of 00 will be used, specifyingno encryption and no compression. This value is only used when ModeOfOperation is :AddFile, ReplaceFile, ReadFile
• filesize (Filesize or int) – The filesize of the file to write when ModeOfOperation isAddFile or ReplaceFile. If filesize is an object of type Filesize, the uncompressed sizeand compressed size will be encoded on the minimum amount of bytes necessary, unless a
18 Chapter 4. Services
udsoncan Documentation, Release 0
width is explicitly defined. If no compressed size is given or filesize is an int, then thecompressed size will be set equal to the uncompressed size or the integer value given asspecified by ISO-14229
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod RequestFileTransfer.interpret_response(response, toler-ate_zero_padding=True)
Populates the response service_data property with an instance ofRequestFileTransfer.ResponseData
Parameters response (Response) – The received response to interpret
Raises
• InvalidResponseException – If length of response.data is too short or pay-load does not respect ISO-14229 specifications
• NotImplementedError – If the MaxNumberOfBlock or fileSizeUncompresse-dOrDirInfoLength value is encoded over more than 8 bytes.
class RequestFileTransfer.ResponseData
moop_echo(int)Request ModeOfOperation echoed back by the server
max_length(int)The MaxNumberOfBlockLength returned by the server. Represent the number of data bytes that shouldbe included in each subsequent TransferData request excepted the last one that might be smaller.
Not set for a response to DeleteFile.
dfi(DataFormatIdentifier)Request DataFormatIdentifier echoed back by the server.
Not set for a response to DeleteFile. Set to Compression=0, Encryption=0, when getting a responsefor ReadDir as specified by ISO-14229.
filesize(Filesize)Defines the size fo the file to be read in bytes, including its uncompressed and compressed size.
Only set when performing a ReadFile request
dirinfo_length(int)Defines the size of the directory information to be read in bytes.
Only set when performing a ReadDir request
Note: This service does not have subfunctions
4.11 ReadDTCInformation (0x19)
classmethod ReadDTCInformation.make_request(subfunction, status_mask=None, sever-ity_mask=None, dtc=None, snap-shot_record_number=None, ex-tended_data_record_number=None)
Generates a request for ReadDTCInformation. Each subfunction uses a subset of parameters.
4.11. ReadDTCInformation (0x19) 19
udsoncan Documentation, Release 0
Parameters
• subfunction (int) – The service subfunction. Values are defined inReadDTCInformation.Subfunction
• status_mask (int or Dtc.Status) – A DTC status mask used to filter DTC
• severity_mask (int or Dtc.Severity) – A severity mask used to filter DTC
• dtc (int or Dtc) – A DTC mask used to filter DTC
• snapshot_record_number (int) – Snapshot record number
• extended_data_record_number (int) – Extended data record number
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod ReadDTCInformation.interpret_response(response, subfunction, ex-tended_data_size=None, tol-erate_zero_padding=True,ignore_all_zero_dtc=True,dtc_snapshot_did_size=2, didcon-fig=None)
Populates the response service_data property with an instance ofReadDTCInformation.ResponseData
Parameters
• response (Response) – The received response to interpret
• subfunction (int) – The service subfunction. Values are defined inReadDTCInformation.Subfunction
• extended_data_size (int) – Extended data size to expect. Extended data is imple-mentation specific, therefore, size is not standardized
• tolerate_zero_padding (bool) – Ignore trailing zeros in the response data avoidingraising false InvalidResponseException.
• ignore_all_zero_dtc (bool) – Discard any DTC entries that have an ID of 0. Avoidreading extra DTCs when using a transport protocol using zero padding.
• dtc_snapshot_did_size (int) – Number of bytes to encode the data identifier num-ber. Other services such as ReadDataByIdentifier encode DID over 2 bytes. UDS standarddoes not define the size of the snapshot DID, therefore, it must be supplied.
• didconfig (dict[int] = DidCodec) – Definition of DID codecs. Dictionary mapping aDID (int) to a valid DidCodec class or pack/unpack string
Raises
• InvalidResponseException – If response length is wrong or does not match DIDconfiguration
• ValueError – If parameters are out of range, missing or wrong types
• ConfigError – If the server returns a snapshot DID not defined in didconfig
class ReadDTCInformation.ResponseData
subfunction_echoSubfunction echoed back by the server
dtcsDTC instances and their status read from the server.
20 Chapter 4. Services
udsoncan Documentation, Release 0
dtc_countNumber of DTC read or available
dtc_formatInteger indicating the format of the DTC. See DTC.Format
status_availabilityDtc.Status indicating which status the server supports
extended_dataList of bytes containing the DTC extended data
class ReadDTCInformation.Subfunction
reportNumberOfDTCByStatusMask = 1
reportDTCByStatusMask = 2
reportDTCSnapshotIdentification = 3
reportDTCSnapshotRecordByDTCNumber = 4
reportDTCSnapshotRecordByRecordNumber = 5
reportDTCExtendedDataRecordByDTCNumber = 6
reportNumberOfDTCBySeverityMaskRecord = 7
reportDTCBySeverityMaskRecord = 8
reportSeverityInformationOfDTC = 9
reportSupportedDTCs = 10
reportFirstTestFailedDTC = 11
reportFirstConfirmedDTC = 12
reportMostRecentTestFailedDTC = 13
reportMostRecentConfirmedDTC = 14
reportMirrorMemoryDTCByStatusMask = 15
reportMirrorMemoryDTCExtendedDataRecordByDTCNumber = 16
reportNumberOfMirrorMemoryDTCByStatusMask = 17
reportNumberOfEmissionsRelatedOBDDTCByStatusMask = 18
reportEmissionsRelatedOBDDTCByStatusMask = 19
reportDTCFaultDetectionCounter = 20
reportDTCWithPermanentStatus = 21
4.11. ReadDTCInformation (0x19) 21
udsoncan Documentation, Release 0
4.11.1 make_request() parameters per subfunction
Table 4.1: make_request() parameters per subfunction
subfunction sta-tus_mask
sever-ity_mask
dtc snap-shot_record_number
ex-tended_data_record_number
reportNumberOfDTCByStatusMask YesreportDTCByStatusMask YesreportDTCSnapshotIdentificationreportDTCSnapshotRecordByDTC-Number
Yes Yes
reportDTCSnapshotRecordByRecord-Number
Yes
reportDTCExtendedDataRecordBy-DTCNumber
Yes Yes
reportNumberOfDTCBySeverity-MaskRecord
Yes Yes
reportDTCBySeverityMaskRecord Yes YesreportSeverityInformationOfDTC Yes YesreportSupportedDTCsreportFirstTestFailedDTCreportFirstConfirmedDTCreportMostRecentTestFailedDTCreportMostRecentConfirmedDTCreportMirrorMemoryDTCByStatus-Mask
Yes
reportMirrorMemoryDTCExtended-DataRecordByDTCNumber
Yes Yes
reportNumberOfMirrorMemory-DTCByStatusMask
Yes
reportNumberOfEmissionsRelate-dOBDDTCByStatusMask
Yes
reportEmissionsRelatedOBD-DTCByStatusMask
Yes
reportDTCFaultDetectionCounterreportDTCWithPermanentStatus
22 Chapter 4. Services
udsoncan Documentation, Release 0
4.11.2 interpret_response() parameters per subfunction
Table 4.2: interpret_response() parameters per subfunction
subfunction ex-tended_data_size
toler-ate_zero_padding
ig-nore_all_zero_dtc
dtc_snapshot_did_sizedid-con-fig
reportNumberOfDTCByStatusMaskreportDTCByStatusMask Yes YesreportDTCSnapshotIdentification Yes YesreportDTCSnapshotRecordByDTC-Number
Yes Yes Yes
reportDTCSnapshotRecord-ByRecordNumber
Yes Yes Yes
reportDTCExtendedDataRecordBy-DTCNumber
Yes Yes
reportNumberOfDTCBySeverity-MaskRecordreportDTCBySeverityMaskRecord Yes YesreportSeverityInformationOfDTC Yes YesreportSupportedDTCs Yes YesreportFirstTestFailedDTC Yes YesreportFirstConfirmedDTC Yes YesreportMostRecentTestFailedDTC Yes YesreportMostRecentConfirmedDTC Yes YesreportMirrorMemoryDTCByStatus-Mask
Yes Yes
reportMirrorMemoryDTCExtended-DataRecordByDTCNumber
Yes Yes
reportNumberOfMirrorMemory-DTCByStatusMaskreportNumberOfEmissionsRelate-dOBDDTCByStatusMaskreportEmissionsRelatedOBD-DTCByStatusMask
Yes Yes
reportDTCFaultDetectionCounter Yes YesreportDTCWithPermanentStatus Yes Yes
4.12 ReadMemoryByAddress (0x23)
classmethod ReadMemoryByAddress.make_request(memory_location)Generates a request for ReadMemoryByAddress
Parameters memory_location (MemoryLocation) – The address and the size of the memoryblock to read.
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod ReadMemoryByAddress.interpret_response(response)Populates the response service_data property with an instance ofReadMemoryByAddress.ResponseData
4.12. ReadMemoryByAddress (0x23) 23
udsoncan Documentation, Release 0
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class ReadMemoryByAddress.ResponseData
memory_blockbytes object reflecting the content of the read memory
Note: This service does not have subfunctions
4.13 RequestDownload (0x34)
classmethod RequestDownload.make_request(memory_location, dfi=None)Generates a request for RequestDownload
Parameters
• memory_location (MemoryLocation) – The address and the size of the memory blockto be written.
• dfi (DataFormatIdentifier) – Optional DataFormatIdentifier defining the compression andencryption scheme of the data. If not specified, the default value of 00 will be used, speci-fying no encryption and no compression
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod RequestDownload.interpret_response(response)Populates the response service_data property with an instance ofRequestDownload.ResponseData
Parameters response (Response) – The received response to interpret
Raises
• InvalidResponseException – If length of response.data is too short
• NotImplementedError – If the maxNumberOfBlockLength value is encoded overmore than 8 bytes.
class RequestDownload.ResponseData
max_length(int) Maximum number of data blocks to write
Note: This service does not have subfunctions
24 Chapter 4. Services
udsoncan Documentation, Release 0
4.14 RequestTransferExit (0x37)
classmethod RequestTransferExit.make_request(data=None)Generates a request for RequestTransferExit
Parameters data (bytes) – Additional optional data to send to the server
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod RequestTransferExit.interpret_response(response)Populates the response service_data property with an instance ofRequestTransferExit.ResponseData
Parameters response (Response) – The received response to interpret
class RequestTransferExit.ResponseData
parameter_recordsbytes object containing optional data provided by the server
Note: This service does not have subfunctions
4.15 RequestUpload (0x35)
classmethod RequestUpload.make_request(memory_location, dfi=None)Generates a request for RequestUpload
Parameters
• memory_location (MemoryLocation) – The address and the size of the memory blockto be read.
• dfi (DataFormatIdentifier) – Optional dataFormatIdentifier defining the compression andencryption scheme of the data. If not specified, the default value of 00 will be used, speci-fying no encryption and no compression
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod RequestUpload.interpret_response(response)Populates the response service_data property with an instance of RequestUpload.ResponseData
Parameters response (Response) – The received response to interpret
Raises
• InvalidResponseException – If length of response.data is too short
• NotImplementedError – If the maxNumberOfBlockLength value is encoded overmore than 8 bytes.
class RequestUpload.ResponseData
max_length(int) Maximum number of data blocks to read
4.14. RequestTransferExit (0x37) 25
udsoncan Documentation, Release 0
Note: This service does not have subfunctions
4.16 RoutineControl (0x31)
classmethod RoutineControl.make_request(routine_id, control_type, data=None)Generates a request for RoutineControl
Parameters
• routine_id (int) – The routine ID. Value should be between 0 and 0xFFFF
• control_type (bytes) – Service subfunction. Allowed values are from 0 to 0x7F
• data (bytes) – Optional additional data to provide to the server
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod RoutineControl.interpret_response(response)Populates the response service_data property with an instance of RoutineControl.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class RoutineControl.ResponseData
control_type_echoRequests subfunction echoed back by the server
routine_id_echoRequests routine ID echoed back by the server.
routine_status_recordAdditional data associated with the response.
class RoutineControl.ControlTypeRoutineControl defined subfunctions
startRoutine = 1
stopRoutine = 2
requestRoutineResults = 3
4.17 SecurityAccess (0x27)
classmethod SecurityAccess.make_request(level, mode, key=None)Generates a request for SecurityAccess
Parameters
26 Chapter 4. Services
udsoncan Documentation, Release 0
• level (int) – Service subfunction. The security level to unlock. Value ranging from 0 to7F For mode=‘‘RequestSeed‘‘ (0), level must be an even value. For mode=‘‘SendKey‘‘ (1),level must be an odd value. If the even/odd constraint is not respected, the level value willbe corrected to properly set the LSB.
• mode (SecurityAccess.Mode, int) – Type of request to perform.SecurityAccess.Mode.RequestSeed or SecurityAccess.Mode.SendKey
• key (bytes) – When mode=‘‘SendKey‘‘, this value must be provided.
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod SecurityAccess.interpret_response(response, mode)Populates the response service_data property with an instance of SecurityAccess.ResponseData
Parameters response (Response) – The received response to interpret
Raises
• InvalidResponseException – If length of response.data is too short
• ValueError – If mode is not RequestSeed or SendKey
class SecurityAccess.ResponseData
security_level_echoRequests subfunction echoed back by the server
seedSeed value. Only present if request mode was RequestSeed (even subfunction)
class SecurityAccess.Mode
RequestSeed = 0
SendKey = 1
Note: The level that acts as the subfunction can range from 1 to 0x7E. The LSB is a flag indicating the type ofrequest. When the LSB is set to 1, the request is a RequestSeed message, when it is set to 0, the request is a SendKeymessage. This leaves 6 effective bits allowing 63 security levels.
Example :
• 01: RequestSeed, 02 SendKey that goes with 01.
• 03: RequestSeed, 04 SendKey that goes with 03.
• etc
4.18 TesterPresent (0x3E)
classmethod TesterPresent.make_request()Generates a request for TesterPresent
classmethod TesterPresent.interpret_response(response)Populates the response service_data property with an instance of TesterPresent.ResponseData
4.18. TesterPresent (0x3E) 27
udsoncan Documentation, Release 0
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class TesterPresent.ResponseData
subfunction_echoRequests subfunction echoed back by the server. This value should always be 0
Note: TesterPresent subfunction is always 0
4.19 TransferData (0x36)
classmethod TransferData.make_request(sequence_number, data=None)Generates a request for TransferData
Parameters
• sequence_number (int) – Corresponds to an 8bit counter that should increment foreach new block transferred. Allowed values are from 0 to 0xFF
• data (bytes) – Optional additional data to send to the server
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod TransferData.interpret_response(response)Populates the response service_data property with an instance of TransferData.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class TransferData.ResponseData
sequence_number_echoRequests subfunction echoed back by the server
parameter_recordsOptional additional data associated with the response.
Note: This service does not have subfunctions
4.20 WriteDataByIdentifier (0x2E)
classmethod WriteDataByIdentifier.make_request(did, value, didconfig)Generates a request for WriteDataByIdentifier
Parameters
• did (int) – The data identifier to write
28 Chapter 4. Services
udsoncan Documentation, Release 0
• value (object) – Value given to the DidCodec.encode method. If involved codec isdefined with a pack string (default codec), multiple values may be passed with a tuple.
• didconfig (dict[int] = DidCodec) – Definition of DID codecs. Dictionary mapping aDID (int) to a valid DidCodec class or pack/unpack string
Raises
• ValueError – If parameters are out of range, missing or wrong type
• ConfigError – If didlist contains a DID not defined in didconfig
classmethod WriteDataByIdentifier.interpret_response(response)Populates the response service_data property with an instance ofWriteDataByIdentifier.ResponseData
Parameters response (Response) – The received response to interpret
Raises InvalidResponseException – If length of response.data is too short
class WriteDataByIdentifier.ResponseData
did_echoThe DID echoed back by the server
Note: This service does not have subfunctions
4.21 WriteMemoryByAddress (0x3D)
classmethod WriteMemoryByAddress.make_request(memory_location, data)Generates a request for ReadMemoryByAddress
Parameters
• memory_location (MemoryLocation) – The address and the size of the memory blockto write.
• data (bytes) – The data to write into memory.
Raises ValueError – If parameters are out of range, missing or wrong type
classmethod WriteMemoryByAddress.interpret_response(response, memory_location)Populates the response service_data property with an instance ofWriteMemoryByAddress.ResponseData
Parameters
• response (Response) – The received response to interpret
• memory_location (MemoryLocation) – The memory location used for the request. Thebytes position varies depending on the memory_location format
Raises InvalidResponseException – If length of response.data is too short
class WriteMemoryByAddress.ResponseData
4.21. WriteMemoryByAddress (0x3D) 29
udsoncan Documentation, Release 0
alfid_echoAddressAndLengthFormatIdentifier used in the MemoryLocation object echoed back by the server.
memory_location_echoAn instance of MemoryLocation that includes the address, size and alfid that the server echoed back.
Note: This service does not have subfunctions
4.22 DynamicallyDefineDataIdentifier (0x2C)
Warning: Not implemented
4.23 SecuredDataTransmission (0x84)
Warning: Not implemented
4.24 ResponseOnEvent (0x86)
Warning: Not implemented
4.25 ReadScalingDataByIdentifier (0x24)
Warning: Not implemented
4.26 ReadDataByPeriodicIdentifier (0x2A)
Warning: Not implemented
30 Chapter 4. Services
CHAPTER 5
Client
The UDS client is a simple client that works synchronously and can handle a single request/response at a time. Whenrequesting 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, hidingrepetitive 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 thisexception while parsing the response data.
The client may raise UnexpectedResponseException if the response from the server does not match the last requestsent. For example, if the service number in the response is different from the service number in the request. Anothercase would be if the echo of a parameter for a specific service does not match the request. For instance, if an ECUResetsubfunction 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)Object that interacts with a UDS server. It builds a service request, sends it to the server, receives and parses itsresponse, 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. Thisparameter exists for backward compatibility only. For detailed timeout handling, see Clientconfiguration
31
udsoncan Documentation, Release 0
5.1 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 negativeresponse. 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 inter-pret_response raises the same exception. When set to False, the returned Response will have its property validset to False
exception_on_unexpected_response (bool)When set to True, the client will raise a UnexpectedResponseException when the server returns a response thatis not expected. For instance, a response for a different service or when the subfunction echo doesn’t matchthe request. When set to False, the returned Response will have its property unexpected set to True in thesame case.
security_algo (callable)The implementation of the security algorithm necessary for the SecurityAccess service. This function must havethe 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 configurationsecurity_algo_params
Returns The security keyReturn 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 asignature 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 canbe 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 codecswill be used to convert values to byte payload and vice-versa when sending/receiving data for a service thatneeds a DID, i.e.:
•ReadDataByIdentifier
•WriteDataByIdentifier
•ReadDTCInformation with subfunction reportDTCSnapshotRecordByDTCNumber andreportDTCSnapshotRecordByRecordNumber
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
32 Chapter 5. Client
udsoncan Documentation, Release 0
input_output (dict)This configuration is a dictionary that is mapping an integer (the IO data identifier) with a DidCodec specificallyfor the InputOutputControlByIdentifier service. Just like config[data_identifers], these codecs will be used toconvert 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 acodec 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
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 Read-DataByIdentifier, ReadDTCInformation. It has to ignore trailing zeros in the response data to avoid falselyraising 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 anID 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 useszero-padding. Let’s study 5 different payloads.
1.1234567800 (invalid)
2.123456780000 (invalid)
3.12345678000000 (invalid)
4.1234567800000000 (valid)
5.123456780000000000 (invalid)
In this situation, all cases except case 4 would raise a InvalidResponseException because of their incorrectlengths (unless config[’tolerate_zero_padding’] is set to True). Case 4 would return 2 DTCs, thesecond 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 methodsexpecting 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 meth-ods expecting a parameter of type MemoryLocation
See an example
5.1. Configuration 33
udsoncan Documentation, Release 0
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 responsewhen 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 long0x123457 : 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 Read-DTCInformation subfunction reportDTCSnapshotRecordByDTCNumber andreportDTCSnapshotRecordByRecordNumber. The UDS standard does not specify a DID sizealthough 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 (positive or negative except NRC 0x78) after sendinga request. After this time is elapsed, a TimeoutException will be raised regardless of other timeouts value orprevious client response. Ensure an exit path if the ECU keeps requesting to wait. 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 thistime 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 receptionof 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 LayerServices) 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 aDiagnosticSessionControl request. By setting this parameter to True, the value received from the server willbe used. When False, these timing values will be ignored and local configuration timing will be used. Notethat no timeout value can exceed the config[’request_timeout’] as it is meant to avoid the client fromhanging for too long.
This parameter has no effect when config[’standard_version’] is set to 2006.
Default value is True
5.2 Suppress positive response
The UDS standard proposes a mechanism to avoid treating useless positive responses. For all services using a sub-function byte, the client can set bit 7 of the subfunction byte to signal that no response is necessary if the response ispositive. 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:client.tester_present()
34 Chapter 5. Client
udsoncan Documentation, Release 0
When suppress_positive_response is asking for a service using a subfunction byte, the client will set sup-pressPosRspMsgIndicationBit before sending the request. The client will not wait for any response and will disregardnegative responses if they happen. The response returned by the client function will always be None in that case.
If suppress_positive_response is asking for a service with no subfunction byte, the directive will be ignoredand a warning message will be logged.
5.3 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 parsethe 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" statementclient.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 outputclient.tester_present()
When using that feature, the client will process the response from the server just like if a valid request was sent. Theresponse may be Invalid, Unexpected or Negative.
Note: It is possible to change the behaviour of the client on failing requests. See the client parameters excep-tion_on_invalid_response, exception_on_unexpected_response and exception_on_negative_response
5.4 Methods by services
5.4.1 AccessTimingParameter
Client.read_extended_timing_parameters()Reads the timing parameters from the server with AccessTimingParameter service with subfunctionreadExtendedTimingParameterSet (0x01).
Effective configuration exception_on_<type>_response
Returns The server response parsed by AccessTimingParameter.interpret_response
Return type Response
Client.reset_default_timing_parameters()Resets the server timing parameters to their default value with AccessTimingParameter service with subfunctionsetTimingParametersToDefaultValues (0x02).
Effective configuration exception_on_<type>_response
5.3. Overriding the output 35
udsoncan Documentation, Release 0
Returns The server response parsed by AccessTimingParameter.interpret_response
Return type Response
Client.read_active_timing_parameters()Reads the currently active timing parameters from the server with AccessTimingParameter service with sub-function 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)Sets the timing parameters into the server with AccessTimingParameter service with subfunctionsetTimingParametersToGivenValues (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
5.4.2 ClearDiagnosticInformation
Client.clear_dtc(group=16777215)Requests the server to clear its active Diagnostic Trouble Codes with the ClearDiagnosticInformation service.
Effective configuration exception_on_<type>_response
Parameters group (int) – The group of DTCs to clear. It may refer to Powertrain DTCs, ChassisDTCs, etc. Values are defined by the ECU manufacturer except for two specific values
• 0x000000 : Emissions-related systems
• 0xFFFFFF : All DTCs
Returns The server response parsed by ClearDiagnosticInformation.interpret_response
Return type Response
5.4.3 CommunicationControl
Client.communication_control(control_type, communication_type)Switches the transmission or reception of certain messages on/off with CommunicationControl service.
Effective configuration exception_on_<type>_response
Parameters
• control_type (int) – The action to request such as enabling or disabling some mes-sages. See CommunicationControl.ControlType. This value can also be ECUmanufacturer-specific
36 Chapter 5. Client
udsoncan Documentation, Release 0
• communication_type (CommunicationType, bytes, int) – Indicates what section of thenetwork and the type of message that should be affected by the command. Refer to Com-municationType for more details. If an integer or a bytes is given, the value will be decodedto create the required CommunicationType object
Returns The server response parsed by CommunicationControl.interpret_response
Return type Response
5.4.4 ControlDTCSetting
Client.control_dtc_setting(setting_type, data=None)Controls some settings related to the Diagnostic Trouble Codes by sending a ControlDTCSetting service request.It can enable/disable some DTCs or perform some ECU specific configuration.
Effective configuration exception_on_<type>_response
Parameters
• setting_type (int) – Allowed values are from 0 to 0x7F. SeeControlDTCSetting.SettingType
• data (bytes) – Optional additional data sent with the request called DTCSettingCon-trolOptionRecord
Returns The server response parsed by ControlDTCSetting.interpret_response
Return type Response
5.4.5 DiagnosticSessionControl
Client.change_session(newsession)Requests the server to change the diagnostic session with a DiagnosticSessionControl service request
Effective configuration exception_on_<type>_response
Parameters newsession (int) – The session to try to switch. Values fromDiagnosticSessionControl.Session can be used.
Returns The server response parsed by DiagnosticSessionControl.interpret_response
Return type Response
5.4.6 ECUReset
Client.ecu_reset(reset_type)Requests the server to execute a reset sequence through the ECUReset service.
Effective configuration exception_on_<type>_response
Parameters reset_type (int) – The type of reset to perform. ECUReset.ResetType
Returns The server response parsed by ECUReset.interpret_response
5.4. Methods by services 37
udsoncan Documentation, Release 0
Return type Response
5.4.7 InputOutputControlByIdentifier
Client.io_control(did, control_param=None, values=None, masks=None)Substitutes the value of an input signal or overrides the state of an output by sending a InputOutputControlByI-dentifier service request.
Effective configuration exception_on_<type>_response input_outputtolerate_zero_padding
Parameters
• did (int) – Data identifier to represent the IO
• control_param (int) – Optional parameter that can be a value fromInputOutputControlByIdentifier.ControlParam
• values (list, dict, IOValues) – Optional values to send to the server. This parameter willbe given to DidCodec.encode() method. It can be:
– A list for positional arguments
– A dict for named arguments
– An instance of IOValues for mixed arguments
• masks (list, dict, IOMask, bool) – Optional mask record for composite values. The maskdefinition must be included in config[’input_output’] It can be:
– A list naming the bit mask to set
– A dict with the mask name as a key and a boolean setting or clearing the mask as thevalue
– An instance of IOMask
– A boolean value to set all masks to the same value.
Returns The server response parsed by InputOutputControlByIdentifier.interpret_response
Return type Response
5.4.8 LinkControl
Client.link_control(control_type, baudrate=None)Controls the communication baudrate by sending a LinkControl service request.
Effective configuration exception_on_<type>_response
Parameters
• control_type (int) – Allowed values are from 0 to 0xFF. SeeLinkControl.ControlType
• baudrate (Baudrate) – Required baudrate value when control_typeis either verifyBaudrateTransitionWithFixedBaudrate (1) orverifyBaudrateTransitionWithSpecificBaudrate (2)
38 Chapter 5. Client
udsoncan Documentation, Release 0
Returns The server response parsed by LinkControl.interpret_response
Return type Response
5.4.9 ReadDataByIdentifier
Client.read_data_by_identifier(didlist)Requests a value associated with a data identifier (DID) through the ReadDataByIdentifier service.
Effective configuration exception_on_<type>_response data_identifierstolerate_zero_padding
See an example about how to read a DID
Parameters didlist (list[int]) – The list of DID to be read
Returns The server response parsed by ReadDataByIdentifier.interpret_response
Return type Response
5.4.10 ReadDTCInformation
Client.get_dtc_by_status_mask(status_mask)Reads all the Diagnostic Trouble Codes that have a status matching the given mask. The server will check all ofits DTCs and if (Dtc.status & status_mask) != 0, then the DTCs match the filter and are sent back to the client.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Parameters status_mask (int or Dtc.Status) – The status mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_emission_dtc_by_status_mask(status_mask)Reads the emission-related Diagnostic Trouble Codes that have a status matching the given mask. The serverwill check its emission-related DTCs and if (Dtc.status & status_mask) != 0, then the DTCs match the filter andare sent back to the client.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Parameters status_mask (int or Dtc.Status) – The status mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_mirrormemory_dtc_by_status_mask(status_mask)Reads all the Diagnostic Trouble Codes stored in mirror memory that have a status matching the given mask.The server will check all of its DTCs and if (Dtc.status & status_mask) != 0, then the DTCs match the filter andare sent back to the client.
5.4. Methods by services 39
udsoncan Documentation, Release 0
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Parameters status_mask (int or Dtc.Status) – The status mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_by_status_severity_mask(status_mask, severity_mask)Reads all the Diagnostic Trouble Codes that have a status and a severity matching the given masks. The serverwill check all of its DTCs and if ( (Dtc.status & status_mask) != 0 && (Dtc.severity & severity) !=0), then theDTCs match the filter and are sent back to the client.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Parameters
• status_mask (int or Dtc.Status) – The status mask against which the DTCs are tested.
• severity_mask (int or Dtc.Severity) – The severity mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_number_of_dtc_by_status_mask(status_mask)Gets the number of DTCs that match the specified status mask.
Effective configuration exception_on_<type>_response
Parameters status_mask (int or Dtc.Status) – The status mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_mirrormemory_number_of_dtc_by_status_mask(status_mask)Gets the number of DTCs that match the specified status mask in mirror memory.
Effective configuration exception_on_<type>_response
Parameters status_mask (int or Dtc.Status) – The status mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_number_of_emission_dtc_by_status_mask(status_mask)Gets the number of emission-related DTCs that match the specified status mask.
Effective configuration exception_on_<type>_response
Parameters status_mask (int or Dtc.Status) – The status mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_number_of_dtc_by_status_severity_mask(status_mask, severity_mask)Gets the number of DTCs that match the specified status mask and severity mask.
40 Chapter 5. Client
udsoncan Documentation, Release 0
Effective configuration exception_on_<type>_response
Parameters
• status_mask (int or Dtc.Status) – The status mask against which the DTCs are tested.
• severity_mask (int or Dtc.Severity) – The severity mask against which the DTCs aretested.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_severity(dtc)Requests the server for a specific DTC severity level.
Effective configuration exception_on_<type>_response
Parameters dtc (int or Dtc) – The DTC ID for which we request the severity. It can be a 3-byteinteger or a DTC instance with an ID set.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_supported_dtc()Requests the list of supported DTCs by the server.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_first_test_failed_dtc()Reads a single DTC. Requests the server for the first DTC that set its Dtc.Status.test_failed bit.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_first_confirmed_dtc()Reads a single DTC. Requests the server for the first DTC that set its Dtc.Status.confirmed bit.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_most_recent_test_failed_dtc()Reads a single DTC. Requests the server for the last DTC that set its Dtc.Status.test_failed bit.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_most_recent_confirmed_dtc()Reads a single DTC. Requests the server for the last DTC that set its Dtc.Status.confirmed bit.
5.4. Methods by services 41
udsoncan Documentation, Release 0
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_with_permanent_status()Returns all DTCs that the server marked as permanent.
A permanent DTC is a DTC stored in Non-Volatile memory and that cannot be erased by test equipment or bypower-cycling the ECU.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_fault_counter()Requests the server for all DTCs that are prefailed along with their fault detection counter.
A prefailed DTC is a DTC for which the detection condition is met, but has not been identified as pending orconfirmed yet.
If the ECU follows the UDS guidelines, it will wait to detect a fault many times before setting a status bit for thisfault DTC. Each time the fault is detected, a fault counter is incremented, when it is not detected, the counter isdecremented. Once the fault counter reaches a threshold, a status bit is set and the DTC is not prefailed anymore.A prefailed DTC is any DTC that has fault detection counter greater than 0, but less than the detection threshold.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_snapshot_identification()Requests the server to return an index of all the DTC snapshots available. The server will respond with a list ofDTCs and a list of snapshot record numbers for each DTC.
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_snapshot_by_dtc_number(dtc, record_number=255)Requests the server for one or many specific DTC snapshots associated with a single DTC. Each snapshothas a data identifier associated with it. The data will be decoded using the associated DidCodec defined inconfig[’data_identifiers’].
Effective configuration exception_on_<type>_response tolerate_zero_paddingignore_all_zero_dtc dtc_snapshot_did_size
Parameters
• dtc (int or Dtc) – The DTC ID for which we request the snapshot data. It can be a 3-byteinteger or a DTC instance with an ID set.
• record_number (int) – The record number of the snapshot data to read. If 0xFF isgiven, then all snapshots will be read, otherwise, a single snapshot will be read.
42 Chapter 5. Client
udsoncan Documentation, Release 0
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_snapshot_by_record_number(record_number=255)Requests the server for one or many DTC snapshots by specifying a record number. This functionality can existonly if the server assigns globally unique record_numbers to DTC snapshots, regardless of the DTC ID.
Each snapshot has a data identifier associated with it. The data will be decoded using the associated DidCodecdefined in config[’data_identifiers’].
Effective configuration exception_on_<type>_response tolerate_zero_paddingdtc_snapshot_did_size
Parameters record_number (int) – The record number of the snapshot data to read. If 0xFFis given, then all snapshots will be read, otherwise, a single snapshot will be read.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_dtc_extended_data_by_dtc_number(dtc, record_number=255, data_size=None)Requests the server for one or many DTC extended data by specifying a record number.
The DTC extended data is an ECU specific set of data that is not associated with a data identifier. Given asbytes
Effective configuration exception_on_<type>_response tolerate_zero_paddingextended_data_size
Parameters
• dtc (int or Dtc) – The DTC ID for which we request the extended data. It can be a 3-byteinteger or a DTC instance with an ID set.
• record_number (int) – The record number of the extended data to read. If 0xFF isgiven, then all extended data entries will be read, otherwise, a single entry will be read.
• data_size (int or None) – The number of bytes of an extended data record. If notspecified config[’extended_data_size’][dtc] will be used.
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
Client.get_mirrormemory_dtc_extended_data_by_dtc_number(dtc, record_number=255,data_size=None)
Requests the server for one or many DTC extended data stored in mirror memory by specifying a recordnumber.
The DTC extended data is an ECU specific set of data that is not associated with a data identifier. Given asbytes
Effective configuration exception_on_<type>_response tolerate_zero_paddingextended_data_size
Parameters
• dtc (int or Dtc) – The DTC ID for which we request the extended data. It can be a 3-byteinteger or a DTC instance with an ID set.
• record_number (int) – The record number of the extended data to read. If 0xFF isgiven, then all extended data entries will be read, otherwise, a single entry will be read.
• data_size (int or None) – The number of bytes of an extended data record. If notspecified config[’extended_data_size’][dtc] wil be used.
5.4. Methods by services 43
udsoncan Documentation, Release 0
Returns The server response parsed by ReadDTCInformation.interpret_response
Return type Response
5.4.11 ReadMemoryByAddress
Client.read_memory_by_address(memory_location)Reads a block of memory from the server by sending a ReadMemoryByAddress service request.
Effective configuration exception_on_<type>_response server_address_formatserver_memorysize_format
Parameters memory_location (MemoryLocation) – The address and the size of the memoryblock to read.
Returns The server response parsed by ReadMemoryByAddress.interpret_response
Return type Response
Note: See an example showing how to use default format configuration.
5.4.12 RequestDownload
Client.request_download(memory_location, dfi=None)Informs the server that the client wants to initiate a download from the client to the server by sending a Request-Download service request.
Effective configuration exception_on_<type>_response server_address_formatserver_memorysize_format
Parameters
• memory_location (MemoryLocation) – The address and size of the memory block tobe written.
• dfi (DataFormatIdentifier) – Optional DataFormatIdentifier defining the compression andencryption scheme of the data. If not specified, the default value of 00 will be used, speci-fying no encryption and no compression
Returns The server response parsed by RequestDownload.interpret_response
Return type Response
Note: See an example showing how to use default format configuration.
44 Chapter 5. Client
udsoncan Documentation, Release 0
5.4.13 RequestTransferExit
Client.request_transfer_exit(data=None)Informs the server that the client wants to stop the data transfer by sending a RequestTransferExit service request.
Effective configuration exception_on_<type>_response
Parameters data (bytes) – Optional additional data to send to the server
Returns The server response parsed by RequestTransferExit.interpret_response
Return type Response
5.4.14 RequestUpload
Client.request_upload(memory_location, dfi=None)Informs the server that the client wants to initiate an upload from the server to the client by sending a Reques-tUpload service request.
Effective configuration exception_on_<type>_response server_address_formatserver_memorysize_format
Parameters
• memory_location (MemoryLocation) – The address and size of the memory block tobe written.
• dfi (DataFormatIdentifier) – Optional DataFormatIdentifier defining the compression andencryption scheme of the data. If not specified, the default value of 00 will be used, speci-fying no encryption and no compression
Returns The server response parsed by RequestUpload.interpret_response
Return type Response
Note: See an example showing how to use default format configuration.
5.4.15 RoutineControl
Client.start_routine(routine_id, data=None)Requests the server to start a routine through the RoutineControl service (subfunction = 0x01).
Effective configuration exception_on_<type>_response
Parameters
• routine_id – The 16-bit numerical ID of the routine to start
• data (bytes) – Optional additional data to give to the server
Returns The server response parsed by RoutineControl.interpret_response
Return type Response
Client.stop_routine(routine_id, data=None)Requests the server to stop a routine through the RoutineControl service (subfunction = 0x02).
5.4. Methods by services 45
udsoncan Documentation, Release 0
Effective configuration exception_on_<type>_response
Parameters
• routine_id – The 16-bit numerical ID of the routine to stop
• data (bytes) – Optional additional data to give to the server
Returns The server response parsed by RoutineControl.interpret_response
Return type Response
Client.get_routine_result(routine_id, data=None)Requests the server to send back the execution result of the specified routine through the RoutineControl service(subfunction = 0x03).
Effective configuration exception_on_<type>_response
Parameters
• routine_id – The 16-bit numerical ID of the routine
• data (bytes) – Optional additional data to give to the server
Returns The server response parsed by RoutineControl.interpret_response
Return type Response
5.4.16 SecurityAccess
Client.request_seed(level)Requests a seed to unlock a security level with the SecurityAccess service
Effective configuration exception_on_<type>_response
Parameters level (int) – The security level to unlock. If value is even, it will be converted tothe corresponding odd value
Returns The server response parsed by SecurityAccess.interpret_response
Return type Response
Client.send_key(level, key)Sends a key to unlock a security level with the SecurityAccess service
Effective configuration exception_on_<type>_response
Parameters
• level (int) – The security level to unlock. If value is odd, it will be converted to thecorresponding even value
• key (bytes) – The key to send to the server
Returns The server response parsed by SecurityAccess.interpret_response
Return type Response
Client.unlock_security_access(level)Successively calls request_seed and send_key to unlock a security level with the SecurityAccess service. Thekey computation is done by calling config[’security_algo’]
Effective configuration exception_on_<type>_response security_algosecurity_algo_params
46 Chapter 5. Client
udsoncan Documentation, Release 0
Parameters level (int) – The level to unlock. Can be the odd or even variant of it.
Returns The server response parsed by SecurityAccess.interpret_response
Return type Response
Note: See this example to see how to define the security algorithm
5.4.17 TesterPresent
Client.tester_present()Sends a TesterPresent request to keep the session active.
Effective configuration exception_on_<type>_response
Returns The server response parsed by TesterPresent.interpret_response
Return type Response
5.4.18 TransferData
Client.transfer_data(sequence_number, data=None)Transfer a block of data to/from the client to/from the server by sending a TransferData service request andreturning the server response.
Effective configuration exception_on_<type>_response
Parameters
• sequence_number (int) – Corresponds to an 8bit counter that should increment foreach new block transferred. Allowed values are from 0 to 0xFF
• data (bytes) – Optional additional data to send to the server
Returns The server response parsed by TransferData.interpret_response
Return type Response
5.4.19 WriteDataByIdentifier
Client.write_data_by_identifier(did, value)Requests to write a value associated with a data identifier (DID) through the WriteDataByIdentifier service.
Effective configuration exception_on_<type>_response data_identifiers
Parameters
• didlist (int) – The DID to write its value
• value (int) – Value given to the DidCodec.encode method. The payload returned by thecodec will be sent to the server.
Returns The server response parsed by WriteDataByIdentifier.interpret_response
5.4. Methods by services 47
udsoncan Documentation, Release 0
Return type Response
Note: If the DID Codec that is written is defined with a pack string (default codec), multiple values may be passedwith a tuple.
5.4.20 WriteMemoryByAddress
Client.write_memory_by_address(memory_location, data)Writes a block of memory in the server by sending a WriteMemoryByAddress service request.
Effective configuration exception_on_<type>_response server_address_formatserver_memorysize_format
Parameters
• memory_location (MemoryLocation) – The address and the size of the memory blockto read.
• data (bytes) – The data to write into memory.
Returns The server response parsed by WriteMemoryByAddress.interpret_response
Return type Response
5.4.21 RequestFileTransfer
Client.add_file(filename, dfi=None, filesize=None)Sends a RequestFileTransfer request with ModeOfOperation=AddFile(1).
Effective configuration exception_on_<type>_response tolerate_zero_padding
Parameters
• filename (str) – The name of the file to create, limited to ASCII characters.
• dfi (DataFormatIdentifier) – DataFormatIdentifier defining the compression and encryp-tion scheme of the data. If not specified, the default value of 00 will be used, specifying noencryption and no compression.
• filesize (Filesize or int) – The filesize of the file to write. If filesize is an object oftype Filesize, the uncompressed size and compressed size will be encoded on the minimumamount of bytes necessary, unless a width is explicitly defined. If no compressed size isgiven or filesize is an int, then the compressed size will be set equal to the uncompressedsize or the integer value given as specified by ISO-14229
Returns The server response parsed by RequestFileTransfer.interpret_response
Return type Response
Client.delete_file(filename)Sends a RequestFileTransfer request with ModeOfOperation=DeleteFile(2).
Effective configuration exception_on_<type>_response tolerate_zero_padding
Parameters filename (str) – The name of the file to delete, limited to ASCII characters.
48 Chapter 5. Client
udsoncan Documentation, Release 0
Returns The server response parsed by RequestFileTransfer.interpret_response
Return type Response
Client.replace_file(filename, dfi=None, filesize=None)Sends a RequestFileTransfer request with ModeOfOperation=ReplaceFile(3).
Effective configuration exception_on_<type>_response tolerate_zero_padding
Parameters
• filename (str) – The name of the file to replace, limited to ASCII characters.
• dfi (DataFormatIdentifier) – DataFormatIdentifier defining the compression and encryp-tion scheme of the data. If not specified, the default value of 00 will be used, specifying noencryption and no compression.
• filesize (Filesize or int) – The filesize of the file to write. If filesize is an object oftype Filesize, the uncompressed size and compressed size will be encoded on the minimumamount of bytes necessary, unless a width is explicitly defined. If no compressed size isgiven or filesize is an int, then the compressed size will be set equal to the uncompressedsize or the integer value given as specified by ISO-14229
Returns The server response parsed by RequestFileTransfer.interpret_response
Return type Response
Client.read_file(filename, dfi=None)Sends a RequestFileTransfer request with ModeOfOperation=ReadFile(4).
Effective configuration exception_on_<type>_response tolerate_zero_padding
Parameters
• filename (str) – The name of the file to read, limited to ASCII characters.
• dfi (DataFormatIdentifier) – DataFormatIdentifier defining the compression and encryp-tion scheme of the data. If not specified, the default value of 00 will be used, specifying noencryption and no compression.
Returns The server response parsed by RequestFileTransfer.interpret_response
Return type Response
Client.read_dir(path)Sends a RequestFileTransfer request with ModeOfOperation=ReadDir(5).
Effective configuration exception_on_<type>_response tolerate_zero_padding
Parameters path (str) – The name of the directory to read, limited to ASCII characters.
Returns The server response parsed by RequestFileTransfer.interpret_response
Return type Response
5.4. Methods by services 49
udsoncan Documentation, Release 0
50 Chapter 5. Client
CHAPTER 6
Helper classes
This section provides a definition for several classes included in this project.
6.1 CommunicationType
class udsoncan.CommunicationType(subnet, normal_msg=False, network_management_msg=False)This class represents a pair of subnet and message types. This value is mainly used by the CommunicationCon-trol service
Parameters
• subnet (int) – Represent the subnet number. Value ranges from 0 to 0xF
• normal_msg (bool) – Bit indicating that the normal messages are involved
• network_management_msg (bool) – Bit indicating that the network managementmessages are involved
6.2 MemoryLocation
class udsoncan.MemoryLocation(address, memorysize, address_format=None, memory-size_format=None)
This class defines a memory block location including : address, size, AddressAndLengthFormatIdentifier (ad-dress format and memory size format)
Parameters
• address (int) – A memory address pointing to the beginning of the memory block
• memorysize (int) – The size of the memory block
• address_format (int or None) – The number of bits on which an address shouldbe encoded. Possible values are 8, 16, 24, 32, 40. If None is specified, the smallest sizerequired to store the given address will be used
• memorysize_format (int or None) – The number of bits on which a memory sizeshould be encoded. Possible values are 8, 16, 24, 32 If None is specified, the smallest sizerequired to store the given memorysize will be used
51
udsoncan Documentation, Release 0
6.3 DidCodec
class udsoncan.DidCodec(packstr=None)This class defines how to encode/decode a Data Identifier value to/from a binary payload.
One should extend this class and override the encode, decode, __len__ methods as they will be used togenerate or parse binary payloads.
•encode Must receive any Python object and must return a bytes payload
•decode Must receive a bytes payload and may return any Python object
•__len__ Must return the length of the bytes payload or raise aDidCodec.ReadAllRemainingData to read the whole payload. Reading the whole payloadis not a feature proposed by ISO-14229.
If a data can be processed by a pack string, then this class may be used as is, without being extended.
Parameters packstr (string) – A pack string used with struct.pack / struct.unpack.
6.4 Baudrate
class udsoncan.Baudrate(baudrate, baudtype=3)Represents a link speed in bit per seconds (or symbol per seconds to be more accurate). This class is used bythe LinkControl service that controls the underlying protocol speeds.
The class can encode the baudrate in 2 different fashions : Fixed or Specific.
Some standard baudrate values are defined within ISO-14229:2006 Annex B.3
Parameters
• baudrate (int) – The baudrate to be used.
• baudtype (int) – Tells how the baudrate shall be encoded. 4 values are possible:
– Baudrate.Type.Fixed (0) : Will encode the baudrate in a single byte Fixed fashion.baudrate should be a supported value such as 9600, 19200, 125000, 250000, etc.
– Baudrate.Type.Specific (1) : Will encode the baudrate in a three-byte Specificfashion. baudrate can be any value ranging from 0 to 0xFFFFFF
– Baudrate.Type.Identifier (2) : Will encode the baudrate in a single byte Fixedfashion. baudrate should be the byte value to encode if the user wants to use a customtype.
– Baudrate.Type.Auto (3) : Let the class guess the type.
* If baudrate is a known standard value (19200, 38400, etc), then Fixed shall be used
* If baudrate is an integer that fits in a single byte, then Identifier shall be used
* If baudrate is none of the above, then Specific will be used.
52 Chapter 6. Helper classes
udsoncan Documentation, Release 0
6.5 DataFormatIdentifier
class udsoncan.DataFormatIdentifier(compression=0, encryption=0)Defines the compression and encryption method of a specific chunk of data. Mainly used by the RequestUploadand RequestDownload services
Parameters
• compression (int) – Value between 0 and 0xF specifying the compression method.Only the value 0 has a meaning defined by UDS standard and it is No compression. Allother values are ECU manufacturer specific.
• encryption (int) – Value between 0 and 0xF specifying the encryption method. Onlythe value 0 has a meaning defined by UDS standard and it is No encryption. All other valuesare ECU manufacturer specific.
6.6 AddressAndLengthFormatIdentifier
class udsoncan.AddressAndLengthFormatIdentifier(address_format, memorysize_format)This class defines how many bytes of a memorylocation, composed of an address and a memorysize, should beencoded when sent over the underlying protocol. Mainly used by ReadMemoryByAddress, WriteMemoryByAd-dress, RequestDownload and RequestUpload services
Defined by ISO-14229:2006, Annex G
Parameters
• address_format (int) – The number of bits on which an address should be encoded.Possible values are 8, 16, 24, 32, 40
• memorysize_format (int) – The number of bits on which a memory size should beencoded. Possible values are 8, 16, 24, 32
6.7 Filesize
class udsoncan.Filesize(uncompressed=None, compressed=None, width=None)This class represent a file size used by the RequestFileTransfer service.
Parameters
• uncompressed (int) – Represent the uncompressed size in bytes
• compressed (int) – Represent the compressed size in bytes
• width (int) – The number of byte that should be used to encode the filesize in a payload
6.5. DataFormatIdentifier 53
udsoncan Documentation, Release 0
6.8 DTC
class udsoncan.Dtc(dtcid)Defines a Diagnostic Trouble Code which consist of a 3-byte ID, a status, a severity and some diagnostic data.
Parameters dtcid (int) – The 3-byte ID of the DTC
6.9 DTC.Status
class Dtc.Status(test_failed=False, test_failed_this_operation_cycle=False, pend-ing=False, confirmed=False, test_not_completed_since_last_clear=False,test_failed_since_last_clear=False, test_not_completed_this_operation_cycle=False,warning_indicator_requested=False)
Represents a DTC status which consists of 8 boolean flags (a byte). All flags can be set after instantiationwithout problems.
Parameters
• test_failed (bool) – DTC is no longer failed at the time of the request
• test_failed_this_operation_cycle (bool) – DTC never failed on the currentoperation cycle.
• pending (bool) – DTC failed on the current or previous operation cycle.
• confirmed (bool) – DTC is not confirmed at the time of the request.
• test_not_completed_since_last_clear (bool) – DTC test has been com-pleted since the last codeclear.
• test_failed_since_last_clear (bool) – DTC test failed at least once since lastcode clear.
• test_not_completed_this_operation_cycle (bool) – DTC test completedthis operation cycle.
• warning_indicator_requested (bool) – Server is not requesting warningIndica-tor to be active.
6.10 DTC.Severity
class Dtc.Severity(maintenance_only=False, check_at_next_exit=False, check_immediately=False)Represents a DTC severity which consists of 3 boolean flags. All flags can be set after instantiation withoutproblems.
Parameters
• maintenance_only (bool) – This value indicates that the failure requests maintenanceonly
• check_at_next_exit (bool) – This value indicates that the failure requires a checkof the vehicle at the next halt.
54 Chapter 6. Helper classes
udsoncan Documentation, Release 0
• check_immediately (bool) – This value indicates that the failure requires an imme-diate check of the vehicle.
6.11 DTC.Format
class Dtc.FormatProvide a list of DTC formats and their indices. These values are used by the The ReadDTCInformation whenrequesting a number of DTCs.
ISO15031_6 = 0
ISO14229_1 = 1
SAE_J1939_73 = 2
ISO11992_4 = 3
6.12 IOValues
class udsoncan.IOValues(*args, **kwargs)This class saves a function argument so they can be passed to a callback function.
Parameters
• args – Arguments
• kwargs – Named arguments
6.13 IOMasks
class udsoncan.IOMasks(*args, **kwargs)Allow to specify a list of masks for a InputOutputControlByIdentifier composite codec.
Example : IOMasks(mask1,mask2, mask3=True, mask4=False)
Parameters
• args – Masks to set to True
• kwargs – Masks and their values
6.11. DTC.Format 55
udsoncan Documentation, Release 0
6.14 Routine
class udsoncan.RoutineDefines a list of constants that are routine identifiers defined by the UDS standard. This class provides nofunctionality apart from defining these constants
DeployLoopRoutineID = 57856
EraseMemory = 65280
CheckProgrammingDependencies = 65281
EraseMirrorMemoryDTCs = 65282
6.15 DataIdentifier
class udsoncan.DataIdentifierDefines a list of constants that are data identifiers defined by the UDS standard. This class provides no function-ality apart from defining these constants
BootSoftwareIdentification = 61824
ApplicationSoftwareIdentification = 61825
ApplicationDataIdentification = 61826
BootSoftwareFingerprint = 61827
ApplicationSoftwareFingerprint = 61828
ApplicationDataFingerprint = 61829
ActiveDiagnosticSession = 61830
VehicleManufacturerSparePartNumber = 61831
VehicleManufacturerECUSoftwareNumber = 61832
VehicleManufacturerECUSoftwareVersionNumber = 61833
SystemSupplierIdentifier = 61834
ECUManufacturingDate = 61835
ECUSerialNumber = 61836
SupportedFunctionalUnits = 61837
VehicleManufacturerKitAssemblyPartNumber = 61838
ISOSAEReservedStandardized = 61839
VIN = 61840
VehicleManufacturerECUHardwareNumber = 61841
SystemSupplierECUHardwareNumber = 61842
SystemSupplierECUHardwareVersionNumber = 61843
SystemSupplierECUSoftwareNumber = 61844
SystemSupplierECUSoftwareVersionNumber = 61845
56 Chapter 6. Helper classes
udsoncan Documentation, Release 0
ExhaustRegulationOrTypeApprovalNumber = 61846
SystemNameOrEngineType = 61847
RepairShopCodeOrTesterSerialNumber = 61848
ProgrammingDate = 61849
CalibrationRepairShopCodeOrCalibrationEquipmentSerialNumber = 61850
CalibrationDate = 61851
CalibrationEquipmentSoftwareNumber = 61852
ECUInstallationDate = 61853
ODXFile = 61854
Entity = 61855
6.15. DataIdentifier 57
udsoncan Documentation, Release 0
58 Chapter 6. Helper classes
CHAPTER 7
Exceptions
This section explains the different exceptions used in the project.
7.1 NegativeResponseException
class udsoncan.exceptions.NegativeResponseException(response, *args, **kwargs)Raised when the server returns a negative response (response code starting by 0x7F). The response that triggeredthe exception is available in e.response
Parameters response (Response) – The response that triggered the exception
7.2 InvalidResponseException
class udsoncan.exceptions.InvalidResponseException(response, *args, **kwargs)Raised when a service fails to decode a server response data. A bad message length or a value that is out ofrange may both be valid causes. The response that triggered the exception is available in e.response
Parameters response (Response) – The response that triggered the exception
7.3 UnexpectedResponseException
class udsoncan.exceptions.UnexpectedResponseException(response, details=’<No detailsgiven>’, *args, **kwargs)
Raised when the client receives a valid response but considers the one received to not be the expected response.The response that triggered the exception is available in e.response
Parameters
• response (Response) – The response that triggered the exception
• details (string) – Additional details about the error
7.4 TimeoutException
class udsoncan.exceptions.TimeoutException(*args, **kwargs)Simple extension of Exception with no additional property. Raised when a timeout in the communication
59
udsoncan Documentation, Release 0
happens.
7.5 ConfigError
class udsoncan.exceptions.ConfigError(key, msg=’<No details given>’, *args, **kwargs)Raised when a bad configuration element is encountered.
Parameters key (object) – The configuration key that failed to resolve properly
60 Chapter 7. Exceptions
CHAPTER 8
Examples
8.1 Different layers of intelligence (1 to 4)
In the following examples, we will request an ECU reset in 4 different ways. We will start by crafting a binary payloadmanually, then we will add a layer of interpretation making the code more comprehensive each time.
8.1.1 1. Raw Connection
my_connection.send(b'\x11\x01\x77\x88\x99') # Sends ECU Reset, with subfunction = 1payload = my_connection.wait_frame(timeout=1)if payload == b'\x51\x01':
print('Success!')else:
print('Reset failed')
8.1.2 2. Request and Responses
req = Request(services.ECUReset, subfunction=1, data=b'\x77\x88\x99')my_connection.send(req.get_payload())payload = my_connection.wait_frame(timeout=1)response = Response.from_payload(payload)if response.service == service.ECUReset and response.code == Response.Code.PositiveResponse and response.data == b'\x01':
print('Success!')else:
print('Reset failed')
8.1.3 3. Services
req = services.ECUReset.make_request(reset_type=1, data=b'\x77\x88\x99')my_connection.send(req.get_payload())payload = my_connection.wait_frame(timeout=1)response = Response.from_payload(payload)services.ECUReset.interpret_response(response)if response.service == service.ECUReset and response.code == Response.Code.PositiveResponse and response.service_data.reset_type_echo == 1:
print('Success!')else:
print('Reset failed')
61
udsoncan Documentation, Release 0
8.1.4 4. Client
try:client.ecu_reset(reset_type=1, data=b'\x77\x88\x99')print('Success!')
except:print('Reset failed')
8.2 Using UDS over python-can
In this example, we show how to use PythonIsoTpConnection with a fictive Vector interface. Note that, in orderto run this code, both python-can and can-isotp must be installed.
from can.interfaces.vector import VectorBusfrom udsoncan.connections import PythonIsoTpConnectionfrom udsoncan.client import Clientimport isotp
# Refer to isotp documentation for full details about parametersisotp_params = {
'stmin' : 32, # Will request the sender to wait 32ms between consecutive frame. 0-127ms or 100-900ns with values from 0xF1-0xF9'blocksize' : 8, # Request the sender to send 8 consecutives frames before sending a new flow control message'wftmax' : 0, # Number of wait frame allowed before triggering an error'll_data_length' : 8, # Link layer (CAN layer) works with 8 byte payload (CAN 2.0)'tx_padding' : 0, # Will pad all transmitted CAN messages with byte 0x00. None means no padding'rx_flowcontrol_timeout' : 1000 # Triggers a timeout if a flow control is awaited for more than 1000 milliseconds'rx_consecutive_frame_timeout' : 1000, # Triggers a timeout if a consecutive frame is awaited for more than 1000 milliseconds'squash_stmin_requirement' : False # When sending, respect the stmin requirement of the receiver. If set to True, go as fast as possible.
}
bus = VectorBus(channel=0, bitrate=500000) # Link Layer (CAN protocol)tp_addr = isotp.Address(isotp.AddressingMode.Normal_11bits, txid=0x123, rxid=0x456) # Network layer addressing schemestack = isotp.CanStack(bus=bus, address=tp_addr, params=isotp_params) # Network/Transport layer (IsoTP protocol)conn = PythonIsoTpConnection(stack) # interface between Application and Transport layerwith Client(conn, request_timeout=1) as client: # Application layer (UDS protocol)
client.change_session(1)# ...
8.3 Server default address and size format
In this example, we show how the Client uses the memory location format configurations.
client.config['server_address_format'] = 16client.config['server_memorysize_format'] = 8# Explicit declaration. Client will used this valuememloc1 = MemoryLocation(address=0x1234, memorysize=0x10, address_format=16, address_format=8)# No explicit declaration. Client will use the default values in the configurationmemloc2 = MemoryLocation(address=0x1234, memorysize=0x10)response = client.read_memory_by_address(memloc1)response = client.read_memory_by_address(memloc2)
62 Chapter 8. Examples
udsoncan Documentation, Release 0
8.4 Security algorithm implementation
The following example shows how to define a security algorithm in the client configuration. The algorithmXOR the seed with a pre-shared key passed as a parameter.
def myalgo(level, seed, params):"""Builds the security key to unlock a security level. Returns the seed xor'ed with pre-shared key."""
output_key = bytearray(seed)xorkey = bytearray(params['xorkey'])
for i in range(len(seed)):output_key[i] = seed[i] ^ xorkey[i%len(xorkey)]
return bytes(output_key)
client.config['security_algo'] = myalgoclient.config['security_algo_params'] = dict(xorkey=b'\x12\x34\x56\x78')
Warning: This algorithm is not secure and is given as an example only because of its simple implementation.XOR encryption is weak on many levels; it is vulnerable to known-plaintext attacks, relatively weak against replayattacks and does not provide enough diffusion (pattern recognition is possible). If you are an ECU programmer,please do not implement this.
8.5 Reading a DID with ReadDataByIdentifier
This example shows how to configure the client with a DID configuration and request the server with ReadDataByI-dentifier
import udsoncanfrom udsoncan.Connection import IsoTPConnectionfrom udsoncan.client import Clientimport udsoncan.configs
class MyCustomCodecThatShiftBy4(udsoncan.DidCodec):def encode(self, val):
val = (val << 4) & 0xFFFFFFFF # Do some stuffreturn struct.pack('<L', val) # Little endian, 32 bit value
def decode(self, payload):val = struct.unpack('<L', payload)[0] # decode the 32 bits valuereturn val >> 4 # Do some stuff (reversed)
def __len__(self):return 4 # encoded paylaod is 4 byte long.
config = dict(udsoncan.configs.default_client_config)config['data_identifiers'] = {
0x1234 : MyCustomCodecThatShiftBy4, # Uses own custom defined codec. Giving the class is ok0x1235 : MyCustomCodecThatShiftBy4(), # Same as 0x1234, giving an instance is good also0xF190 : udsoncan.AsciiCodec(15) # Codec that read ASCII string. We must tell the length of the string}
8.4. Security algorithm implementation 63
udsoncan Documentation, Release 0
conn = IsoTPConnection('vcan0', rxid=0x123, txid=0x456)with Client(conn, request_timeout=2, config=config) as client:
response = client.read_data_by_identifier(0xF190)print(response.service_data.values[0xF190]) # This is a dict of DID:Value
# Or, if a single DID is expected, a shortcut to read the value of the first DIDvin = client.read_data_by_identifier_first(0xF190)print(vin) # 'ABCDE0123456789' (15 chars)
8.6 InputOutputControlByIdentifier Composite DID
This example shows how the InputOutputControlByIdentifier can be used with a composite data identifier and how tobuild a proper ioconfig dict which can be tricky. The example shown below correspond to a real example provided inISO-14229 document
# Example taken from UDS standard
class MyCompositeDidCodec(DidCodec):def encode(self, IAC_pintle, rpm, pedalA, pedalB, EGR_duty):
pedal = (pedalA << 4) | pedalBreturn struct.pack('>BHBB', IAC_pintle, rpm, pedal, EGR_duty)
def decode(self, payload):vals = struct.unpack('>BHBB', payload)return {
'IAC_pintle': vals[0],'rpm' : vals[1],'pedalA' : (vals[2] >> 4) & 0xF,'pedalB' : vals[2] & 0xF,'EGR_duty' : vals[3]
}
def __len__(self):return 5
ioconfig = {0x132 : MyDidCodec,0x456 : '<HH',0x155 : {
'codec' : MyCompositeDidCodec,'mask' : {
'IAC_pintle': 0x80,'rpm' : 0x40,'pedalA' : 0x20,'pedalB' : 0x10,'EGR_duty' : 0x08
},'mask_size' : 2 # Mask encoded over 2 bytes
}}
values = {'IAC_pintle': 0x07, 'rpm': 0x1234, 'pedalA': 0x4, 'pedalB' : 0x5, 'EGR_duty': 0x99}req = InputOutputControlByIdentifier.make_request(0x155, values=values, masks=['IAC_pintle', 'pedalA'], ioconfig=ioconfig)
64 Chapter 8. Examples
CHAPTER 9
Questions and answers
9.1 What version of the standard has been used?
The cod ewas originally written based on ISO-14229:2006. Some addition from the 2013 version hasbeen added, but not exhaustively.
9.2 Can we expect an update for the 2020 version?
Yes, one day, when I’ll put my hands on the 2020 document. Access to ISO standard costs money andthis project is 100% voluntary.
9.3 How reliable is this code?
To the best of my knowledge, quite good. This project comes with a fair amount of unit tests, many basedon examples proposed in the UDS standard document. Every service encoding/decoding is unit-tested.
Only a few common services have been tested on a real ECU.
9.4 Why is there unimplemented services?
One of these reasons:
• The actual synchronous client doesn’t support it.
• The ratio of “service usage in the industry” over “the amount of work necessary to implement it” istoo poor.
As for the client capabilities, I am aware that the single-request/single-response mechanism of the actualclient is limiting. I believe it is enough to handle the majority of today’s use-cases. I may work in a futureversion for a more sophisticated client that will have message queues for each service with callback andeverything, therefore allowing asynchronous services such as ResponseOnEvent or ReadDataByPeriodi-cIdentifier
65
udsoncan Documentation, Release 0
9.5 I have a CAN transceiver, how do I use this project now?
This project is not all you need; you need to create a path for the data to reach your CAN box.
Under Linux, if your CAN box is supported by SocketCAN, you should have a new network interfaceafter plugging in the device. Compile and install this module, then find out what CAN IDs are used fordiagnostics and use the SocketConnection or IsoTPSocketConnection
If you do not want to rely on SocketCAN, you can use PythonIsoTpConnection. This connectionwill make usage of Python’s can-isotp module which can be coupled with python-can to access the CANlayer. The main advantage of doing this is that python-can supports many can interface, both underWindows and Linux. Unfortunately, the transport layer (IsoTp) implementation needs to be in the userspace, which usually fails to meet the protocol timing requirements. Most of time, this is not an issue.
If you can’t use any of the above solution, you will need to write your own Connection class that handleseverything from the transport protocol (IsoTP) to the hardware which means interacting with the drivers.See Defining a new Connection
9.6 What is the DTC mirror memory?
A mirror memory is an optional feature that a UDS server can offer. It’s a snapshot of a specific memorysection that is frozen in time. Interacting with this mirror memory avoids race conditions such as a DTCstatus changing while reading its value.
The client may ask the server to copy the mirror memory or erase it by calling a routine or writing a dataidentifier. The implementation is ECU manufacturer specific.
9.7 What makes a DTC permanent?
Some diagnostic trouble codes are severe and can only be removed by the manufacturer. A permanentDTC is stored in a non-volatile memory and cannot be cleared with a common test tool or by removingpower on the ECU.
9.8 How can I contribute?
Create a Github issue, fork the project, propose a pull request and I will review it; that’s the best way.
66 Chapter 9. Questions and answers
CHAPTER 10
Purpose
This project is an implementation of the Unified Diagnostic Services (UDS) protocol defined by ISO-14229 written inPython 3. The code is published under MIT license on GitHub (pylessard/python-udsoncan).
The goal of this project is to provide with a set of tool to interract with a UDS server by building/interpreting UDSpayload and detecting malformed messages. All of this, with minimal effort and comprehensive code. It can be usefulto develop a tester unit, debugging a server code, searching for security flaws or just messing with your car.
67
udsoncan Documentation, Release 0
68 Chapter 10. Purpose
CHAPTER 11
Example
Here is an example of code to give an insight of the grammar.
import SomeLib.SomeCar.SomeModel as MyCar
import udsoncanfrom udsoncan.connections import IsoTPSocketConnectionfrom udsoncan.client import Clientfrom udsoncan.exceptions import *from udsoncan.services import *
udsoncan.setup_logging()
conn = IsoTPSocketConnection('can0', rxid=0x123, txid=0x456)with Client(conn, request_timeout=2, config=MyCar.config) as client:
try:client.change_session(DiagnosticSessionControl.Session.extendedDiagnosticSession) # integer with value of 3client.unlock_security_access(MyCar.debug_level) # Fictive security level. Integer coming from fictive lib, let's say its value is 5client.write_data_by_identifier(udsoncan.DataIdentifier.VIN, 'ABC123456789') # Standard ID for VIN is 0xF190. Codec is set in the client configurationprint('Vehicle Identification Number successfully changed.')client.ecu_reset(ECUReset.ResetType.hardReset) # HardReset = 0x01
except NegativeResponseException as e:print('Server refused our request for service %s with code "%s" (0x%02x)' % (e.response.service.get_name(), e.response.code_name, e.response.code))
except InvalidResponseException, UnexpectedResponseException as e:print('Server sent an invalid payload : %s' % e.response.original_payload)
69
udsoncan Documentation, Release 0
70 Chapter 11. Example
Index
AAccessDenied (udsoncan.Response.Code attribute), 10AccessTimingParameter.AccessType (class in udson-
can.services), 12AccessTimingParameter.ResponseData (class in udson-
can.services), 12AccessTimingParameter.ResponseData.access_type_echo
(built-in variable), 12AccessTimingParameter.ResponseData.timing_param_record
(built-in variable), 12ActiveDiagnosticSession (udsoncan.DataIdentifier
attribute), 56add_file() (udsoncan.client.Client method), 48AddressAndLengthFormatIdentifier (class in udsoncan),
53ApplicationDataFingerprint (udsoncan.DataIdentifier at-
tribute), 56ApplicationDataIdentification (udsoncan.DataIdentifier
attribute), 56ApplicationSoftwareFingerprint (udsoncan.DataIdentifier
attribute), 56ApplicationSoftwareIdentification (udson-
can.DataIdentifier attribute), 56AuditTrailInformationNotAvailable (udson-
can.Response.Code attribute), 10
BBaudrate (class in udsoncan), 52BootSoftwareFingerprint (udsoncan.DataIdentifier
attribute), 56BootSoftwareIdentification (udsoncan.DataIdentifier at-
tribute), 56BrakeSwitchNotClosed (udsoncan.Response.Code
attribute), 10BusyRepeatRequest (udsoncan.Response.Code attribute),
9
CCalibrationDate (udsoncan.DataIdentifier attribute), 57CalibrationEquipmentSoftwareNumber (udson-
can.DataIdentifier attribute), 57
CalibrationRepairShopCodeOrCalibrationEquipmentSerialNumber(udsoncan.DataIdentifier attribute), 57
CertificateNotAvailable (udsoncan.Response.Codeattribute), 10
change_session() (udsoncan.client.Client method), 37CheckProgrammingDependencies (udsoncan.Routine at-
tribute), 56clear_dtc() (udsoncan.client.Client method), 36Client (class in udsoncan.client), 31close() (udsoncan.connections.BaseConnection method),
5communication_control() (udsoncan.client.Client
method), 36CommunicationControl.ControlType (class in udson-
can.services), 13CommunicationControl.ResponseData (class in udson-
can.services), 13CommunicationControl.ResponseData.control_type_echo
(built-in variable), 13CommunicationType (class in udsoncan), 51ConditionsNotCorrect (udsoncan.Response.Code at-
tribute), 9ConfigError (class in udsoncan.exceptions), 60control_dtc_setting() (udsoncan.client.Client method), 37ControlDTCSetting.ResponseData (class in udson-
can.services), 13ControlDTCSetting.ResponseData.setting_type_echo
(built-in variable), 13ControlDTCSetting.SettingType (class in udson-
can.services), 13
Ddata_identifiers, 32DataFormatIdentifier (class in udsoncan), 53DataIdentifier (class in udsoncan), 56defaultSession (udsoncan.services.DiagnosticSessionControl.Session
attribute), 14delete_file() (udsoncan.client.Client method), 48DeployLoopRoutineID (udsoncan.Routine attribute), 56DiagnosticSessionControl.ResponseData (class in udson-
can.services), 14
71
udsoncan Documentation, Release 0
DiagnosticSessionControl.ResponseData.p2_server_max(built-in variable), 14
DiagnosticSessionControl.ResponseData.p2_star_server_max(built-in variable), 14
DiagnosticSessionControl.ResponseData.session_echo(built-in variable), 14
DiagnosticSessionControl.ResponseData.session_param_records(built-in variable), 14
DiagnosticSessionControl.Session (class in udson-can.services), 14
DidCodec (class in udsoncan), 52disableRapidPowerShutDown (udson-
can.services.ECUReset.ResetType attribute),15
disableRxAndEnableTx (udson-can.services.CommunicationControl.ControlTypeattribute), 13
disableRxAndTx (udson-can.services.CommunicationControl.ControlTypeattribute), 13
Dtc (class in udsoncan), 54Dtc.Format (class in udsoncan), 55Dtc.Severity (class in udsoncan), 54Dtc.Status (class in udsoncan), 54dtc_snapshot_did_size, 34
Eecu_reset() (udsoncan.client.Client method), 37ECUInstallationDate (udsoncan.DataIdentifier attribute),
57ECUManufacturingDate (udsoncan.DataIdentifier at-
tribute), 56ECUReset.ResetType (class in udsoncan.services), 15ECUReset.ResponseData (class in udsoncan.services), 15ECUReset.ResponseData.powerdown_time (built-in vari-
able), 15ECUReset.ResponseData.reset_type_echo (built-in vari-
able), 15ECUSerialNumber (udsoncan.DataIdentifier attribute),
56empty_rxqueue() (udson-
can.connections.BaseConnection method),5
enableRapidPowerShutDown (udson-can.services.ECUReset.ResetType attribute),15
enableRxAndDisableTx (udson-can.services.CommunicationControl.ControlTypeattribute), 13
enableRxAndTx (udson-can.services.CommunicationControl.ControlTypeattribute), 13
EngineIsNotRunning (udsoncan.Response.Code at-tribute), 10
EngineIsRunning (udsoncan.Response.Code attribute),10
EngineRunTimeTooLow (udsoncan.Response.Code at-tribute), 10
Entity (udsoncan.DataIdentifier attribute), 57EraseMemory (udsoncan.Routine attribute), 56EraseMirrorMemoryDTCs (udsoncan.Routine attribute),
56ExceedNumberOfAttempts (udsoncan.Response.Code at-
tribute), 9exception_on_invalid_response, 32exception_on_negative_response, 32exception_on_unexpected_response, 32ExhaustRegulationOrTypeApprovalNumber (udson-
can.DataIdentifier attribute), 56extended_data_size, 33extendedDiagnosticSession (udson-
can.services.DiagnosticSessionControl.Sessionattribute), 14
FFailurePreventsExecutionOfRequestedAction (udson-
can.Response.Code attribute), 9Filesize (class in udsoncan), 53from_payload() (udsoncan.Request class method), 7from_payload() (udsoncan.Response class method), 9
GGeneralProgrammingFailure (udsoncan.Response.Code
attribute), 9GeneralReject (udsoncan.Response.Code attribute), 9GeneralSecurityViolation (udsoncan.Response.Code at-
tribute), 10get_dtc_by_status_mask() (udsoncan.client.Client
method), 39get_dtc_by_status_severity_mask() (udson-
can.client.Client method), 40get_dtc_extended_data_by_dtc_number() (udson-
can.client.Client method), 43get_dtc_fault_counter() (udsoncan.client.Client method),
42get_dtc_severity() (udsoncan.client.Client method), 41get_dtc_snapshot_by_dtc_number() (udson-
can.client.Client method), 42get_dtc_snapshot_by_record_number() (udson-
can.client.Client method), 43get_dtc_snapshot_identification() (udsoncan.client.Client
method), 42get_dtc_with_permanent_status() (udsoncan.client.Client
method), 42get_emission_dtc_by_status_mask() (udson-
can.client.Client method), 39get_first_confirmed_dtc() (udsoncan.client.Client
method), 41
72 Index
udsoncan Documentation, Release 0
get_first_test_failed_dtc() (udsoncan.client.Clientmethod), 41
get_mirrormemory_dtc_by_status_mask() (udson-can.client.Client method), 39
get_mirrormemory_dtc_extended_data_by_dtc_number()(udsoncan.client.Client method), 43
get_mirrormemory_number_of_dtc_by_status_mask()(udsoncan.client.Client method), 40
get_most_recent_confirmed_dtc() (udson-can.client.Client method), 41
get_most_recent_test_failed_dtc() (udson-can.client.Client method), 41
get_number_of_dtc_by_status_mask() (udson-can.client.Client method), 40
get_number_of_dtc_by_status_severity_mask() (udson-can.client.Client method), 40
get_number_of_emission_dtc_by_status_mask() (udson-can.client.Client method), 40
get_payload() (udsoncan.Request method), 7get_payload() (udsoncan.Response method), 9get_routine_result() (udsoncan.client.Client method), 46get_supported_dtc() (udsoncan.client.Client method), 41
HhardReset (udsoncan.services.ECUReset.ResetType at-
tribute), 15
Iignore_all_zero_dtc, 33IncorrectMessageLengthOrInvalidFormat (udson-
can.Response.Code attribute), 9input_output, 32InputOutputControlByIdentifier.ResponseData (class in
udsoncan.services), 16InputOutputControlByIdentifier.ResponseData.control_param_echo
(built-in variable), 16InputOutputControlByIdentifier.ResponseData.decoded_data
(built-in variable), 16InputOutputControlByIdentifier.ResponseData.did_echo
(built-in variable), 16InsufficientProtection (udsoncan.Response.Code at-
tribute), 10interpret_response() (udson-
can.services.AccessTimingParameter classmethod), 11
interpret_response() (udson-can.services.ClearDiagnosticInformationclass method), 12
interpret_response() (udson-can.services.CommunicationControl classmethod), 13
interpret_response() (udson-can.services.ControlDTCSetting class method),13
interpret_response() (udson-can.services.DiagnosticSessionControl classmethod), 14
interpret_response() (udsoncan.services.ECUReset classmethod), 14
interpret_response() (udson-can.services.InputOutputControlByIdentifierclass method), 16
interpret_response() (udsoncan.services.LinkControlclass method), 17
interpret_response() (udson-can.services.ReadDataByIdentifier classmethod), 17
interpret_response() (udson-can.services.ReadDTCInformation classmethod), 20
interpret_response() (udson-can.services.ReadMemoryByAddress classmethod), 23
interpret_response() (udson-can.services.RequestDownload class method),24
interpret_response() (udson-can.services.RequestFileTransfer classmethod), 19
interpret_response() (udson-can.services.RequestTransferExit classmethod), 25
interpret_response() (udsoncan.services.RequestUploadclass method), 25
interpret_response() (udsoncan.services.RoutineControlclass method), 26
interpret_response() (udsoncan.services.SecurityAccessclass method), 27
interpret_response() (udsoncan.services.TesterPresentclass method), 27
interpret_response() (udsoncan.services.TransferDataclass method), 28
interpret_response() (udson-can.services.WriteDataByIdentifier classmethod), 29
interpret_response() (udson-can.services.WriteMemoryByAddress classmethod), 29
InvalidKey (udsoncan.Response.Code attribute), 9InvalidResponseException (class in udson-
can.exceptions), 59io_control() (udsoncan.client.Client method), 38IOMasks (class in udsoncan), 55IOValues (class in udsoncan), 55ISO11992_4 (udsoncan.Dtc.Format attribute), 55ISO14229_1 (udsoncan.Dtc.Format attribute), 55ISO15031_6 (udsoncan.Dtc.Format attribute), 55ISOSAEReserved (udsoncan.Response.Code attribute),
Index 73
udsoncan Documentation, Release 0
10ISOSAEReservedStandardized (udsoncan.DataIdentifier
attribute), 56IsoTPSocketConnection (class in udsoncan.connections),
4
KkeyOffOnReset (udsoncan.services.ECUReset.ResetType
attribute), 15
Llink_control() (udsoncan.client.Client method), 38LinkControl.ControlType (class in udsoncan.services), 17LinkControl.ResponseData (class in udsoncan.services),
17LinkControl.ResponseData.control_type_echo (built-in
variable), 17
Mmake_request() (udson-
can.services.AccessTimingParameter classmethod), 11
make_request() (udson-can.services.ClearDiagnosticInformationclass method), 12
make_request() (udson-can.services.CommunicationControl classmethod), 12
make_request() (udsoncan.services.ControlDTCSettingclass method), 13
make_request() (udson-can.services.DiagnosticSessionControl classmethod), 14
make_request() (udsoncan.services.ECUReset classmethod), 14
make_request() (udson-can.services.InputOutputControlByIdentifierclass method), 15
make_request() (udsoncan.services.LinkControl classmethod), 17
make_request() (udson-can.services.ReadDataByIdentifier classmethod), 17
make_request() (udson-can.services.ReadDTCInformation classmethod), 19
make_request() (udson-can.services.ReadMemoryByAddress classmethod), 23
make_request() (udsoncan.services.RequestDownloadclass method), 24
make_request() (udsoncan.services.RequestFileTransferclass method), 18
make_request() (udsoncan.services.RequestTransferExitclass method), 25
make_request() (udsoncan.services.RequestUpload classmethod), 25
make_request() (udsoncan.services.RoutineControl classmethod), 26
make_request() (udsoncan.services.SecurityAccess classmethod), 26
make_request() (udsoncan.services.TesterPresent classmethod), 27
make_request() (udsoncan.services.TransferData classmethod), 28
make_request() (udson-can.services.WriteDataByIdentifier classmethod), 28
make_request() (udson-can.services.WriteMemoryByAddress classmethod), 29
MemoryLocation (class in udsoncan), 51
NNegativeResponseException (class in udson-
can.exceptions), 59NoResponseFromSubnetComponent (udson-
can.Response.Code attribute), 9
OODXFile (udsoncan.DataIdentifier attribute), 57off (udsoncan.services.ControlDTCSetting.SettingType
attribute), 13on (udsoncan.services.ControlDTCSetting.SettingType
attribute), 13open() (udsoncan.connections.BaseConnection method),
5
Pp2_star_timeout, 34p2_timeout, 34PositiveResponse (udsoncan.Response.Code attribute), 9ProgrammingDate (udsoncan.DataIdentifier attribute), 57programmingSession (udson-
can.services.DiagnosticSessionControl.Sessionattribute), 14
PythonIsoTpConnection (class in udsoncan.connections),4
QQueueConnection (class in udsoncan.connections), 5
Rread_active_timing_parameters() (udsoncan.client.Client
method), 36read_data_by_identifier() (udsoncan.client.Client
method), 39
74 Index
udsoncan Documentation, Release 0
read_dir() (udsoncan.client.Client method), 49read_extended_timing_parameters() (udson-
can.client.Client method), 35read_file() (udsoncan.client.Client method), 49read_memory_by_address() (udsoncan.client.Client
method), 44readCurrentlyActiveTimingParameters (udson-
can.services.AccessTimingParameter.AccessTypeattribute), 12
ReadDataByIdentifier.ResponseData (class in udson-can.services), 18
ReadDataByIdentifier.ResponseData.values (built-in vari-able), 18
ReadDTCInformation.ResponseData (class in udson-can.services), 20
ReadDTCInformation.ResponseData.dtc_count (built-invariable), 20
ReadDTCInformation.ResponseData.dtc_format (built-invariable), 21
ReadDTCInformation.ResponseData.dtcs (built-in vari-able), 20
ReadDTCInformation.ResponseData.extended_data(built-in variable), 21
ReadDTCInformation.ResponseData.status_availability(built-in variable), 21
ReadDTCInformation.ResponseData.subfunction_echo(built-in variable), 20
ReadDTCInformation.Subfunction (class in udson-can.services), 21
readExtendedTimingParameterSet (udson-can.services.AccessTimingParameter.AccessTypeattribute), 12
ReadMemoryByAddress.ResponseData (class in udson-can.services), 24
ReadMemoryByAddress.ResponseData.memory_block(built-in variable), 24
RepairShopCodeOrTesterSerialNumber (udson-can.DataIdentifier attribute), 57
replace_file() (udsoncan.client.Client method), 49reportDTCBySeverityMaskRecord (udson-
can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCByStatusMask (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCExtendedDataRecordByDTCNumber (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCFaultDetectionCounter (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCSnapshotIdentification (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCSnapshotRecordByDTCNumber (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCSnapshotRecordByRecordNumber (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportDTCWithPermanentStatus (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportEmissionsRelatedOBDDTCByStatusMask (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportFirstConfirmedDTC (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportFirstTestFailedDTC (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportMirrorMemoryDTCByStatusMask (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportMirrorMemoryDTCExtendedDataRecordByDTCNumber(udsoncan.services.ReadDTCInformation.Subfunctionattribute), 21
reportMostRecentConfirmedDTC (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportMostRecentTestFailedDTC (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportNumberOfDTCBySeverityMaskRecord (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportNumberOfDTCByStatusMask (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportNumberOfEmissionsRelatedOBDDTCByStatusMask(udsoncan.services.ReadDTCInformation.Subfunctionattribute), 21
reportNumberOfMirrorMemoryDTCByStatusMask (ud-soncan.services.ReadDTCInformation.Subfunctionattribute), 21
reportSeverityInformationOfDTC (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
reportSupportedDTCs (udson-can.services.ReadDTCInformation.Subfunctionattribute), 21
Request (class in udsoncan), 7request_download() (udsoncan.client.Client method), 44request_seed() (udsoncan.client.Client method), 46request_timeout, 34request_transfer_exit() (udsoncan.client.Client method),
45
Index 75
udsoncan Documentation, Release 0
request_upload() (udsoncan.client.Client method), 45RequestCorrectlyReceived_ResponsePending (udson-
can.Response.Code attribute), 9RequestDownload.ResponseData (class in udson-
can.services), 24RequestDownload.ResponseData.max_length (built-in
variable), 24RequestFileTransfer.ResponseData (class in udson-
can.services), 19RequestFileTransfer.ResponseData.dfi (built-in variable),
19RequestFileTransfer.ResponseData.dirinfo_length (built-
in variable), 19RequestFileTransfer.ResponseData.filesize (built-in vari-
able), 19RequestFileTransfer.ResponseData.max_length (built-in
variable), 19RequestFileTransfer.ResponseData.moop_echo (built-in
variable), 19RequestOutOfRange (udsoncan.Response.Code at-
tribute), 9requestRoutineResults (udson-
can.services.RoutineControl.ControlTypeattribute), 26
RequestSeed (udsoncan.services.SecurityAccess.Modeattribute), 27
RequestSequenceError (udsoncan.Response.Code at-tribute), 9
RequestTransferExit.ResponseData (class in udson-can.services), 25
RequestTransferExit.ResponseData.parameter_records(built-in variable), 25
RequestUpload.ResponseData (class in udson-can.services), 25
RequestUpload.ResponseData.max_length (built-in vari-able), 25
RequiredTimeDelayNotExpired (udson-can.Response.Code attribute), 9
reset_default_timing_parameters() (udson-can.client.Client method), 35
Response (class in udsoncan), 8Response.code (built-in variable), 8Response.Code (class in udsoncan), 9Response.code_name (built-in variable), 8Response.data (built-in variable), 8Response.invalid_reason (built-in variable), 8Response.original_payload (built-in variable), 8Response.positive (built-in variable), 8Response.service (built-in variable), 8Response.service_data (built-in variable), 8Response.unexpected (built-in variable), 8Response.valid (built-in variable), 8ResponseTooLong (udsoncan.Response.Code attribute),
9
Routine (class in udsoncan), 56RoutineControl.ControlType (class in udsoncan.services),
26RoutineControl.ResponseData (class in udson-
can.services), 26RoutineControl.ResponseData.control_type_echo (built-
in variable), 26RoutineControl.ResponseData.routine_id_echo (built-in
variable), 26RoutineControl.ResponseData.routine_status_record
(built-in variable), 26RpmTooHigh (udsoncan.Response.Code attribute), 9RpmTooLow (udsoncan.Response.Code attribute), 10
SSAE_J1939_73 (udsoncan.Dtc.Format attribute), 55safetySystemDiagnosticSession (udson-
can.services.DiagnosticSessionControl.Sessionattribute), 14
SecuredLinkNotSupported (udsoncan.Response.Code at-tribute), 10
SecuredModeRequested (udsoncan.Response.Code at-tribute), 10
security_algo, 32security_algo_params, 32SecurityAccess.Mode (class in udsoncan.services), 27SecurityAccess.ResponseData (class in udson-
can.services), 27SecurityAccess.ResponseData.security_level_echo
(built-in variable), 27SecurityAccess.ResponseData.seed (built-in variable), 27SecurityAccessDenied (udsoncan.Response.Code at-
tribute), 9send() (udsoncan.connections.BaseConnection method),
3send_key() (udsoncan.client.Client method), 46SendKey (udsoncan.services.SecurityAccess.Mode at-
tribute), 27server_address_format, 33server_memorysize_format, 33ServiceNotSupported (udsoncan.Response.Code at-
tribute), 9ServiceNotSupportedInActiveSession (udson-
can.Response.Code attribute), 9set_timing_parameters() (udsoncan.client.Client
method), 36setTimingParametersToDefaultValues (udson-
can.services.AccessTimingParameter.AccessTypeattribute), 12
setTimingParametersToGivenValues (udson-can.services.AccessTimingParameter.AccessTypeattribute), 12
ShifterLeverNotInPark (udsoncan.Response.Code at-tribute), 10
76 Index
udsoncan Documentation, Release 0
SocketConnection (class in udsoncan.connections), 4softReset (udsoncan.services.ECUReset.ResetType at-
tribute), 15SomeAlgorithm() (built-in function), 32specific_send() (udsoncan.connections.BaseConnection
method), 5specific_wait_frame() (udson-
can.connections.BaseConnection method),5
standard_version, 34start_routine() (udsoncan.client.Client method), 45startRoutine (udsoncan.services.RoutineControl.ControlType
attribute), 26stop_routine() (udsoncan.client.Client method), 45stopRoutine (udsoncan.services.RoutineControl.ControlType
attribute), 26SubFunctionNotSupported (udsoncan.Response.Code at-
tribute), 9SubFunctionNotSupportedInActiveSession (udson-
can.Response.Code attribute), 9SupportedFunctionalUnits (udsoncan.DataIdentifier at-
tribute), 56SystemNameOrEngineType (udsoncan.DataIdentifier at-
tribute), 57SystemSupplierECUHardwareNumber (udson-
can.DataIdentifier attribute), 56SystemSupplierECUHardwareVersionNumber (udson-
can.DataIdentifier attribute), 56SystemSupplierECUSoftwareNumber (udson-
can.DataIdentifier attribute), 56SystemSupplierECUSoftwareVersionNumber (udson-
can.DataIdentifier attribute), 56SystemSupplierIdentifier (udsoncan.DataIdentifier
attribute), 56
TTemperatureTooHigh (udsoncan.Response.Code at-
tribute), 10TemperatureTooLow (udsoncan.Response.Code at-
tribute), 10TerminationWithSignatureRequested (udson-
can.Response.Code attribute), 10tester_present() (udsoncan.client.Client method), 47TesterPresent.ResponseData (class in udsoncan.services),
28TesterPresent.ResponseData.subfunction_echo (built-in
variable), 28ThrottlePedalTooHigh (udsoncan.Response.Code at-
tribute), 10ThrottlePedalTooLow (udsoncan.Response.Code at-
tribute), 10TimeoutException (class in udsoncan.exceptions), 59tolerate_zero_padding, 33
TorqueConverterClutchLocked (udson-can.Response.Code attribute), 10
transfer_data() (udsoncan.client.Client method), 47TransferData.ResponseData (class in udsoncan.services),
28TransferData.ResponseData.parameter_records (built-in
variable), 28TransferData.ResponseData.sequence_number_echo
(built-in variable), 28TransferDataSuspended (udsoncan.Response.Code
attribute), 9transitionBaudrate (udson-
can.services.LinkControl.ControlType at-tribute), 17
TransmissionRangeNotInGear (udsoncan.Response.Codeattribute), 10
TransmissionRangeNotInNeutral (udson-can.Response.Code attribute), 10
UUnexpectedResponseException (class in udson-
can.exceptions), 59unlock_security_access() (udsoncan.client.Client
method), 46UploadDownloadNotAccepted (udson-
can.Response.Code attribute), 9use_server_timing, 34
VVehicleManufacturerECUHardwareNumber (udson-
can.DataIdentifier attribute), 56VehicleManufacturerECUSoftwareNumber (udson-
can.DataIdentifier attribute), 56VehicleManufacturerECUSoftwareVersionNumber
(udsoncan.DataIdentifier attribute), 56VehicleManufacturerKitAssemblyPartNumber (udson-
can.DataIdentifier attribute), 56VehicleManufacturerSparePartNumber (udson-
can.DataIdentifier attribute), 56VehicleSpeedTooHigh (udsoncan.Response.Code at-
tribute), 10VehicleSpeedTooLow (udsoncan.Response.Code at-
tribute), 10verifyBaudrateTransitionWithFixedBaudrate (udson-
can.services.LinkControl.ControlType at-tribute), 17
verifyBaudrateTransitionWithSpecificBaudrate (ud-soncan.services.LinkControl.ControlTypeattribute), 17
VersionNotSupported (udsoncan.Response.Code at-tribute), 10
VIN (udsoncan.DataIdentifier attribute), 56VoltageTooHigh (udsoncan.Response.Code attribute), 10VoltageTooLow (udsoncan.Response.Code attribute), 10
Index 77
udsoncan Documentation, Release 0
Wwait_frame() (udsoncan.connections.BaseConnection
method), 3write_data_by_identifier() (udsoncan.client.Client
method), 47write_memory_by_address() (udsoncan.client.Client
method), 48WriteDataByIdentifier.ResponseData (class in udson-
can.services), 29WriteDataByIdentifier.ResponseData.did_echo (built-in
variable), 29WriteMemoryByAddress.ResponseData (class in udson-
can.services), 29WriteMemoryByAddress.ResponseData.alfid_echo
(built-in variable), 29WriteMemoryByAddress.ResponseData.memory_location_echo
(built-in variable), 30WrongBlockSequenceCounter (udsoncan.Response.Code
attribute), 9
78 Index