Diagnostic Messages Translation

Translation implementation is located in uds.translator sub-package.

Translator

Translator is the high level interface that can be used to build diagnostic messages and decode information carried by them.

Configuration:

Translators are configured upon Translator class object creation. All you have to do is provide collection of Service class objects that contain translation logic for each diagnostic service.

Example code:

from typing import Collection
from uds.translator import Translator, Service

# let's assume we have some services already defined
my_services: Collection[Service]

# configure translator
my_translator = Translator(my_services)

Diagnostic Messages payload building (encoding):

Translators might be used to build payload of diagnostic messages. This feature is provided by encode() method. You might use it to build all diagnostic messages types (request, positive and negative responses).

Example code:

from uds.message import RequestSID, ResponseSID, NRC

# let's assume that we have `my_translator` already configured with Diagnostic Session Control service
# Diagnostic Session Control service structure must match `data_records_values` parameters
my_translator: Translator

# build payload of example request message for Diagnostic Session Control service
request_payload = my_translator.encode(sid=RequestSID.DiagnosticSessionControl,
                                       data_records_values={"subFunction": {"SPRMIB": 1,
                                                                            "diagnosticSessionType": 3}})

# build payload of example positive response message for Diagnostic Session Control service
positive_response_payload = my_translator.encode(rsid=ResponseSID.DiagnosticSessionControl,
                                                 data_records_values={"subFunction": 3,
                                                                      "sessionParameterRecord": {
                                                                          "P2Server_max": 0x1234,
                                                                          "P2*Server_max": 0x5678}})

# build payload of example negative response message for Diagnostic Session Control service
negative_response_payload = my_translator.encode(rsid=ResponseSID.NegativeResponse,
                                                 sid=RequestSID.DiagnosticSessionControl,
                                                 data_records_values={"NRC": NRC.SubFunctionNotSupported})

Extracting information carried by Diagnostic Messages (decoding):

Translators might be used to extract comprehensive information carried by diagnostic messages. This functionality is provided by decode() method. You might use it with all diagnostic messages types (request, positive and negative responses).

Example code:

from uds.message import UdsMessage, UdsMessageRecord

# let's assume that we have `my_translator` already configured and some messages defined
my_translator: Translator
some_message: UdsMessage
some_message_record: UdsMessageRecord

# decode information
decoded_message_information = my_translator.decode(some_message)
decoded_message_record_information = my_translator.decode(some_message_record)

Translator Definitions

Package defines following standard (compatible with ISO 14229-1) translators:

BASE_TRANSLATOR - bases on the newest ISO 14229-1 version
BASE_TRANSLATOR_2020 - bases on ISO 14229-1:2020
BASE_TRANSLATOR_2013 - bases on ISO 14229-1:2013

Service

Each object of Service class defines a translation logic for one specific diagnostic service.

Configuration:

Services are configured upon Service class object creation. You must provide Service Identifier (SID) value, request and response message structure. Optionally, you might also provide NRC codes that are supported by this service.

Example code:

from uds.translator import Service, AbstractDataRecord
from uds.message import NRC, RequestSID

# let's assume that we have `sub_function_data_record` and `session_parameter_data_record` Data Records defined
sub_function_data_record: AbstractDataRecord
session_parameter_data_record: AbstractDataRecord

# configure example diagnostic service
diagnostic_session_control = Service(request_sid=RequestSID.DiagnosticSessionControl,
                                     request_structure=[sub_function_data_record],
                                     response_structure=[sub_function_data_record, session_parameter_data_record],
                                     supported_nrc={NRC.SubFunctionNotSupported,
                                                    NRC.IncorrectMessageLengthOrInvalidFormat,
                                                    NRC.BusyRepeatRequest,
                                                    NRC.ConditionsNotCorrect})

Diagnostic Messages payload building (encoding):

Services might be used directly (or through Translator) to build payload of diagnostic messages. This feature is provided by multiple methods:

encode() - supports all messages types (request, positive and negative responses)

encode_request() - for request messages only

encode_positive_response() - for positive response messages only

encode_negative_response() - for negative response messages only

Example code:

from uds.translator import Service, AbstractDataRecord
from uds.message import NRC, RequestSID, ResponseSID

# let's assume that we have `diagnostic_session_control` Service defined
diagnostic_session_control: Service

# build payload of example request message for Diagnostic Session Control service
request_payload = diagnostic_session_control.encode(sid=RequestSID.DiagnosticSessionControl,
                                                    data_records_values={"subFunction": {
                                                                             "SPRMIB": 1,
                                                                             "diagnosticSessionType": 3}})
request_payload = diagnostic_session_control.encode_request(data_records_values={"subFunction": {
                                                                                     "SPRMIB": 1,
                                                                                     "diagnosticSessionType": 3}})

# build payload of example positive response message for Diagnostic Session Control service
positive_response_payload = diagnostic_session_control.encode(rsid=ResponseSID.DiagnosticSessionControl,
                                                              data_records_values={"subFunction": 3,
                                                                                   "sessionParameterRecord": {
                                                                                       "P2Server_max": 0x1234,
                                                                                       "P2*Server_max": 0x5678}})
positive_response_payload = diagnostic_session_control.encode_positive_response(data_records_values={
                                                                                    "subFunction": 3,
                                                                                    "sessionParameterRecord": {
                                                                                        "P2Server_max": 0x1234,
                                                                                        "P2*Server_max": 0x5678}})

# build payload of example negative response message for Diagnostic Session Control service
negative_response_payload = diagnostic_session_control.encode(rsid=ResponseSID.NegativeResponse,
                                                              sid=RequestSID.DiagnosticSessionControl,
                                                              data_records_values={
                                                                  "NRC": NRC.SubFunctionNotSupported})
negative_response_payload = diagnostic_session_control.encode_negative_response(nrc=NRC.SubFunctionNotSupported)

Extracting information carried by Diagnostic Messages (decoding):

Services might be used directly (or though Translator) to extract comprehensive information carried by diagnostic messages. This feature is provided by multiple methods:

decode() - supports all messages types (request, positive and negative responses)

decode_request() - for request messages only

decode_positive_response() - for positive response messages only

decode_negative_response() - for negative response messages only

Example code:

from uds.message import UdsMessage, UdsMessageRecord

# let's assume that we have `diagnostic_session_control` Service and messages for this service defined
diagnostic_session_control: Service
diagnostic_session_control_message: UdsMessage
diagnostic_session_control_message_record: UdsMessageRecord

# decode information
decoded_message_information = diagnostic_session_control.decode(diagnostic_session_control_message)
decoded_message_record_information = diagnostic_session_control.decode(diagnostic_session_control_message_record)

# decode request messages
decoded_request_message_information = diagnostic_session_control.decode_request(diagnostic_session_control_message)
decoded_request_message_record_information = diagnostic_session_control.decode_request(diagnostic_session_control_message_record)

# decode positive response messages
decoded_positive_response_message_information = diagnostic_session_control.decode_positive_response(diagnostic_session_control_message)
decoded_positive_response_message_record_information = diagnostic_session_control.decode_positive_response(diagnostic_session_control_message_record)

# decode negative response messages
decoded_negative_response_message_information = diagnostic_session_control.decode_negative_response(diagnostic_session_control_message)
decoded_negative_response_message_record_information = diagnostic_session_control.decode_negative_response(diagnostic_session_control_message_record)

Service Definitions

Package defines following standard (compatible with ISO 14229-1) diagnostic services translators: