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

odxtools/preconditionstateref.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from xml.etree import ElementTree
+
+from .exceptions import odxassert, odxrequire
+from .odxlink import OdxDocFragment, OdxLinkDatabase, OdxLinkId, OdxLinkRef
+from .odxtypes import ParameterValueDict
+from .parameters.parameter import Parameter
+from .snrefcontext import SnRefContext
+from .state import State
+from .statetransitionref import _check_applies
+from .utils import dataclass_fields_asdict
+
+if TYPE_CHECKING:
+    from .statemachine import StateMachine
+
+
+@dataclass
+class PreConditionStateRef(OdxLinkRef):
+    """
+    This class represents the PRE-CONDITION-STATE-REF XML tag.
+    """
+    value: Optional[str]
+
+    in_param_if_snref: Optional[str]
+    in_param_if_snpathref: Optional[str]
+
+    @property
+    def state(self) -> "State":
+        return self._state
+
+    @staticmethod
+    def from_et(  # type: ignore[override]
+            et_element: ElementTree.Element,
+            doc_frags: List[OdxDocFragment]) -> "PreConditionStateRef":
+        kwargs = dataclass_fields_asdict(OdxLinkRef.from_et(et_element, doc_frags))
+
+        value = et_element.findtext("VALUE")
+
+        in_param_if_snref = None
+        if (in_param_if_snref_elem := et_element.find("IN-PARAM-IF-SNREF")) is not None:
+            in_param_if_snref = odxrequire(in_param_if_snref_elem.get("SHORT-NAME"))
+
+        in_param_if_snpathref = None
+        if (in_param_if_snpathref_elem := et_element.find("IN-PARAM-IF-SNPATHREF")) is not None:
+            in_param_if_snpathref = odxrequire(in_param_if_snpathref_elem.get("SHORT-NAME-PATH"))
+
+        return PreConditionStateRef(
+            value=value,
+            in_param_if_snref=in_param_if_snref,
+            in_param_if_snpathref=in_param_if_snpathref,
+            **kwargs)
+
+    def __post_init__(self) -> None:
+        if self.value is not None:
+            odxassert(self.in_param_if_snref is not None or self.in_param_if_snref is not None,
+                      "If VALUE is specified, a parameter must be referenced")
+
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        return {}
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        self._state = odxlinks.resolve(self, State)
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        pass
+
+    def applies(self, state_machine: "StateMachine", params: List[Parameter],
+                param_value_dict: ParameterValueDict) -> bool:
+        """Given a state machine, evaluate whether the precondition is fulfilled or not
+
+        Note that the specification is unclear about what the
+        parameters are: It says "The optional VALUE together with the
+        also optional IN-PARAM-IF snref at STATE-TRANSITION-REF and
+        PRE-CONDITION-STATE-REF can be used if the STATE-TRANSITIONs
+        and pre-condition STATEs are dependent on the values of the
+        referenced PARAMs.", but it does not specify what the
+        "referenced PARAMs" are. For the state transition refs, let's
+        assume that they are the parameters of a positive response
+        received from the ECU, whilst we assume that they are the
+        parameters of the request for PRE-CONDITION-STATE-REFs.
+        """
+
+        return _check_applies(self, state_machine, params, param_value_dict)

odxtools/progcode.py

@@ -31,7 +31,6 @@ class ProgCode:
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "ProgCode":
         code_file = odxrequire(et_element.findtext("CODE-FILE"))
-
         encryption = et_element.findtext("ENCRYPTION")
         syntax = odxrequire(et_element.findtext("SYNTAX"))
         revision = odxrequire(et_element.findtext("REVISION"))
@@ -44,9 +43,9 @@ class ProgCode:
 
         return ProgCode(
             code_file=code_file,
+            encryption=encryption,
             syntax=syntax,
             revision=revision,
-            encryption=encryption,
             entrypoint=entrypoint,
             library_refs=library_refs,
         )

odxtools/protstack.py

@@ -19,6 +19,10 @@ class ProtStack(IdentifiableElement):
     physical_link_type: str
     comparam_subset_refs: List[OdxLinkRef]
 
