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 another property named service_data. This service_data property will be an instance of the ResponseData class 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))

AccessTimingParameter (0x83)

classmethod AccessTimingParameter.make_request(access_type, timing_param_record=None)[source]

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 only when access_type=``AccessType.setTimingParametersToGivenValues`` (4)

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod AccessTimingParameter.interpret_response(response)[source]

Populates the response service_data property with an instance of AccessTimingParameter.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class AccessTimingParameter.ResponseData(access_type_echo, timing_param_record)[source]
Parameters:

  • access_type_echo (int) –

  • timing_param_record (bytes) –

access_type_echo

Request subfunction echoed back by the server

timing_param_record

Additional data associated with the response.

class AccessTimingParameter.AccessType[source]

AccessTimingParameter defined subfunctions

readExtendedTimingParameterSet = 1
setTimingParametersToDefaultValues = 2
readCurrentlyActiveTimingParameters = 3
setTimingParametersToGivenValues = 4

ClearDiagnosticInformation (0x14)

classmethod ClearDiagnosticInformation.make_request(group=16777215, memory_selection=None, standard_version=2020)[source]

Generates a request for ClearDiagnosticInformation

Parameters:

  • group (int) – DTC mask ranging from 0 to 0xFFFFFF. 0xFFFFFF means all DTCs

  • memory_selection (int) – Number identifying the respective DTC memory. This value is user defined and introduced in 2013 version of ISO-14229-1. Only added to the request payload when different from None. Default : None

  • standard_version (int) – The version of the ISO-14229 (the year). eg. 2006, 2013, 2020

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod ClearDiagnosticInformation.interpret_response(response)[source]

Populates the response service_data property with an instance of ClearDiagnosticInformation.ResponseData

Parameters:

response (Response) – The received response to interpret

Return type:

InterpretedResponse

Note

This service have empty response data

Note

This service does not have subfunctions

CommunicationControl (0x28)

classmethod CommunicationControl.make_request(control_type, communication_type, node_id=None, standard_version=2020)[source]

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

  • node_id (int) – DTC memory identifier. This value is user defined and introduced in 2013 version of ISO-14229-1. Possible and required only when control_type is enableRxAndDisableTxWithEnhancedAddressInformation or enableRxAndTxWithEnhancedAddressInformation Default : None

  • standard_version (int) – The version of the ISO-14229 (the year). eg. 2006, 2013, 2020

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod CommunicationControl.interpret_response(response)[source]

Populates the response service_data property with an instance of CommunicationControl.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class CommunicationControl.ResponseData(control_type_echo)[source]
Parameters:

control_type_echo (int) –

control_type_echo

Request subfunction echoed back by the server

class CommunicationControl.ControlType[source]

CommunicationControl defined subfunctions

enableRxAndTx = 0
enableRxAndDisableTx = 1
disableRxAndEnableTx = 2
disableRxAndTx = 3
enableRxAndDisableTxWithEnhancedAddressInformation = 4
enableRxAndTxWithEnhancedAddressInformation = 5

ControlDTCSetting (0x85)

classmethod ControlDTCSetting.make_request(setting_type, data=None)[source]

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 DTCSettingControlOptionRecord

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod ControlDTCSetting.interpret_response(response)[source]

Populates the response service_data property with an instance of ControlDTCSetting.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class ControlDTCSetting.ResponseData(setting_type_echo)[source]
Parameters:

setting_type_echo (int) –

setting_type_echo

Request subfunction echoed back by the server

class ControlDTCSetting.SettingType[source]

ControlDTCSetting defined subfunctions

on = 1
off = 2

DiagnosticSessionControl (0x10)

classmethod DiagnosticSessionControl.make_request(session)[source]

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

Return type:

Request

classmethod DiagnosticSessionControl.interpret_response(response, standard_version=2020)[source]

Populates the response service_data property with an instance of DiagnosticSessionControl.ResponseData

