PyOpenocdClient 0.1.1__tar.gz → 0.2.0__tar.gz

{pyopenocdclient-0.1.1/src/PyOpenocdClient.egg-info → pyopenocdclient-0.2.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: PyOpenocdClient
-Version: 0.1.1
+Version: 0.2.0
 Summary: Library for controlling OpenOCD from Python programs
 Author-email: Jan Matyas <info@janmatyas.net>
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/HonzaMat/PyOpenocdClient
 Project-URL: Issues, https://github.com/HonzaMat/PyOpenocdClient/issues
 Project-URL: Documentation, https://pyopenocdclient.readthedocs.io/en/latest/
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -24,11 +24,13 @@ Dynamic: license-file
 **PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
 software tool.
 
-It allows to send TCL commands from Python programs to OpenOCD &mdash; for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+It allows to send Tcl commands from Python programs to OpenOCD &mdash; for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+
+In addition, a console utility is included with PyOpenocdClient that can be used to send Tcl commands to OpenOCD from non-Python software, such as shell scripts.
 
 Main features of PyOpenocdClient:
 
-* allow to send any TCL command to OpenOCD and obtain its result;
+* you can send any Tcl command to OpenOCD and obtain its result;
 
 * shorcuts for quick use of most common OpenOCD commands are provided;
 
@@ -36,11 +38,11 @@ Main features of PyOpenocdClient:
 
 * the code is fully covered via unit tests;
 
-* automatic integration testing against multiple versions of OpenOCD;
+* integration testing regularly runs against multiple versions of OpenOCD;
 
 * the code is multiplatform and portable &mdash; it does not have any dependencies except for the Python's standard library;
 
-* fully open-source under a permissive license (MIT license).
+* the library is fully open-source under a permissive license (MIT license).
 
 
 ## Quick instructions
@@ -51,7 +53,7 @@ Install PyOpenocdClient package using Pip:
 $ python3 -m pip install PyOpenocdClient
 ```
 
-Basic usage:
+Basic usage from Python:
 
 ```python
 from py_openocd_client import PyOpenocdClient
@@ -64,6 +66,18 @@ with PyOpenocdClient(host="localhost", port=6666) as ocd:
     # ...
 ```
 
+Basic usage from a command-line or shell scripts:
+
+```bash
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 version
+Open On-Chip Debugger 0.12.0+dev-02634-g390b9d731 (2026-08-29-14:15)
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 "reset halt ; reg pc"
+pc (/32): 0x08001234
+
+```
+
 ## Documentation
 
 For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/README.md

@@ -8,11 +8,13 @@
 **PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
 software tool.
 
-It allows to send TCL commands from Python programs to OpenOCD — for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+It allows to send Tcl commands from Python programs to OpenOCD — for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+
+In addition, a console utility is included with PyOpenocdClient that can be used to send Tcl commands to OpenOCD from non-Python software, such as shell scripts.
 
 Main features of PyOpenocdClient:
 
-* allow to send any TCL command to OpenOCD and obtain its result;
+* you can send any Tcl command to OpenOCD and obtain its result;
 
 * shorcuts for quick use of most common OpenOCD commands are provided;
 
@@ -20,11 +22,11 @@ Main features of PyOpenocdClient:
 
 * the code is fully covered via unit tests;
 
-* automatic integration testing against multiple versions of OpenOCD;
+* integration testing regularly runs against multiple versions of OpenOCD;
 
 * the code is multiplatform and portable — it does not have any dependencies except for the Python's standard library;
 
-* fully open-source under a permissive license (MIT license).
+* the library is fully open-source under a permissive license (MIT license).
 
 
 ## Quick instructions
@@ -35,7 +37,7 @@ Install PyOpenocdClient package using Pip:
 $ python3 -m pip install PyOpenocdClient
 ```
 
-Basic usage:
+Basic usage from Python:
 
 ```python
 from py_openocd_client import PyOpenocdClient
@@ -48,6 +50,18 @@ with PyOpenocdClient(host="localhost", port=6666) as ocd:
     # ...
 ```
 
+Basic usage from a command-line or shell scripts:
+
+```bash
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 version
+Open On-Chip Debugger 0.12.0+dev-02634-g390b9d731 (2026-08-29-14:15)
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 "reset halt ; reg pc"
+pc (/32): 0x08001234
+
+```
+
 ## Documentation
 
 For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/pyproject.toml

@@ -1,19 +1,30 @@
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
 [project]
 name = "PyOpenocdClient"
-version = "0.1.1"
+version = "0.2.0"
 authors = [
   { name="Jan Matyas", email="info@janmatyas.net" },
 ]
 description = "Library for controlling OpenOCD from Python programs"
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.10"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
+license = "MIT"
 
 [project.urls]
 Homepage = "https://github.com/HonzaMat/PyOpenocdClient"
 Issues = "https://github.com/HonzaMat/PyOpenocdClient/issues"
 Documentation = "https://pyopenocdclient.readthedocs.io/en/latest/"
+
+[project.scripts]
+openocd_cmd = "py_openocd_client.cli:main"
+
+[tool.setuptools.package-data]
+py_openocd_client = ["py.typed"]

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0/src/PyOpenocdClient.egg-info}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: PyOpenocdClient
-Version: 0.1.1
+Version: 0.2.0
 Summary: Library for controlling OpenOCD from Python programs
 Author-email: Jan Matyas <info@janmatyas.net>
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/HonzaMat/PyOpenocdClient
 Project-URL: Issues, https://github.com/HonzaMat/PyOpenocdClient/issues
 Project-URL: Documentation, https://pyopenocdclient.readthedocs.io/en/latest/
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -24,11 +24,13 @@ Dynamic: license-file
 **PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
 software tool.
 
