Port DIAGNOSTICS - KWP2000-CAN 🛈¶

SOCKETCAN-HW access to KWP2000 via CAN. Component of the Add-on ecu.test diagnostics

Stimulation¶

This port has no stimulus capabilities.

Properties 🛈¶

Name	Default value	Valid values	Type	Description
Interface	‘1’	[‘<online query>’, ‘<no toollib start>’]	string	Selection of the CAN interface
Bit rate	‘500KB’	[‘10KB’, ‘20KB’, ‘50KB’, ‘83.333KB’, ‘100KB’, ‘125KB’, ‘250KB’, ‘500KB’, ‘666.667KB’, ‘800KB’, ‘1000KB’]	string	Bit rate
Mode	Standard	[Standard, Extended, All]	string	Addressing mode (Standard = 11bit, Extended = 29bit)
Listen only	☐		bool	Controller is running in passive mode. Automatic ACK is disabled, and sending CAN frames is not possible.
Receive error frames	☐		bool	Receive error frames

Jobs 🛈¶

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

ClearDTCs¶

ClearDiagnosticInformation (0x14): Used by the client to clear diagnostic information in the server’s memory.

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

Parameter

Name	Default value	Type	Description
GroupOfDTC	0xFF00	int	Number of the DTC group to be cleared (Default: 0xFF00 = all DTCs, 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

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).

ECUReset¶

ECUReset (0x11): Requests the server to perform an ECU reset effectively based on the content of the ResetMode parameter value.

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

Parameter

