odxtools 9.4.1__py3-none-any.whl → 9.6.0__py3-none-any.whl

odxtools/unitgroup.py

@@ -28,13 +28,14 @@ class UnitGroup(NamedElement):
     unit_refs: List[OdxLinkRef]
     oid: Optional[str]
 
-    def __post_init__(self) -> None:
-        self._units = NamedItemList[Unit]()
+    @property
+    def units(self) -> NamedItemList[Unit]:
+        return self._units
 
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "UnitGroup":
-        oid = et_element.get("OID")
         kwargs = dataclass_fields_asdict(NamedElement.from_et(et_element, doc_frags))
+
         category_str = odxrequire(et_element.findtext("CATEGORY"))
         try:
             category = UnitGroupCategory(category_str)
@@ -42,10 +43,11 @@ class UnitGroup(NamedElement):
             category = cast(UnitGroupCategory, None)
             odxraise(f"Encountered unknown unit group category '{category_str}'")
 
-        unit_refs: List[OdxLinkRef] = [
+        unit_refs = [
             odxrequire(OdxLinkRef.from_et(el, doc_frags))
             for el in et_element.iterfind("UNIT-REFS/UNIT-REF")
         ]
+        oid = et_element.get("OID")
 
         return UnitGroup(category=category, unit_refs=unit_refs, oid=oid, **kwargs)
 
@@ -57,7 +59,3 @@ class UnitGroup(NamedElement):
 
     def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
-
-    @property
-    def units(self) -> NamedItemList[Unit]:
-        return self._units

odxtools/variantmatcher.py

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: MIT
+from copy import copy
+from enum import Enum
+from typing import Dict, Generator, List, Optional, Tuple, Union
+
+from .diaglayers.basevariant import BaseVariant
+from .diaglayers.ecuvariant import EcuVariant
+from .exceptions import DecodeError, odxraise
+from .matchingparameter import MatchingParameter
+from .response import Response
+
+
+class VariantMatcher:
+    """VariantMatcher implements the matching algorithm of ECU and
+    base variants according to their ECU-VARIANT-PATTERNs or
+    BASE-VARIANT-PATTERNs according to ISO 22901-1.
+
+        Usage (example):
+
+    ```python
+
+    # initialize the matcher with a list of base or ECU variants
+    matcher = VariantMatcher(candidates=[...], use_cache=use_cache)
+
+    # run the request loop to obtain responses for every request
+    for use_physical_addressing, encoded_request in matcher.request_loop():
+        if use_physical_addressing:
+            resp = send_to_ecu_using_physical_addressing(encoded_request)
+        else:
+            resp = send_to_ecu_using_functional_addressing(encoded_request)
+        matcher.evaluate(resp)
+
+    # result
+    if matcher.has_match():
+        if isinstance(matcher.matching_variant, BaseVariant):
+            print(f"Match found for base variant "
+                  f"{matcher.matching_variant.short_name}")
+        elif isinstance(matcher.matching_variant, EcuVariant):
+            print(f"Match found for ECU variant "
+                  f"{matcher.matching_variant.short_name}")
+        else:
+            print(f"Match found for unknown diag layer type "
+                  f"{type(matcher.matching_variant).__name__}")
+    else:
+        print("No matching base- or ECU variant found")
+    ```
+
+    TODO: Note that only patterns that exclusivly reference diagnostic
+    services (i.e., no single-ECU jobs) in their matching parameters
+    are currently supported.
+    """
+
+    class State(Enum):
+        PENDING = 0
+        NO_MATCH = 1
+        MATCH = 2
+
+    def __init__(self,
+                 variant_candidates: Union[List[EcuVariant], List[BaseVariant]],
+                 use_cache: bool = True):
+
+        self.variant_candidates = variant_candidates
+        self.use_cache = use_cache
+        self.req_resp_cache: Dict[bytes, bytes] = {}
+        self._recent_ident_response: Optional[bytes] = None
+
+        self._state = VariantMatcher.State.PENDING
+        self._matching_variant: Optional[Union[EcuVariant, BaseVariant]] = None
+
+    def request_loop(self) -> Generator[Tuple[bool, bytes], None, None]:
+        """The request loop yielding tuples of byte sequences of
+        requests and the whether physical addressing ought to be used
+        to send them
+
+        Each of these requests needs to be send to the ECU to be
+        identified using the specified addressing scheme. The response
+        of the ECU is then required to be passed to the matcher using
+        the `evaluate()` method.
+        """
+        from .basevariantpattern import BaseVariantPattern
+        from .ecuvariantpattern import EcuVariantPattern
+        from .matchingbasevariantparameter import MatchingBaseVariantParameter
+
+        if not self.is_pending():
+            return
+
+        self._matching_variant = None
+        for variant in self.variant_candidates:
+            variant_patterns: Union[List[EcuVariantPattern], List[BaseVariantPattern]]
+            if isinstance(variant, EcuVariant):
+                variant_patterns = variant.ecu_variant_patterns
+            elif isinstance(variant, BaseVariant):
+                if variant.base_variant_pattern is None:
+                    variant_patterns = []
+                else:
+                    variant_patterns = [variant.base_variant_pattern]
+            else:
+                odxraise(f"Only EcuVariant and BaseVariant are supported "
+                         f"for pattern matching, not {type(self).__name__}")
+                self._state = VariantMatcher.State.NO_MATCH
+                return
+
+            any_pattern_matches = False
+            for pattern in variant_patterns:
+                all_params_match = True
+                for matching_param in pattern.get_matching_parameters():
+                    req_bytes = matching_param.get_ident_service(variant).encode_request()
+
+                    if self.use_cache and req_bytes in self.req_resp_cache:
+                        resp_values = copy(self.req_resp_cache[req_bytes])
+                    else:
+                        if isinstance(matching_param, MatchingBaseVariantParameter):
+                            yield matching_param.use_physical_addressing, req_bytes
+                        else:
+                            yield True, req_bytes
+                        resp_values = self._get_ident_response()
+                        self._update_cache(req_bytes, copy(resp_values))
+
+                    cur_response_matches = self._ident_response_matches(
+                        variant, matching_param, resp_values)
+                    all_params_match = all_params_match and cur_response_matches
+                    if not all_params_match:
+                        break
+
+                if all_params_match:
+                    any_pattern_matches = True
+                    break
+
+            if any_pattern_matches:
+                self._state = VariantMatcher.State.MATCH
+                self._matching_variant = variant
+                break
+
+        if self.is_pending():
+            # no pattern has matched for any ecu variant
+            self._state = VariantMatcher.State.NO_MATCH
+
+    def evaluate(self, resp_bytes: bytes) -> None:
+        """Update the matcher with the response to a requst.
+
+        Warning: Use this method EXACTLY once within the loop body of the request loop.
+        """
+        self._recent_ident_response = bytes(resp_bytes)
+
+    def is_pending(self) -> bool:
+        """True iff request loop has not yet been run."""
+        return self._state == VariantMatcher.State.PENDING
+
+    def has_match(self) -> bool:
+        """Returns true iff the non-pending matcher found a matching ecu variant.
+
+        Raises a runtime error if the matcher is pending.
+        """
+        if self.is_pending():
+            raise RuntimeError(
+                "EcuVariantMatcher is pending. Run the request_loop to determine the active ecu variant."
+            )
+        return self._state == VariantMatcher.State.MATCH
+
+    @property
+    def matching_variant(self) -> Optional[Union[EcuVariant, BaseVariant]]:
+        """Returns the matched, i.e., active ecu variant if such a variant has been found."""
+        return self._matching_variant
+
+    def _ident_response_matches(
+        self,
+        variant: Union[EcuVariant, BaseVariant],
+        matching_param: MatchingParameter,
+        response_bytes: bytes,
+    ) -> bool:
+        """Decode a binary response and extract the identification string according
+        to the snref or snpathref of the matching_param.
+        """
+        service = matching_param.get_ident_service(variant)
+
+        # ISO 22901 requires that snref or snpathref is resolvable in
+        # at least one POS-RESPONSE or NEG-RESPONSE
+        all_responses: List[Response] = []
+        all_responses.extend(service.positive_responses)
+        all_responses.extend(service.negative_responses)
+        all_responses.extend(variant.global_negative_responses)
+
+        for cur_response in all_responses:
+            try:
+                decoded_vals = cur_response.decode(response_bytes)
+            except DecodeError:
+                # the current response object could not decode the received
+                # data. Ignore it.
+                continue
+
+            if not matching_param.matches(decoded_vals):
+                # This particular response object does not match the
+                # expected value of the specified matching
+                # parameter. Ignore it.
+                continue
+
+            return True
+
+        return False
+
+    def _update_cache(self, req_bytes: bytes, resp_bytes: bytes) -> None:
+        if self.use_cache:
+            self.req_resp_cache[req_bytes] = resp_bytes
+
+    def _get_ident_response(self) -> bytes:
+        if not self._recent_ident_response:
+            raise RuntimeError(
+                "No response available. Did you forget to call 'evaluate()' in a loop?")
+        return self._recent_ident_response

odxtools/variantpattern.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Union
+from xml.etree import ElementTree
+
+from .exceptions import odxraise
+from .matchingparameter import MatchingParameter
+from .odxlink import OdxDocFragment
+
+if TYPE_CHECKING:
+    from .matchingbasevariantparameter import MatchingBaseVariantParameter
+    from .matchingparameter import MatchingParameter
+
+
+@dataclass
+class VariantPattern:
+    """Variant patterns are used to identify the concrete variant of an ECU
+
+    This is done by observing the responses after sending it some
+    requests. There are two kinds of variant patterns:
+    `BaseVariantPattern`s which are used to identify the applicable
+    base variant and ECU variant patterns which can be used identify
+    concrete revisions of the ECU in question. (Both types of pattern
+    are optional, i.e., it might not be possible to identify the base-
+    or ECU variant present.)
+    """
+
+    def get_matching_parameters(
+            self) -> Union[List["MatchingParameter"], List["MatchingBaseVariantParameter"]]:
+        odxraise(
+            f"VariantPattern subclass `{type(self).__name__}` does not "
+            f"implement `.get_match_parameters()`", RuntimeError)
+        return []
+
+    @staticmethod
+    def from_et(et_element: ElementTree.Element,
+                doc_frags: List[OdxDocFragment]) -> "VariantPattern":
+        return VariantPattern()

odxtools/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '9.4.1'
-__version_tuple__ = version_tuple = (9, 4, 1)
+__version__ = version = '9.6.0'
+__version_tuple__ = version_tuple = (9, 6, 0)

{odxtools-9.4.1.dist-info → odxtools-9.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: odxtools
-Version: 9.4.1
+Version: 9.6.0
 Summary: Utilities to work with the ODX standard for automotive diagnostics
 Author-email: Katrin Bauer <katrin.bauer@mbition.io>, Andreas Lauser <andreas.lauser@mbition.io>, Ayoub Kaanich <kayoub5@live.com>
 Maintainer-email: Andreas Lauser <andreas.lauser@mbition.io>, Ayoub Kaanich <kayoub5@live.com>
@@ -43,6 +43,7 @@ Provides-Extra: examples
 Requires-Dist: can-isotp>=1.9; extra == "examples"
 Provides-Extra: all
 Requires-Dist: odxtools[browse-tool,examples,test]; extra == "all"
+Dynamic: license-file
 
 <!-- SPDX-License-Identifier: MIT -->
 [![PyPi - Version](https://img.shields.io/pypi/v/odxtools)](https://pypi.org/project/odxtools)