Plot commands

plot [options] [variables]

Command for plotting [variables] into plots. Plots can be viewed in real-time in the scope. Scope can be opened by clicking Ctrl + S while in the terminal of the controller. If no arguments and no options are specified, selects the next plot as active and prints out the active plot to the terminal (if the previous active plot was 3, selects plot 0). The format in which the data will be visualized can be further adjusted in the scope window or with the legend command.

Multiple variables can be entered, separated by spaces, and always at the end.

Options:

• -p<number> - sets active plot, acceptable values are 0 - 3
• -f<number> - sets format in which are data plotted (if not specified, the default, usually the best option, will be used):
  • 0 - one byte (int8)
  • 1 - two bytes (int16)
  • 2 - four bytes (int32)
  • 3 - float
• -d<number> - sets sampling period in milliseconds
• -l - toggle on data logging. Flowing data is not shown in the plot but is redirected to flash memory. For further work with the data in flash memory and playback of this data take a look at proclog command
• -w - Synchronization option. If used, the command is blocking other execution until the current sample is sent (useful for more complex constructs).
• -a - plot array, X-axis are indices and Y-axis are values of an array.
• -q - quiet option, suppress textual output
• -o - stops periodic sampling and plots only the current value (one call of the command with -o options always plots one value)
• -e - clear all plots
• -c - clear the active plot

Return value

retval	meaning
-3	unknown option
-2	error evaluating variable to plot
-1	error allocating plot
non-negative number	returns number of current plot

Examples

AM-felix#/common>plot                 # print the active plot
current plot 1
AM-felix#/common>plot -p1 -d30 gpio0  # plot gpio0 to plot 2 with period 30ms
gpio0 (1) sampled in plot 1
AM-felix#/common>plot                 # the active plot was switched to plot 2 (with -p1)
current plot 2

When using the option -p<index> we are indexing the plot we want to use, meaning that plot 0 will be selected with -p0, plot 1 with -p1 and so on up to plot 3.

AM-felix#>var array.10                     # create array of 10 ints
AM-felix#>set array 1,2,3,4,5,6,7,8,9,10   # populate the array
AM-felix#>vr array
-> array int32 : 1,2,3,4,5,6,7,8,9,10

Total 1 entries
AM-felix#>plot -a array                    # plot the array to the current (active) plot
array (1) sampled in plot 0

---

clear [arg]

Clears the plot(s). If run without arguments clears the active (current) plot. If run with argument(s) (doesn't matter what argument, or arguments) clears all the plots. Works essentially the same as plot -c and plot -e.

Examples:

AM-felix#/common>clear
plot1 cleared
AM-felix#/common>clear something
all plots cleared

---

period [-p<n>] [-g/c] [number]

Changes or prints the period of the selected plot. If no argument is given prints out the period of the active (current) plot or the selected plot by the -p option. If run with argument sets the period of the current or selected plot to the [number] argument.

Options:

• -p<n> - selects the plot of which we want to change the period. If left out, the active (current) plot is selected.
• -g - this option is only significant if no argument is given. If present, the command will return the group number (only when no argument is provided if used with an argument the option makes no change).
• -c - this option is only significant if no argument is given. If present, the command will return the current period along with the group in one int. period is saved in the lower two bytes and group in the upper two. Again if an argument is given, this option makes no change.

Options -g and -c cannot be used together.

Return value

Implicitly returns the current/set period, but can be changed with options, more information above. Look at options -g and -c.

---

legend

This command sets attributes of the Scope. Scope is controlled by registers - part of memory, where actual settings of the Scope are saved. Command legend writes values to the registers. Registers are divided into several sections. Different data types are located in different sections and are set by different parameters.

The command legend has two different syntaxes. One for setting registers that hold int16 and int32 values and another one for setting control, float, and string values.

First syntax option - setting int16 and int32 registers

The syntax prototype for setting/changing the integer register values:

legend -p<plot-number> -s<int16-address>/-i<int32-address> <setmask> <clrmask>

• -p<plot-number> - select which plot you want to edit
• -s<int16-address>/-i<int32-address> - select the address of the value you want to edit. More info on address matching is in the tables below.
• <setmask> - select which bits you want to turn from 0 to 1. Has to be a number, what happens the number is converted to binary form and binary OR operation is made with the register.
• <clrmask> - select which bits you want to turn from 1 to 0. Has to be a number, you can interpret it as (~<clrmask>) | <register>. Where <clrmask> has one, there will be zero in the register, in binary terms.

You cannot omit <setmask> or <clrmask>, but if you don't want to set any bits to 0, you can insert 0 for <clrmask>.

int16 register address table

address	name	notes
20	flags	hexadecimal masks and corresponding functions in plot INTER -- 0x01 SCROLL -- 0x02 MASTER -- 0x04 SLAVE -- 0x08 XSCALE -- 0x10 XOFFSET -- 0x20 TDRAW -- 0x40 TERASE -- 0x80
21	trends	disable displaying trends in plot (LSB is trend 1, MSB is trend 8)

int32 register address table

address	name	notes
28	memory size	number of scope samples
96 - 103	trend 1 - 8 color and style, each address for one trend	3 bytes RGB + 1 byte style

Second syntax option - setting control, float and string registers

The syntax prototype:

legend -p<plot-number> -c<control-address>/-f<float-address>/-l<string-address> <value1> [values]

• -p<plot-number> - select which plot you want to edit
• -c/-f/-l - exactly one of these options has to be present, more info on address matching in the tables below:
  • -c<control-address> - select control register
  • -f<float-address> - select float register
  • -l<string-address> - select string register
• <value1> [values] - at least one value has to be present, which will be set into the addressed register (for strings, no spaces are allowed). If more values are given, separated by spaces, each new value is saved into register with <address>++.

control register address table

address	name	notes
16	control	Keypress emulation. A number of ASCII character that will be sent as if a key on a keyboard was pressed.

float register address table

address	name
8	gainY
9	biasY
10	gainX
11	biasX
32	scaleY
33	offsetY
34	scaleX
35	offsetX

string register address table

address	name
72	figure name
74	plot name
76	unit name
78	Xunit name
80 - 87	trend 1 - 8 name

Return value

retval	meaning
-3	unknown option
2	wrong syntax
-1	unspecified error
0	success

Examples

AM-felix#>plot -p0 common/gpio0               # plot gpio0 to plot0
common/gpio0 (1) sampled in plot 0
AM-felix#>legend -p0 -s20 3 0                 # set the plot to interpolate and scroll
AM-felix#>legend -p0 -l72 watching-inputs     # change the figure name to "watching-inputs"
AM-felix#>legend -f33 30                      # set the offsetY to 30

---