uds.translator.service

Implementation of diagnostic services data encoding and decoding.

Attributes

SingleDataRecordValueAlias

Alias for a single occurrence Data Record. Either:

MultipleDataRecordValueAlias

Alias for a multiple occurrences Data Record. It is a sequence where each element represents a single occurrence.

DataRecordValueAlias

Alias for a Data Record value that can be used in the Data Records Mapping.

DataRecordsValuesAlias

Alias for Data Records values mapping.

DecodedMessageAlias

Alias for decoded information about a Diagnostic Message.

Classes

Service

Translator for a diagnostic service.

Module Contents

uds.translator.service.SingleDataRecordValueAlias

Alias for a single occurrence Data Record. Either: - int type - a single raw value - mapping type - children values - None - no occurrence

uds.translator.service.MultipleDataRecordValueAlias

Alias for a multiple occurrences Data Record. It is a sequence where each element represents a single occurrence. Each element is either raw value (int type) or children values (mapping type).

uds.translator.service.DataRecordValueAlias

Alias for a Data Record value that can be used in the Data Records Mapping.

uds.translator.service.DataRecordsValuesAlias

Alias for Data Records values mapping. Mapping keys are Data Records names. Mapping values are corresponding Data Records values.

uds.translator.service.DecodedMessageAlias

Alias for decoded information about a Diagnostic Message.

class uds.translator.service.Service(request_sid, request_structure, response_structure, supported_nrc=tuple(NRC))[source]

Translator for a diagnostic service.

Interactions via UDS protocol with servers (ECUs) are possible via diagnostic services which are basically functions that you can request as a client.

Features:

  • contains structures of diagnostic messages (both request and response) for a single diagnostic service

  • provides tools for decoding meaningful information (physical values) from diagnostic messages

  • provides tools for creating diagnostic messages out of meaningful information (physical values)

Define a translator for a single diagnostic service.

Parameters:

  • request_sid (uds.message.RequestSID) – Service Identifier for request message.

  • request_structure (uds.translator.data_record.AliasMessageStructure) – Data Records that contains translation for response message continuation.

  • response_structure (uds.translator.data_record.AliasMessageStructure) – Data Records that contains translation for diagnostic message continuation.

  • supported_nrc (Collection[uds.message.NRC]) – NRC codes that are supported by this service.

Warning

Arguments request_structure and response_structure must not contain Data Records for the first byte of respectively request message (SID) and response message (RSID) as those values are passed via other parameters.

NEGATIVE_RESPONSE_LENGTH = 3
property request_sid: uds.message.RequestSID

Get Service Identifier (SID) value for this diagnostic service.

Return type:

uds.message.RequestSID

property request_structure: uds.translator.data_record.AliasMessageStructure

Get Data Records used for translating request messages for this diagnostic service.

Return type:

uds.translator.data_record.AliasMessageStructure

property response_structure: uds.translator.data_record.AliasMessageStructure

Get Data Records used for translating positive response messages for this diagnostic service.

Return type:

uds.translator.data_record.AliasMessageStructure

property supported_nrc: Set[uds.message.NRC]

Get NRC codes that are supported by this diagnostic service.

Return type:

Set[uds.message.NRC]

property response_sid: uds.message.ResponseSID

Get Response Service Identifier (RSID) value for this diagnostic service.

Return type:

uds.message.ResponseSID

property name: str

Get name of this service.

Return type:

str

_get_rsid_info(positive=True)[source]

Get detailed information about Response Service Identifier.

Parameters:

positive (bool) – RSID is for positive or negative response message.

Returns:

Detailed information about RSID value.

Return type:

uds.translator.data_record.SingleOccurrenceInfo

_get_sid_info()[source]

Get detailed information about Service Identifier.

Return type:

uds.translator.data_record.SingleOccurrenceInfo

static _get_nrc_info(nrc)[source]

Get detailed information about Negative Response Code.

Parameters:

nrc (uds.message.NRC) – The value of NRC.

Returns:

Detailed information for single occurrence of NRC Data Record.

Return type:

uds.translator.data_record.SingleOccurrenceInfo

static _get_single_data_record_occurrence(data_record, value)[source]

Get occurrence value for a single occurrence Data Record.

Parameters:

  • data_record (uds.translator.data_record.AbstractDataRecord) – Data Record object.

  • value (SingleDataRecordValueAlias) –

    Data Record value. Either:

    • None - no value (valid for Data Records with min_occurrences=0)

    • int type - raw value

    • mapping type - children values

Raises:

  • TypeError – Provided value has incorrect type that cannot be handled for the provided Data Record.

  • ValueError – Provided value is incorrect.

Returns:

List with either 1 or 0 raw values for this Data Record.

Return type:

List[int]

static _get_reoccurring_data_record_occurrences(data_record, value)[source]

Get occurrences values for multiple occurrences Data Record.

Parameters:

  • data_record (uds.translator.data_record.AbstractDataRecord) – Data Record object.

  • value (MultipleDataRecordValueAlias) – Sequence with Data Record values (either int or mapping type).

Raises:

  • TypeError – Provided value has incorrect type that cannot be handled for the provided Data Record.

  • ValueError – Provided value is incorrect.

Returns:

List with raw values for this Data Record.

Return type:

List[int]

classmethod _get_data_record_occurrences(data_record, value)[source]

Get raw values of all occurrences provided as value.

Parameters:

  • data_record (uds.translator.data_record.AbstractDataRecord) – Data Record object.

  • value (DataRecordValueAlias) – Data Record values. Either for a single occurrence or multiple occurrences. Each occurrence might be a raw value or mapping with children values.

