Port DIAGNOSTICS - DOIP 🛈¶

Port for diagnostics based on the DoIP protocol. Part of the Add-on ecu.test diagnostics

Stimulation¶

This port has no stimulus capabilities.

Properties 🛈¶

Name	Default value	Valid values	Type	Description
TLS		[ONLINE]	string	[Optional] Name of the TLS port if the connection is to be protected with TLS. The TLS port must be created on this tool.
Network name			string	Name of the network as defined in SIL-Kit Config yaml.
Controller name			string	Name of the controller as defined in SIL-Kit Config yaml.
MAC address ❲client❳	‘02:00:4C:4F:4F:50’		string	String (format: 02:00:4C:4F:4F:50), ‘default’ if the adapter MAC address should be used
IP version	IPv4	[IPv4, IPv6]	string	Selection of the IP version used
IP address ❲client❳			string	IP address to be used as a client. It must be located in the same subnet as the IP address of the device under test, and must not be equal to the IP address of another participant.
Gateway address			string	IP address, leave empty if no gateway is needed
Subnet mask / prefix length	‘default’		string	For IPv4 addresses a subnet mask or prefix length can be given (format: ‘255.255.255.0’ or ‘24’). ‘default’ uses the default subnet mask of the network class of IP address (client). For IPv6 only a prefix length is accepted and the value ‘default’ is not supported.
VLAN ID	0		int	ID with which VLAN packets should be tagged. (0 -> VLAN is not used)

Jobs 🛈¶

AuthenticationConfiguration¶

Authentication (0x29) AuthenticationConfiguration: Authentication (0x29) authenticationConfiguration (0x08): Indicates the provided authentication configuration of the server.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - AuthenticationConfigurationResult - or NegativeResponse

AuthenticationDeauthenticate¶

Authentication (0x29) DeAuthenticate: Authentication (0x29) deAuthenticate (0x00): Requests to leave the authenticated state

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - AuthenticationDeauthenticateResult - or NegativeResponse

AuthenticationProofOfOwnership¶

Authentication (0x29) ProofOfOwnership: Authentication (0x29) proofOfOwnership (0x03): Verifies the Proof of Ownership from the client.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
EphemeralPublicKeyClient	ByteStream	Ephemeral public key generated by the client for Diffie-Hellman key agreement. ByteStream
ProofOfOwnershipClient	ByteStream	Proof of Ownership of the previous given challenge to be verified by the server. ByteStream
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - AuthenticationProofOfOwnershipResult - or NegativeResponse

AuthenticationVerifyCertificateUnidirectional¶

Authentication (0x29) VerifyCertificateUnidirectional: Authentication (0x29) verifyCertificateUnidirectional (0x01): Initiates authentication by verifying the certificate.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
CertificateClient	ByteStream	The Certificate to verify. ByteStream
ChallengeClient	ByteStream	The challenge contains vehicle manufacturer specific formatted client data (likely containing randomized information) or is a random number. This parameter record is to transmit the challenge to the server. ByteStream
CommunicationConfiguration	int	Configuration information about how to proceed with security in further diagnostic communication after the Authentication. NOTE 1 This information is linked to the presence and the contents of theresponse message data-parameter sessionKeyInfo. The format of this parameter aswell as the creation of the session key(s) and the computation of the proofvalue(s) are up to the vehicle manufacturer choice.
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - AuthenticationVerifyCertificateUnidirectionalResult - or NegativeResponse

CallService¶

Executes a diagnostic service request.

Example: To call the UDS Service Read Data by Identifier (SID=0x22, DID=0xACDC) the Request is ByteStream(“22 AC DC”)

Parameter

Name	Type	Description
Request	ByteStream	Diagnostic service request to be sent (ByteStream)
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DiagResult - or NegativeResponse

CallServiceFunctional¶

Executes a diagnostic service request functionally.