Name	Type	Description
ResetMode	int	Mode of the reset (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

Return value

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

InputOutputControlByCommonIdentifier¶

InputOutputControlByCommonIdentifier (0x2F): Used by the client to substitute a value for an input signal, internal ECU function and/or an control output (actuator) of electronic systems referenced by an InputOutputCommonIdentifier of the server.

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

Parameter

Name	Type	Description
ControlOption	ByteStream	Describes how the server has to control its inputs and outputs - ByteStream (optional)
DataIdentifierHighByte	int	Identifier of the data (High Byte)
DataIdentifierLowByte	int	Identifier of the data (Low Byte)
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

InputOutputControlByLocalIdentifier¶

InputOutputControlByLocalIdentifier (0x30): Used by the client to substitute a value for an input signal, internal ECU function and/or control an output (actuator) of an electronic system referenced by an InputOutputLocalIdentifier of the server.

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

Parameter

Name	Type	Description
ControlOption	ByteStream	Describes how the server has to control its inputs and outputs - ByteStream (optional)
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 - DiagResult - or NegativeResponse

OpenDiagSession¶

Opens a KWP2000 diagnostic session which uses ISO-TP. 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	Type	Description
AddressByte		ByteStream	Network target address or address extension (only relevant for extended or mixed addressing) - ByteStream of length 1
AddressMode	0	int	Code of addressing mode - Integer (0: Standard Addressing \| 1: Extended Addressing)
BlockSize	0	int	Number (0 - 255) of consecutive frames that can be received without an intermediate flow control - Integer
DiagTimeoutCanIsoTp	2000	int	Timeout in milliseconds when waiting for responses on diagnostic requests via the ISO-TP protocol - Integer
FillByte		ByteStream	Byte to fill messages (optional) - ByteStream of lenght 1
FlowControlAddressByte		ByteStream	Different network destination address or address extension for FlowControl (only relevant for extended and mixed addressing) - ByteStream of length 1
FlowControlId		int	Message ID for flow control messages (optional) - Hex (optional Integer)
IsExtended	-1	int	Use Extended CAN-ID format? (1=yes / 29 Bits; 0=no / 11 Bits; -1 = Use setting from TBC)
IsExtendedFlowControlId	-1	int	Use Extended CAN ID format (for FlowControlId)? (1=yes/29 bit; 0=no/11 bit;-1 = use same setting as IsExtended)
IsExtendedRequestId	-1	int	Use Extended CAN ID format (for RequestId)? (1=yes/29 bit; 0=no/11 bit;-1 = use same setting as IsExtended)
IsExtendedResponseId	-1	int	Use Extended CAN ID format (for ResponseId)? (1=yes/29 bit; 0=no/11 bit;-1 = use same setting as IsExtended)
RequestId		int	Message ID for ECU requests - Hex (optional Integer)
ResponseId		int	Message ID for ECU responses - Hex (optional Integer)
SeparationTime	0	int	Minimal time separation between successive fragments 0x00..0x7F => 0..127ms, 0x80..0xf0 => reserved, 0xf1..0xf9 => 100.900µs, 0xfa..0xff => reserved - Integer
StartRequest		ByteStream	Diagnostic request to open a session (optional) - ByteStream
StopRequest		ByteStream	Diagnostic request to end a session (optional) - ByteStream
TesterPresentCycleTime		int	Period length (ms) for cyclic tester-available signaling (optional) - Integer
TesterPresentRequest		ByteStream	Diagnostic request for periodic tester-available signaling (optional) - ByteStream

Return value

Name	Available if	Default value	Valid values	Type	Description
SessionHandle				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.

ReadDataByCommonIdentifier¶

ReadDataByCommonIdentifier (0x22): Requests data record values from the server(s) identified by a common RecordCommonIdentifier.

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

Parameter

Name	Type	Description
DataIdentifierHighByte	int	Identifier of the data (High Byte)
DataIdentifierLowByte	int	Identifier of the data (Low Byte)
MaximumNumberOfResponsesToSend	int	Indicates the maximum number of responses (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
TransmissionMode	int	Indication of the transmission mode (optional) 0x01 = single, 0x02 = slow, 0x03 = medium, 0x04 = fast, 0x05 = stop (stops the data transmission for 0x02-0x04)

Return value

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

ReadDataByLocalIdentifier¶

ReadDataByLocalIdentifier (0x21): Requests data record values from the server identified by a RecordLocalIdentifier.

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

Parameter

Name	Type	Description
DataIdentifier	int	Identifier
MaximumNumberOfResponsesToSend	int	Indicates the maximum number of responses
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
TransmissionMode	int	Indication of the transmission mode 0x01 = single, 0x02 = slow, 0x03 = medium, 0x04 = fast, 0x05 = stop (stops the data transmission for 0x02-0x04)

Return value

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

ReadDiagnosticTroubleCodes¶

ReadDiagnosticTroubleCodes (0x13): Used by the client to read diagnostic trouble codes from the server’s memory.

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

Parameter

Name	Default value	Type	Description
GroupOfDTC	0xFF00	int	Number of the DTC group (Default: 0xFF00 = 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

ReadDiagnosticTroubleCodesByStatus¶

ReadDiagnosticTroubleCodesByStatus (0x18): Used by the client to read diagnostic trouble codes by status from the server’s memory.

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

Parameter

Name	Default value	Type	Description
GroupOfDTC	0xFF00	int	Number of the DTC group (Default: 0xFF00 = 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).
StatusOfDTC	0x00	int	Status of the DTCs
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

ReadECUIdentification¶

ReadECUIdentification (0x1A): Requests identification data from the server.

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

Parameter

Name	Type	Description
IdentificationOption	int	Description of the identification data (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

Return value

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

ReadStatusOfDiagnosticTroubleCodes¶

ReadStatusOfDiagnosticTroubleCodes (0x17): Used by the client to read diagnostic trouble codes with their associated status from the server’s memory.

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

Parameter

Name	Default value	Type	Description
GroupOfDTC	0xFF00	int	Number of the DTC group (Default: 0xFF00 = 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

RequestRoutineByLocalIdentifier¶

RequestRoutineResultsByLocalIdentifier (0x33): Used by the client to request results (e.g. exit status information) referenced by a RoutineLocalIdentifier and generated by the routine which was executed in the server’s memory.

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

Parameter

Name	Type	Description
RoutineId	int	ID of the routine
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

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

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’.

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

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

StartRoutineByLocalIdentifier¶

StartRoutineByLocalIdentifier (0x31): Used by the client to start a routine in the server’s memory.

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

Parameter

Name	Type	Description
RoutineEntryOption	int	Routine parameter as ByteStream (optional)
RoutineId	int	ID of the routine
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

StopRoutineByLocalIdentifier¶

StopRoutineByLocalIdentifier (0x32): Used by the client to stop a routine in the server’s memory referenced by a RoutineLocalIdentifier.

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

Parameter

Name	Type	Description
RoutineExitOption	int	Routine parameter as ByteStream (optional)
RoutineId	int	ID of the routine
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

WriteDataByCommonIdentifier¶

WriteDataByCommonIdentifier (0x2E): Used by the client to write RecordValues (data values) to multiple servers with a single request message.

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

Parameter

Name	Type	Description
DataIdentifierHighByte	int	Identifier of the data (High Byte)
DataIdentifierLowByte	int	Identifier of the data (Low Byte)
RecordValue	ByteStream	Data 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 - DiagResult - or NegativeResponse

WriteDataByLocalIdentifier¶

WriteDataByLocalIdentifier (0x3B): Used by the client to write RecordValues (data values) to a server.

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

Parameter

Name	Type	Description
DataIdentifier	int	Identifier
RecordValue	ByteStream	Data 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 - DiagResult - or NegativeResponse