uds.translator.service ====================== .. py:module:: uds.translator.service .. autoapi-nested-parse:: Implementation of diagnostic services data encoding and decoding. Attributes ---------- .. autoapisummary:: uds.translator.service.SingleDataRecordValueAlias uds.translator.service.MultipleDataRecordValueAlias uds.translator.service.DataRecordValueAlias uds.translator.service.DataRecordsValuesAlias uds.translator.service.DecodedMessageAlias Classes ------- .. autoapisummary:: uds.translator.service.Service Module Contents --------------- .. py:data:: SingleDataRecordValueAlias Alias for a single occurrence Data Record. Either: - int type - a single raw value - mapping type - children values - None - no occurrence .. py:data:: 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). .. py:data:: DataRecordValueAlias Alias for a Data Record value that can be used in the Data Records Mapping. .. py:data:: DataRecordsValuesAlias Alias for Data Records values mapping. Mapping keys are Data Records names. Mapping values are corresponding Data Records values. .. py:data:: DecodedMessageAlias Alias for decoded information about a Diagnostic Message. .. py:class:: Service(request_sid, request_structure, response_structure, supported_nrc = tuple(NRC)) Translator for a diagnostic service. Interactions via UDS protocol with servers (ECUs) are possible via :ref:`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. :param request_sid: Service Identifier for request message. :param request_structure: Data Records that contains translation for response message continuation. :param response_structure: Data Records that contains translation for diagnostic message continuation. :param supported_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. .. py:attribute:: NEGATIVE_RESPONSE_LENGTH :value: 3 .. py:property:: request_sid :type: uds.message.RequestSID Get Service Identifier (SID) value for this diagnostic service. .. py:property:: request_structure :type: uds.translator.data_record.AliasMessageStructure Get Data Records used for translating request messages for this diagnostic service. .. py:property:: response_structure :type: uds.translator.data_record.AliasMessageStructure Get Data Records used for translating positive response messages for this diagnostic service. .. py:property:: supported_nrc :type: Set[uds.message.NRC] Get NRC codes that are supported by this diagnostic service. .. py:property:: response_sid :type: uds.message.ResponseSID Get Response Service Identifier (RSID) value for this diagnostic service. .. py:property:: name :type: str Get name of this service. .. py:method:: _get_rsid_info(positive = True) Get detailed information about Response Service Identifier. :param positive: RSID is for positive or negative response message. :return: Detailed information about RSID value. .. py:method:: _get_sid_info() Get detailed information about Service Identifier. .. py:method:: _get_nrc_info(nrc) :staticmethod: Get detailed information about Negative Response Code. :param nrc: The value of NRC. :return: Detailed information for single occurrence of NRC Data Record. .. py:method:: _get_single_data_record_occurrence(data_record, value) :staticmethod: Get occurrence value for a single occurrence Data Record. :param data_record: Data Record object. :param value: Data Record value. Either: - None - no value (valid for Data Records with min_occurrences=0) - int type - raw value - mapping type - children values :raise TypeError: Provided value has incorrect type that cannot be handled for the provided Data Record. :raise ValueError: Provided value is incorrect. :return: List with either 1 or 0 raw values for this Data Record. .. py:method:: _get_reoccurring_data_record_occurrences(data_record, value) :staticmethod: Get occurrences values for multiple occurrences Data Record. :param data_record: Data Record object. :param value: Sequence with Data Record values (either int or mapping type). :raise TypeError: Provided value has incorrect type that cannot be handled for the provided Data Record. :raise ValueError: Provided value is incorrect. :return: List with raw values for this Data Record. .. py:method:: _get_data_record_occurrences(data_record, value) :classmethod: Get raw values of all occurrences provided as value. :param data_record: Data Record object. :param value: Data Record values. Either for a single occurrence or multiple occurrences. Each occurrence might be a raw value or mapping with children values. :return: Raw values for following Data Record occurrences. .. py:method:: _get_remaining_length(message_structure) :staticmethod: Get minimal remaining length for the provided message structure. :param message_structure: Message structure to check. :raise TypeError: All elements of the message structure must be instances of `AbstractDataRecord` class. :return: Minimal length of the provided messages structure. .. py:method:: _decode_payload(payload, message_structure, check_remaining_length = True) :classmethod: Decode information for given message structure and payload. :param payload: Payload to decode. :param message_structure: Defined structure of a diagnostic message. :param check_remaining_length: Whether to raise an exception when only part of the message was decoded. :raise ValueError: Provided message payload was too short. :raise RuntimeError: An error occurred which was caused by incorrect message structure. :raise NotImplementedError: There is missing implementation for at least one Data Record in the provided message structure. :return: Decoded information from the provided payload. .. py:method:: _encode_message(data_records_values, message_structure, check_unused_data_record_values = True) :classmethod: Encode payload of a diagnostic message. :param data_records_values: 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. :param message_structure: Data Records that form the remaining structure of the diagnostic message. :param check_unused_data_record_values: Whether to raise an exception when unused Data Record value found. :raise RuntimeError: An error occurred which was caused by incorrect message structure. :raise ValueError: Value for at least one Data Record that is no part of the message, was provided. :raise NotImplementedError: There is missing implementation for at least one Data Record in the provided message structure. :return: Payload of a diagnostic message created from provided data records values. .. py:method:: validate_message_structure(value) :staticmethod: Validate whether the provided value is a structure of diagnostic message. :param value: Value to check. .. py:method:: decode_request(payload) Decode information carried by a request message for this diagnostic service. :param payload: Payload of a request message. :raise ValueError: Provided payload does not carry a request to this diagnostic service. :return: Decoded information from the provided payload. .. py:method:: decode_positive_response(payload) Decode information carried by a positive response message for this diagnostic service. :param payload: Payload of a positive response message. :raise ValueError: Provided payload does not carry a positive response to this diagnostic service. :return: Decoded information from the provided payload. .. py:method:: decode_negative_response(payload) Decode information carried by a negative response message for this diagnostic service. :param payload: Payload of a negative response message. :raise ValueError: Provided payload does not carry a negative response to this diagnostic service. :return: Decoded information from the provided payload. .. py:method:: decode(payload) Decode information carried by a diagnostic message for this diagnostic service. :param payload: Payload of a diagnostic message. :raise ValueError: Provided message payload does not start from a SID value for this service. :return: Decoded information from the provided payload. .. py:method:: encode_request(data_records_values) Encode request message payload for this service. :param data_records_values: 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. :return: Payload of a request message. .. py:method:: encode_positive_response(data_records_values) Encode positive response message payload for this service. :param data_records_values: 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. :return: Payload of a positive response message. .. py:method:: encode_negative_response(nrc) Encode negative response message payload for this service. :param nrc: NRC value to use. :return: Payload of a negative response message for this service. .. py:method:: encode(data_records_values, sid = None, rsid = None) Encode diagnostic message payload for this service. :param data_records_values: 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. :param sid: Request SID value. Used by request message (first byte) and negative response message (second byte). :param rsid: Response SID value. Used by response messages only (first byte). :raise ValueError: Missing or provided SID/RSID value cannot be handled by this service. :raise InconsistencyError: Value only for `NRC` :return: Payload of a diagnostic message created from provided data records values.