Example: To call the UDS Service Read Data by Identifier (SID=0x22, DID=0xACDC) the Request is ByteStream(“22 AC DC”)

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
Request	ByteStream	Diagnostic service request to be sent. ByteStream
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				object	List of diagnostic results (DiagResult or NegativeResponse).

ClearDTCs¶

ClearDiagnosticInformation (0x14): Clears diagnostic information in one or multiple servers’ memory.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
GroupOfDTC	0xFFFFFF	int	Number of the DTC or DTC group to clear (default: 0xFFFFFF = all DTCs)
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DiagResult - or NegativeResponse

CloseSession¶

Closes a diagnostic session.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).

DiagnosticSessionControl¶

DiagnosticSessionControl (0x10): Enables different diagnostic sessions in the server. Note, that switching the diagnostic session can cause an ecu reset.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
SessionType	int	Diagnostic Session which shall be send. 1: DefaultSession, 2: ProgrammingSession, 3: ExtendedDiagnosticSession, 4: Safety SystemDiagnosticSession
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DiagnosticSessionControlResult - or NegativeResponse

ECUReset¶

ECUReset (0x11): Requests a server reset.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Subfunction	int	Reset-subfunction to be executed
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - ECUResetResult - or NegativeResponse

InputOutputControlByIdentifier¶

InputOutputControlByIdentifier (0x2F): Substitutes a value for an input signal, internal server function and/or forces control to a value for an output (actuator) of an electronic system.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
ControlEnableMaskRecord	ByteStream	Bit mask specifying the parameters to adjust in case of shortTermAdjustment. ISO 14229-1 says to use this only if the DID consists of more than one parameter.
ControlStateRecord	ByteStream	DataRecord for Control type “shortTermAdjustment”
DataIdentifier	int	Identifier
InputOutputControlParameter	int	Type of control according to ISO 14229-1 annex E.1: 0 = returnControlToECU, 1 = resetToDefault, 2 = freezeCurrentState, 3 = shortTermAdjustment
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - InputOutputControlByIdentifierResult - or NegativeResponse

OpenDiagSession¶

Opens a UDS diagnostic session which uses DoIP. If a session with the specified parameters already exists, the handle of the existing session is returned instead of opening a new one.

Parameter

Name	Default value	Valid values	Type	Description
activateRouting	False	[False, True]	bool	Indicates whether the DoIP entity shall forward diagnostic messages to an internal device - Boolean
activationType	ByteStream(“00”)		ByteStream	Routing type in case of routing activation (e..b 0x00 -> default, 0x01 -> WWH-OBD, 0xE0 -> Central Security, further values can be taken from the standard)
diagTimeout	5000		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout
doIpVersion	2		int	Version of the DoIP protocol
eid	ByteStream(“”)		ByteStream	ID of the DoIP entity to which a connection is to be established. If specified, a vehicle identification request is sent to this ID to establish the connection. If not, a general vehicle identification request is sent and a connection is established with the first responding control unit.
listenPort	0		int	Port on which to expect responses from the DoIP entity.
remotePort	13400		int	Destination port on which the DoIP entity receives diagnostic requests
retryDelay			int	Delay in ms between retries. With None, the delay is approx. 300 ms.
retryOnBusy	-1		int	Number of retries in case of error (-1 for infinity)
sourceAddress	ByteStream(“”)		ByteStream	The diagnostic address from which diagnostic messages are sent
startRequest			ByteStream	Diagnostic request to open a session
stopRequest			ByteStream	Diagnostic request to end a session
targetAddress	ByteStream(“”)		ByteStream	The diagnostic address of the DoIP entity(ies). If specified, no vehicle identification request is sent and UDS requests are sent directly to this address.
targetIp			string	IP address of the DoIP entity
testerPresentCycleTime			int	Interval for periodic tester-present signaling (in ms)
testerPresentRequest			ByteStream	Diagnostic request for periodic tester-available signaling

Return value

Name	Available if	Default value	Valid values	Type	Description
SessionId				int	Handle of the diagnostic session

OpenTcfDiagSession¶

Opens a diagnostic session configured in the TCF.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SUT				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF or None. None can only be used if there is only one SUT specified.

ReadDataByIdentifier¶

ReadDataByIdentifier (0x22): Requests data record values from the server identified by one or more dataIdentifiers.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
DataIdentifier	int	Identifier
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DataRecordDiagResult - or NegativeResponse

ReadMemoryByAddress¶

ReadMemoryByAddress (0x23): Allows the client to request memory data from the server via provided starting address and size of memory to be read.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
MemoryAddress	int	Memory address
MemorySize	int	Length of the data to read
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - MemoryDiagResult - or NegativeResponse

RecoverDiagnosticSessions¶

Shutsdown and reopens all open diagnostic sessions of the port the job is called on. Each session will keep its currently active settings.

ReportDTCByStatusMask¶

ReadDTCInformation (0x19) reportDTCByStatusMask (0x02): This parameter specifies that the server shall transmit to the client a list of DTCs and corresponding statuses matching a client defined status mask.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportDTCFaultDetectionCounter¶

ReadDTCInformation (0x19) reportDTCFaultDetectionCounter (0x14): This parameter specifies that the server shall transmit to the client a list of current “prefailed” DTCs which have or have not yet been detected as “pending” or “confirmed”.

The intention of the DTCFaultDetectionCounter is a simple method to identify a growing or intermittent problem which can not be identified/read by the statusOfDTC byte of a particular DTC. The internal implementation of the DTCFaultDetectionCounter shall be vehicle manufacturer specific (e.g. number of bytes, signed versus unsigned, etc.) but the reported value shall be a scaled 1 byte signed value so that +127 (7F16) represents a test result of “failed” and any other non-zero positive value represents a test result of “prefailed”. However DTCs with DTCFaultDetectionCounter with the value +127 shall not be reported according to below stated rule. The DTCFaultDetectionCounter shall be incremented by a vehicle manufacturer specific amount each time the test logic runs and indicates a fail for that test run.

A reported DTCFaultDetectionCounter value greater than zero and less than +127 (i.e. 0116 to 7E16) indicates that the DTC enable criteria was met and that a non completed test result prefailed at least in one condition or threshold.

Only DTCs with DTCFaultDetectionCounters with a non-zero positive value less than +127 (7F16) shall be reported.

The DTCFaultDetectionCounter shall be decremented by a vehicle manufacturer specific amount each time the test logic runs and indicates a pass for that test run. If the DTCFaultDetectionCounter is decremented to zero or below the DTC shall no longer be reported in the positive response message. The value of the DTCFaultDetectionCounter shall not be maintained between operation cycles.

If a ClearDiagnosticInformation service request is received the DTCFaultDetectionCounter value shall be reset to zero for all DTCs. Additional reset conditions shall be defined by the vehicle manufacturer.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCFaultCounterDiagResult - or NegativeResponse

ReportDTCSnapshotIdentification¶

ReadDTCInformation (0x19) reportDTCSnapshotIdentification (0x03): This parameter specifies that the server shall transmit to the client all DTCSnapshot data record identifications [DTC number(s) and DTCSnapshot record number(s)].

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCSnapshotIdentificationDiagResult - or NegativeResponse

ReportDTCSnapshotRecordByDTCNumber¶

ReadDTCInformation (0x19) reportDTCSnapshotRecordByDTCNumber (0x04): This parameter specifies that the server shall transmit to the client the DTCSnapshot record(s) associated with a client defined DTC number and DTCSnapshot record number (FF16 for all records).

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Valid values	Type	Description
DoExtendedInterpretation	False	[False, True]	bool	True if the snapshot data is to be returned in interpreted form, otherwise False. The interpretation is performed by additional ReadDataByIdentifier calls (0x22). Only works with fixed length Data Identifier values. Default: False
DTCMaskRecord			object	DTC identifier: 3-Byte value containing DTCHighByte, DTCMiddleByte and DTCLowByte, which together represent the unique identification number for the diagnostic trouble code that shall be reported. E.g. 0x123456 or SAE J2012 P-code: “P1234-56”
DTCSnapshotRecordNumber			int	DTC snapshot record number: a particular occurrence of the specified DTC for which DTC snapshot record data shall be retrieved. Specify 0xFF if all recorded snapshots shall be reported.
SessionId			object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout			int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCSnapshotRecordDiagResult - or NegativeResponse

