Documentation: system: cu: document the cu serial terminal

Documentation/applications/system/cu/index.rst

@@ -1,3 +1,128 @@
 =================================
 ``cu`` CU minimal serial terminal
 =================================
+
+Description
+-----------
+
+The ``cu`` application is a minimalistic implementation of the classic
+``cu`` ("call up") terminal program from Taylor UUCP. It connects the
+current console bidirectionally to another serial device: everything
+typed on the console is sent to the device, and everything received
+from the device is printed on the console.
+
+This effectively turns the board into a serial bridge, which is handy
+to talk directly to devices attached to the system (GNSS receivers,
+GSM/LTE modems, RS-485 buses, or another board) using the NuttX
+console as a passthrough, without writing any application code.
+
+Usage
+-----
+
+Basic Syntax
+^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   cu [options]
+
+Options:
+
+============== ==========================================================
+``-l <dev>``   Use named device (default
+               ``CONFIG_SYSTEM_CUTERM_DEFAULT_DEVICE``, normally
+               ``/dev/ttyS0``)
+``-s <baud>``  Use given speed (default
+               ``CONFIG_SYSTEM_CUTERM_DEFAULT_BAUD``)
+``-e``         Set even parity
+``-o``         Set odd parity
+``-f``         Disable RTS/CTS flow control (default: on)
+``-c``         Disable LF -> CRLF conversion (default: off)
+``-E <char>``  Set the escape character (default ``~``). Use ``-E ''``
+               to eliminate the escape character (raw 8-bit transfers)
+``-?``         Show help
+============== ==========================================================
+
+The ``-s``, ``-e``, ``-o`` and ``-f`` options require
+``CONFIG_SERIAL_TERMIOS``.
+
+Escape Sequences
+^^^^^^^^^^^^^^^^
+
+At the beginning of a line, the escape character (default ``~``)
+introduces a command:
+
+======= ====================================
+``~.``  Hang up and drop back to the shell
+``~?``  Show the available escape sequences
+======= ====================================
+
+When talking to binary protocols (firmware upload, binary GPS
+protocols, etc.), disable the escape character with ``-E ''`` so
+every byte is forwarded untouched.
+
+Example
+^^^^^^^
+
+Bridging the console to a device attached to a second serial port:
+
+.. code-block:: bash
+
+   nsh> cu -l /dev/ttyS1 -s 115200
+   [everything typed here is transmitted on the serial port,
+    and received data is printed to the console]
+   ~.
+   nsh>
+
+Bridging two serial ports
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``cu`` always bridges the *console* to one device. To bridge two
+serial ports directly to each other, leaving the console free, use
+the shell output redirection in background instead:
+
+.. code-block:: bash
+
+   nsh> cat /dev/ttyS1 > /dev/ttyS2 &
+   nsh> cat /dev/ttyS2 > /dev/ttyS1 &
+
+With both commands running the bridge is bidirectional: everything
+received on one port is retransmitted on the other, in both
+directions. Running only one of them creates a unidirectional
+bridge, which is useful to forward or monitor a single direction.
+Use ``kill`` on the background task PIDs to undo the bridge.
+
+The two ports do not need the same line configuration: each one
+keeps its own baud rate and framing (as set by ``CONFIG_UARTx_BAUD``
+or changed by an application through termios), so the bridge also
+works as a rate adapter between buses running at different speeds.
+
+Configuration
+-------------
+
+**CONFIG_SYSTEM_CUTERM**
+
+Options:
+
+* **CONFIG_SYSTEM_CUTERM_DEFAULT_DEVICE** - Serial device used when
+  ``-l`` is not given (default ``/dev/ttyS0``)
+* **CONFIG_SYSTEM_CUTERM_DEFAULT_BAUD** - Baud rate used when ``-s``
+  is not given
+* **CONFIG_SYSTEM_CUTERM_DISABLE_ERROR_PRINT** - Suppress error
+  messages to reduce size
+
+Dependencies
+^^^^^^^^^^^^
+
+* **CONFIG_SERIAL_TERMIOS** - Optional, required for the baud rate,
+  parity and flow control options; without it ``cu`` uses the device
+  as configured by the driver
+
+Limitations
+-----------
+
+* File transfer escape commands (``~>``/``~<``) are not implemented;
+  for file transfers see ``apps/system/zmodem`` or ``ymodem``.
+* ``cu`` bridges the *current console* to one device. It does not run
+  as a background daemon bridging two arbitrary ports; for that, see
+  `Bridging two serial ports`_ above.

Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst

@@ -415,6 +415,36 @@ After flashing and reboot your board you should see in your dmesg logs::
 
 You may need to press ENTER 3 times before the NSH show up.
 