Parameters:

  • response (Response) – The received response to interpret

  • standard_version (int) – The version of the ISO-14229 (the year). eg. 2006, 2013, 2020

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class DiagnosticSessionControl.ResponseData(session_echo, session_param_records, p2_server_max=None, p2_star_server_max=None)[source]
Parameters:

  • session_echo (int) –

  • session_param_records (bytes) –

  • p2_server_max (float | None) –

  • p2_star_server_max (float | None) –

session_echo

Request subfunction echoed back by the server

session_param_records

Raw session parameter records. Data given by the server. For 2006 configurations, this data can is manufacturer specific. For 2013 version and above, this data correspond to P2 and P2* timing requirement.

p2_server_max

Default P2 max timing supported by the server for the activated diagnostic session. Applicable for 2013 version and above. Value in seconds.

p2_star_server_max

Default P2* (NRC 0x78) max timing supported by the server for the activated diagnostic session. Applicable for 2013 version and above. Value in seconds

class DiagnosticSessionControl.Session[source]

DiagnosticSessionControl defined subfunctions

defaultSession = 1
programmingSession = 2
extendedDiagnosticSession = 3
safetySystemDiagnosticSession = 4

ECUReset (0x11)

classmethod ECUReset.make_request(reset_type)[source]

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

Return type:

Request

classmethod ECUReset.interpret_response(response)[source]

Populates the response service_data property with an instance of ECUReset.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class ECUReset.ResponseData(reset_type_echo, powerdown_time=None)[source]
Parameters:

  • reset_type_echo (int) –

  • powerdown_time (int | None) –

reset_type_echo

Request subfunction echoed back by the server

powerdown_time

Amount of time, in seconds, before the power down sequence is executed. Should be provided only when reset type is enableRapidPowerShutDown

class ECUReset.ResetType[source]

ECUReset defined subfunctions

hardReset = 1
keyOffOnReset = 2
softReset = 3
enableRapidPowerShutDown = 4
disableRapidPowerShutDown = 5

InputOutputControlByIdentifier (0x2F)

classmethod InputOutputControlByIdentifier.make_request(did, control_param=None, values=None, masks=None, ioconfig=None)[source]

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 in InputOutputControlByIdentifier.ControlParam

  • values (list, dict, IOValues) –

    Optional values to send to the server. This parameter will be 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 mask definition 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.

  • ioconfig (dict[int] = DidCodec, dict) – Definition of DID codecs. Dictionary mapping a DID (int) to a valid DidCodec class or pack/unpack string. It is possible to use composite DidCodec 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

Return type:

Request

classmethod InputOutputControlByIdentifier.interpret_response(response, control_param=None, tolerate_zero_padding=True, ioconfig=None)[source]

Populates the response service_data property with an instance of InputOutputControlByIdentifier.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 avoiding raising false InvalidResponseException.

  • ioconfig (dict[int] = DidCodec, dict) – Definition of DID codecs. Dictionary mapping a DID (int) to a valid DidCodec class or pack/unpack string. It is possible to use composite DidCodec 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 not match codec length.

Return type:

InterpretedResponse

class InputOutputControlByIdentifier.ResponseData(did_echo, control_param_echo=None, decoded_data=None)[source]
Parameters:

  • did_echo (int) –

  • control_param_echo (int | None) –

  • decoded_data (Any | None) –

did_echo

DID echoed back by the server

control_param_echo

control_param echoed back by the server

decoded_data

Value processed by the DidCodec.decode() method

Note

This service does not have subfunctions

Note

Example available here

LinkControl (0x87)

classmethod LinkControl.make_request(control_type, baudrate=None)[source]

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_type is either verifyBaudrateTransitionWithFixedBaudrate (1) or verifyBaudrateTransitionWithSpecificBaudrate (2)

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod LinkControl.interpret_response(response)[source]

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

Return type:

InterpretedResponse

class LinkControl.ResponseData(control_type_echo)[source]
Parameters:

control_type_echo (int) –

control_type_echo

Request subfunction echoed back by the server

class LinkControl.ControlType[source]

LinkControl defined subfunctions

verifyBaudrateTransitionWithFixedBaudrate = 1
verifyBaudrateTransitionWithSpecificBaudrate = 2
transitionBaudrate = 3

ReadDataByIdentifier (0x22)

