makefiles/tools: enhance miniterm path finding in serial.inc.mk [backport 2026.04]

cpu/esp8266/doc.md

@@ -1200,10 +1200,8 @@ following.
 1. Start in first terminal window a terminal program which connects to the
 port of the ESP8266 module as console window:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-term1> python -m serial.tools.miniterm <port> 115200
+make BOARD=esp8266-esp-12x term
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-where `<port>` is the serial interface to which the ESP8266 module is connected,
-e.g., `/dev/ttyUSB0`.
 
 2. Start GDB with the application in a second terminal window:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/guides/misc/terminal_config.md

@@ -1,5 +1,5 @@
 ---
-title: Terminal Programs Configuration
+title: Terminal Program Configuration
 description: How to configure popular terminal programs for correct display of newlines
 ---
 
@@ -41,6 +41,13 @@ that will make them correctly display newlines.
 - Via RIOT build system:
     - `RIOT_TERMINAL=miniterm make term`
 
+:::note
+You can install miniterm by installing `pyserial`. The preferred method
+for most Linux distributions is to install `python3-serial` with your
+package manager. If that is not possible or desired, you can also install
+`pyserial` with `pipx`.
+:::
+
 ## picocom
 
 - Generic method:

examples/lang_support/community/lua_REPL/README.md

@@ -12,12 +12,13 @@ system's default lua installation.
 Type `make all flash` to program your board. The lua interpreter communicates
 via UART (like the shell).
 
-It is not recommended to use `make term` because the default RIOT terminal messes
+It is not recommended to use the default RIOT terminal from `make term` because it
 up the input and output and the REPL needs multi-line input. Instead, use something
-like `miniterm.py` from pyserial:
+like `miniterm` from `pyserial` by setting the `RIOT_TERMINAL` environment
+variable:
 
 ```
-miniterm.py --eol LF --echo /dev/ttyACM0 115200
+RIOT_TERMINAL=miniterm BOARD=... make term
 ```
 
 By default only some of the builtin modules are loaded, to preserve RAM. See

makefiles/tools/serial.inc.mk

@@ -73,13 +73,21 @@ else ifeq ($(RIOT_TERMINAL),picocom)
   TERMPROG  ?= picocom
   TERMFLAGS ?= --nolock --imap lfcrlf --baud "$(BAUD)" "$(PORT)"
 else ifeq ($(RIOT_TERMINAL),miniterm)
-  # Check if miniterm.py is available in the path, if not use just miniterm
-  # since new versions will only have miniterm and not miniterm.py
-  ifeq (,$(shell command -v miniterm.py 2>/dev/null))
+  # The executable for miniterm depends on the version and the way it was
+  # installed. Check for all (currently) known possibilities and select
+  # the correct one.
+  ifneq (,$(shell command -v pyserial-miniterm.py 2>/dev/null))
+    TERMPROG ?= pyserial-miniterm.py
+  else ifneq (,$(shell command -v pyserial-miniterm 2>/dev/null))
+    TERMPROG ?= pyserial-miniterm
+  else ifneq (,$(shell command -v miniterm.py 2>/dev/null))
+    TERMPROG ?= miniterm.py
+  else ifneq (,$(shell command -v miniterm 2>/dev/null))
     TERMPROG ?= miniterm
   else
-    TERMPROG ?= miniterm.py
+    $(error The pyserial miniterm was not found! Check if pyserial is installed.)
   endif
+
   # The RIOT shell will still transmit back a CRLF, but at least with --eol LF
   # we avoid sending two lines on every "enter".
   TERMFLAGS ?= --eol LF "$(PORT)" "$(BAUD)" $(MINITERMFLAGS)

tests/pkg/tinyusb_cdc_msc/README.md

@@ -35,7 +35,7 @@ It should then be possible
    of the operating system
 2. to connect to the serial interface of the device with a terminal program, e.g.
    ```
-   python -m serial.tools.miniterm /dev/ttyACM0 115200
+   BOARD=... make term
    ```
    and get the entered characters sent back.