doc: make serial port mentions OS neutral

greg-fer · rlubos · commit d4cf3f2f8530 · 2025-07-07T15:04:44.000+02:00
Removed Windows-only information about locating serial port.
Added a shortcut with information how to list serial ports for Nordic
devices using nRF Util.
Edited documents that mention COM ports and tty devices.
Added cross links for default baud rate mentions.
NCD-685.

Signed-off-by: Grzegorz Ferenc &lt;Grzegorz.Ferenc@nordicsemi.no&gt;
diff --git a/applications/connectivity_bridge/README.rst b/applications/connectivity_bridge/README.rst
@@ -70,7 +70,7 @@ Testing
 After programming the sample to your kit, test it by performing the following steps:
 
 1. Connect the kit to the host using a USB cable.
-#. Observe that the CDC ACM devices enumerate on the USB host (COM ports on Windows, /dev/tty* on Linux and Mac).
+#. Observe that the CDC ACM devices enumerate to serial ports on the USB host (COM ports on Windows, /dev/tty* on Linux and Mac).
 #. Use a serial client on the USB host to communicate over the kit's UART pins.
 
 
diff --git a/applications/connectivity_bridge/boards/thingy91_nrf52840_readme.txt b/applications/connectivity_bridge/boards/thingy91_nrf52840_readme.txt
@@ -7,20 +7,21 @@ https://nordicsemi.com/thingy91
 
 This USB interface has the following functions:
 * Disk drive containing this file and others
-* COM ports for nRF91 debug, trace, and firmware update
+* Serial ports for nRF91 debug, trace, and firmware update
 * CMSIS-DAP 2.1 compliant debug probe interface for accessing the nRF91 SiP
 
-COM Ports
-=========
+Serial ports
+============
 
-This USB interface exposes two COM ports mapped to the physical UART interfaces between the nRF91 Series and nRF52840 devices.
-When opening these ports manually (without using the nRF Connect Serial Terminal), be aware that the USB COM port baud rate selection is applied to the UART.
+This USB interface exposes two serial ports mapped to the physical UART interfaces between the nRF91 Series and nRF52840 devices.
+Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS.
+When opening these ports manually (without using the Serial Terminal app), be aware that the USB serial port baud rate selection is applied to the UART.
 
 Bluetooth® LE Central UART Service
 ==================================
 
 This device advertises as configured in BLE_NAME in Config.txt, default being "Thingy:91 UART".
-Connect using a Bluetooth LE Central device, for example a phone running the nRF Connect app:
+Connect using a Bluetooth LE Central device, for example a phone running the nRF Connect for Mobile app:
 https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Connect-for-mobile/
 
 NOTE: The Bluetooth LE interface is unencrypted and intended to be used during debugging.
diff --git a/applications/connectivity_bridge/boards/thingy91x_nrf5340_cpuapp_readme.txt b/applications/connectivity_bridge/boards/thingy91x_nrf5340_cpuapp_readme.txt
@@ -4,19 +4,20 @@
 
 This USB interface has the following functions:
 * Disk drive containing this file and others
-* COM ports for nRF91 debug, trace, and firmware update
+* Serial ports for nRF91 debug, trace, and firmware update
 * CMSIS-DAP 2.1 compliant debug probe interface for accessing the nRF91 SiP
 
-COM Ports
-=========
-This USB interface exposes two COM ports mapped to the physical UART interfaces between the nRF91 Series and nRF5340 devices.
-When opening these ports manually (without using the nRF Connect Serial Terminal), be aware that the USB COM port baud rate selection is applied to the UART.
+Serial ports
+============
+
+This USB interface exposes two serial ports mapped to the physical UART interfaces between the nRF91 Series and nRF5340 devices.
+When opening these ports manually (without using the Serial Terminal app), be aware that the USB serial port baud rate selection is applied to the UART.
 
 Bluetooth® LE Central UART Service
 ==================================
 
 This device advertises as configured in BLE_NAME in Config.txt, default being "Thingy:91 X UART".
-Connect using a Bluetooth LE Central device, for example a phone running the nRF Connect app:
+Connect using a Bluetooth LE Central device, for example a phone running the nRF Connect for Mobile app:
 https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Connect-for-mobile/
 
 NOTE: The Bluetooth LE interface is unencrypted and intended to be used during debugging.