classmethod ReadDataByIdentifier.make_request(didlist, didconfig)[source]

Generates a request for ReadDataByIdentifier

Parameters:

  • didlist (list[int]) – List of data identifier to read.

  • didconfig (dict[int] = DidCodec) – Optional definition of DID codecs for validation. Dictionary mapping a DID (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

Return type:

Request

classmethod ReadDataByIdentifier.interpret_response(response, didlist, didconfig, tolerate_zero_padding=True)[source]

Populates the response service_data property with an instance of ReadDataByIdentifier.ResponseData

Parameters:

  • 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 a DID (int) to a valid DidCodec class or pack/unpack string

  • tolerate_zero_padding (bool) – Ignore trailing zeros in the response data avoiding raising 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 in didconfig.

  • InvalidResponseException – If response data is incomplete or if DID data does not match codec length.

Return type:

InterpretedResponse

class ReadDataByIdentifier.ResponseData(values)[source]
Parameters:

values (Dict[int, Any]) –

values

Dictionary 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.unpack
   0x2222 : MyCustomDidCodec, # Inherits the udsoncan.DidCodec,
   0x3333 : MyCustomDidCodec(param1='hello') # Instance can also be provided
   0x4444 : dict(key1='val1', key2='val2', codec=MyCustomDidCodec} # If dict is given, a key named "codec" will be searched for
}

RequestFileTransfer (0x38)

classmethod RequestFileTransfer.make_request(moop, path, dfi=None, filesize=None)[source]

Generates a request for RequestFileTransfer

Parameters:

  • moop (int) – Mode of operation. Can be AddFile(1), DeleteFile(2), ReplaceFile(3), ReadFile(4), ReadDir(5), ResumeFile(6). See RequestFileTransfer.ModeOfOperation

  • path (string) – String representing the path to the target file or directory.

  • dfi (DataFormatIdentifier) – DataFormatIdentifier defining the compression and encryption scheme of the data. If not specified, the default value of 00 will be used, specifying no encryption and no compression. This value is only used when ModeOfOperation is : AddFile, ReplaceFile, ReadFile, ResumeFile

  • filesize (Filesize or int) – The filesize of the file to write when ModeOfOperation is AddFile, ReplaceFile or ResumeFile. If filesize is an object of type Filesize, the uncompressed size and compressed size will be encoded on the minimum amount of bytes necessary, unless a width is explicitly defined. If no compressed size is given or filesize is an int, then the compressed size will be set equal to the uncompressed size or the integer value given as specified by ISO-14229

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod RequestFileTransfer.interpret_response(response, tolerate_zero_padding=True)[source]

Populates the response service_data property with an instance of RequestFileTransfer.ResponseData

Parameters:

  • response (Response) – The received response to interpret

  • tolerate_zero_padding (bool) –

Raises:

  • InvalidResponseException – If length of response.data is too short or payload does not respect ISO-14229 specifications

  • NotImplementedError – If the MaxNumberOfBlock or fileSizeUncompressedOrDirInfoLength value is encoded over more than 8 bytes.

Return type:

InterpretedResponse

class RequestFileTransfer.ResponseData(moop_echo, max_length=None, dfi=None, filesize=None, dirinfo_length=None, fileposition=None)[source]
Parameters:

  • moop_echo (int) –

  • max_length (int | None) –

  • dfi (DataFormatIdentifier | None) –

  • filesize (Filesize | None) –

  • dirinfo_length (int | None) –

  • fileposition (int | None) –

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 should be 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 response for 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

fileposition(int)

Defines the position of the at which the tester will resume downloading after an initial download is suspended.

Only set when performing a ResumeFile request

Note

This service does not have subfunctions

ReadDTCInformation (0x19)

classmethod ReadDTCInformation.make_request(subfunction, status_mask=None, severity_mask=None, dtc=None, snapshot_record_number=None, extended_data_record_number=None, memory_selection=None, standard_version=2020)[source]

Generates a request for ReadDTCInformation. Each subfunction uses a subset of parameters.