Returns:

Raw values for following Data Record occurrences.

Return type:

List[int]

static _get_remaining_length(message_structure)[source]

Get minimal remaining length for the provided message structure.

Parameters:

message_structure (uds.translator.data_record.AliasMessageStructure) – Message structure to check.

Raises:

TypeError – All elements of the message structure must be instances of AbstractDataRecord class.

Returns:

Minimal length of the provided messages structure.

Return type:

int

classmethod _decode_payload(payload, message_structure, check_remaining_length=True)[source]

Decode information for given message structure and payload.

Parameters:

  • payload (uds.utilities.RawBytesAlias) – Payload to decode.

  • message_structure (uds.translator.data_record.AliasMessageStructure) – Defined structure of a diagnostic message.

  • check_remaining_length (bool) – Whether to raise an exception when only part of the message was decoded.

Raises:

  • ValueError – Provided message payload was too short.

  • RuntimeError – An error occurred which was caused by incorrect message structure.

  • NotImplementedError – There is missing implementation for at least one Data Record in the provided message structure.

Returns:

Decoded information from the provided payload.

Return type:

DecodedMessageAlias

classmethod _encode_message(data_records_values, message_structure, check_unused_data_record_values=True)[source]

Encode payload of a diagnostic message.

Parameters:

  • data_records_values (Dict[str, DataRecordValueAlias]) – Mapping with Data Records values that are part of the message. Mapping keys are Data Records names. Mapping values are either a single occurrence or multiple occurrences values. Each occurrence can be a raw value or a mapping with children names and its corresponding values.

  • message_structure (uds.translator.data_record.AliasMessageStructure) – Data Records that form the remaining structure of the diagnostic message.

  • check_unused_data_record_values (bool) – Whether to raise an exception when unused Data Record value found.

Raises:

  • RuntimeError – An error occurred which was caused by incorrect message structure.

  • ValueError – Value for at least one Data Record that is no part of the message, was provided.

  • NotImplementedError – There is missing implementation for at least one Data Record in the provided message structure.

Returns:

Payload of a diagnostic message created from provided data records values.

Return type:

bytearray

static validate_message_structure(value)[source]

Validate whether the provided value is a structure of diagnostic message.

Parameters:

value (uds.translator.data_record.AliasMessageStructure) – Value to check.

Return type:

None

decode_request(payload)[source]

Decode information carried by a request message for this diagnostic service.

Parameters:

payload (uds.utilities.RawBytesAlias) – Payload of a request message.

Raises:

ValueError – Provided payload does not carry a request to this diagnostic service.

Returns:

Decoded information from the provided payload.

Return type:

DecodedMessageAlias

decode_positive_response(payload)[source]

Decode information carried by a positive response message for this diagnostic service.

Parameters:

payload (uds.utilities.RawBytesAlias) – Payload of a positive response message.

Raises:

ValueError – Provided payload does not carry a positive response to this diagnostic service.

Returns:

Decoded information from the provided payload.

Return type:

DecodedMessageAlias

decode_negative_response(payload)[source]

Decode information carried by a negative response message for this diagnostic service.

Parameters:

payload (uds.utilities.RawBytesAlias) – Payload of a negative response message.

Raises:

ValueError – Provided payload does not carry a negative response to this diagnostic service.

Returns:

Decoded information from the provided payload.

Return type:

DecodedMessageAlias

decode(payload)[source]

Decode information carried by a diagnostic message for this diagnostic service.

Parameters:

payload (uds.utilities.RawBytesAlias) – Payload of a diagnostic message.

Raises:

ValueError – Provided message payload does not start from a SID value for this service.

Returns:

Decoded information from the provided payload.

Return type:

DecodedMessageAlias

encode_request(data_records_values)[source]

Encode request message payload for this service.

Parameters:

data_records_values (DataRecordsValuesAlias) – Mapping with Data Records values that are part of the message. Mapping keys are Data Records names. Mapping values are either a single occurrence or multiple occurrences values. Each occurrence can be a raw value or a mapping with children names and its corresponding values.

Returns:

Payload of a request message.

Return type:

bytearray

encode_positive_response(data_records_values)[source]

Encode positive response message payload for this service.

Parameters:

data_records_values (DataRecordsValuesAlias) – Mapping with Data Records values that are part of the message. Mapping keys are Data Records names. Mapping values are either a single occurrence or multiple occurrences values. Each occurrence can be a raw value or a mapping with children names and its corresponding values.

Returns:

Payload of a positive response message.

Return type:

bytearray

encode_negative_response(nrc)[source]

Encode negative response message payload for this service.

Parameters:

nrc (uds.message.NRC) – NRC value to use.

Returns:

Payload of a negative response message for this service.

Return type:

bytearray

encode(data_records_values, sid=None, rsid=None)[source]

Encode diagnostic message payload for this service.

Parameters:

  • data_records_values (DataRecordsValuesAlias) – Mapping with Data Records values that are part of the message. Mapping keys are Data Records names. Mapping values are either a single occurrence or multiple occurrences values. Each occurrence can be a raw value or a mapping with children names and its corresponding values.

  • sid (Optional[uds.message.RequestSID]) – Request SID value. Used by request message (first byte) and negative response message (second byte).

  • rsid (Optional[uds.message.ResponseSID]) – Response SID value. Used by response messages only (first byte).

Raises:
Returns:

Payload of a diagnostic message created from provided data records values.

Return type:

bytearray