ReportDTCWithPermanentStatus¶

ReadDTCInformation (0x19) reportDTCWithPermanentStatus (0x15): This parameter specifies that the server shall transmit to the client a list of DTCs with “permanent DTC” status.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportEmissionsOBDDTCByStatusMask¶

ReadDTCInformation (0x19) reportEmissionsOBDDTCByStatusMask (0x13): This parameter specifies that the server shall transmit to the client a list of emissions-related OBD DTCs and corresponding statuses matching a client defined status mask. The list of OBD DTCs reported shall only be those which are required to be compatible with emissions-related legal requirements.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportFirstConfirmedDTC¶

ReadDTCInformation (0x19) reportFirstConfirmedDTC (0x0C): This parameter specifies that the server shall transmit to the client the first confirmed DTC to be detected by the server since the last clear of diagnostic information.

The information reported via this SubFunction parameter shall be independent of the aging process of confirmed DTCs (e.g. if a DTC ages such that its status is allowed to be reset, the first confirmed DTC record shall continue to be preserved by the server, regardless of any other DTCs that become confirmed afterwards).

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportFirstTestFailedDTC¶

ReadDTCInformation (0x19) reportFirstTestFailedDTC (0x0B): This parameter specifies that the server shall transmit to the client the first failed DTC to be detected by the server since the last clear of diagnostic information. Note that the information reported via this SubFunction parameter shall be independent of whether or not the DTC was confirmed or aged.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportMirrorMemoryDTCByStatusMask¶

ReadDTCInformation (0x19) reportMirrorMemoryDTCByStatusMask (0x0F): This parameter specifies that the server shall transmit to the client a list of DTCs out of the DTC mirror memory and corresponding statuses matching a client defined status mask.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportMostRecentConfirmedDTC¶

ReadDTCInformation (0x19) reportMostRecentConfirmedDTC (0x0E): This parameter specifies that the server shall transmit to the client the most recent confirmed DTC to be detected by the server since the last clear of diagnostic information.

Note that the information reported via this SubFunction parameter shall be independent of the aging process of confirmed DTCs (e.g. if a DTC ages such that its status is allowed to be reset, the first confirmed DTC record shall continue to be preserved by the server assuming no other DTCs become confirmed afterwards).

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportMostRecentTestFailedDTC¶

ReadDTCInformation (0x19) reportMostRecentTestFailedDTC (0x0D): This parameter specifies that the server shall transmit to the client the most recent failed DTC to be detected by the server since the last clear of diagnostic information. Note that the information reported via this SubFunction parameter shall be independent of whether or not the DTC was confirmed or aged.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportNumberOfDTCByStatusMask¶

ReadDTCInformation (0x19) reportNumberOfDTCByStatusMask (0x01): This parameter specifies that the server shall transmit to the client the number of DTCs matching a client defined status mask.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCNumberDiagResult - or NegativeResponse

ReportNumberOfEmissionsOBDDTCByStatusMask¶

ReadDTCInformation (0x19) reportNumberOfEmissionsOBDDTCByStatusMask (0x12): This parameter specifies that the server shall transmit to the client the number of emissions-related OBD DTCs matching a client defined status mask. The number of OBD DTCs reported shall only be those which are required to be compatible with emissions-related legal requirements.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCNumberDiagResult - or NegativeResponse

ReportNumberOfMirrorMemoryDTCByStatusMask¶

ReadDTCInformation (0x19) reportNumberOfMirrorMemoryDTCByStatusMask (0x11): This parameter specifies that the server shall transmit to the client the number of DTCs out of mirror memory matching a client defined status mask.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCNumberDiagResult - or NegativeResponse