-It allows to send TCL commands from Python programs to OpenOCD &mdash; for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+It allows to send Tcl commands from Python programs to OpenOCD &mdash; for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+
+In addition, a console utility is included with PyOpenocdClient that can be used to send Tcl commands to OpenOCD from non-Python software, such as shell scripts.
 
 Main features of PyOpenocdClient:
 
-* allow to send any TCL command to OpenOCD and obtain its result;
+* you can send any Tcl command to OpenOCD and obtain its result;
 
 * shorcuts for quick use of most common OpenOCD commands are provided;
 
@@ -36,11 +38,11 @@ Main features of PyOpenocdClient:
 
 * the code is fully covered via unit tests;
 
-* automatic integration testing against multiple versions of OpenOCD;
+* integration testing regularly runs against multiple versions of OpenOCD;
 
 * the code is multiplatform and portable &mdash; it does not have any dependencies except for the Python's standard library;
 
-* fully open-source under a permissive license (MIT license).
+* the library is fully open-source under a permissive license (MIT license).
 
 
 ## Quick instructions
@@ -51,7 +53,7 @@ Install PyOpenocdClient package using Pip:
 $ python3 -m pip install PyOpenocdClient
 ```
 
-Basic usage:
+Basic usage from Python:
 
 ```python
 from py_openocd_client import PyOpenocdClient