diff --git a/applications/nrf_desktop/doc/ble_qos.rst b/applications/nrf_desktop/doc/ble_qos.rst
@@ -131,10 +131,10 @@ The thread is used to periodically perform the following operations:
 * Submit the suggested channel map as ``ble_qos_event``.
 * If the device is a Bluetooth central, update the used Bluetooth LE channel map.
 
-If the :ref:`CONFIG_DESKTOP_BLE_QOS_STATS_PRINTOUT_ENABLE <config_desktop_app_options>` Kconfig option is set, the module prints the following information through the virtual COM port:
+If the :ref:`CONFIG_DESKTOP_BLE_QOS_STATS_PRINTOUT_ENABLE <config_desktop_app_options>` Kconfig option is set, the module prints the following information through the virtual serial port:
 
 * HID report rate
-   The module counts the number of HID input reports received through Bluetooth LE and prints the report rate through the virtual COM port every 100 packets.
+   The module counts the number of HID input reports received through Bluetooth LE and prints the report rate through the virtual serial port every 100 packets.
    The report rate is printed with a timestamp.
 
    Example output:
diff --git a/applications/serial_lte_modem/doc/PPP_linux.rst b/applications/serial_lte_modem/doc/PPP_linux.rst
@@ -32,7 +32,7 @@ Configuration
 To build the SLM application, use the :file:`overlay-ppp-cmux-linux.conf` configuration overlay.
 
 You can adjust the serial port baud rate using the devicetree overlay file.
-By default, the baud rate is set to 115200.
+The :ref:`baud rate is set to 115200 <test_and_optimize>` by default.
 If you change the baud rate, set the same rate in the :file:`scripts/slm_start_ppp.sh` and :file:`scripts/slm_stop_ppp.sh` scripts.
 
 .. note::
diff --git a/applications/serial_lte_modem/doc/slm_description.rst b/applications/serial_lte_modem/doc/slm_description.rst
@@ -612,7 +612,7 @@ Use the following UART devices:
 * nRF52 or nRF53 Series DK - UART0
 * nRF91 Series DK - UART2
 
-Use the following UART configuration:
+Use the following UART configuration, which is different from the :ref:`default serial port connection settings <test_and_optimize>`:
 
 * Hardware flow control: enabled
 * Baud rate: 115200
diff --git a/doc/nrf/app_dev/device_guides/nrf53/logging_nrf5340.rst b/doc/nrf/app_dev/device_guides/nrf53/logging_nrf5340.rst
@@ -7,27 +7,29 @@ Getting logging output with nRF5340 DK
    :local:
    :depth: 2
 
-When connected to a computer, the nRF5340 DK emulates virtual COM ports.
-The number of COM ports depends on the DK version you are using.
+When connected to a computer, the nRF5340 DK emulates virtual serial ports.
+The number of serial ports depends on the DK version you are using.
 
-nRF5340 DK v2.0.0 COM ports
-***************************
+|serial_port_number_list|
 
-When connected to a computer, the nRF5340 DK v2.0.0 emulates two virtual COM ports.
+nRF5340 DK v2.0.0 serial ports
+******************************
+
+When connected to a computer, the nRF5340 DK v2.0.0 emulates two virtual serial ports.
 In the default configuration, they are set up as follows:
 
-* The first COM port outputs the log from the network core (if available).
-* The second COM port outputs the log from the application core.
+* The first serial port outputs the log from the network core (if available).
+* The second serial port outputs the log from the application core.
 
-nRF5340 DK v1.0.0 COM ports
-***************************
+nRF5340 DK v1.0.0 serial ports
+******************************
 
 When connected to a computer, the nRF5340 DK v1.0.0 emulates three virtual COM ports.
 In the default configuration, they are set up as follows:
 
-* The first COM port outputs the log from the network core (if available).
-* The second (middle) COM port is routed to the **P24** connector of the nRF5340 DK.
-* The third (last) COM port outputs the log from the application core.
+* The first serial port outputs the log from the network core (if available).
+* The second (middle) serial port is routed to the **P24** connector of the nRF5340 DK.
+* The third (last) serial port outputs the log from the application core.
 
 To use the middle COM port in the nRF5340 DK v1.0.0, complete the following steps:
 