Parameters:

  • subfunction (int) – The service subfunction. Values are defined in ReadDTCInformation.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

  • memory_selection (int) – Memory selection for user defined memory DTC

  • standard_version (int) –

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod ReadDTCInformation.interpret_response(response, subfunction, extended_data_size=None, tolerate_zero_padding=True, ignore_all_zero_dtc=True, dtc_snapshot_did_size=2, didconfig=None, standard_version=2020)[source]

Populates the response service_data property with an instance of ReadDTCInformation.ResponseData

Parameters:

  • response (Response) – The received response to interpret

  • subfunction (int) – The service subfunction. Values are defined in ReadDTCInformation.Subfunction

  • extended_data_size (int or dict[int, int] to specify a size per extended data ID) – Extended data size to expect. Extended data is implementation specific, therefore, size is not standardized

  • tolerate_zero_padding (bool) – Ignore trailing zeros in the response data avoiding raising false InvalidResponseException.

  • ignore_all_zero_dtc (bool) – Discard any DTC entries that have an ID of 0. Avoid reading extra DTCs when using a transport protocol using zero padding.

  • dtc_snapshot_did_size (int) – Number of bytes to encode the data identifier number. Other services such as ReadDataByIdentifier encode DID over 2 bytes. UDS standard does not define the size of the snapshot DID, therefore, it must be supplied.

  • didconfig (dict[int] = DidCodec) – Definition of DID codecs. Dictionary mapping a DID (int) to a valid DidCodec class or pack/unpack string

  • standard_version (int) –

Raises:

  • InvalidResponseException – If response length is wrong or does not match DID configuration

  • ValueError – If parameters are out of range, missing or wrong types

  • ConfigError – If the server returns a snapshot DID not defined in didconfig

Return type:

InterpretedResponse

class ReadDTCInformation.ResponseData(subfunction_echo, dtcs=None, dtc_count=None, dtc_format=None, status_availability=None, extended_data=[], memory_selection_echo=None)[source]
Parameters:

  • subfunction_echo (int) –

  • dtcs (List[Dtc]) –

  • dtc_count (int | None) –

  • dtc_format (int | None) –

  • status_availability (Status | None) –

  • extended_data (List[bytes] | None) –

  • memory_selection_echo (int | None) –

subfunction_echo

Subfunction echoed back by the server

dtcs

DTC instances and their status read from the server.

dtc_count

Number of DTC read or available

dtc_format

Integer indicating the format of the DTC. See DTC.Format

status_availability

Dtc.Status indicating which status the server supports

extended_data

List of bytes containing the DTC extended data

memory_selection_echo

Echo of the memory selection byte

class ReadDTCInformation.Subfunction[source]
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
reportDTCExtDataRecordByRecordNumber = 22
reportUserDefMemoryDTCByStatusMask = 23
reportUserDefMemoryDTCSnapshotRecordByDTCNumber = 24
reportUserDefMemoryDTCExtDataRecordByDTCNumber = 25
reportSupportedDTCExtDataRecord = 26
reportWWHOBDDTCByMaskRecord = 66
reportWWHOBDDTCWithPermanentStatus = 85
reportDTCInformationByDTCReadinessGroupIdentifier = 86

make_request() parameters per subfunction

make_request() parameters per subfunction

subfunction

status_mask

severity_mask

dtc

snapshot_record_number

extended_data_record_number

reportNumberOfDTCByStatusMask

Yes

reportDTCByStatusMask

Yes

reportDTCSnapshotIdentification

reportDTCSnapshotRecordByDTCNumber

Yes

Yes

reportDTCSnapshotRecordByRecordNumber

Yes

reportDTCExtendedDataRecordByDTCNumber

Yes

Yes

reportNumberOfDTCBySeverityMaskRecord

Yes

Yes

reportDTCBySeverityMaskRecord

Yes

Yes

reportSeverityInformationOfDTC

Yes

Yes

reportSupportedDTCs

reportFirstTestFailedDTC

reportFirstConfirmedDTC

reportMostRecentTestFailedDTC

reportMostRecentConfirmedDTC

reportMirrorMemoryDTCByStatusMask

Yes

reportMirrorMemoryDTCExtendedDataRecordByDTCNumber

Yes

Yes

