Updated Squelch Docs

docs/CONFIGURE.md

@@ -483,29 +483,26 @@ Here are the column headers and some sample data:
 
 This file allows for you to specify additional information about conventional channels. A recorder is started for each line in the file and set the to frequency specified. The type of recorder is based on the type of System. A **conventional** system would have Analog Recorders, while **conventionalP25** or **conventionalDMR** would have digital recorders. **conventionalSIGMF** is a conventional system with SIGMF Recorders.
 
-*Tone based squelch is currently not supported.*
-
-
 | Column Name | Required | Value |
 |-------------|----------|-------|
 | TG Number     | ✔️        | The Talkgroup Number formatted as a decimal number. This has to be the first column |
 | Frequency        |  ✔️       | The frequency in MHz or Hz for the channel (decimal point must be used for MHz) |
-| Tone | ✔️        | The Tone for the talkgroup. This value is not used. *Tone based squelch is currently not supported.* |
+| Tone |        | The CTCSS Tone for the talkgroup. |
 | Alpha Tag |       | A 16 character description that is intended as a shortened display on radio displays |
+| Description |   | A longer description of the talkgroup  |
 | Category |    |  The category for the Talkgroup |
 | Tag       |   |  The Service Tag for the Talkgroup |
 | Comment |        | Use this field to capture comments about a talkgroup. It will be ignored by Trunk Recorder. |
 | Enable |        | Set to 'false' if you do not want this talkgroup/channel to created |
 | Signal Detector |    | Set to `false` if you do not want to use the Signal Detector for this channel. The Signal Detector scans a source's bandwidth and only enables a channel if a signal over a threshold is detected. If it not used, the channel will always be enabled and the Squelch will be running which uses more CPU. Default is `true`|
 | Squelch |    | Value in dB to use for the Squelch for this channel. If this is not set then the System Squelch value will be used instead. |
 
+A **Header Row** is required for the file, with a header provided for each of the columns that will be used. The columns can be in any order. For the Optional columns, if they are left blank for some of the rows, the default value will be used instead.
 
-The **Enable** Column is optional and defaults to *True*. It only needs to be added to rows that you do not want to have recorded. For those rows, set **Enable** to *False*.
-
-| TG Number | Frequency | Tone     | Alpha Tag     | Description            | Tag    | Category  | Enable (*optional*) |
-| --------- | --------- | -------- | ------------- | ---------------------- | ------ | ------ | ------------------- |
-| 300       | 462275000 | 94.8  | Town A Police | Town A Police Dispatch | Police | Town A |                     |
-| 325       | 462275000 | 151.4 | Town B DPW    | Town B Trash Dispatch  | DPW    | Town B | False               |
+| TG Number | Frequency | Tone     | Alpha Tag     | Description            | Tag    | Category  | Enable | Signal Detector | Squelch |
+| --------- | --------- | -------- | ------------- | ---------------------- | ------ | ------ | ------------------- | ---- | ---- |
+| 300       | 462275000 | 94.8  | Town A Police | Town A Police Dispatch | Police | Town A |    |  false |  |
+| 325       | 462275000 | 151.4 | Town B DPW    | Town B Trash Dispatch  | DPW    | Town B | false   |  |  -50 |
 
 
 ## unitTagsFile

docs/SQUELCH.md

