Screen Capture, Periodic and Scheduled Actions in Spectrum Lab
Overview
See also: Spectrum Lab's main index, command interpreter .
For long-term (or late-night) observations, the program can save the contents of the waterfall screen periodically (idea from Petr, OK1FIG). Use the item "Periodic Actions" in the main menu under "file". This will open the following dialog:
The "Periodic actions" tab defines the start time, end time, the interval when an action shall take place, for example saving the waterfall as a bitmap file. Don't forget to activate the 'Periodic Actions' here.
To be compatible with old program versions, enter the command "capture" as the action macro. Other interpreter commands may be also be entered in this line, separated with the ":" character.
In the shown example, every 30 minutes between 21:00 and 05:00 a picture will be saved in the specified directory (Note: Spectrum Lab will never support the AM/PM format, only the 24 hour format). After that, the export function is started (it writes some 'interesting' data into a text file).
The "Test" button here executes the action macros for testing purposes, the result (error code, etc) is printed in the grey field next to the button.
Similar to the periodic actions (which take place at constant intervals), it's possible to define some "scheduled actions" which take place at arbitrary times (in a 24-hour period).
Use the item "Scheduled Actions" in the main menu under "file". This will open the following dialog:
The "Scheduled Actions" tab defines a 24-hour-schedule (times in UTC). Every line in this table can define a number or programmable interpreter commands, separated with a ":"-character.
To be compatible with older versions of the program, just enter the command "capture" (with or without arguments) in the 'Action' column. This will do a screen capture at the specified time.
To rearrange the lines in the schedule table, you can move a single line up or down with the mouse. Keep the left button pressed while the arrow is in the first column (index column, grey, labelled "Nr").
Up to 12 (or more?) entries can be entered into the schedule, so a maximum of (at least) 12 different actions PER DAY is possible. Don't forget to activate the schedule with the checkmark on the left side ("active"). You can use a combination of 'periodic' and 'scheduled' actions, but this doesn't make sense for most purposes.
If neither "periodic" nor "scheduled" actions are the solution, you can also use the conditional actions which will be explained in this chapter. The basic principle is:
peak_a(1495,1505) > (noise(300,2700) +
10)
timer0.start(5) : capture
The definition table for "Conditional Actions" may look like this:
Note: Since V2.7, all conditions which are momentarily TRUE will be marked with a green background in the corresponding cells (in the "IF"-column). These indicators are only updated if the Conditional Actions are enabled.
Some interpreter functions which have been implemented especially for the IF-column in this table:
initialisingterminatingalwaysnever elsetimerX.expired (where X is the timer number,
0...19)timerX.expired(1)timerX.valuereplay_startedSome interpreter commands which you may frequently use in the THEN-column in the conditional event table:
timerX.start(<interval>)timerX.restart(<interval>)timerX.periodic(<interval>)timer5.periodic(1.5) lets timer 5 to produce "events"
(timer5.expired) every 1.5 seconds.Complete examples:
| IF-column | THEN-column |
always |
N = noise_n( 300, 2700) : REM calculate normalized noise level in passband |
peak_a(1745,1755) > (N+10) |
bb[2].agc.max_gain=+90 : REM let AGC amplify if pilot tone is detected |
else |
bb[2].agc.max_gain= -6 : REM let AGC attenuate if pilot tone NOT detected |
always |
T2=now : P=15*60 : REM GB3SSS beacon TX cycle is 15 minutes, ... |
int((T1+5)/P)<>int((T2+5)/P) |
T1=T2 : BeaconIsOn=1 : REM see GB3SSS_beacon_monitor.usr for details |
Note: This "else"-condition is just an arithmetic function which returns either 0 (zero=FALSE) or 1 (one=TRUE). It can even be used in a numeric expression (unlike the "else" in a real script language). For example, the term "!else" ("not else") returns the value of the condition in the previous line, and can therefore be used when running out of space in the THEN-column in a single line.
See also: Overwiev of interpreter commands , interpreter functions .
A frequently used 'periodic' or 'scheduled' action is to capture the current
waterfall screen -alias spectrogram- as a file. To produce such a capture,
use the "capture" command, or select the function
from the main menu: File...Screen Capture...Capture the screen NOW.
Some options for saving graphic files can be set on the "Screen Capture"
tab (from the main menu: File...Screen Capture...Options):
capture command, so you can have
different quality settings for capturing the spectrogram image or other
'diagrams' like the curve plotter. But the quality specified in the command
only affects that single captured image; it does not modify the
configuration.
A text editor on the "Screen Capture Configuration" dialog is used to define additional info strings which will be visible in the captured images.
The info definitions are evaluated by Spectrum Lab's interpreter like the parameters for the "print" commands. The interpreter uses a "pseudo-programming language" which may be confusing for non-programmers... so here a few guidelines:
There can be many fixed strings and formatted values in one definition line. For typical applications, you will find a few examples which you can copy & paste into the info text definitions (mark them with the mouse here, press CTRL-C (or STRG-C on a german keyboard), then switch to the Capture Configuration dialog, place the cursor in the text field and press CTRL-V to insert the text line.
Time & Date
Frequency range and related parameters
File Information
A detailed description of the interpreter functions used in these examples can be found in another file. Look for:
str-function, format-string, noise, peak, capture.xxx, water.xxx
If you prefer to write some information about the captured image into a text
file instead of putting them as graphics in the captured image,
use the Screen Capture Extension
Macros.
The following interpreter commands and functions and procedures can be called from Spectrum Lab's command window, or as a periodic or scheduled action:
This procedure saves the current waterfall and/or spectrum plot as a graphic
file (called a "screen capture"). Without arguments, the filename is generated
as defined in the periodic action dialog, and
the sequence counter is incremented.
A filename may be passed in argument parenthesis (see examples below).
If a filename (or string expression) is passed to the capture command, the
sequence counter is NOT incremented.
Other parameters and options for the sreen capture can be defined in the
"screen capture" configuration dialog. The
quality for screens captured as JPEG files can optionally be specified in
the command's argument list
Examples:
capture
Saves the diagram (here: usually spectrogram) as a graphic file with the name specified in the screen capture configuration dialog. The file index (or "serial number") will be incremented after completion of the command.
capture("p"+str("YMMDDhh",now)+".jpg")
Saves the diagram as a JPEG image, a date-and-time dependent file name will
be generated automatically.
The string expression in the argument
builds a filename, depending on the current date and time.
capture("gram50.jpg",50)
Saves the diagram as a JPEG image with a quality of 50 (percent) which is ok for most applications. If the quality value is not specified in the argument list, the value from the screen capture options dialog is used.
The function returns the truncated filename (tfn) of the last
saved screen capture. This is not necessarily the filename defined in the
"screen capture" configuration dialog, it may
also be the last filename which was generated when the last
capture command was executed !
Truncated means, "only the file path and file name, but not the extension".
This makes it easier to replace the extension of the saved image (.bmp of
.jpg) with the extension ".txt" if you want to produce a description for
the file with the optional screen capture
extension macros.
See also: Overwiev of all interpreter commands
Screen Capture Extension Macros
..can be defined in the capture configuration dialog. These macros are no "specialized" interpreter commands, just any sequence of interpreter commands can be used (as shown in the following example). The example creates a textfile with additional info about a captured image (waterfall etc). You will find some of these in a file named "capture_macros.txt" in the directory where Spectrum Lab has been installed, but you can also copy & paste them from the example into the "screen capture" configuration dialog (use CTRL-C to copy and CTRL-V to paste).
An example to extend the functionality of the "capture" command:
print("Producing screenshot info file \""+capture.tfn+".txt\"...")
fopen(capture.tfn+".txt")
fprint("Info for capture \""+capture.tfn+"\"")
fp("-------------------------------------------------------------------")
fp("Date=";str("YYYY-MM-DD",now),"time="+str("hh:mm:ss",now))
fp("Contrast=";cfg.Wat1ClContrast,"Brightness=";cfg.Wat1ClBrightns)
fp("Noise(n)=";noise_n(10,2000);"dB,
Peak_f=";peak_f(10,2000);"Hz,Peak_a=";peak_a(10,2000);"dB")
fclose
The first line is just an info which will be printed into the "output" window of the command interpreter.
The commands fopen, fprint (abbreviated as "fp") and fclose are described
here. The sample code produces a
text file with same path+filename like the captured image, but the extension
".txt". Then, a few text lines are written into the file, with date, time,
and a few parameters (here: waterfall contrast and -brightness) and calculated
results from the last collected data (here: the normalized noise level, peak
frequecy and peak amplitude).
Finally, the text file is closed again (so other programs can read it).
See also: Overwiev of interpreter commands, overwiev of interpreter functions