reference/usage/subcommands: monitor subcommand

[bxparks]

Document the tinygo monitor subcommand. And the -monitor flag on the tinygo flash command.

[aykevl]

I did an initial review, but I didn't write this code so I'm not very familiar with this code. It looks good though.

@sago35 can you take a look?

[aykevl]

Most of these are just regular shell shortcuts, TinyGo doesn't handle them in any special way (for example, Control-\ always terminates the current process). But I guess they could still be useful as documentation.

[sago35]

I believe these are shell operations.
I think the minimum is just ctrl-c.
But I think it would be useful.

I would add Ctrl-J (LF) to the list.
When reading from bufio.Scanner, etc., pressing Enter (or Return or Ctrl-M : CR) does not respond. In this case, you need to press Ctrl-J (LF).

[bxparks]

It's been a few years since I did a deep dive into the terminal driver configuration on Linux, but my understanding is that the handling of control characters is performed by the terminal driver, not the shell. When an application launches into the foreground, it can choose to configure the terminal driver to handle these control character in a wide assortment of ways.

By default, various control characters are configured to send signals to the foreground process. For example, ^C sends the SIGINT, ^Z sends SIGTSTP, ^\ sends SIGQUIT. But the terminal driver can be configured to not send those signals at all. In addition, the terminal driver can be configured to bind alternative control characters to various signals. For example, I can run the command $ stty intr '^X' to replace ^C with ^X in the shell.

(I think there is an additional complexity in all this, because even if the terminal driver sends one of these SIGXXX signals, the application can trap it, fire off a signal handler, and then choose to either eat the control character, or pass along the control character to the microcontroller.)

Flow control seems to be slightly different than other control characters, because ^S and ^Q don't generate Unix signals. I believe they are handled directly in the terminal driver itself. I normally have flow control turned off in my bash shell, but it looks like tinygo monitor explicitly turns them back on, or uses some defaults with these enabled.

So I think it's useful to have these control characters listed, because tinygo monitor could have been configured to transparently pass every control character to the microcontroller without interpretation. But it does not. I normally use picocom, and I have it configured to send almost all control characters to the microcontroller, including ^C, ^Z, ^Q, ^S, and so on. Even ^\ can be configured to be ignored and sent along to the microcontroller.

@sago35: I am not sure I understand your comment about ^J, ^M, and bufio.Scanner. I wasn't able to find the source code for tinygo monitor, but I would be surprised to learn that it used buffered IO when reading from the keyboard. I think you are referring to the confusing complexity of handling DOS line terminators (\r\n) versus Unix line terminator (\n). To be honest, I don't know whether the println() or fmt.Println() functions send DOS terminators or Unix terminators from the microcontrollers. I have my picocom configured to automatically translate DOS terminators into Unix terminators, because the Arduino Serial.println() is usually configured to use DOS terminators. But many people write Serial.printf("...\n"), which sends only a Unix line terminator.

[sago35]

bufio.Scanner is useful when reading lines typed from the keyboard.

In the following example, LF must be sent.
If you use tinygo monitor, you need to press Ctrl-j.

https://github.com/tinygo-org/tinygo/blob/v0.27.0/src/examples/echo2/echo2.go

[bxparks]

@sago35:

bufio.Scanner is useful when reading lines typed from the keyboard.

In the following example, LF must be sent. If you use tinygo monitor, you need to press Ctrl-j.

https://github.com/tinygo-org/tinygo/blob/v0.27.0/src/examples/echo2/echo2.go

Ah, you are talking about running bufio.Scanner on the microcontroller, not in the tinygo monitor code on the host.

This feels like this is a bug with os.Stdin on the microcontroller, or a missing terminal driver layer on the microcontroller.
The fact that a ^M is passed to the microcontroller as ^M without processing seems like a good thing. Something on the microcontroller should be converting the physical control character \r (i.e.^M, CR) into the logical control character \n (aka ^J, LF) to indicate end of line.

It's not clear to me that this information belongs in this section, but since you brought it up I added the following:

Note: If you are using os.Stdin on the microcontroller, you may find that
an Enter character on the host computer (also known as ^M, \r, or CR) is
transmitted to the microcontroller without conversion, so os.Stdin returns a
\r character instead of the expected \n (also known as ^J 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.

[aykevl]

Looking at the source code, it appears you can actually use tinygo monitor -target=xxx to filter the ports. For many boards, TinyGo knows the USB vid/pid of the port and thus can pick the right port automatically.

[sago35]

For USB-compatible microcontrollers, it is convenient to specify -target=xxx instead of -port=xxx.
However, when two identical microcontrollers are connected, for example, it is necessary to use -port=xxx.

USB-compatible microcontrollers at tinygo 0.27 : samd21, samd51, nrf52840, rp2040

[bxparks]

When there are multiple microcontrollers connected, the tinygo monitor prints an error message like this:

error: multiple serial ports available - use -port flag, available ports are /dev/ttyACM0, /dev/ttyACM1

I think it would be more clear to tell the user to use the -port flag as instructed by the error message. Please take a look at my wording of this in the updated commit.

[sago35]

When running tinygo flash, -target is required, but -port is not.
I created tinygo monitor with the scenario that I would first try tinygo monitor -target, and if that could not connect, then I would use -port.

I don't know which is better, but it would be better to at least have it written that -target=xxx can be specified instead of -port=yyy.

[bxparks]

When running tinygo flash, -target is required, but -port is not. I created tinygo monitor with the scenario that I would first try tinygo monitor -target, and if that could not connect, then I would use -port.

I don't know which is better, but it would be better to at least have it written that -target=xxx can be specified instead of -port=yyy.

I added explanations of the various -port, -baudrate, and -target flags on the tinygo monitor subcommand. They don't always work consistently. For example, on Arduino Zero clone (SAMD21, on /dev/ttyACM0), using just the -target=arduino-zero does not work if there is an Arduino Nano (/dev/ttyUSB0) attached.

[deadprogram]

Thanks for working on this @bxparks and to @sago35 and @aykevl for all the great review comments.

Squashed/merged.