reportNumberOfMirrorMemoryDTCByStatusMask

Yes

reportNumberOfEmissionsRelatedOBDDTCByStatusMask

Yes

reportEmissionsRelatedOBDDTCByStatusMask

Yes

reportDTCFaultDetectionCounter

reportDTCWithPermanentStatus

interpret_response() parameters per subfunction

interpret_response() parameters per subfunction

subfunction

extended_data_size

tolerate_zero_padding

ignore_all_zero_dtc

dtc_snapshot_did_size

didconfig

reportNumberOfDTCByStatusMask

reportDTCByStatusMask

Yes

Yes

reportDTCSnapshotIdentification

Yes

Yes

reportDTCSnapshotRecordByDTCNumber

Yes

Yes

Yes

reportDTCSnapshotRecordByRecordNumber

Yes

Yes

Yes

reportDTCExtendedDataRecordByDTCNumber

Yes

Yes

reportNumberOfDTCBySeverityMaskRecord

reportDTCBySeverityMaskRecord

Yes

Yes

reportSeverityInformationOfDTC

Yes

Yes

reportSupportedDTCs

Yes

Yes

reportFirstTestFailedDTC

Yes

Yes

reportFirstConfirmedDTC

Yes

Yes

reportMostRecentTestFailedDTC

Yes

Yes

reportMostRecentConfirmedDTC

Yes

Yes

reportMirrorMemoryDTCByStatusMask

Yes

Yes

reportMirrorMemoryDTCExtendedDataRecordByDTCNumber

Yes

Yes

reportNumberOfMirrorMemoryDTCByStatusMask

reportNumberOfEmissionsRelatedOBDDTCByStatusMask

reportEmissionsRelatedOBDDTCByStatusMask

Yes

Yes

reportDTCFaultDetectionCounter

Yes

Yes

reportDTCWithPermanentStatus

Yes

Yes

ReadMemoryByAddress (0x23)

classmethod ReadMemoryByAddress.make_request(memory_location)[source]

Generates a request for ReadMemoryByAddress

Parameters:

memory_location (MemoryLocation) – The address and the size of the memory block to read.

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod ReadMemoryByAddress.interpret_response(response)[source]

Populates the response service_data property with an instance of ReadMemoryByAddress.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class ReadMemoryByAddress.ResponseData(memory_block)[source]
Parameters:

memory_block (bytes) –

memory_block

bytes object reflecting the content of the read memory

Note

This service does not have subfunctions

RequestDownload (0x34)

classmethod RequestDownload.make_request(memory_location, dfi=None)[source]

Generates a request for RequestDownload

Parameters:

  • memory_location (MemoryLocation) – The address and the size of the memory block to be written.

  • dfi (DataFormatIdentifier) – Optional DataFormatIdentifier defining the compression and encryption scheme of the data. If not specified, the default value of 00 will be used, specifying no encryption and no compression

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod RequestDownload.interpret_response(response)[source]

Populates the response service_data property with an instance of RequestDownload.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 over more than 8 bytes.

Return type:

InterpretedResponse

class RequestDownload.ResponseData(max_length)[source]
Parameters:

max_length (int) –

max_length

(int) Maximum number of data blocks to write

Note

This service does not have subfunctions

RequestTransferExit (0x37)

classmethod RequestTransferExit.make_request(data=None)[source]

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

Return type:

Request

classmethod RequestTransferExit.interpret_response(response)[source]

Populates the response service_data property with an instance of RequestTransferExit.ResponseData

Parameters:

response (Response) – The received response to interpret

Return type:

InterpretedResponse

class RequestTransferExit.ResponseData(parameter_records)[source]
Parameters:

parameter_records (bytes) –

parameter_records

bytes object containing optional data provided by the server

Note

This service does not have subfunctions

RequestUpload (0x35)

classmethod RequestUpload.make_request(memory_location, dfi=None)[source]

Generates a request for RequestUpload

Parameters:

  • memory_location (MemoryLocation) – The address and the size of the memory block to be read.

  • dfi (DataFormatIdentifier) – Optional dataFormatIdentifier defining the compression and encryption scheme of the data. If not specified, the default value of 00 will be used, specifying no encryption and no compression

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod RequestUpload.interpret_response(response)[source]

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 over more than 8 bytes.

