Add documentation for serial plotter

[cousteaulecommandant]

I haven't found any documentation for the serial plotter, is there any? For example, I've noticed that you can just print comma-separated (or space-separated) values, but I don't know if there's more to this (can I name the plots, doing something like A=1 B=2, for example? Also, are there other options to separate values? What values can I plot? etc). This, combined with the fact that the serial plotter is kind of hidden, may make people not know it exists.

[q2dg]

There are some (good but very hidden) examples in https://github.com/arduino/Arduino/issues/3451

[per1234]

Serial Plotter needs to be added to the Tools section of https://www.arduino.cc/en/Guide/Environment.

are there other options to separate values?

From https://www.arduino.cc/en/Tutorial/ArduinoSoundSpectrumSerialPlotter I just learned that \t will also work.

[rin67630]

You have got https://github.com/arduino/Arduino/blob/ba34eb640e5f6c2f8618debf61022f731c0eab74/build/shared/ArduinoSerialPlotterProtocol.md albeit it is not easy to find.

[madsdyd]

Serial Plotter needs to be added to the Tools section of https://www.arduino.cc/en/Guide/Environment.

What is the process for doing this?

[per1234]

What is the process for doing this?

That documentation content is not hosted in a public repository, so there is no way to propose changes to it via a pull request. The way is to provide a detailed description of the proposed change here. Ideally, this would make the update process as close as possible to a quick copy/paste for the people who do have edit access to that content.

[madsdyd]

Ok, let me have a go:

Description of change

Proposal is to add a documentation section for the Serial Plotter to the page at https://www.arduino.cc/en/Guide/Environment. The section should follow immediately after the "Serial Monitor" section.

Proposed Text

Heading: Serial Plotter

This works much like the Serial Monitor, but instead of showing the data as text, the data is interpreted as floating point or integer values to be graphed on a chart. This is very useful to quickly get a visualization of e.g. sensor readings or similar.

The Serial Plotter is quite versatile, and supports both multiple data series (lines on the graph) as well as labeling of data series.

Similar to the Serial Monitor, it works by reading a line of input from a selected serial connection. Every line is then analyzed for data points from one or more data series. Each data point is added to a matching data seruies based on order of data in the line and graphed. When more than 500 data points are collected for a data series, the oldest data point for the given series is discarded. This means that the visualization is always of at most the 500 newest data points in each data series.

The data series are visualized as lines. The Y value of any given point is the value read from the serial port. The X value is effectively just the order in which the data was read.

Data points on an input line are separated by spaces, comma or tabulator. Values that can not be parsed as a float or integer value are ignored. To prefix a label to a data point, use "mylabel:" with no spaces (nor comma or tab character) in the label or between the label and the value.

The full protocol for the Serial Plotter, with examples, is available at https://github.com/arduino/Arduino/blob/master/build/shared/ArduinoSerialPlotterProtocol.md

[per1234]

The examples component of the Serial Plotter documentation is tracked by https://github.com/arduino/arduino-examples/issues/8

[per1234]

A general overview of Serial Plotter is now available: https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-serial-plotter

The source of it is hosted in the public repository and contributions of enhancements and corrections are welcome:

https://github.com/arduino/docs-content/tree/main/content/software/ide-v2/tutorials/ide-v2-serial-plotter

However, the issue is not yet resolved because the data format is not specified anywhere in the user accessible documentation content. The linked plotter protocol document might serve as a reference for that but it contains critical technical errors and is not as user friendly as it might be:

https://github.com/arduino/Arduino/blob/master/build/shared/ArduinoSerialPlotterProtocol.md