remote/client: Provide an internal console

sjg20 · sjg20 · commit b4e11ea192ac · 2026-07-12T15:11:45.000-06:00
At present Labgrid uses microcom as its console. This has some
limitations:

- console output is lost between when the board is reset and microcom
  connects
- txdelay cannot be handled in microcom, meaning that boards may fail
  to receive expected output
- the console may echo a few characters back to the caller in the time
  between when 'labgrid-client console' is executed and when microcom
  starts (which causes failures with U-Boot test system)

For many use cases, microcom is more than is needed, so provide a simple
internal terminal which resolves the above problems.

It is enabled by a '-i' option to the 'console' command, as well as an
environment variable, so that it can be adjusted without updating a lot
of scripts.

To exit, press Ctrl-] twice, quickly.

Use prompt_toolkit to look after the terminal, since it already knows
how to put it into raw mode and how to watch it from the event loop.
The keystrokes themselves are read with os.read() rather than
prompt_toolkit's read_keys(), since the board needs a transparent byte
stream: read_keys() decodes the input and parses escape sequences into
key objects, so control characters and escape sequences would no longer
reach the board as they were typed.

Series-changes: 4
- Get internal console working with qemu
- Show a prompt when starting, to indicate it is waiting for the board

Series-changes: 5
- Use prompt_toolkit to handle the terminal, rather than driving termios
  directly (Rouven)
- Watch the keyboard from the event loop, instead of polling stdin

Signed-off-by: Simon Glass &lt;sjg@chromium.org&gt;
diff --git a/doc/usage.rst b/doc/usage.rst
@@ -839,3 +839,14 @@ like this:
   $ labgrid-client -p example allow sirius/john
 
 To remove the allow it is currently necessary to unlock and lock the place.
+
+Internal console
+^^^^^^^^^^^^^^^^
+
+Labgrid uses microcom as its console by default. For situations where this is
+not suitable, an internal console is provided. To use this, provide the
+``--internal`` flag to the ``labgrid client`` command.
+
+When the internal console is used, the console transitions cleanly between use
+within a strategy or driver, and interactive use for the user. The console is
+not closed and therefore there is no loss of data.
diff --git a/labgrid/remote/client.py b/labgrid/remote/client.py
@@ -1029,43 +1029,49 @@ def digital_io(self):
             drv.set(False)
 
     async def _console(self, place, target, timeout, *, logfile=None, loop=False, listen_only=False):
+        from ..protocol import ConsoleProtocol
+
         name = self.args.name
-        from ..resource import NetworkSerialPort
 
-        # deactivate console drivers so we are able to connect with microcom
-        try:
-            con = target.get_active_driver("ConsoleProtocol")
-            target.deactivate(con)
-        except NoDriverFoundError:
-            pass
+        if not place.acquired:
+            print("place released")
+            return 255
 
-        resource = target.get_resource(NetworkSerialPort, name=name, wait_avail=False)
+        if self.args.internal or os.environ.get("LG_CONSOLE") == "internal":
+            console = target.get_driver(ConsoleProtocol, name=name)
+            returncode = await term.internal(lambda: self.is_allowed(place), console, logfile, listen_only)
+        else:
+            from ..resource import NetworkSerialPort
 
-        # async await resources
-        timeout = Timeout(timeout)
-        while True:
-            target.update_resources()
-            if resource.avail or (not loop and timeout.expired):
-                break
-            await asyncio.sleep(0.1)
+            # deactivate console drivers so we are able to connect with microcom
+            try:
+                con = target.get_active_driver("ConsoleProtocol")
+                target.deactivate(con)
+            except NoDriverFoundError:
+                pass
 
-        # use zero timeout to prevent blocking sleeps
-        target.await_resources([resource], timeout=0.0)
+            resource = target.get_resource(NetworkSerialPort, name=name, wait_avail=False)
 
-        if not place.acquired:
-            print("place released")
-            return 255
+            # async await resources
+            timeout = Timeout(timeout)
+            while True:
+                target.update_resources()
+                if resource.avail or (not loop and timeout.expired):
+                    break
+                await asyncio.sleep(0.1)
 
