Document Serial Monitor changes

[tigoe]

The 2.0 IDE and the Pro IDE introduced a major change to the UX of the Serial Monitor. Instead of being its own window, it now is attached to a sketch window. This is a change that is likely to cause confusion in many classrooms, and requires better thought to the UX and more documentation so as not to lose users.

Example:

1. Open a serial sketch (say AnalogReadSerial, from the Basics menu)
2. Pick a board and port
3. upload code
4. open serial monitor
5. open a new sketch window, write a new sketch
6. attempt to upload

The result will be that the second sketch will not upload and you;'ll get a "port busy" error. But you can't see the Serial Monitor, because it's in the sketch window behind the current one, so you don't know where to look.

This will result in beginning users wasting hours trying to solve the problem. It could be addressed by a better error message, e.g. "error: serial port is in use. Check to see if you have the Serial Monitor open in another sketch window."

it could also be solved by moving the Serial Monitor to the in-focus window, however, this is a problem if you have more than one board attached at time.

---

Example 2:

1. Attach a board to USB port 1
2. Attach another to USB port 2
3. In one window, select board 1 on port 1
4. Upload a sketch to board 1
5. Open serial port 1
6. In a second window, select board 2 on port 2
7. Upload a sketch to board 2
8. Attempt to open port 2

This is a nice change, it allows you to have two serial monitors open at a time. But it doesn't work by default. When you click the Serial Monitor icon in window 2, it attempts to open serial port 1 rather than the port it just uploaded to! You have to explicitly pick the second port AFTER you upload to open both ports. That's confusing. Whatever board and port you select for a given window should be the default for all the serial operations associated with that window.

---

There are a series of pop-up toasts that pop up when you upload a changed sketch while the serial monitor is open warning that the port's not available, etc. These are distracting, and not useful if you're handling the closing of the port, the upload, and the re-opening in the background. They should be kept in the error log, not in pop-up toasts.

---

These problems will become more confusing as more cases pop up. If the new model is a strong connection between window, board, and port, and the Serial Monitor (and later, the Serial Plotter) is no longer independent, that needs to be made very clear in announcements, documentations, and tutorials. It is a potential advantage, but it is also a potential learning hazard, as teachers are used to the old way and will trip over the new way if they're not informed. I did.

[ubidefeo]

hi @tigoe

I see your point.
I have sent this to Content so they can use your feedback as a source for amending the official tutorial.
Would you have time to go through it and let us know if there's something you'd change?

Documentation on IDE 2.0 is in progress, and we add more content as we go, but on such a feature your feedback is precious
https://www.arduino.cc/en/Tutorial/getting-started-with-ide-v2/ide-v2-serial-monitor

thanks
ubi

[karlsoderby]

Hi @tigoe and @ubidefeo I will revise the Serial Monitor tutorial for IDE 2.0, and see if I can highlight this better, perhaps adding a comparison section between the old Serial Monitor window and the new one!

[tigoe]

Happy to look at notes, @ubidefeo and @karlsoderby .

First thing I'd do is make sure that when you select a serial port for a given window, it stays with that window. See Example 2 above, which does not conform to what you're describing in the documentation page in progress that you're citing.

On the documentation page:
I'd avoid adverbs like "simply" and "easily" like this: "You can easily download the editor from...". While it may be an attempt to reassure the reader, for those who don't get what you're describing to work, they then feel stupid because you told them it should be easy. Be matter-of-fact about it: "you can download the editor from..."

I also think it's better to write instructions in the second person, so the reader knows what they should do, rather than the first person plural. "You" are doing this, not "we". I have a style guide I try to use that may be of use.

In this draft, you're jumping straight to the exciting (and advanced) thing without explaining the new UX concept or the potential problem it raises with with a more basic activity. I think I'd mention explicitly that the 2.0 IDE, unlike the 1.0, can keep track of multiple boards plugged into multiple ports on your computer. To you, the user, this means that you choose a board and port from the Board/port selection option menu in the sketch window, and that sketch window gets control over that port and board. When you switch from one sketch window to another, the serial port that you opened in the first window is still open in that window. If you try to upload code to the same board and port in the second window, you'll get an error. It's a change of mindset from the 1.0 IDE, where the serial monitor was an independent window, and the IDE kept track of only one port.

Then I'd go on to explain how this is an advantage as you did in this tutorial.

[tigoe]

Related to this: in IDE 1.0 and before:

1. Click upload
2. Click "Serial Monitor"
3. Serial monitor opens
4. When upload begins, serial monitor greys out
5. When upload completes serial monitor re-activates.

In IDE2.0:

1. Click upload
2. Click "Serial Monitor"
3. Console message appears, "Compilation complete. Cannot perform port reset: opening port at 1200bps: Serial port busy"
4. No indication that upload is in progress, no indication of how or when it's okay to open Serial Monitor again.
5. Several seconds later, console message appears: "No device found on XXXX. Upload error: Error: 2 UNKNOWN: uploading error: uploading error: exit status 1"

This is much less clear or useful behavior than IDE 1.0