reference/usage/subcommands: monitor subcommand (#330)

reference/usage/subcommands: Document the `tinygo monitor` subcommand. And the `-monitor` flag on the
`tinygo flash` command.

content/docs/reference/usage/subcommands.md

@@ -36,7 +36,58 @@ Compile and link the program into a regular executable. For microcontrollers, it
 Run the program, either directly on the host or in an emulated environment (depending on `-target`).
 
 ### flash
-Flash the program to a microcontroller.
+Flash the program to a microcontroller. Some common flags are described below.
+
+`-target={name}`: Specifies the type of microcontroller that is used. The `name`
+of the microcontroller is given on the individual pages for each board type
+listed under [Microcontrollers]({{<ref "../microcontrollers/">}}). For example,
+`arduino-nano`, `d1mini`, `xiao`.
+
+`-monitor`: Start the serial monitor (see below) immediately after flashing.
+However, some microcontrollers need a split second or two to configure the
+serial port after flashing, and using the `-monitor` flag can fail because the
+serial monitor starts too quickly. In that case, use the `tinygo monitor`
+command explicitly.
+
+### monitor
+Start the serial monitor on the serial port that is connected to the
+microcontroller. If there is only a single board attached to the host computer,
+the default values for various options should be sufficient. In other
+situations, particularly if you have multiple microcontrollers attached, some
+parameters may need to be overridden using the following flags:
+
+`-port={port}`: If there are multiple microcontroller attached, an error message
+will display a list of potential serial ports. The appropriate port can be
+specified by this flag. On Linux, the port will be something like `/dev/ttyUSB0`
+or `/dev/ttyACM1`. On MacOS, the port will look like `/dev/cu.usbserial-1420`.
+On Windows, the port will be something like `COM1` or `COM31`.
+
+`-baudrate={rate}`: The default baud rate is 115200. Boards using the AVR
+processor (e.g. [Arduino Nano]({{<ref "../microcontrollers/arduino-nano.md">}}),
+[Arduino Mega 2560]({{<ref "../microcontrollers/arduino-mega2560">}})) use 9600
+instead.
+
+`-target={name}`: If you have more than one microcontrollers attached, you can
+sometimes just specify the target name and let `tinygo monitor` figure out the
+port. Sometimes, this does not work and you have to explicitly use the `-port`
+flag.
+
+The serial monitor intercepts several control characters for its own use instead
+of sending them to the microcontroller:
+
+* Control-C: terminates the `tinygo monitor`
+* Control-Z: suspends the `tinygo monitor` and drops back into shell
+* Control-\\: terminates the `tinygo monitor` with a stack trace
+* Control-S: flow control, suspends output to the console
+* Control-Q: flow control, resumes output to the console
+* Control-@: thrown away by `tinygo monitor`
+
+**Note**: If you are using `os.Stdin` on the microcontroller, you may find that
+a CR character on the host computer (also known as Enter, `^M`, or `\r`) is
+transmitted to the microcontroller without conversion, so `os.Stdin` returns a
+`\r` character instead of the expected `\n` (also known as `^J`, NL, or LF) to
+indicate end-of-line. You may be able to get around this problem by hitting
+`Control-J` in `tinygo monitor` to transmit the `\n` end-of-line character.
 
 ### gdb
 Compile the program, optionally flash it to a microcontroller if it is a remote target, and drop into a GDB shell. From there you can set breakpoints, start the program with `run` or `continue` (`run` for a local program, `continue` for on-chip debugging), single-step, show a backtrace, break and resume the program with Ctrl-C/`continue`, etc. You may need to install extra tools (like `openocd` and `arm-none-eabi-gdb`) to be able to do this. Also, you may need a dedicated debugger to be able to debug certain boards if no debugger is integrated. Some boards (like the BBC micro:bit and most professional evaluation boards) have an integrated debugger.