diff --git a/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_logging.rst b/doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_logging.rst
@@ -161,7 +161,7 @@ To read the dictionary-based STM log output, do the following:
      When using several domains, use a comma (`,`) to separate each domain in the list.
    * ``<app_name>`` is the application name.
    * ``<port>`` is the serial port used for output.
-     Use ``nrfutil device list`` to identify the serial ports exposed by the development kit.
+     |serial_port_number_list|
    * The output can be either the console (``--stdout ascii``) or a file (the :file:`out.txt` file if ``--output-ascii out.txt``).
 
 #. Capture and decode the logs.
diff --git a/doc/nrf/app_dev/device_guides/thingy91/thingy91_connecting.rst b/doc/nrf/app_dev/device_guides/thingy91/thingy91_connecting.rst
@@ -35,7 +35,7 @@ Thingy:91 uses the following UART baud rate configuration:
    * - UART Interface
      - Baud Rate
    * - UART_0
-     - 115200
+     - 115200 (:ref:`default <test_and_optimize>`)
    * - UART_1
      - 1000000
 
diff --git a/doc/nrf/libraries/shell/shell_bt_nus.rst b/doc/nrf/libraries/shell/shell_bt_nus.rst
@@ -55,6 +55,9 @@ The script requires the following parameters:
 
 * ``com`` - the COM port of the development kit used by the script
 
+  .. note::
+     |serial_port_number_list|
+
 Additionally, following parameters are option:
 
 * ``snr`` - the SEGGER board ID
diff --git a/doc/nrf/protocols/thread/certification.rst b/doc/nrf/protocols/thread/certification.rst
@@ -148,6 +148,9 @@ Thread Test Harness does not correctly identify the nRF52840 DK (PCA10056) out-o
 Due to a collision of USB PID:VID with another vendor, Nordic devices are not automatically added to the device list.
 This is valid only for Nordic Semiconductor development kits with a J-Link virtual COM port.
 
+.. note::
+   |serial_port_number_list|
+
 To add an nRF52840 DK, drag the nRF52840 DK and drop it on the test bed configuration page.
 After that, the device is configured and the :ref:`proper baud rate (115200) <test_and_optimize>` and COM port are set.
 
diff --git a/doc/nrf/protocols/wifi/regulatory_certification/test_setup.rst b/doc/nrf/protocols/wifi/regulatory_certification/test_setup.rst
@@ -188,36 +188,33 @@ To program firmware in the nRF7002 DK or EK setup, complete the following steps.
 VCOM settings
 =============
 
-Use a baud rate setting of 115,200 bps.
+Complete the following steps to set the VCOM settings for the nRF7002 DK or EK:
 
-To choose the correct COM port to interact with the network core on the nRF7002 DK or EK, connect your computer to the nRF7002 board with a USB cable and enter the following command in the command prompt window:
+1. Connect your computer to the nRF7002 board with a USB cable.
+#. Use the :ref:`default baud rate (115200) <test_and_optimize>` for testing.
+#. |serial_port_number_list|
+   Typically, VCOM0 is connected to the nRF5340 network core running a Radio test (short-range) and VCOM1 is connected to the nRF5340 application core running a Wi-Fi Radio test.
+#. Verify the mapping of the serial ports based on the available commands for each port.
+   See the following code example and figures:
 
-.. code-block:: console
-
-    $ nrfutil device list
-
-Typically, VCOM0 is connected to the nRF5340 network core running a Radio test (short-range) and VCOM1 is connected to the nRF5340 application core running a Wi-Fi Radio test.
-Verify the mapping of the COM ports based on the available commands for each port, see Short-range Radio test port, Wi-Fi Radio test port, and the following example:
-
-.. code-block:: console
-
-    $ nrfutil device list
-    1050753610
-    product         J-Link
-    board version   PCA10143
-    ports           /dev/ttyACM4, vcom: 0   // This is for Radio Test, note baud rate is 115200bps
-                    /dev/ttyACM5, vcom: 1   // This is for Wi-Fi Radio Test, note baud rate is 115200bps
-    traits          devkit, jlink, seggerUsb, serialPorts, usb
+   .. code-block:: console
 
