Wiki › SDR SA PRO

Alarm zones and alarm actions

PRO Alarm zones are the watch and guard rows of the frequency table: with a level threshold and a hold, visible on the spectrum, with edges you can drag with the mouse. Alarm actions are what the app does when an alarm occurs: it speaks, plays a siren, takes a snapshot of the window, starts your program, sends the alarm to your address (a webhook). All of this lives on the Scanner tab, in the Frequency table: N list; every action is off by default. The alarm rules themselves, the event log and IQ recording are on the page Frequency table and alarms; the webhook, MQTT and the local REST on the page Webhook, MQTT and local REST.

Threshold and hold in a row 0.9.57

An unfolded table row with the watch or guard role has two fields. A row with the label role does not show them: a label raises no alarms.

Threshold, dB above floor

An alarm only on a signal whose level is no lower than this many decibels above the local noise floor. From 0 to 200; zero or an empty field means no condition. This is not dBm: that is the level the signal list carries. A threshold, if there is one, also stands in the folded table row, for example ≥12 dB.

Hold, s

An alarm only when the signal has been seen for no less than this many seconds. From 0 to 3600; zero or an empty field means at once.

Text is applied with Enter or by leaving the field; Esc restores the previous value. A value outside the limits is not accepted: the field returns to the value in force, and the group above the list says Not accepted — … in red, with the reason.

How this is judged

• At every look. A signal that has not met the conditions yet gives no alarm and is judged again in the next look — until there has been an alarm about it.
• The level is the same as in the row’s Level cell: the median over the latest hits; for a channel row, the power of the channel above the floor. A row with no level does not pass the threshold.
• The hold is the time from the row’s first detection to its latest hit. It is not continuous presence: a signal that disappeared and came back as the same row counts from its first appearance. At the moment of the alarm the row must be in the “signal is there” state and in the current look.
• What is in a zone. A signal lies in a zone when the centre of its row lies within the zone’s edges — with a tolerance of half a bin or 1 ppm of the frequency, whichever is greater. A wide signal with its centre outside the zone does not belong to it, even if its edge reaches in.
• Several rows. A row without conditions fires by covering alone. Where several rows of one role cover a frequency, one whose conditions are met is enough.
• Guard still says nothing about a signal whose class comes from a label row: see Alarms.
• The alarm on types has no conditions: the threshold and the hold apply only to watch and guard.
• One alarm per row. A signal that falls below the threshold after the alarm does not cancel it; rising again, it gives no second one.

The Alarms line in the “How far to trust the list” fold of the Scanner tab says how many rows have a threshold or a hold: ; with a level threshold above the floor or a hold — N.

Zones on the spectrum 0.9.57

Each watch and guard row is a band over the whole height of the spectrum field: yellow for watch, red for guard. Zones travel with the spectrum when the view is dragged or zoomed. They are not on the waterfall.

• The label at the top left of the zone says: role · name · threshold · hold, for example watch · Wi-Fi · ≥12 dB · 5 s. The threshold and hold are shown only when they are not zero. The width of the label is limited by the width of the zone (but it is no narrower than 24 pixels): in a narrow zone the text is cut off.
• The switch Zones on the spectrum is in the Frequency table group. It is on by default and saved between runs. It affects the appearance only: hidden zones are judged just the same.
• There are no more than 200 zones on the spectrum, in table order; how many did not fit is shown by more zones: N in the corner. This does not affect the judging of alarms.

A zone and the mouse

Zone edge

Each edge has a strip 7 pixels wide that takes the mouse. Drag it to change one bound; an edge does not cross the opposite one.

The label

Dragging it moves the whole zone: both bounds together, the width unchanged.

Double click on the label

On the Scanner tab it switches to Frequency table: N, unfolds the row of this zone and scrolls the list to it. It does not open the tab itself: if another tab is showing in the side panel, go to the Scanner tab (Ctrl+5).

