Charts

Turning a stream of numbers into a curve you can read

A terminal shows you what a device said. A chart shows you what it did — a supply current over an hour, a temperature settling after a step, a frequency sweep. The Charts tab draws recordings: measurement files that a Lua script writes while it talks to your device.

A recording is a file

This one sentence explains most of the tab's behaviour. There is no “live mode” separate from “open a saved measurement”. There is a file, which sometimes grows. The script appends to the end, the tab reads the new part and extends the curve.

What follows from that:

• You cannot forget to save. Saving is not a separate step — the measurement is on disk from the first sample.
• The measurement survives closing the tab, restarting the app, even a crash. Whatever was written stays written.
• A live chart is simply a recording someone is writing to right now. Show it and it grows in front of you.
• An older measurement is just another file, so opening it does not interrupt one in progress.

One recording holds one measured quantity — voltage in one, current in another. A chart showing both is built by ticking two recordings in the list, not by writing two columns into one file.

Where the data comes from

From your script. The Charts tab never writes measurements — it reads them, and the only things it writes back are presentation choices (the curve colour) and deletion of a whole recording. The script side is four calls, described in full on the Lua API page:

create_chart_file('current', { unit = 'A', step = 0.001, type = 'u16',
                              factor = 0.0012, draw = 'line' })

for i = 1, 1000 do
  add_to_chart_file('current', read_adc())   -- one measurement, one call
  sleep(1)
end

You do not batch the writes yourself. Values collect in memory and reach the disk every 100 ms, or once 512 records have piled up — whichever comes first. Call add_to_chart_file per measurement and let the app worry about the disk.

A name that is already taken is an error, not an append to the old curve — deliberately, so two measurements never get glued into one. Use exists_chart_file to pick a free name when your script may run twice.

Why the files stay small

An hour of current sampled a thousand times a second is 3.6 million points. Stored as full-precision time and value that is 57 MB; stored the way this format allows, 7 MB. Two options do it, and both are set when the recording is created:

• The number type — a 12-bit converter reading fits in u16, two bytes instead of eight. factor and offset turn it into amperes when it is read, so nothing is rounded on the way in and the original reading stays in the file.
• A computed X axis — give step and the horizontal coordinate is not stored at all; it follows from the record number. Half the file disappears.

The Charts tab

Open it from the Charts icon on the top bar. Across the top of the tab:

• Recordings — a button with a counter that drops down the list of every recording on disk. The list is rebuilt from the folder every second and a half while the tab is open, so a file the script has just created appears on its own — and one deleted from outside the app disappears just as reliably.
• two pin buttons — an arrow running into a vertical bar, one for each end of the time axis. The right-hand one pins the view to the newest sample, the left-hand one to the start of the recording. They work independently, and the combination decides what a running measurement looks like: with only the end pinned the view is a window of fixed width travelling along like tape; with both pinned the chart stretches instead, showing everything from the first sample to the latest one. Pin neither and the view stays where you put it. Zooming with the wheel releases both, since one turn moves both ends at once; dragging a figure at either end of the time axis releases only the pin at that end, leaving the other to carry on.
• info box — shows or hides the details panel drawn in the corner of the chart (see below).
• Save image — writes the chart as a PNG.

Each row in the recordings list carries three controls: a tick that shows or hides that curve, a coloured dot that opens a colour picker, and a bin that deletes the file. Deleting asks first, and it is permanent — the measurement file is gone.

Several curves on one chart

Tick more than one recording and they share the chart, each keeping its own vertical scale — current in amperes on one side, voltage in volts on the other. That is the point of recording quantities separately.

Two things refuse to share, and the app says so rather than drawing nonsense:

• Different X axes or chart kinds — a curve against time and a curve against frequency have nothing in common to line up. Untick one to show the other.
• A waterfall — a 3D surface is shown on its own, because it would bury anything drawn behind it.

How a curve is drawn

The stored measurement and the picture of it are two different things. The same file can be drawn five ways, and switching between them changes nothing on disk:

• line — the default, right for anything sampled over time.
• points — use this whenever X is not time and the sweep may go both ways. An I-V curve drawn as a line folds back over itself and cannot be read.
• steps — for a value that switches and then holds until the next sample: a setpoint, a gear, a relay state.
• bars and area — for counts and for filled envelopes.

The script picks the starting one with draw; you can change it later from the tab. Either axis can also be logarithmic — a 20 Hz to 20 kHz sweep is unreadable on a linear axis, and that too is presentation only.

Waterfall — a spectrum over time

Set vector above 1 when a recording is created and each record stops being one number and becomes a whole row of them for one moment — an FFT spectrum, a line scan, a set of channels read together. Write them with add_vector_to_chart_file, giving the same number of values every time; a mismatch is an error at write time, not a silent trim.

The tab draws such a recording as a 3D surface: time along one edge, frequency (or whatever the vector axis is) along the other, amplitude as height and colour. This is how a bearing fault shows itself — a sideband that grows over minutes is obvious as a ridge and invisible in any single spectrum.

A waterfall gets two colours: a base colour and a peak colour, with the surface graded between them.

The info box

A recording can carry meta — free-form text entries written into its header by the script: who ran the measurement, when, on what device, with what settings. The tab draws them as a small box in the corner of the chart, so a saved image explains itself months later without anyone remembering the circumstances.

The keys are yours to choose — whatever the script puts in shows up as a row. When several recordings on the chart carry their own entries, each gets its own block headed by the recording name. Keep them short; the box has to fit in the corner. The info box tick turns the whole thing off when you want a clean picture.

Saving the picture

Save image asks where to put a PNG and writes exactly what you see — the recordings you ticked, the zoom you set, the theme colours, the info box and any logo. It is the chart as displayed, not a re-render with different settings.

The AI assistant can produce the same image on request, with one difference: an image it asks for is written inside the sandbox folder, never anywhere you did not choose. Picking a location yourself in the save dialog is your consent to write there; a model asking for a file never got that consent, so it gets the sandbox.