-        host, port = proxymanager.get_host_and_port(resource)
+            # use zero timeout to prevent blocking sleeps
+            target.await_resources([resource], timeout=0.0)
+            host, port = proxymanager.get_host_and_port(resource)
 
-        # check for valid resources
-        assert port is not None, "Port is not set"
-        try:
-            returncode = await term.external(
-                lambda: self.is_allowed(place), host, port, resource, logfile, listen_only
-            )
-        except FileNotFoundError as e:
-            raise ServerError(f"failed to execute remote console command: {e}")
+            # check for valid resources
+            assert port is not None, "Port is not set"
+            try:
+                returncode = await term.external(
+                    lambda: self.is_allowed(place), host, port, resource, logfile, listen_only
+                )
+            except FileNotFoundError as e:
+                raise ServerError(f"failed to execute remote console command: {e}")
 
         # Raise an exception if the place was released
         self._check_allowed(place)
@@ -1966,6 +1972,7 @@ def get_parser(auto_doc_mode=False) -> "argparse.ArgumentParser | AutoProgramArg
     subparser.set_defaults(func=ClientSession.digital_io)
 
     subparser = subparsers.add_parser("console", aliases=("con",), help="connect to the console")
+    subparser.add_argument("-i", "--internal", action="store_true", help="use an internal console instead of microcom")
     subparser.add_argument(
         "-l", "--loop", action="store_true", help="keep trying to connect if the console is unavailable"
     )
diff --git a/labgrid/util/term.py b/labgrid/util/term.py
@@ -1,9 +1,17 @@
-"""Terminal handling, using microcom or telnet"""
+"""Terminal handling, using microcom, telnet or an internal function"""
 
 import asyncio
+import collections
+import contextlib
 import logging
+import os
 import sys
 import shutil
+import time
+
+from pexpect import TIMEOUT
+from prompt_toolkit.input import create_input
+from serial.serialutil import SerialException
 
 EXIT_CHAR = 0x1d    # FS (Ctrl + ])
 
@@ -69,3 +77,159 @@ async def external(check_allowed, host, port, resource, logfile, listen_only):
     if p.returncode:
         print("connection lost", file=sys.stderr)
     return p.returncode
