From 52e982e9e297d83603948159eae9773ad0b02bbe Mon Sep 17 00:00:00 2001 From: Brian Park Date: Fri, 21 Apr 2023 23:31:07 -0700 Subject: [PATCH] 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 | 53 ++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/content/docs/reference/usage/subcommands.md b/content/docs/reference/usage/subcommands.md index 310be5e5..0192c15f 100644 --- a/content/docs/reference/usage/subcommands.md +++ b/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]({{}}). 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]({{}}), +[Arduino Mega 2560]({{}})) 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.