fix: Add 'UdsAuxiliary.send_uds' with clearer return type to replace 'send_uds_raw' (#561)

Author: thc3si

.gitignore

@@ -43,6 +43,7 @@ pip-delete-this-directory.txt
 # other logs
 *.log
 *.trc
+BrainStemLog.txt
 
 # Unit test / coverage reports
 htmlcov/

docs/modules_usage/uds_auxiliary.rst

@@ -26,7 +26,7 @@ Find below a complete configuration example :
             com: can_channel
         config:
           # you can specify your odx file by using odx_file_path parameter
-          # and instead of using send_uds_raw method use the send_uds_config
+          # and instead of using send_uds method use the send_uds_config
           # for a more human readable command
           odx_file_path: null
           request_id : 0x123
@@ -75,14 +75,10 @@ Send UDS Raw Request
 
 Send UDS request as list of raw bytes.
 
-The method send_uds_raw(:py:meth:`pykiso.lib.auxiliaries.udsaux.UdsAuxiliary.send_uds_raw`) takes one mandatory parameter msg_to_send and one optional : timeout_in_s
+The method send_uds(:py:meth:`pykiso.lib.auxiliaries.udsaux.UdsAuxiliary.send_uds`) takes one mandatory parameter msg_to_send
 The parameter msg_to_send is simply the UDS request payload which is a list of bytes.
 
-The optional parameter timeout_in_s (by default fixed to 5 seconds) simply represent the maximum
-amount of time in second to wait for a response from the device under test. If this timeout is reached, the
-uds-auxiliary stop to acquire and log an error.
-
-The method send_uds_raw method returns a :py:class:`~ebplugins.udsaux.uds_response.UdsResponse` object, which is a subclass of `UserList
+The method send_uds method returns a :py:class:`~ebplugins.udsaux.uds_response.UdsResponse` object, which is a subclass of `UserList
 <https://docs.python.org/3/library/collections.html#collections.UserList>`_.
 UserList allow to keep property of the list, meanwhile attributes can be set, for UdsResponse, defined attributes
 refer to the positivity of the response, and its NRC if negative.
@@ -117,7 +113,7 @@ Here is an example:
 
         def test_run(self):
             # Set extended session
-            diag_session_response = uds_aux.send_uds_raw([0x10, 0x03])
+            diag_session_response = uds_aux.send_uds([0x10, 0x03])
             self.assertEqual(diag_session_response[:2], [0x50, 0x03])
             self.assertEqual(type(diag_session_response), UserList)
             self.assertFalse(diag_session_response.is_negative)

docs/whats_new/version_1_6_0.rst

@@ -0,0 +1,19 @@
+Version 1.6.0
+-------------
+
+Better return type when sending UDS messages
+^^^^^^^^^^^^^^^^^
+
+New method `UdsAuxiliary.send_uds`, available in two versions (`typing.overload`):
+- when expecting a response (`response_required=True`) from remote component, returns the response,
+or fails with an exception
+- otherwise, return `None`, or fail with an exception
+
+This is more in line with what exising clients expected.
+
+The previous version of this method, `UdsAuxiliary.send_uds_raw`, has been kept with the same API,
+for backwards compatibility: return `False` on error, unless the error is because no response
+was received while one was expected, in which case a `ReponseNotReceivedException` is raised.
+
+
+See :ref:`uds_server_auxiliary`

examples/uds.yaml

@@ -4,7 +4,7 @@ auxiliaries:
         com: can_channel
     config:
       # you can specify your odx file by using odx_file_path parameter
-      # and instead of using send_uds_raw method use the send_uds_config
+      # and instead of using send_uds method use the send_uds_config
       # for a more human readable command
       odx_file_path: ~
       request_id : 0x123

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pykiso"
-version = "1.5.2"
+version = "1.6.0"
 description = "Embedded integration testing framework."
 authors = ["Sebastian Fischer <sebastian.fischer@de.bosch.com>"]
 license = "Eclipse Public License - v 2.0"

src/pykiso/lib/auxiliaries/udsaux/uds_auxiliary.py

@@ -23,7 +23,7 @@
 import time
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Iterator, List, Optional, Union
+from typing import Iterator, List, Literal, Optional, Union, overload
 
 try:
     import can
@@ -90,26 +90,46 @@ def transmit(self, data: bytes, req_id: int, extended: bool = False) -> None:
         """
         self.channel._cc_send(msg=data, remote_id=req_id)
 
-    def send_uds_raw(
+    # Response is required, it is returned
+    @overload
+    def send_uds(
+        self,
+        msg_to_send: Union[bytes, List[int], tuple],
+    ) -> UdsResponse:
+        ...  # pragma: no cover
+
+    # Response is required, it is returned (explicit alias kept for backwards compatibility)
+    @overload
+    def send_uds(
+        self,
+        msg_to_send: Union[bytes, List[int], tuple],
+        response_required: Literal[True] = True,
+    ) -> UdsResponse:
+        ...  # pragma: no cover
+
+    # Response ignored, `None` is returned
+    @overload
+    def send_uds(
+        self,
+        msg_to_send: Union[bytes, List[int], tuple],
+        response_required: Literal[False] = False,
+    ) -> None:
+        ...  # pragma: no cover
+
+    def send_uds(
         self,
         msg_to_send: Union[bytes, List[int], tuple],
-        timeout_in_s: float = 6,
         response_required: bool = True,
-    ) -> Union[UdsResponse, bool]:
+    ) -> Union[UdsResponse, None]:
         """Send a UDS diagnostic request to the target ECU and check response.
 
         :param msg_to_send: can uds raw bytes to be sent
-        :param timeout_in_s: not used, actual timeout in seconds for the response can be
-            configured with the uds_aux.config.uds_layer.p2_can_client parameter
-            inside the yaml config file. (default value is 5s)
         :param response_required: Wait for a response if True
 
         :raise ResponseNotReceivedError: raised when no answer has been received
         :raise Exception: raised when the raw message could not be send properly
 
-        :return: the raw uds response's bytes, or True if a response is
-            not expected and the command is properly sent otherwise
-            False
+        :return: the raw uds response's bytes if `response_required` is set, else None
         """
         try:
             if log.isEnabledFor(logging.getLogger().level):
@@ -122,13 +142,13 @@ def send_uds_raw(
                 responseRequired=response_required,
                 tpWaitTime=self.tp_waiting_time,
             )
-        except Exception:
+        except Exception as exc:
             log.exception("Error while sending uds raw request")
-            return False
+            raise exc
 
         if resp is None:
             if not response_required:
-                return True
+                return
             else:
                 raise self.errors.ResponseNotReceivedError(msg_to_send)
 
@@ -140,6 +160,35 @@ def send_uds_raw(
         log.internal_info("UDS response received %s", resp)
         return resp
 
+    def send_uds_raw(
+        self,
+        msg_to_send: Union[bytes, List[int], tuple],
+        timeout_in_s: float = 6,
+        response_required: bool = True,
+    ) -> Union[UdsResponse, bool]:
+        """Send a UDS diagnostic request to the target ECU and check response.
+        Deprecated alias of `send_uds` that returns `False` on error,
+        kept for backwards compatibility
+
+        :param msg_to_send: can uds raw bytes to be sent
+        :param timeout_in_s: not used, actual timeout in seconds for the response can be
+            configured with the uds_aux.config.uds_layer.p2_can_client parameter
+            inside the yaml config file. (default value is 5s)
+        :param response_required: Wait for a response if True
+
+        :raise ResponseNotReceivedError: raised when no answer has been received
+
+        :return: the raw uds response's bytes, or True if a response is
+            not expected and the command is properly sent otherwise
+            False
+        """
+        try:
+            return True if (response := self.send_uds(msg_to_send, response_required)) is None else response
+        except self.errors.ResponseNotReceivedError as exc:
+            raise exc
+        except Exception:
+            return False
+
     @staticmethod
     def check_max_pending_time(resp: UdsResponse, max_pending_time: float) -> bool:
         """Check that the time between pending response messages does not exceed a