ReportSupportedDTCs¶

ReadDTCInformation (0x19) reportSupportedDTC (0x0A): This parameter specifies that the server shall transmit to the client a list of all DTCs and corresponding statuses supported within the server.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DTCListDiagResult - or NegativeResponse

ReportUserDefMemoryDTCByStatusMask¶

ReadDTCInformation (0x19) reportUserDefMemoryDTCByStatusMask (0x17): This parameter specifies that the server shall transmit to the client a list of DTCs out of the user defined DTC memory and corresponding statuses matching a client defined status mask.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
MemorySelection		int	User-defined DTC memory: Only DTCs stored in the selected memory will be retrieved.
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
StatusMask	0xFF	int	Status mask: Only DTCs having at least one of the status bits specified in the mask set are queried. (default: 0xFF = any status)
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - UserDTCListDiagResult - or NegativeResponse

RequestDownload¶

RequestDownload (0x34): Used to initiate a data transfer from the client to the server (download).

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
DataFormatIdentifier	00	ByteStream	Specifies the compression (higher nibble) and encrypting (lower nibble) method used on the data to be sent. Value 0 indicates no compression or encryption. All other values are manufacturer specific. ByteStream
MemoryAddress		ByteStream	Starting address of the server memory the data is to be written to. ByteStream
MemorySize		ByteStream	The size of the data to be sent by the TransferData job. In case compression is used on the data, it is manufacturer specific whether this parameter refers to the size of the compressed or uncompressed data. ByteStream
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout		int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - RequestDownloadResult - or NegativeResponse

RequestSeed¶

SecurityAccess (0x27) requestSeed: Requests a seed with the level of security defined by the vehicle manufacturer.

This job is part of the Add-on ecu.test diagnostics.

Note: The job is no longer supported. It can be replaced by the job ‘SecurityAccessRequestSeed’.

Parameter

Name	Type	Description
DataRecord	ByteStream	DataRecord: optional, to send data in the request. ByteStream
SecurityLevel	int	Security level: odd number between 0x01 and 0x7D
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - SecurityAccessDiagResult - or NegativeResponse

RequestTransferExit¶

RequestTransferExit (0x37): Used by the client to terminate a data transfer between client and server (upload or download).

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout				int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DiagResult - or NegativeResponse

RestartDefaultSession¶

Restarts the diagnostic session set up in the test configuration.

This job is part of the Add-on ecu.test diagnostics.

Note: The job is no longer supported. It can be replaced by the combination of the jobs ‘CloseSession’ and ‘OpenTcfDiagSession’.

RoutineControl¶

RoutineControl (0x31): The RoutineControl service is used by the client to execute a defined sequence of steps and obtain any relevant results.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Valid values	Type	Description
hasRoutineInfo		[False, True]	bool	optional
RoutineId			int	ID of the routine
RoutineOptionRecord			ByteStream	Routine parameters (optional) ByteStream
SessionId			object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Subfunction	1		int	Subfunction: Start (0x01), Stop (0x02), Request (0x03)
Timeout			int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - RoutineDiagResult - or NegativeResponse

SecurityAccessRequestSeed¶