+    @property
+    def comparam_subsets(self) -> NamedItemList[ComparamSubset]:
+        return self._comparam_subsets
+
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "ProtStack":
         kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
@@ -47,7 +51,3 @@ class ProtStack(IdentifiableElement):
 
     def _resolve_snrefs(self, context: SnRefContext) -> None:
         pass
-
-    @property
-    def comparam_subsets(self) -> NamedItemList[ComparamSubset]:
-        return self._comparam_subsets

odxtools/relateddoc.py

@@ -11,20 +11,19 @@ from .xdoc import XDoc
 
 @dataclass
 class RelatedDoc:
-    description: Optional[Description]
     xdoc: Optional[XDoc]
+    description: Optional[Description]
 
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "RelatedDoc":
-        description = Description.from_et(et_element.find("DESC"), doc_frags)
-
         xdoc: Optional[XDoc] = None
         if (xdoc_elem := et_element.find("XDOC")) is not None:
             xdoc = XDoc.from_et(xdoc_elem, doc_frags)
+        description = Description.from_et(et_element.find("DESC"), doc_frags)
 
         return RelatedDoc(
-            description=description,
             xdoc=xdoc,
+            description=description,
         )
 
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:

odxtools/scaleconstr.py

@@ -35,7 +35,6 @@ class ScaleConstr:
                              value_type: DataType) -> "ScaleConstr":
         short_label = et_element.findtext("SHORT-LABEL")
         description = Description.from_et(et_element.find("DESC"), doc_frags)