-   Found 1 supported device(s)
+      $ nrfutil device list
+      1050753610
+      product         J-Link
+      board version   PCA10143
+      ports           /dev/ttyACM4, vcom: 0   // This is for Radio Test, note baud rate is 115200bps
+                      /dev/ttyACM5, vcom: 1   // This is for Wi-Fi Radio Test, note baud rate is 115200bps
+      traits          devkit, jlink, seggerUsb, serialPorts, usb
 
+      Supported devices found: 1
 
-.. figure:: images/sr_radio_test_port.png
-   :alt: Short-range Radio test port
+   .. figure:: images/sr_radio_test_port.png
+      :alt: Short-range Radio test port
 
-   Short-range Radio test port
+      Short-range Radio test port
 
-.. figure:: images/wifi_radio_test_port.png
-   :alt: Wi-Fi Radio test port
+   .. figure:: images/wifi_radio_test_port.png
+      :alt: Wi-Fi Radio test port
 
-   Wi-Fi Radio test port
+      Wi-Fi Radio test port
diff --git a/doc/nrf/security/tfm/tfm_logging.rst b/doc/nrf/security/tfm/tfm_logging.rst
@@ -10,7 +10,11 @@ TF-M logging
 
 TF-M employs two UART interfaces for logging: one for the :ref:`Secure Processing Environment<app_boards_spe_nspe>` (including MCUboot and TF-M), and one for the :ref:`Non-Secure Processing Environment<app_boards_spe_nspe>` (including user application).
 
-By default, the logs from Nordic Semiconductor's Development Kits (DKs) arrive on different COM ports on the host PC.
+By default, the logs from Nordic Semiconductor's Development Kits (DKs) arrive on different serial ports on the host PC.
+
+.. note::
+   |serial_port_number_list|
+
 The UART instances can vary by device family:
 
 * nRF5340 and nRF91 Series: The application typically uses the UART instance ``0`` (``uart0``), and TF-M uses the UART instance ``1`` (``uart1``) by default.
diff --git a/doc/nrf/shortcuts.txt b/doc/nrf/shortcuts.txt
@@ -19,10 +19,16 @@
 .. |test_application| replace:: After programming the application to your development kit, complete the following steps to test it:
 
 .. |connect_generic| replace:: Connect the device to the computer using a USB cable.
-   The device is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
+   The device is assigned a serial port.
+   Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS.
+   To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the ``nrfutil device list`` command.
+   Alternatively, check your operating system's device manager or its equivalent.
 
 .. |connect_kit| replace:: Connect the kit to the computer using a USB cable.
-   The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
+   The kit is assigned a serial port.
+   Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS.
+   To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the ``nrfutil device list`` command.
+   Alternatively, check your operating system's device manager or its equivalent.
 
 .. |connect_terminal_generic| replace:: Connect to the device with a terminal emulator (for example, the `Serial Terminal app`_).
    See :ref:`test_and_optimize` for the required settings and steps.
@@ -45,6 +51,10 @@
 .. |connect_terminal_both_ANSI| replace:: Connect to both kits with a terminal emulator that supports VT100/ANSI escape characters (for example, the `Serial Terminal app`_).
    See :ref:`test_and_optimize` for the required settings and steps.
 
+.. |serial_port_number_list| replace:: Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS.
+   To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the ``nrfutil device list`` command.
+   Alternatively, check your operating system's device manager or its equivalent.
+
 .. |ANSI| replace:: that supports VT100/ANSI escape characters
 
 .. |open_terminal_window_with_environment| replace:: Start the :ref:`toolchain environment <using_toolchain_environment>` in a terminal window.
diff --git a/doc/nrf/test_and_optimize.rst b/doc/nrf/test_and_optimize.rst
@@ -103,19 +103,10 @@ Use one of the following methods:
             PuTTY configuration for sending commands through UART
 
       #. Click the **Serial** category under the **Connection** category in the category selection tree to see options controlling the local serial line.
-      #. Type the COM port corresponding to your DK in the **Serial line to connect to** field.
+      #. Type the serial port corresponding to your DK in the **Serial line to connect to** field.
 