• The table takes the new bounds as soon as the button is released; until then only the zone on screen moves.
• Bounds the table does not accept (for example, the range became narrower than the channel step) do not take effect: the zone goes back, and the Frequency table group says Not accepted — ….
• A change of the bounds restarts the occupancy count of this range.
• Dragging is accurate to a screen pixel. Exact bounds are set in the Range, MHz fields.
• The rest of the field is transparent to the mouse: a click outside the handles stays a tuning, a double click stays a view reset, a right click stays the spectrum menu.

A watch zone from the spectrum menu

Right click on the spectrum → Watch zone from the selection. A new row goes to the end of the table, named new, with the watch role and no threshold or hold; on the Scanner tab it is unfolded, and over the spectrum the app says Watch zone … MHz is in the frequency table of the Scanner. When the window holds several stations, the row goes into the table of the station whose spectrum was clicked: the click makes it active 0.9.58.

Table exchange: JSON 0.9.57

A JSON file is the way to share collections of zones and labels, or to keep several tables to choose from. The buttons are in the Frequency table group, next to the CSV buttons.

From a JSON file…

Adds rows to those already there. The same name and edges are not taken twice: a row already there stays as it was, even if the file gives it another threshold or role. A file with even one error gives no rows: “…”: …. No row was added. If the new rows together with the existing ones do not fit into 2000, none is added.

To a JSON file…

Writes the whole table. Active when the table is not empty.

• The format is the same as that of the table’s own file table.json: {"schema": 2, "rows": […]}. The row fields are name, kind, f0, f1, w0, w1, step, role, priority, comment, min_db, hold_s. Frequencies, widths and the step are in hertz.
• A file of schema 1 (written before 0.9.57) is read: its min_db and hold_s fields are zero. A file of a newer schema is not read.
• An unknown field is an error, not a silent drop. A number in quotes is not a number.
• A written file is UTF-8; a file with a byte-order mark is read too.
• CSV carries the threshold and hold as well — the min_db and hold_s columns; see CSV format.

Alarm actions 0.9.57

The actions are in the Frequency table group, in the Alarm actions fold. It is folded by default and does not remember its state between runs; the number in brackets by the heading says how many actions are on. The Windows sound, the event log and IQ recording are separate switches above the fold: see Sound, event log and IQ recording.

• There are five actions: the voice, the siren, a window snapshot, starting a program and the webhook 0.9.58 — an HTTP POST with the alarm to your address. Publishing to an MQTT broker is switched on separately, in the “How far to trust the list” fold (see MQTT).
• Every action is off by default; the switches, paths, the webhook address and the arguments are saved between runs.
• Actions fire only on a new alarm. A recording from a file and the demo signal give no alarms, and so no actions.
• No action stops the list: what failed is said in words (see below).

Voice

The Voice switch. The phrase is spoken by a Windows speech engine (SAPI or WinRT); the engine starts on the first phrase. The voice speaks once per look, however many alarms it holds: about the first one and how many more, for example: “Alarm 3: watch, Wi-Fi 2.4, 2437 megahertz, 23 decibels above the floor. And 2 more.” An alarm of the video channel search is named just that: “video”. Until the voice has finished, a new phrase does not start: it is skipped and counted.

The intent for the language is this: the interface language, and without a voice for it, English, with the line below the switches saying — in English: Windows has no voice for the interface language.

With no voice at all, the action says why: no voice: Windows has no speech engine or no voice: the speech engine did not start (…).

Siren

The Siren from a WAV file switch, next to it a path field and a Choose… button (active while the switch is on). The file plays once per look with alarms. While it plays, it does not start again. WAV only. Refusals:

• no siren file has been chosen;
• the siren file was not found: …;
• the siren file cannot be read — a WAV file is needed: ….

Window snapshot

The Window snapshot switch. One PNG of the whole window per look with alarms — the same picture as the F9 key gives. The file goes into the alarms subfolder of the app’s snapshot folder: Pictures\SDR SA PRO\alarms. The app creates the folder itself. The name is the local time to the second: sdrsa-YYYYMMDD-HHMMSS.png; two snapshots in one second do not overwrite each other. If a file was not written, the app says so: snapshot: ….