+
+
+BUF_SIZE = 1024
+
+async def run(check_allowed, cons, log_fd, listen_only, inp=None):
+    """Handle the console session, passing data between board and terminal
+
+    Args:
+        check_allowed (lambda): Function to call to make sure the terminal is
+            still accessible. No args. Returns True if allowed, False if not.
+        cons (ConsoleProtocol): Console device to read/write
+        log_fd (file): File to write console output to, or None
+        listen_only (bool): True to ignore keyboard input
+        inp (prompt_toolkit Input): Terminal to read keystrokes from, or None
+            to ignore the keyboard
+    """
+    prev = collections.deque(maxlen=2)
+
+    deadline = None
+    to_cons = b''
+    next_cons = time.monotonic()
+    txdelay = cons.txdelay
+    typed = bytearray()
+
+    def read_keys():
+        """Collect what the user types, called by the event loop
+
+        This reads the bytes as they arrive, rather than using prompt_toolkit's
+        read_keys(), since the board needs a transparent stream: it must see
+        escape sequences and control characters exactly as they were typed.
+        """
+        try:
+            data = os.read(inp.fileno(), BUF_SIZE)
+        except OSError:
+            data = b''
+        if data:
+            typed.extend(data)
+        else:
+            # The terminal is gone (e.g. a closed pipe), so stop watching it,
+            # else the event loop calls us forever
+            asyncio.get_running_loop().remove_reader(inp.fileno())
+
+    # Show a message to indicate we are waiting for output from the board
+    msg = 'Terminal ready...press Ctrl-] twice to exit'
+    sys.stdout.write(msg)
+    sys.stdout.flush()
+    erase_msg = '\b' * len(msg) + ' ' * len(msg) + '\b' * len(msg)
+    have_output = False
+
+    # Ask the event loop to tell us when the user types something
+    watch_keys = inp.attach(read_keys) if inp else contextlib.nullcontext()
+
+    with watch_keys:
+        while True:
+            activity = bool(to_cons)
+            try:
+                data = cons.read(size=BUF_SIZE, timeout=0.001)
+                if data:
+                    activity = True
+                    if not have_output:
+                        # Erase our message
+                        sys.stdout.write(erase_msg)
+                        sys.stdout.flush()
+                        have_output = True
+                    sys.stdout.buffer.write(data)
+                    sys.stdout.buffer.flush()
+                    if log_fd:
+                        log_fd.write(data)
+                        log_fd.flush()
+
+            except TIMEOUT:
+                pass
+
+            except SerialException:
+                break
+
+            if typed:
+                data = bytes(typed)
+                typed.clear()
+                activity = True
+                if not deadline:
+                    deadline = time.monotonic() + .5  # seconds
+                prev.extend(data)
+                count = prev.count(EXIT_CHAR)
+                if count == 2:
+                    break
+
+                to_cons += data
+
+            if to_cons and time.monotonic() > next_cons:
+                cons._write(to_cons[:1])
+                to_cons = to_cons[1:]
+                if txdelay:
+                    next_cons += txdelay
+
+            if deadline and time.monotonic() > deadline:
+                prev.clear()
+                deadline = None
+            if check_allowed():
+                break
+
+            # Give the event loop a chance to run read_keys()
+            await asyncio.sleep(0 if activity else .001)
+
+    # Blank line to move past any partial output
+    print()
+
+
+async def internal(check_allowed, cons, logfile, listen_only):
+    """Start an internal terminal session
+
+    This talks to the board directly, rather than starting a separate tool.
+
+    Args:
+        check_allowed (lambda): Function to call to make sure the terminal is
+            still accessible. No args. Returns True if allowed, False if not.
+        cons (ConsoleProtocol): Console device to read/write
+        logfile (str): Logfile to write output too, or None
+        listen_only (bool): True to ignore keyboard input
+
+    Return:
+        int: Result code
+    """
+    returncode = 0
+    log_fd = None
+    inp = None
+    try:
+        # Watch the keyboard, unless we only care about what the board says
+        if not listen_only:
+            inp = create_input()
+
+        if logfile:
+            log_fd = open(logfile, 'wb')
+
+        logging.info('Console start:')
+
+        # Put the terminal in raw mode, so that keystrokes reach the board
+        # untouched.  As well as the echo and line editing, this turns off
+        # flow control (so that Ctrl-S and Ctrl-Q get through) and the
+        # carriage-return translation.  It does nothing if stdin is not a
+        # terminal, such as when input is piped in
+        raw_mode = inp.raw_mode() if inp else contextlib.nullcontext()
+        with raw_mode:
+            await run(check_allowed, cons, log_fd, listen_only, inp)
+
+    except OSError as err:
+        print('error', err)
+        returncode = 1
+
+    finally:
+        if inp:
+            inp.close()
+        if log_fd:
+            log_fd.close()
+
+    return returncode
diff --git a/man/labgrid-client.1 b/man/labgrid-client.1
@@ -233,7 +233,7 @@ connect to the console
 .INDENT 3.5
 .sp
 .EX
-usage: labgrid\-client console|con [\-l] [\-o] [\-\-logfile FILE] [name]
+usage: labgrid\-client console|con [\-i] [\-l] [\-o] [\-\-logfile FILE] [name]
 .EE
 .UNINDENT
 .UNINDENT
@@ -244,6 +244,11 @@ optional resource name
 .UNINDENT
 .INDENT 0.0
 .TP
+.B \-i, \-\-internal
+use an internal console instead of microcom
+.UNINDENT
+.INDENT 0.0
+.TP
 .B \-l, \-\-loop
 keep trying to connect if the console is unavailable
 .UNINDENT
diff --git a/pyproject.toml b/pyproject.toml
@@ -39,6 +39,7 @@ dependencies = [
     "protobuf>=5.27.0",
     "jinja2>=3.0.2",
     "pexpect>=4.8.0",
+    "prompt-toolkit>=3.0.0",
     "pyserial-labgrid>=3.4.0.1",
     "pytest>=7.0.0",
     "pyudev>=0.24.4",