SecurityAccess (0x27) requestSeed: Requests a seed with the level of security defined by the vehicle manufacturer. Allows additionally to specify a Seed&Key library to calculate the key corresponding to the gained seed.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
Options	object	The option string to be passed to the Seed&Key library (optional - str). If Options is None, the library function GenerateKeyEx() is called. If Options is a string, the library function GenerateKeyExOpt() is called, this is even the case for empty strings.
SecurityAccessDataRecord	ByteStream	Additional data to be transmitted when requesting the seed information (optional). ByteStream
SecurityLevel	int	Security level to unlock, odd number between 0x01 and 0x7D
SeedAndKeyLibraryPath	string	Path to a Seed&Key library that shall be used to compute the key corresponding to the gained seed (optional)
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout
Variant	string	The ECU variant`s qualifier to be passed to the Seed&Key library (optional)

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - SecurityAccessDiagResult - or NegativeResponse

SecurityAccessSendKey¶

SecurityAccess (0x27) sendKey: Sends a key with the level of security defined by the vehicle manufacturer.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
SecurityKey	ByteStream	Key to unlock the required security level. If a Seed&Key library is used by the SecurityAccessRequestSeed job, the computed key is returned in the result of the SecurityAccessRequestSeed job. Otherwise the key has to be calculated beforehand corresponding to the seed returned in the result of the SecurityAccessRequestSeed job. ByteStream
SecurityLevel	int	Security level to unlock, even number between 0x02 and 0x7E (= SecurityLevel from SecurityAccessRequestSeed + 1)
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - DiagResult - or NegativeResponse

SendKey¶

SecurityAccess (0x27) sendKey: Sends a key with the level of security defined by the vehicle manufacturer.

This job is part of the Add-on ecu.test diagnostics.

Note: The job is no longer supported. It can be replaced by the job ‘SecurityAccessSendKey’.

Parameter

Name	Type	Description
SecurityKey	ByteStream	Key derived from the seed as ByteStream. ByteStream
SecurityLevel	int	Security Level: even number between 0x02 and 0x7E (= SecurityLevel from RequestSeed + 1)
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - SecurityAccessSuccessDiagResult - or NegativeResponse

SetDiagTimeout¶

Sets the timeout for the diagnostic session. Note: When setting the timeout while a diagnostic request is in progress, the timing behaviour can be unpredictable.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
DiagTimeout				int	Timeout (ms). If this value is set to None, the timeout will be reset to the initial value when the session was opened.
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).

SetTargetAddress¶

Changes the diagnostic target address of the given DoIP session

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Available if	Default value	Valid values	Type	Description
SessionId				object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
targetAddress		ByteStream(“”)		ByteStream	The diagnostic address of the DoIP entity(ies). If specified, no vehicle identification request is sent and UDS requests are sent directly to this address.

SetTesterPresent¶

Changes the parameters specified in the test configuration for cyclically sent TesterPresent messages.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Default value	Type	Description
SessionId		object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
TesterPresentCycleTime		int	Period length (ms) for the cyclically sent request. If 0 is specified as period length, cyclic transmission gets deactivated
TesterPresentRequest	ByteStream()	ByteStream	The payload of the cyclically sent message

TransferData¶

TransferData (0x36): Used by the client to transfer data either from the client to the server (download) or from the server to the client (upload).

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
BlockLength	int	Maximum amount of data which can be transferred within one block. Does include the service ID and the sequence counter of the respective block. - int
FlashData	ByteStream	Total data to be transferred. The job automatically splits the data based on the value specified in the block length parameter. ByteStream
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - TransferDataResult

WriteDataByIdentifier¶

WriteDataByIdentifier (0x2E): Allows the client to write information into the server at an internal location specified by the provided data identifier.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
DataIdentifier	int	Identifier
DataRecord	ByteStream	Data record to be written ByteStream
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - WriteDataByIdentifierResult - or NegativeResponse

WriteMemoryByAddress¶

WriteMemoryByAddress (0x3D): The WriteMemoryByAddress service allows the client to write information into the server at one or more contiguous memory locations.

This job is part of the Add-on ecu.test diagnostics.

Parameter

Name	Type	Description
DataRecord	ByteStream	Data to be written ByteStream
MemoryAddress	int	Start address for the data to write
MemorySize	int	Number of bytes to be written
SessionId	object	Handle of the diagnostic session. This can be either the name of the SUT specified in the TCF, the handle returned by the OpenDiagSession job or None (can only be used if there is one SUT specified).
Timeout	int	Timeout (ms) after the diagnostic system aborts waiting for a diagnostic response (optional) - Must be greater than the send confirmation timeout

Return value

Name	Available if	Default value	Valid values	Type	Description
Return				DiagResult	Result of diagnostic service call - WriteMemoryByAddressResult - or NegativeResponse