+rs485
+-----
+
+Configures the NuttShell (nsh) with the two on-board RS-485
+transceivers enabled (UART4 on ``/dev/ttyS1`` and USART6 on
+``/dev/ttyS2``, 115200 8N1). The RS-485 driver-enable pins (DE) are
+handled automatically by the serial driver on every transmission.
+
+The ``cu`` serial terminal is included, so the console can be bridged
+directly to one of the RS-485 buses, which is useful to talk to
+devices on the bus (sensors, drives, another board) without writing
+any code::
+
+    nsh> cu -l /dev/ttyS1 -s 115200
+
+Everything typed on the console is transmitted on the RS-485 bus and
+received data is printed back. Type ``~.`` at the beginning of a line
+to exit back to nsh.
+
+The two buses can also be bridged to each other in the background,
+leaving the console free, by binding the two ports with output
+redirection::
+
+    nsh> cat /dev/ttyS1 > /dev/ttyS2 &
+    nsh> cat /dev/ttyS2 > /dev/ttyS1 &
+
+Since the board has two transceivers, a loopback self-test is
+possible by wiring A-A and B-B between the two RS-485 terminals and
+running ``cu`` on one port while sending data on the other.
+
 modbus_slave
 ------------
 

boards/arm/stm32h7/linum-stm32h753bi/configs/rs485/defconfig

@@ -0,0 +1,66 @@
+#
+# This file is autogenerated: PLEASE DO NOT EDIT IT.
+#
+# You can use "make menuconfig" to make any modifications to the installed .config file.
+# You can then do "make savedefconfig" to generate a new defconfig file that includes your
+# modifications.
+#
+# CONFIG_STANDARD_SERIAL is not set
+CONFIG_ARCH="arm"
+CONFIG_ARCH_BOARD="linum-stm32h753bi"
+CONFIG_ARCH_BOARD_LINUM_STM32H753BI=y
+CONFIG_ARCH_CHIP="stm32h7"
+CONFIG_ARCH_CHIP_STM32=y
+CONFIG_ARCH_CHIP_STM32H753BI=y
+CONFIG_ARCH_CHIP_STM32H7=y
+CONFIG_ARCH_CHIP_STM32H7_CORTEXM7=y
+CONFIG_ARCH_INTERRUPTSTACK=2048
+CONFIG_ARCH_STACKDUMP=y
+CONFIG_ARMV7M_DCACHE=y
+CONFIG_ARMV7M_DCACHE_WRITETHROUGH=y
+CONFIG_ARMV7M_DTCM=y
+CONFIG_ARMV7M_ICACHE=y
+CONFIG_BOARD_LOOPSPERMSEC=43103
+CONFIG_BUILTIN=y
+CONFIG_DEBUG_FEATURES=y
+CONFIG_DEBUG_SYMBOLS=y
+CONFIG_EXAMPLES_ALARM=y
+CONFIG_FS_PROCFS=y
+CONFIG_IDLETHREAD_STACKSIZE=2048
+CONFIG_INIT_ENTRYPOINT="nsh_main"
+CONFIG_INIT_STACKSIZE=4096
+CONFIG_INTELHEX_BINARY=y
+CONFIG_LIBM=y
+CONFIG_LINE_MAX=64
+CONFIG_MM_REGIONS=4
+CONFIG_NSH_BUILTIN_APPS=y
+CONFIG_NSH_DISABLE_IFUPDOWN=y
+CONFIG_NSH_DISABLE_VCONFIG=y
+CONFIG_NSH_FILEIOSIZE=512
+CONFIG_NSH_READLINE=y
+CONFIG_PREALLOC_TIMERS=4
+CONFIG_RAM_SIZE=245760
+CONFIG_RAM_START=0x20010000
+CONFIG_RAW_BINARY=y
+CONFIG_RR_INTERVAL=200
+CONFIG_RTC_ALARM=y
+CONFIG_RTC_DATETIME=y
+CONFIG_RTC_DRIVER=y
+CONFIG_SCHED_CPULOAD_SYSCLK=y
+CONFIG_SCHED_WAITPID=y
+CONFIG_SERIAL_TERMIOS=y
+CONFIG_STACK_COLORATION=y
+CONFIG_START_DAY=6
+CONFIG_START_MONTH=12
+CONFIG_START_YEAR=2011
+CONFIG_STM32_PWR=y
+CONFIG_STM32_RTC=y
+CONFIG_STM32_UART4=y
+CONFIG_STM32_USART1=y
+CONFIG_STM32_USART6=y
+CONFIG_SYSTEM_CUTERM=y
+CONFIG_SYSTEM_NSH=y
+CONFIG_TASK_NAME_SIZE=20
+CONFIG_UART4_RS485=y
+CONFIG_USART1_SERIAL_CONSOLE=y
+CONFIG_USART6_RS485=y