When the window holds several stations, the Scanner of each takes a snapshot of the window on its own alarms 0.9.58. The snapshot shows the whole window with all the stations, and it goes into the same folder.

Start a program

The Start a program switch, next to it a path field and a Choose… button (it offers .exe, .bat, .cmd); below is the Arguments field. Only what you named yourself is started; by default, nothing.

• Each alarm gets its own process, no more than 8 per look; the rest are counted as skipped: starts skipped: N (at most 8 per look).
• The alarm parameters go in the arguments only. The app adds no environment variables with them.
• The app does not wait for the process to end and does not read its output.
• No path given — no program to start has been given; the start refused — the start failed: ….

The default arguments are {mhz} {level} {time} {reason} {name}. The placeholders:

• The arguments line is split at spaces; quotes around a whole argument hold spaces together and are removed, while quotes inside a word stay as text and do not hold spaces; the backslashes of paths stay. An unclosed quote means a plain split at spaces.
• Substitution comes after the split: a name with spaces stays one argument, and an empty level stays an empty argument in its place.
• An unknown placeholder stays as it is, as text. The list of placeholders is shown below the field while the switch is on.
• There is no placeholder for the video standard (PAL or NTSC); the video field of the webhook body carries it.

Test

The Test button is active while the voice, the siren or the webhook is on. Without an alarm it speaks a test phrase if the voice is on (“Alarm voice test. This is how the scanner speaks.”, or “Проба голосу тривоги. Сканер каже так.” when the phrase comes in Ukrainian), plays the siren file if the siren is on, and sends a test event to the webhook address if that is on 0.9.58 (see Test and counters). It takes no snapshot and starts no program.

What came of the actions

Below the switches inside the fold is a line with counters since the program started, the latest thing done and the refusals, for example:

Alarm actions: voice — 4 (skipped 1), siren — 4, snapshots — 4, starts — 6 (skipped 1, failed 0). Last: voice · siren · snapshot … · started 2.

The brackets by the starts are there only when something was skipped or failed; in “Last” the snapshot is named by the path to its file, and refusals stand at the end of the line. With the webhook on, the line also holds webhook: N, and its latest refusal stands at the end as webhook: … (see Test and counters).

When at least one action is on, the Actions line in the “How far to trust the list” fold says which and adds the refusals — it is visible even when the actions fold is closed.

Where this is saved

• The threshold, the hold and the zone bounds are in the frequency table, the table.json file.
• The zones switch, the action switches, the paths of the siren and the program, the arguments and the webhook address are in the settings.json file.
• Both files lie in the scanner folder of the SDR SA PRO data folder; for the program installed from a package this is Documents\SDR SA PRO\scanner. On a station other than the main one they are in scanner\stations\<station>: each station has its own zones and actions. See What is saved between runs and The Scanner on several stations.
• Alarm snapshots lie apart: Pictures\SDR SA PRO\alarms.
• The state of the actions fold is not saved.

Limits

• The threshold is in dB above the local floor, not in dBm: the calibration table does not reach the Scanner’s levels.
• The threshold is not drawn on the level axis: a zone is a band over the whole height of the field, and it can be dragged only along the frequencies.
• A signal must first become a row of the list: the appearance rule (see How a row appears and disappears) comes before the threshold and the hold, so an alarm does not come earlier than it.
• The frequency of a row and a zone is as the receiver itself shows it: the Scanner does not know the error of the receiver’s reference oscillator.
• The class in {name} and in the voice is a frequency label from the table, not a recognised kind of signal.
• The voice and the siren act once per look, a snapshot once per look, a program up to 8 starts per look, the webhook up to 8 requests per look.
• A recording from a file and the demo signal give no alarms and no actions.

The wiki describes version 0.9.58. Your app's version is shown in the Help menu, under About. Found a mistake? Write to us.