Return type:

InterpretedResponse

class RequestUpload.ResponseData(max_length)[source]
Parameters:

max_length (int) –

max_length

(int) Maximum number of data blocks to read

Note

This service does not have subfunctions

RoutineControl (0x31)

classmethod RoutineControl.make_request(routine_id, control_type, data=None)[source]

Generates a request for RoutineControl

Parameters:

  • routine_id (int) – The routine ID. Value should be between 0 and 0xFFFF

  • control_type (int) – 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

Return type:

Request

classmethod RoutineControl.interpret_response(response)[source]

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

Return type:

InterpretedResponse

class RoutineControl.ResponseData(control_type_echo, routine_id_echo, routine_status_record)[source]
Parameters:

  • control_type_echo (int) –

  • routine_id_echo (int) –

  • routine_status_record (bytes) –

control_type_echo

Requests subfunction echoed back by the server

routine_id_echo

Requests routine ID echoed back by the server.

routine_status_record

Additional data associated with the response.

class RoutineControl.ControlType[source]

RoutineControl defined subfunctions

startRoutine = 1
stopRoutine = 2
requestRoutineResults = 3

SecurityAccess (0x27)

classmethod SecurityAccess.make_request(level, mode, data=b'')[source]

Generates a request for SecurityAccess

Parameters:

  • level (int) – Service subfunction. The security level to unlock. Value ranging from 0 to 7F For mode=``RequestSeed`` (0), level must be an odd value. For mode=``SendKey`` (1), level must be an even value. If the even/odd constraint is not respected, the level value will be corrected to properly set the LSB.

  • mode (SecurityAccess.Mode, int) – Type of request to perform. SecurityAccess.Mode.RequestSeed or SecurityAccess.Mode.SendKey

  • data (bytes) – securityAccessDataRecord (optional) for the get seed, securityKey (required) for the send key

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod SecurityAccess.interpret_response(response, mode)[source]

Populates the response service_data property with an instance of SecurityAccess.ResponseData

Parameters:

  • response (Response) – The received response to interpret

  • mode (int) –

Raises:

  • InvalidResponseException – If length of response.data is too short

  • ValueError – If mode is not RequestSeed or SendKey

Return type:

InterpretedResponse

class SecurityAccess.ResponseData(security_level_echo, seed=None)[source]
Parameters:

  • security_level_echo (int) –

  • seed (bytes | None) –

security_level_echo

Requests subfunction echoed back by the server

seed

Seed value. Only present if request mode was RequestSeed (even subfunction)

class SecurityAccess.Mode[source]
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 of request. When the LSB is set to 1, the request is a RequestSeed message, when it is set to 0, the request is a SendKey message. 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

TesterPresent (0x3E)

classmethod TesterPresent.make_request()[source]

Generates a request for TesterPresent

Return type:

Request

classmethod TesterPresent.interpret_response(response)[source]

Populates the response service_data property with an instance of TesterPresent.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class TesterPresent.ResponseData(subfunction_echo)[source]
Parameters:

subfunction_echo (int) –

subfunction_echo

Requests subfunction echoed back by the server. This value should always be 0

Note

TesterPresent subfunction is always 0

TransferData (0x36)

classmethod TransferData.make_request(sequence_number, data=None)[source]

Generates a request for TransferData

Parameters:

  • sequence_number (int) – Corresponds to an 8bit counter that should increment for each 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

Return type:

Request

classmethod TransferData.interpret_response(response)[source]

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

Return type:

InterpretedResponse

class TransferData.ResponseData(sequence_number_echo, parameter_records)[source]
Parameters:

  • sequence_number_echo (int) –

  • parameter_records (bytes) –

sequence_number_echo

Requests subfunction echoed back by the server

parameter_records

Optional additional data associated with the response.

Note

This service does not have subfunctions

WriteDataByIdentifier (0x2E)

classmethod WriteDataByIdentifier.make_request(did, value, didconfig)[source]

Generates a request for WriteDataByIdentifier