@@ -12,7 +12,7 @@ flowchart TD
     style nk stroke-width:2px,stroke-dasharray: 2
 ```
 
-Conventional Systems can use up a lot of CPU. Prior to v5.0, conventional recorders are always "on" waiting for a signal to break squelch. With v5.0 you now have a Signal Detector per source. Its job is to look over the bandwidth for that source and perform an FFT. For each FFT bin that is over a power threshold, it will look for a **Conventional Recorder** that has similar frequencies. If there is a match, it will Enable the recorder in the Souce's Recorder Selector. The Recorder Selector is just a way to determine if a Recorder should receive samples from the Source. In your logs, look for smoething like `[ 0 ] AnalogC	Enabled - Freq: 855.737500 MHz	 Detected Signal: -63dBM (Threshold: -69dBM)` if you see that, it means that the **Signal Detector** has turned on a conventional recorder. 
+Conventional Systems can use up a lot of CPU. Prior to v5.0, conventional recorders are always "on" waiting for a signal to break squelch. With v5.0 you now have a Signal Detector per source. Its job is to look over the bandwidth for that source and perform an FFT. For each FFT bin that is over a power threshold, it will look for a **Conventional Recorder** that has similar frequencies. If there is a match, it will Enable the recorder in the Souce's Recorder Selector. The Recorder Selector is just a way to determine if a Recorder should receive samples from the Source. In your logs, look for something like `[ 0 ] AnalogC	Enabled - Freq: 855.737500 MHz	 Detected Signal: -63dBM (Threshold: -69dBM)` if you see that, it means that the **Signal Detector** has turned on a conventional recorder. 
 
 The **Signal Detector** automatically tries to find a power threshold to separate signal from noise. It is not perfect. If you are seeing a recorder not turn on when there is a signal, that could be because the Signal Detector threshold is not being set correctly. Or, if the Recorder is always being enabled by the Signal Detector, even when there is not a transmission, that is also a sign that is not automatically being set correctly. You can manually set the Signal Detector Threshold in the `config.json` file. Just to make things more confusing, the power levels used in the Signal Detector are slightly different than the values used for the Squelch. 
 
@@ -23,16 +23,77 @@ Each Conventional Recorder also has a Squelch setting. Once a Conventional Recor
 
 - Use a visual signal analyzer program, like GQRX to explore the signal you are trying to capture
   - Adjust the gain settings so that you have strong signals without adding a lot of noise. Copy these gain settings into the `config.json` file.
-  - Note the Db value for the noise floor. This is the 
+  - Note the Db value for the noise floor. You should set the squelch value to be in between the noise floor value and the the signal peak values.
+  - In the `config.json` file you can specify the squelch value for the whole system, or do it channel by channel, or a mix:
+  - **System Wide Squelch**
+    - `config.json`
+      ```json
+        {
+          "systems": [
+          {
+              "type": "conventional",
+              "squelch": -50 
+          }
+        }
+      ```
+  - **Channel Specific Squelch**
+      - `config.json`
+        ```json
+          {
+            "systems": [
+            {
+                "type": "conventional",
+                "channelFile": "channels.csv",
+            }
+          }
+        ```
+      - `channels.csv`
+        | TG Number | Frequency |  Squelch |
+        | --------- | --------- | -------- |
+        | 300       | 462275000 | -50 |
 
+        ```csv
+        TG Number, Frequency, Squelch
+        300, 462275000, -50
+        ```
+  - **Hybrid Squelch**
+      - `config.json`
+        ```json
+          {
+            "systems": [
+            {
+                "type": "conventional",
+                "channelFile": "channels.csv",
+                "squelch": -50
+            }
+          }
+        ```
+      - `channels.csv`
+        | TG Number | Frequency |  Squelch |
+        | --------- | --------- | -------- |
+        | 300       | 462275000 | -70 |
+        | 301       | 462300000 |  |
 
+        ```csv
+        TG Number, Frequency, Squelch
+        300, 462275000, -70
+        301, 462300000, 
+        ```
 
-Things to try:
+## Debugging a Conventional System
 
-- Use GQRX to fine tune gain. Turn off AGC
-- Set Signal Detector Threshold to something high like -10 so that recorders are always enabled.
-- Set sequelch value for the recorders so that it starts and stop predictably
-- remove Signal Detector Threshold and see if the automatic setting works
-- if auto doesn't work, fine tune the Signal Detector threshold so that it only displays the Enabled when a recording starts
+- ### The Channels for a System are never being recorded
+  - Try setting the squelch value to something very low, like -100. This should cause the Recorder to always be on and recording. When you quit trunk-recorder you should have a long file, possibly of static. If you, it is possible that the Signal Detector is not working correctly. 
+- ### Signal Detector is not working correctly
+  - IF you are not seeing a line like: `[ 0 ] AnalogC	Enabled - Freq: 855.737500 MHz	 Detected Signal: -63dBM (Threshold: -69dBM)` and you know there is a transmission on that frequency, it is a sign the the threshold for the Signal Detector is not being set correctly. To test this out, manually set the signal detector threshold in the `sources: [{}]` section of the config.json file. 
 
-I will try to write up some guide on doing this
+    ```json
+        "sources": [
+          {
+            "center": 851734375,
+            "rate": 2000000,
+            "driver": "osmosdr",
+            "signalDetectorThreshold": -100
+        }]
+    ```
+  This will effectively leave all of the recorders enabled all the time... which is not the most efficient. If this does work, then try to find a value for the `signalDetectorThreshold` that works reliably. RF power is measured differently between the Signal Detector and the Squelch block. You may need to use a value roughly 10 dB higher for the Signal Detector. Ideally, you only want the Signal Detector to enable a recorder when a there is a transmission that would trigger the squelch block in the Recorder.

trunk-recorder/setup_systems.cc

@@ -22,7 +22,7 @@ bool setup_conventional_channel(System *system, double frequency, long channel_i
         tone_freq = tg->tone;
 
         // If there is a per channel squelch setting, use it, otherwise use the system squelch setting
-        if (tg->squelch_db != 999) {
+        if (tg->squelch_db != DB_UNSET) {
           call = new Call_conventional(tg->number, tg->freq, system, config, tg->squelch_db, tg->signal_detection);
         } else {
           call = new Call_conventional(tg->number, tg->freq, system, config, system->get_squelch_db(), tg->signal_detection);

trunk-recorder/talkgroups.cc

@@ -131,8 +131,8 @@ void Talkgroups::load_channels(int sys_num, std::string filename) {
 
     BOOST_LOG_TRIVIAL(error) << "Column Headers are required for Channel CSV files";
     BOOST_LOG_TRIVIAL(error) << "The first column must be 'TG Number'";
-    BOOST_LOG_TRIVIAL(error) << "Required columns are: 'TG Number', 'Tone', 'Frequency',";
-    BOOST_LOG_TRIVIAL(error) << "Optional columns are: 'Alpha Tag', 'Description', 'Category', 'Tag', 'Enable', 'Comment', 'Signal Detector', 'Squelch'";
+    BOOST_LOG_TRIVIAL(error) << "Required columns are: 'TG Number', 'Frequency'";
+    BOOST_LOG_TRIVIAL(error) << "Optional columns are: 'Alpha Tag', 'Tone', 'Description', 'Category', 'Tag', 'Enable', 'Comment', 'Signal Detector', 'Squelch'";
     exit(0);
   } else {
     BOOST_LOG_TRIVIAL(info) << "Found Columns: " << internals::format_row(reader.get_col_names(), ", ");
@@ -141,8 +141,8 @@ void Talkgroups::load_channels(int sys_num, std::string filename) {
   for (size_t i = 0; i < headers.size(); i++) {
     if (find(defined_headers.begin(), defined_headers.end(), headers[i]) == defined_headers.end()) {
       BOOST_LOG_TRIVIAL(error) << "Unknown column header: " << headers[i];
-      BOOST_LOG_TRIVIAL(error) << "Required columns are: 'TG Number', 'Tone', 'Frequency',";
-      BOOST_LOG_TRIVIAL(error) << "Optional columns are: 'Alpha Tag', 'Description', 'Category', 'Tag', 'Enable', 'Comment', 'Signal Detector', 'Squelch'";
+      BOOST_LOG_TRIVIAL(error) << "Required columns are: 'TG Number', 'Frequency'";
+      BOOST_LOG_TRIVIAL(error) << "Optional columns are: 'Alpha Tag', 'Tone', 'Description', 'Category', 'Tag', 'Enable', 'Comment', 'Signal Detector', 'Squelch'";
       exit(0);
     }
   }