docs: Update Serial console page to VyOS 1.5 standards (#2250)

* docs: Update Serial console page to VyOS 1.5 standards

* Remove a passage with outdated information

---------

Co-authored-by: Daniil Baturin <daniil@baturin.org>

1 files changed, 97 insertions, 47 deletions

diff --git a/docs/configuration/system/console.md b/docs/configuration/system/console.md
index 9017fa30..c22fab9f 100644
--- a/docs/configuration/system/console.md
+++ b/docs/configuration/system/console.md
@@ -1,59 +1,109 @@
+---
+myst:
+  html_meta:
+    description: |
+      A serial console provides text-based access to the router's command
+      line over a serial device, useful for diagnostics, upgrades, and other
+      situations where SSH access is unavailable.
+    keywords: serial console, text-based interface, serial device, baud rate
+---
+
 (serial-console)=
 
-# Serial Console
+# Serial console
+
+A serial console is a text-based interface that provides access to the
+router's command line via a serial device.
+
+For routine local access, a serial console offers no advantage over a
+directly attached keyboard and screen.
 
-For the average user a serial console has no advantage over a console offered
-by a directly attached keyboard and screen. Serial consoles are much slower,
-taking up to a second to fill a 80 column by 24 line screen. Serial consoles
-generally only support non-proportional ASCII text, with limited support for
-languages other than English.
+There are some scenarios where serial consoles are useful. Remote
+systems are usually administered over {ref}`ssh`, but sometimes console
+access is the only way to diagnose and correct software failures. Certain
+system upgrades may also require console access.
 
-There are some scenarios where serial consoles are useful. System administration
-of remote computers is usually done using {ref}`ssh`, but there are times when
-access to the console is the only way to diagnose and correct software failures.
-Major upgrades to the installed distribution may also require console access.
+## Configuration
 
 ```{cfgcmd} set system console device \<device\>
 
-Defines the specified device as a system console. Available console devices
-can be (see completion helper):
-* ``ttySN`` - Serial device name
-* ``ttyAMAN``- Serial device name for some arm64 systems
-* ``ttyUSBX`` - USB Serial device name
-* ``hvc0`` - Xen console
+**Enable a serial console on the specified device.**
+
+`<device>` is the device name, in one of the following formats:
+
+- `ttySN`: Standard serial device.
+- `ttyAMAN`: ARM serial device.
+- `usbNbXpY`: {abbr}`USB (Universal Serial Bus)`-to-serial converter,
+  addressed by its bus path.
+- `hvcN`: Xen console.
+
+`N` is a number in all formats. In `usbNbXpY`, `X` and `Y` are the bus
+and port parts of the converter's USB path and can contain dot-separated
+numbers.
+
+A USB serial converter must be connected upon commit. Otherwise, the
+commit fails.
+```
+
+Example:
+
+```none
+set system console device ttyS0
 ```
 
 ```{cfgcmd} set system console device \<device\> kernel
 
-When set, the selected serial console is used as the kernel boot console.
-When removed, the kernel boot console falls back to tty0.
-
-:::{note}
-Only one serial console can carry the ``kernel`` option.
-When VyOS is installed via serial console, this option is set automatically
-for the serial interface used during installation; usually ``ttyS0`` or
-``ttyAMA0``.
-:::
-```
-
-```{cfgcmd} set system console device \<device\> speed \<speed\>
-
-The speed (baudrate) of the console device. Supported values are:
-* ``1200`` - 1200 bps
-* ``2400`` - 2400 bps
-* ``4800`` - 4800 bps
-* ``9600`` - 9600 bps
-* ``19200`` - 19,200 bps
-* ``38400`` - 38,400 bps (default for Xen console)
-* ``57600`` - 57,600 bps
-* ``115200`` - 115,200 bps (default for serial console)
-
-:::{note}
-If you use USB to serial converters for connecting to your VyOS
-appliance please note that most of them use software emulation without flow
-control. This means you should start with a common baud rate (most likely
-9600 baud) as otherwise you probably can not connect to the device using
-high speed baud rates as your serial converter simply can not process this
-data rate.
-:::
+**Output kernel messages to the specified device.**
+
+By default, the router sends them to `tty0`.
+
+The specified device must be a `ttyS` or `ttyAMA` device, and only one
+device can receive kernel messages. Otherwise, the commit fails.
+```
+
+```{note}
+If you install the router from a serial console, the installer sets this
+option automatically on the device used during installation, usually
+`ttyS0` or `ttyAMA0`.
+```
+
+Example:
+
+```none
+set system console device ttyS0 kernel
+```
+
+```{cfgcmd} set system console device \<device\> speed \<1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200\>
+
+**Configure the console baud rate.**
+
+The default is `115200`, except for `hvcN` (Xen) consoles, which default
+to `38400`.
+```
+
+```{note}
+Many USB-to-serial converters lack hardware flow control. Without it, a
+converter may silently drop data at high baud rates. If you cannot
+connect at a high rate, set the speed to `9600`.
+```
+
+Example:
+
+```none
+set system console device ttyS0 speed 115200
+```
+
+```{cfgcmd} set system console powersave
+
+**Enable screen-blank power saving on the local VGA console.**
+
+When enabled, the local console blanks the screen after 15 minutes of
+inactivity and powers down the monitor after 60 minutes. This does not
+affect serial consoles or SSH sessions.
+```
+
+Example:
+
+```none
+set system console powersave
 ```
\ No newline at end of file