-         Depending on what devices you have connected to your computer, you might have several choices.
-         To find the correct port:
-
-         a. Right-click on the Windows Start menu, and select **Device Manager**.
-         #. In the **Device Manager** window, scroll down and expand **Ports (COM & LPT)**.
-         #. Find the port named *JLink CDC UART Port* and note down the number in parentheses.
-
-            If you have more than one J-Link UART Port, unplug the one that you want to use, plug it back in, and observe which one appeared last.
-
-            Your DK can show up as two consecutive COM ports.
-            If this is the case, you need to test which COM port is the correct one.
+         .. note::
+            |serial_port_number_list|
 
       #. Configure the settings in the **Configure the serial line** section using the default serial port connection settings listed at the top of this page.
       #. Click :guilabel:`Open`.
diff --git a/samples/bluetooth/direct_test_mode/README.rst b/samples/bluetooth/direct_test_mode/README.rst
@@ -441,7 +441,8 @@ Testing with another development kit
 ------------------------------------
 
 1. Connect both development kits to the computer using a USB cable.
-   The computer assigns to the development kit a COM port on Windows or a ttyACM device on Linux, which is visible in the Device Manager.
+   The computer assigns to the development kit a serial port.
+   |serial_port_number_list|
 #. Connect to both kits with a terminal emulator.
    See `Direct Test Mode terminal connection`_ for the required settings.
 #. Start ``TRANSMITTER_TEST`` by sending the ``0x80 0x96`` DTM command to one of the connected development kits.
diff --git a/samples/bluetooth/enocean/README.rst b/samples/bluetooth/enocean/README.rst
@@ -63,7 +63,8 @@ Testing
 1. :ref:`Commission one or more EnOcean devices <bt_enocean_commissioning>`.
    The LEDs will blink when each of the devices has been successfully commissioned.
 #. Connect the kit to the computer with a USB cable.
-   The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.
+   The kit is assigned a serial port.
+   |serial_port_number_list|
 #. |connect_terminal_specific|
 #. Depending on the EnOcean devices you commissioned:
 
diff --git a/samples/bluetooth/mesh/chat/sample_description.rst b/samples/bluetooth/mesh/chat/sample_description.rst
@@ -140,7 +140,8 @@ Interacting with the sample
 ---------------------------
 
 1. Connect the development kit to the computer using a USB cable.
-   The development kit is assigned a COM port (Windows), ttyACM device (Linux) or tty.usbmodem (MacOS).
+   The development kit is assigned a serial port.
+   |serial_port_number_list|
 #. |connect_terminal_specific_ANSI|
 #. Enable local echo in the terminal to see the text you are typing.
 
diff --git a/samples/bluetooth/mesh/sensor_client/README.rst b/samples/bluetooth/mesh/sensor_client/README.rst
@@ -200,7 +200,8 @@ Interacting with the sample through shell
 -----------------------------------------
 
 1. Connect the development kit to the computer using a USB cable.
-   The development kit is assigned a COM port (Windows), ttyACM device (Linux) or tty.usbmodem (MacOS).
+   The development kit is assigned a serial port.
+   |serial_port_number_list|
 #. |connect_terminal_specific_ANSI|
 #. Enable local echo in the terminal to see the text you are typing.
 #. Enable mesh shell by typing ``mesh init``
diff --git a/samples/bluetooth/peripheral_uart/README.rst b/samples/bluetooth/peripheral_uart/README.rst
diff --git a/samples/bluetooth/rpc_host/README.rst b/samples/bluetooth/rpc_host/README.rst
diff --git a/samples/cellular/fmfu_smp_svr/README.rst b/samples/cellular/fmfu_smp_svr/README.rst
diff --git a/samples/nrf5340/remote_shell/README.rst b/samples/nrf5340/remote_shell/README.rst
diff --git a/samples/nrf_rpc/entropy_nrf53/README.rst b/samples/nrf_rpc/entropy_nrf53/README.rst
diff --git a/samples/peripheral/802154_phy_test/README.rst b/samples/peripheral/802154_phy_test/README.rst
diff --git a/samples/peripheral/802154_sniffer/README.rst b/samples/peripheral/802154_sniffer/README.rst
diff --git a/samples/peripheral/radio_test/README.rst b/samples/peripheral/radio_test/README.rst
diff --git a/tests/nrf5340_audio/sw_codec_lc3/readme.txt b/tests/nrf5340_audio/sw_codec_lc3/readme.txt