-
         lower_limit = Limit.limit_from_et(
             odxrequire(et_element.find("LOWER-LIMIT")), doc_frags, value_type=value_type)
         upper_limit = Limit.limit_from_et(

odxtools/singleecujob.py

@@ -18,12 +18,16 @@ from .utils import dataclass_fields_asdict
 class SingleEcuJob(DiagComm):
     """A single ECU job is a diagnostic communication primitive.
 
-    A single ECU job is more complex than a diagnostic service and is not provided natively by the ECU.
-    In particular, the job is defined in external programs which are referenced by the attribute `.prog_codes`.
+    A single ECU job is more complex than a diagnostic service and is
+    not provided natively by the ECU.  In particular, the job is
+    defined in external programs which are referenced by the attribute
+    `.prog_codes`.
 
-    In contrast to "multiple ECU jobs", a single ECU job only does service calls to a single ECU.
+    In contrast to "multiple ECU jobs", a single ECU job only involves
+    calls to services provided by a single ECU.
 
-    Single ECU jobs are defined in section 7.3.5.7 of the ASAM MCD-2 standard.
+    Single ECU jobs are defined in section 7.3.5.7 of the ASAM MCD-2
+    standard.
     """
 
     prog_codes: List[ProgCode]

odxtools/specialdata.py

@@ -9,19 +9,11 @@ from .snrefcontext import SnRefContext
 
 @dataclass
 class SpecialData:
+    """This corresponds to the SD XML tag"""
     semantic_info: Optional[str]  # the "SI" attribute
     text_identifier: Optional[str]  # the "TI" attribute, specifies the language used
     value: str
 
-    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
-        return {}
-
-    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
-        pass
-
-    def _resolve_snrefs(self, context: SnRefContext) -> None:
-        pass
-
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "SpecialData":
         semantic_info = et_element.get("SI")
@@ -30,3 +22,12 @@ class SpecialData:
 
         return SpecialData(
             semantic_info=semantic_info, text_identifier=text_identifier, value=value)
+
+    def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
+        return {}
+
+    def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        pass
+
+    def _resolve_snrefs(self, context: SnRefContext) -> None:
+        pass

odxtools/specialdatagroup.py

@@ -11,6 +11,7 @@ from .specialdatagroupcaption import SpecialDataGroupCaption
 
 @dataclass
 class SpecialDataGroup:
+    """This corresponds to the SDG XML tag"""
     sdg_caption: Optional[SpecialDataGroupCaption]
     sdg_caption_ref: Optional[OdxLinkRef]
     values: List[Union["SpecialDataGroup", SpecialData]]

odxtools/standardlengthtype.py

@@ -3,14 +3,14 @@ from dataclasses import dataclass
 from typing import List, Literal, Optional
 from xml.etree import ElementTree
 
-from typing_extensions import SupportsBytes, override
+from typing_extensions import override
 
 from .decodestate import DecodeState
 from .diagcodedtype import DctType, DiagCodedType
 from .encodestate import EncodeState
 from .exceptions import odxassert, odxraise, odxrequire
 from .odxlink import OdxDocFragment
-from .odxtypes import AtomicOdxType, DataType, odxstr_to_bool
+from .odxtypes import AtomicOdxType, BytesTypes, DataType, odxstr_to_bool
 from .utils import dataclass_fields_asdict
 
 
@@ -21,6 +21,14 @@ class StandardLengthType(DiagCodedType):
     bit_mask: Optional[int]
     is_condensed_raw: Optional[bool]
 
+    @property
+    def dct_type(self) -> DctType:
+        return "STANDARD-LENGTH-TYPE"
+
+    @property
+    def is_condensed(self) -> bool:
+        return self.is_condensed_raw is True
+
     @staticmethod
     @override
     def from_et(et_element: ElementTree.Element,
@@ -43,14 +51,6 @@ class StandardLengthType(DiagCodedType):
         return StandardLengthType(
             bit_length=bit_length, bit_mask=bit_mask, is_condensed_raw=is_condensed_raw, **kwargs)
 
-    @property
-    def dct_type(self) -> DctType:
-        return "STANDARD-LENGTH-TYPE"
-
-    @property
-    def is_condensed(self) -> bool:
-        return self.is_condensed_raw is True
-
     def __post_init__(self) -> None:
         if self.bit_mask is not None:
             maskable_types = (DataType.A_UINT32, DataType.A_INT32, DataType.A_BYTEFIELD)
@@ -91,7 +91,7 @@ class StandardLengthType(DiagCodedType):
             return used_mask.to_bytes((bit_sz + 7) // 8, endianness)
 
         sz: int
-        if isinstance(internal_value, (bytearray, SupportsBytes)):
+        if isinstance(internal_value, BytesTypes):
             sz = len(bytes(internal_value))
         else:
             sz = (odxrequire(self.get_static_bit_length()) + 7) // 8
@@ -107,7 +107,7 @@ class StandardLengthType(DiagCodedType):
 
         if self.is_condensed:
             int_value: int
-            if isinstance(internal_value, (bytearray, SupportsBytes)):
+            if isinstance(internal_value, BytesTypes):
                 int_value = int.from_bytes(internal_value, 'big')
             elif isinstance(internal_value, int):
                 int_value = internal_value
@@ -126,14 +126,14 @@ class StandardLengthType(DiagCodedType):
 
                 mask_bit += 1
 
-            if isinstance(internal_value, (bytearray, SupportsBytes)):
+            if isinstance(internal_value, BytesTypes):
                 return result.to_bytes(len(internal_value), 'big')
 
             return result
 
         if isinstance(internal_value, int):
             return internal_value & self.bit_mask
-        if isinstance(internal_value, (bytearray, SupportsBytes)):
+        if isinstance(internal_value, BytesTypes):
             int_value = int.from_bytes(internal_value, 'big')
             int_value &= self.bit_mask
             return int_value.to_bytes(len(bytes(internal_value)), 'big')
@@ -146,7 +146,7 @@ class StandardLengthType(DiagCodedType):
             return raw_value
         if self.is_condensed:
             int_value: int
-            if isinstance(raw_value, (bytearray, SupportsBytes)):
+            if isinstance(raw_value, BytesTypes):
                 int_value = int.from_bytes(raw_value, 'big')
             elif isinstance(raw_value, int):
                 int_value = raw_value
@@ -164,16 +164,16 @@ class StandardLengthType(DiagCodedType):
 
                 mask_bit += 1
 
-            if isinstance(raw_value, (bytearray, SupportsBytes)):
+            if isinstance(raw_value, BytesTypes):
                 return result.to_bytes(len(raw_value), 'big')
 
             return result
         if isinstance(raw_value, int):
             return raw_value & self.bit_mask
-        if isinstance(raw_value, (bytearray, SupportsBytes)):
+        if isinstance(raw_value, BytesTypes):
             int_value = int.from_bytes(raw_value, 'big')
             int_value &= self.bit_mask
-            return int_value
+            return int_value.to_bytes(len(raw_value), 'big')
 
         odxraise(f'Can not apply a bit_mask on a value of type {type(raw_value)}')
         return raw_value

odxtools/statechart.py

@@ -30,6 +30,7 @@ class StateChart(IdentifiableElement):
     @staticmethod
     def from_et(et_element: ElementTree.Element, doc_frags: List[OdxDocFragment]) -> "StateChart":
         kwargs = dataclass_fields_asdict(IdentifiableElement.from_et(et_element, doc_frags))
+
         semantic: str = odxrequire(et_element.findtext("SEMANTIC"))
 
         state_transitions = [
@@ -54,15 +55,18 @@ class StateChart(IdentifiableElement):
     def _build_odxlinks(self) -> Dict[OdxLinkId, Any]:
         odxlinks = {self.odx_id: self}
 
-        for st in self.states:
-            odxlinks.update(st._build_odxlinks())
-
         for strans in self.state_transitions:
             odxlinks.update(strans._build_odxlinks())
 
+        for st in self.states:
+            odxlinks.update(st._build_odxlinks())
+
         return odxlinks
 
     def _resolve_odxlinks(self, odxlinks: OdxLinkDatabase) -> None:
+        for strans in self.state_transitions:
+            strans._resolve_odxlinks(odxlinks)
+
         for st in self.states:
             st._resolve_odxlinks(odxlinks)
 
@@ -77,10 +81,10 @@ class StateChart(IdentifiableElement):
         # does that mean?
         self._start_state = resolve_snref(self.start_state_snref, self.states, State)
 
-        for st in self.states:
-            st._resolve_snrefs(context)
-
         for strans in self.state_transitions:
             strans._resolve_snrefs(context)
 
+        for st in self.states:
+            st._resolve_snrefs(context)
+
         context.state_chart = None

odxtools/statemachine.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: MIT
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generator, Union
+
+from .exceptions import odxraise
+from .odxtypes import ParameterValueDict
+from .state import State
+from .statechart import StateChart
+
+if TYPE_CHECKING:
+    from .diaglayers.diaglayer import DiagLayer
+    from .diagservice import DiagService
+
+
+@dataclass
+class StateMachine:
+    """Objects of this class represent the runtime state of a state chart
+
+    It is used to track which services can be executed at a given time.
+
+    Usage example (using asynchronous communication routines):
+
+    ```python
+    ecu = db.ecu_variants.my_ecu_variant
+    fsm = StateMachine(ecu, ecu.state_charts.my_state_chart)
+
+    for raw_request in (executor := fsm.execute(ecu.services.my_service,
+                                                param1="hello",
+                                                param2=123)):
+        # send raw request to the ECU (usually using ISO-TP or DoIP), and
+        # receive the response
+        await send_to_ecu(raw_request)
+        while odxtools.is_response_pending(raw_response := await receive_from_ecu()):
+            pass
+
+        executor.send(raw_response)
+
+    print(f"Request send: {fsm.succeeded}")
+    ```
+
+    Alternatively, more of the glue functionality can be handled by
+    the calling code:
+
+    ```python
+
+    ecu = db.ecu_variants.my_ecu_variant
+    fsm = StateMachine(ecu, ecu.state_charts.my_state_chart)
+
+    service = ecu.services.my_service
+    request_param_values = { "param1": "hello", "param2":123 }
+    if any(pcs.applies(fsm, service.request.parameters, **request_param_values)
+           for pcs in service.pre_condition_states):
+
+        # send raw request to the ECU (usually using ISO-TP or DoIP), and
+        # receive the response
+        raw_req = service.request.encode(**request_param_values)
+        await send_data_to_ecu(raw_req)
+        while odxtools.is_response_pending(raw_resp := await receive_from_ecu()):
+            pass
+
+        done = False
+        for decoded_resp_msg in ecu.decode_response(raw_resp, raw_req):
+            for stransref in service.state_transition_refs:
+                if stransref.execute(decoded_resp.parameters, decoded_resp_msg.param_dict):
+                   done = True
+                   break
+            if done:
+               break
+    else:
+        raise RuntimeException(f"Cannot execute request for service {service.short_name}")
+    ```
+
+    """
+
+    succeeded: bool
+
+    @property
+    def diag_layer(self) -> "DiagLayer":
+        return self._diag_layer
+
+    @property
+    def state_chart(self) -> StateChart:
+        return self._state_chart
+
+    @property
+    def active_state(self) -> State:
+        return self._active_state
+
+    @active_state.setter
+    def active_state(self, value: State) -> None:
+        self._active_state = value
+
+    def __init__(self, diag_layer: "DiagLayer", state_chart: StateChart) -> None:
+        self.succeeded = True
+        self._diag_layer = diag_layer
+        self._state_chart = state_chart
+        self._active_state = state_chart.start_state
+
+    def execute(self, service: "DiagService", **service_params: Any
+               ) -> Generator[bytes, Union[bytes, bytearray, ParameterValueDict], None]:
+        """Run a diagnostic service and update the state machine
+        depending on the outcome.
+
+        This simplifies error handling, en- and decoding etc.
+
+        Usage example (using asynchronous communication routines):
+
+        ```python
+        ecu = db.ecu_variants.my_ecu_variant
+        fsm = StateMachine(ecu, ecu.state_charts.my_state_chart)
+
+        for raw_request in (executor := fsm.execute(ecu.services.my_service,
+                                                    param1="hello",
+                                                    param2=123)):
+            # send raw request to the ECU (usually using ISO-TP or DoIP), and
+            # receive the response
+            await send_to_ecu(raw_request)
+            while odxtools.is_response_pending(raw_response := await receive_from_ecu()):
+                pass
+
+            executor.send(raw_response)
+
+        print(f"Request send: {fsm.succeeded}")
+        ```
+
+        """
+        if service.request is None:
+            odxraise("Services without requests are not allowed in this context")
+            self.succeeded = False
+            return
+
+        # the service can be executed if any of the specified
+        # precondition states is fulfilled. (TODO: correct?)
+        if service.pre_condition_state_refs is not None:
+            if not any(
+                    x.applies(self, service.request.parameters, service_params)
+                    for x in service.pre_condition_state_refs):
+                # if all preconditions which are applicable are
+                # invalid (i.e., they evaluate to False), we must not
+                # execute the service.
+                self.succeeded = False
+                return
+
+        raw_req = service.request.encode(**service_params)
+        # ask the calling code to send the request to the ECU and
+        # report back the reply
+        raw_resp = yield raw_req
+
+        decoded_req_params = service.request.decode(raw_req)
+        for stransref in service.state_transition_refs:
+            # check if the state transition applies for the
+            # request. Note that the ODX specification is unclear
+            # about which kind of parameters are relevant for
+            # STATE-TRANSITION-REF
+            if stransref.execute(self, service.request.parameters, decoded_req_params):
+                self.succeeded = True
+                yield b''
+                return
+
+        if raw_resp is None:
+            raise RuntimeError("The calling code must send back a reply")
+        elif isinstance(raw_resp, (bytes, bytearray)):
+            for decoded_resp_msg in self.diag_layer.decode_response(raw_resp, raw_req):
+                for stransref in service.state_transition_refs:
+                    # we only execute the first applicable state
+                    # transition: The spec seems to imply a
+                    # deterministic state machine and chaining
+                    # transistions most likely is not what the user
+                    # expects. (The spec seems to be a bit loose on
+                    # this front...)
+                    if stransref.execute(self, decoded_resp_msg.coding_object.parameters,
+                                         decoded_resp_msg.param_dict):
+                        self.succeeded = True
+                        yield b''
+                        return
+        else:
+            resp_object = service.positive_responses[0]
+            for stransref in service.state_transition_refs:
+                if stransref.execute(self, resp_object.parameters, raw_resp):
+                    self.succeeded = True
+                    yield b''
+                    return
+
+        self.succeeded = True
+        yield b''
+        return