Parameters:

  • did (int) – The data identifier to write

  • value (object) – Value given to the DidCodec.encode method. If involved codec is defined with a pack string (default codec), multiple values may be passed with a tuple.

  • didconfig (dict[int] = DidCodec) – Definition of DID codecs. Dictionary mapping a DID (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

Return type:

Request

classmethod WriteDataByIdentifier.interpret_response(response)[source]

Populates the response service_data property with an instance of WriteDataByIdentifier.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class WriteDataByIdentifier.ResponseData(did_echo)[source]
Parameters:

did_echo (int) –

did_echo

The DID echoed back by the server

Note

This service does not have subfunctions

WriteMemoryByAddress (0x3D)

classmethod WriteMemoryByAddress.make_request(memory_location, data)[source]

Generates a request for ReadMemoryByAddress

Parameters:

  • memory_location (MemoryLocation) – The address and the size of the memory block to write.

  • data (bytes) – The data to write into memory.

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod WriteMemoryByAddress.interpret_response(response, memory_location)[source]

Populates the response service_data property with an instance of WriteMemoryByAddress.ResponseData

Parameters:

  • response (Response) – The received response to interpret

  • memory_location (MemoryLocation) – The memory location used for the request. The bytes position varies depending on the memory_location format

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class WriteMemoryByAddress.ResponseData(alfid_echo, memory_location_echo)[source]
Parameters:
alfid_echo

AddressAndLengthFormatIdentifier used in the MemoryLocation object echoed back by the server as a single byte integer.

memory_location_echo

An instance of MemoryLocation that includes the address, size and alfid that the server echoed back.

Note

This service does not have subfunctions

DynamicallyDefineDataIdentifier (0x2C)

classmethod DynamicallyDefineDataIdentifier.make_request(subfunction, did=None, diddef=None)[source]

Generates a request for DynamicallyDefineDataIdentifier

Parameters:

  • subfunction (int) – Service subfunction. Allowed values are from 1 to 3

  • did (int) – The Data Identifier to define. Values from 0x0000 to 0xFFFF

  • diddef (DynamicDidDefinition) – Definition of the DID. Either by source DID or memory address. This parameter is only needed with subfunctions defineByIdentifie (1)` and defineByMemoryAddress (2)

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod DynamicallyDefineDataIdentifier.interpret_response(response)[source]

Populates the response service_data property with an instance of DynamicallyDefineDataIdentifier.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If length of response.data is too short

Return type:

InterpretedResponse

class DynamicallyDefineDataIdentifier.ResponseData(subfunction_echo, did_echo=None)[source]
Parameters:

  • subfunction_echo (int) –

  • did_echo (int | None) –

SecuredDataTransmission (0x84)

Warning

Not implemented

ResponseOnEvent (0x86)

Warning

Not implemented

ReadScalingDataByIdentifier (0x24)

Warning

Not implemented

ReadDataByPeriodicIdentifier (0x2A)

Warning

Not implemented

Authentication (0x29)

classmethod Authentication.make_request(authentication_task, communication_configuration=None, certificate_client=None, challenge_client=None, algorithm_indicator=None, certificate_evaluation_id=None, certificate_data=None, proof_of_ownership_client=None, ephemeral_public_key_client=None, additional_parameter=None)[source]

Generates a request for Authentication

Parameters:

  • authentication_task (int) – Service subfunction. Allowed values are from 0 to 8.

  • communication_configuration (int) – Optional Configuration information about how to proceed with security in further diagnostic communication after the Authentication (vehicle manufacturer specific). Allowed values are from 0 to 255.

  • certificate_client (bytes or None) – Optional The Certificate to verify.

  • challenge_client (bytes or None) – Optional The challenge contains vehicle manufacturer specific formatted client data (likely containing randomized information) or is a random number.

  • algorithm_indicator (bytes or None) – Optional Indicates the algorithm used in the generating and verifying Proof of Ownership (POWN), which further determines the parameters used in the algorithm and possibly the session key creation mode. This field is a 16 byte value containing the BER encoded OID value of the algorithm used. The value is left aligned and right padded with zero up to 16 bytes.

  • certificate_evaluation_id (int or None) – Optional unique ID to identify the evaluation type of the transmitted certificate. The value of this parameter is vehicle manufacturer specific. Subsequent diagnostic requests with the same evaluationTypeId will overwrite the certificate data of the previous requests. Allowed values are from 0 to 0xFFFF.

  • certificate_data (bytes or None) – Optional The Certificate to verify.

  • proof_of_ownership_client (bytes or None) – Optional Proof of Ownership of the previous given challenge to be verified by the server.

  • ephemeral_public_key_client (bytes or None) – Optional Ephemeral public key generated by the client for Diffie-Hellman key agreement.

  • additional_parameter (bytes or None) – Optional additional parameter is provided to the server if the server indicates as neededAdditionalParameter.

Raises:

ValueError – If parameters are out of range, missing or wrong type

Return type:

Request

classmethod Authentication.interpret_response(response)[source]
Populates the response service_data property with an instance of

Authentication.ResponseData

Parameters:

response (Response) – The received response to interpret

Raises:

InvalidResponseException – If response data length is not as expected

Return type:

InterpretedResponse

class Authentication.ResponseData(authentication_task_echo, return_value, challenge_server=None, ephemeral_public_key_server=None, certificate_server=None, proof_of_ownership_server=None, session_key_info=None, algorithm_indicator=None, needed_additional_parameter=None)[source]
Parameters:

  • authentication_task_echo (int) –

  • return_value (int) –

  • challenge_server (bytes | None) –

  • ephemeral_public_key_server (bytes | None) –

  • certificate_server (bytes | None) –

  • proof_of_ownership_server (bytes | None) –

  • session_key_info (bytes | None) –

  • algorithm_indicator (bytes | None) –

  • needed_additional_parameter (bytes | None) –

authentication_task_echo
Authentication Task echoed back by the server
return_value
:ref:`AuthenticationReturnParameter<AuthenticationReturnParameter>` authenticationReturnParameter as defined in
B.5. (ISO 14229-1:2020)
challenge_server
The challenge contains vehicle manufacturer specific formatted server data (eventually containing randomized
information) or is a random number.
ephemeral_public_key_server
Ephemeral public key generated by the server for Diffie-Hellman key agreement.
certificate_server
The Certificate to verify.
proof_of_ownership_server
Proof of Ownership to be verified by the client.
session_key_info
If present, this value shall contain session key information, e.g. the encrypted session key(s) for securing
further communication in the actual session and/or proof value(s) (e.g. a hash value) for the validation of the
session key(s) on the client side.
algorithm_indicator
Indicates the algorithm used in the generating and verifying Proof of Ownership (POWN), which further determines
the parameters used in the algorithm and possibly the session key creation mode. This field is a 16 byte value
containing the BER encoded OID value of the algorithm used. The value is left aligned and right padded with
zero up to 16 bytes.
needed_additional_parameter
Indicate what additional parameters, if needed, are expected by the server.
class Authentication.AuthenticationTask[source]
deAuthenticate = 0
verifyCertificateUnidirectional = 1
verifyCertificateBidirectional = 2
proofOfOwnership = 3
transmitCertificate = 4
requestChallengeForAuthentication = 5
verifyProofOfOwnershipUnidirectional = 6
verifyProofOfOwnershipBidirectional = 7
authenticationConfiguration = 8

make_request() parameters per sub function

make_request() parameters per Authentication Task

authentication_task

communication_configuration

certificate_client

challenge_client

algorithm_indicator

certificate_evaluation_id

certificate_data

proof_of_ownership_client

ephemeral_public_key_client

additional_parameter

deAuthenticate

verifyCertificateUnidirectional

Yes

Yes

Yes

verifyCertificateBidirectional

Yes

Yes

Yes

proofOfOwnership

Yes

Yes

transmitCertificate

Yes

Yes

requestChallengeForAuthentication

Yes

Yes

verifyProofOfOwnershipUnidirectional

Yes

Yes

Yes

Yes

verifyProofOfOwnershipBidirectional

Yes

Yes

Yes

Yes

authenticationConfiguration