@@ -64,6 +66,18 @@ with PyOpenocdClient(host="localhost", port=6666) as ocd:
     # ...
 ```
 
+Basic usage from a command-line or shell scripts:
+
+```bash
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 version
+Open On-Chip Debugger 0.12.0+dev-02634-g390b9d731 (2026-08-29-14:15)
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 "reset halt ; reg pc"
+pc (/32): 0x08001234
+
+```
+
 ## Documentation
 
 For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/src/PyOpenocdClient.egg-info/SOURCES.txt

@@ -4,11 +4,14 @@ pyproject.toml
 src/PyOpenocdClient.egg-info/PKG-INFO
 src/PyOpenocdClient.egg-info/SOURCES.txt
 src/PyOpenocdClient.egg-info/dependency_links.txt
+src/PyOpenocdClient.egg-info/entry_points.txt
 src/PyOpenocdClient.egg-info/top_level.txt
 src/py_openocd_client/__init__.py
 src/py_openocd_client/baseclient.py
 src/py_openocd_client/bp_parser.py
+src/py_openocd_client/cli.py
 src/py_openocd_client/client.py
 src/py_openocd_client/errors.py
+src/py_openocd_client/py.typed
 src/py_openocd_client/types.py
 src/py_openocd_client/wp_parser.py

pyopenocdclient-0.2.0/src/PyOpenocdClient.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openocd_cmd = py_openocd_client.cli:main

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/src/py_openocd_client/__init__.py

@@ -6,6 +6,7 @@ from .errors import (  # noqa: F401
     OcdCommandFailedError,
     OcdCommandTimeoutError,
     OcdConnectionError,
+    OcdEmptyResponseError,
     OcdInvalidResponseError,
 )
 from .types import BpInfo, BpType, OcdCommandResult, WpInfo, WpType  # noqa: F401

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/src/py_openocd_client/baseclient.py

@@ -94,10 +94,35 @@ class _PyOpenocdBaseClient:
             raise ValueError("Timeout must be greater than zero")
         self._default_recv_timeout = timeout
 
-    def _check_no_premature_recvd_bytes(self) -> None:
+    def _check_connection_before_command(self) -> None:
         assert self._socket is not None
         rd, _, _ = select.select([self._socket], [], [], 0)  # Don't block, just poll
-        if len(rd) > 0:
+
+        if len(rd) == 0:
+            # The socket is not ready for recv() now, which is the expected state.
+            # Success.
+            return
+
+        # The socket is ready for recv(). This is unexpected at this point
+        # and always means an error. Try receive from the socket to find out
+        # what happened:
+        try:
+            recvd_data = self._socket.recv(128)
+        except OSError as e:
+            # This is unlikely to happen: It would mean that the socket is ready
+            # for recv() but then recv() failed.
+            raise OcdConnectionError(
+                "Connection to OpenOCD broken for an unknown reason"
+            ) from e
+
+        if len(recvd_data) == 0:
+            # Empty received data means that the connection got closed by OpenOCD
+            # in the meanwhile.
+            raise OcdConnectionError("Connection closed by OpenOCD")
+        else:
+            # It looks like OpenOCD sent us some extra, unsolicited bytes (without us
+            # sending any command to OpenOCD). This is a violation of the communication
+            # protocol.
             raise OcdConnectionError(
                 "Received unexpected bytes from OpenOCD before "
                 "the command was even sent."
@@ -107,12 +132,27 @@ class _PyOpenocdBaseClient:
         assert self.is_connected()
         assert self._socket is not None
 
-        # Safety:
-        self._check_no_premature_recvd_bytes()
+        # Perform basic connection check before sending a command.
+        # Note that this is merely a safety/correctness check which itself
+        # does not guarantee that the subsequent send() and recv() calls
+        # will succeed.
+        self._check_connection_before_command()
 
         data = raw_cmd.encode(self.CHARSET) + self.COMMAND_DELIMITER
-        self._socket.settimeout(self.SEND_TIMEOUT)
-        self._socket.send(data)
+
+        try:
+            self._socket.settimeout(self.SEND_TIMEOUT)
+        except OSError as e:
+            raise OcdConnectionError(
+                "Could not send a command to OpenOCD, failed to set socket timeout"
+            ) from e
+
+        try:
+            self._socket.send(data)
+        except OSError as e:
+            raise OcdConnectionError(
+                "Could not send a command to OpenOCD, socket error occurred"
+            ) from e
 
     def _do_recv_response(self, raw_cmd: str, timeout: Optional[float] = None) -> str:
         assert self.is_connected()
@@ -123,7 +163,13 @@ class _PyOpenocdBaseClient:
             timeout if timeout is not None else self._default_recv_timeout
         )
 
-        self._socket.settimeout(self.RECV_POLL_TIMEOUT)
+        try:
+            self._socket.settimeout(self.RECV_POLL_TIMEOUT)
+        except OSError as e:
+            raise OcdConnectionError(
+                "Could not receive a response from OpenOCD, "
+                "failed to set socket timeout"
+            ) from e
 
         time_start = time.time()
         while time.time() < (time_start + effective_timeout):
@@ -131,6 +177,10 @@ class _PyOpenocdBaseClient:
                 d = self._socket.recv(self.RECV_BLOCK_SIZE)
             except socket.timeout:
                 continue
+            except OSError as e:
+                raise OcdConnectionError(
+                    "Could not receive a response from OpenOCD, socket error occurred"
+                ) from e
 
             if d == b"":
                 raise OcdConnectionError("Connection closed by OpenOCD")

pyopenocdclient-0.2.0/src/py_openocd_client/cli.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+
+import argparse
+import sys
+
+from .client import PyOpenocdClient
+from .errors import OcdCommandTimeoutError, OcdConnectionError, OcdInvalidResponseError
+
+_DEFAULT_HOST = "127.0.0.1"
+_DEFAULT_PORT = 6666
+_DEFAULT_TIMEOUT = 5.0
+
+_EXIT_CODE_CONNECTION_ERROR = 91
+_EXIT_CODE_INVALID_RESPONSE = 92
+_EXIT_CODE_COMMAND_TIMEOUT = 93
+
+
+def eprint(s: str) -> None:
+    print("error: " + s, file=sys.stderr)
+
+
+def parse_args() -> argparse.Namespace:
+    desc = (
+        "Command-line utility that sends a single Tcl command to OpenOCD\n"
+        "through its Tcl-RPC interface."
+    )
+    epilog = (
+        "If the Tcl command completes successfully, this tool exits with code 0.\n"
+        "Connection errors or command execution errors cause it to exit with\n"
+        "a non-zero code.\n\n"
+        "All the output of the Tcl command is written to stdout.\n"
+        "Any error messages coming from this tool are written to stderr."
+    )
+    parser = argparse.ArgumentParser(
+        description=desc,
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.color = False
+
+    parser.add_argument(
+        "--host",
+        default=_DEFAULT_HOST,
+        help=(
+            "Hostname or address of the machine where OpenOCD is running "
+            f"(default: {_DEFAULT_HOST})"
+        ),
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=_DEFAULT_PORT,
+        help=f"OpenOCD's Tcl-RPC server port number (default: {_DEFAULT_PORT})",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=_DEFAULT_TIMEOUT,
+        help=(
+            "Timeout for the command execution in seconds "
+            f"(default: {_DEFAULT_TIMEOUT:.1f})"
+        ),
+    )
+    parser.add_argument(
+        "command",
+        help="The Tcl command to send to OpenOCD",
+    )
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    try:
+        with PyOpenocdClient(args.host, args.port) as ocd:
+            ocd.set_default_timeout(args.timeout)
+            result = ocd.cmd(args.command, throw=False)
+            print(result.out)
+
+            if result.retcode != 0:
+                eprint(f"The command has failed (return code: {result.retcode}).")
+            return result.retcode
+
+    except OcdConnectionError as e:
+        eprint(str(e))
+        return _EXIT_CODE_CONNECTION_ERROR
+
+    except OcdInvalidResponseError as e:
+        eprint("OpenOCD responded unexpectedly: " + str(e))
+        return _EXIT_CODE_INVALID_RESPONSE
+
+    except OcdCommandTimeoutError as e:
+        eprint(f"Timeout: The command did not complete within {e.timeout:.1f} seconds.")
+        return _EXIT_CODE_COMMAND_TIMEOUT
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/src/py_openocd_client/client.py

@@ -7,7 +7,12 @@ from typing import Any, List, Optional, Tuple, Type
 
 from .baseclient import _PyOpenocdBaseClient
 from .bp_parser import _BpParser
-from .errors import OcdCommandFailedError, OcdInvalidResponseError, _OcdParsingError
+from .errors import (
+    OcdCommandFailedError,
+    OcdEmptyResponseError,
+    OcdInvalidResponseError,
+    _OcdParsingError,
+)
 from .types import BpInfo, OcdCommandResult, WpInfo, WpType
 from .wp_parser import _WpParser
 
@@ -211,25 +216,42 @@ class PyOpenocdClient:
             raw_cmd = cmd
 
         raw_cmd = "set CMD_RETCODE [ catch { " + raw_cmd + " } CMD_OUTPUT ] ; "
-        raw_cmd += 'return "$CMD_RETCODE $CMD_OUTPUT" ; '
+
+        # Older OpenOCD versions - prior to 93f16eed4(*) - incorrectly trimmed trailing
+        # whitespace from the string passed to the return command. Work around this bug
+        # by wrapping the string by non-whitespace characters.
+        # (*): https://review.openocd.org/c/openocd/+/9084
+        raw_cmd += 'return "<$CMD_RETCODE,$CMD_OUTPUT>" ; '
 
         raw_result = self.raw_cmd(raw_cmd, timeout=timeout)
 
-        # Verify the raw output from OpenOCD the has the expected format. It can be:
-        #
-        # - Command return code (positive or negative decimal number) and that's it.
-        #
-        # - Or, command return code (positive or negative decimal number) followed by
-        #   a space character and optionally followed by the command's textual output.
-        if re.match(r"^-?\d+($| )", raw_result) is None:
+        def is_expected_raw_result(s: str) -> bool:
+            return (
+                s.startswith("<")
+                and s.endswith(">")
+                and re.match(r"^<-?\d+,", s) is not None
+            )
+
+        if len(raw_result) == 0:
+            msg = (
+                "Received empty response from OpenOCD. "
+                "(This is OK for 'shutdown' or 'exit' commands but unexpected "
+                "for any other command.) "
+            )
+            raise OcdEmptyResponseError(msg, raw_cmd, raw_result)
+
+        if not is_expected_raw_result(raw_result):
             msg = (
                 "Received unexpected response from OpenOCD. "
                 "It looks like OpenOCD misbehaves. "
             )
             raise OcdInvalidResponseError(msg, raw_cmd, raw_result)
 
-        raw_result_parts = raw_result.split(" ", maxsplit=1)
-        assert len(raw_result_parts) in [1, 2]
+        # Remove leading "<" and trailing ">"
+        raw_result = raw_result[1:-1]
+        raw_result_parts = raw_result.split(",", maxsplit=1)
+        assert len(raw_result_parts) == 2
+
         retcode = int(raw_result_parts[0], 10)
         out = raw_result_parts[1] if len(raw_result_parts) == 2 else ""
 
@@ -663,11 +685,37 @@ class PyOpenocdClient:
         """
         self.disconnect()
 
-    def shutdown(self) -> None:
+    def _shutdown_supports_any_exit_code(self) -> bool:
+        return "shutdown ['error'|exit_code]" in self.cmd("help shutdown").out
+
+    def shutdown(self, exit_code: int = 0) -> None:
         """
-        Shut down the OpenOCD process by sending the ``shutdown`` command to it.
-        PyOpenocd client also gets immediately disconnected from OpenOCD.
+        Shut down (terminate) the OpenOCD process by sending the ``shutdown``
+        command to it. PyOpenocdClient also immediately disconnects from OpenOCD.
+
+        The optional argument ``exit_code`` allows to set the exit code
+        of the OpenOCD process. Default is 0 (success).
+
+        .. versionadded:: 0.2.0
+           Argument ``exit_code``.
         """
+        if not (0 <= exit_code <= 255):
+            raise ValueError("The exit_status must be in range 0..255.")
+
+        # For compatibility with older OpenOCD, prefer:
+        # - "shutdown" over "shutdown 0"
+        # - "shutdown error" over "shutdown 1"
+        if exit_code == 0:
+            cmd = "shutdown"
+        elif exit_code == 1:
+            cmd = "shutdown error"
+        else:
+            if not self._shutdown_supports_any_exit_code():
+                raise ValueError(
+                    "This version of OpenOCD supports exit code 0 or 1 only"
+                )
+            cmd = f"shutdown {exit_code}"
+
         # Different OpenOCD versions respond to "shutdown" command differently:
         #
         # - OpenOCD 0.12.0 and older:
@@ -675,16 +723,19 @@ class PyOpenocdClient:
         #   which can be obtained normally as for any other TCL command -
         #   e.g. via the "catch" command.
         #
-        # - OpenOCD 0.13.0-dev and newer (from to commit "93f16eed4"):
+        # - OpenOCD 0.13.0-dev and newer (starting from commit "93f16eed4"):
         #   The "shutdown" command immediately ends the TCL processing and
         #   an empty response is sent back to the TCL client.
 
-        # For the above reasons, send the shutdown command via raw_cmd() and:
-        # - don't wrap "shutdown" into any other TCL commands,
-        # - don't expect any particular response.
-        self.raw_cmd("shutdown")
-
-        self.disconnect()
+        # Tolerate both the above scenarios:
+        try:
+            self.cmd(cmd)
+        except OcdCommandFailedError:
+            pass
+        except OcdEmptyResponseError:
+            pass
+        finally:
+            self.disconnect()
 
     def raw_cmd(self, raw_cmd: str, timeout: Optional[float] = None) -> str:
         """

{pyopenocdclient-0.1.1 → pyopenocdclient-0.2.0}/src/py_openocd_client/errors.py

@@ -1,5 +1,7 @@
 # SPDX-License-Identifier: MIT
 
+import warnings
+
 from .types import OcdCommandResult
 
 
@@ -87,9 +89,9 @@ class OcdInvalidResponseError(OcdBaseException):
     That is, PyOpenocdClient could not parse and/or interpret that command output.
     """
 
-    def __init__(self, msg: str, raw_cmd: str, out: str):
+    def __init__(self, msg: str, raw_cmd: str, raw_out: str):
         self._raw_cmd = raw_cmd
-        self._out = out
+        self._raw_out = raw_out
         super().__init__(msg)
 
     @property
@@ -99,12 +101,44 @@ class OcdInvalidResponseError(OcdBaseException):
         """
         return self._raw_cmd
 
+    @property
+    def raw_out(self) -> str:
+        """
+        The actual raw command's output that was unexpected
+        (that could not be understood or parsed).
+
+        .. versionadded:: 0.2.0
+        """
+        return self._raw_out
+
     @property
     def out(self) -> str:
         """
-        The actual invalid response of the command.
+        Deprecated alias for ``raw_out``, kept just for compatibility.
+
+        .. deprecated:: 0.2.0
         """
-        return self._out
+        warnings.warn(
+            "OcdInvalidResponseError.out is deprecated. "
+            "Please use OcdInvalidResponseError.raw_out instead.",
+            DeprecationWarning,
+        )
+        return self._raw_out
+
+
+class OcdEmptyResponseError(OcdInvalidResponseError):
+    """
+    Exception which denotes that a TCL command produced an empty response.
+    It is a sub-class of :py:class:`py_openocd_client.OcdInvalidResponseError`.
+
+    Empty responses occur for commands ``exit`` and ``shutdown``, that is, commands
+    that immediately terminate the TCL session. For other commands, empty responses are
+    unexpected and would mean that OpenOCD mis-behaves.
+
+    .. versionadded:: 0.2.0
+    """
+
+    pass
 
 
 class OcdConnectionError(OcdBaseException):