Was this page helpful?

Syntax of Deployment Files

From $1

    The deployment.txt files are written in a notation called JSON which, unfortunately, does not allow for embedded documentation.  For now, this page will document only the features most likely to require customization:

    Changing the site code and frequency of GPS fixes

    The default deployment file begins with these lines:

    {
        "info": "default deployment",
        "who": "who is responsible for this deployment",
        "contact": "contact information for responsible party",
        "shortLabel": "SG1",
        "acquire": {
            "gps": {
                "secondsBetweenFixes": 300
            },
    

    The colon (':') separates a quoted field name from its value.  The value is quoted unless it is a number.  Case of letters is significant inside field names, so shortlabel is not the same as shortLabel.  Commas are required at the end of each line, except for the last line before a closing brace ("}").

    shortLabel: this is the only field you really need to change in this section.  You should choose a short mnemonic code for the site or location where this SensorGnome will be deployed.  All datafiles will contain this short label in their names, until you next change the deployment file.  Date information should not be part of this label, as a precise timestamp is also included in each filename.  SensorGnome deployments from Acadia University have typically used site codes consisting of 4 uppercase letters, e.g. BPEL (Bon Portage Island East Lighthouse).  Eventually, we hope to coordinate use of shortLabels among SensorGnome users via the sensorgnome.org site.  Make sure the shortLabel value is surrounded by double quotes.

    secondsBetweenFixes:  this specifies how often you want the SensorGnome to record the GPS lat/long/elevation fix to its output file.  The first fix is output as soon as it is available, and subsequent fixes are output at this interval.  The default is 5 minutes (300 seconds).

    You can of course change values for info, who, and contact, but currently, these items are not visible or used anywhere else.

    Changing the VHF telemetry listening frequency

    If your tags are not transmitting at the default nominal frequency of 166.380 MHz, you can change the listening frequency in this portion of the deployment.txt file:

            "plans": [
                {
                    "key": {
                        "port": ".*",
                        "devType": "funcube.*"
                    },
                    "rate": 48000,
                    "channels": 2,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "devParams": [
                        {
                            "name": "frequency",
                            "schedule": {
                                "type": "Constant",
                                "value": 166.376
                            }
                        }
                    ],
    

    This portion of the file says that for any funcube device plugged into any USB hub port, the device should be sampled at a rate of 48000 Hz in stereo, should always be running, and should listen at the frequency 166.376 - we recommend setting the listening frequency 4 kHz below the nominal tag transmit frequency.  If your tags are transmitting at 150.340 MHz, then you would replace the 166.376 above with 150.336 (i.e. 0.004 MHz = 4 kHz below the nominal frequency).

    Broadening the VHF Listening range for Beeper Tags

    The settings here are good for monitoring a few tags whose range of frequencies (highest - lowest) is at most 48 kHz (i.e. 0.048 MHz):

            "plans": [
                {
                    "key": {
                        "port": ".*",
                        "devType": "funcube.*"
                    },
                    "rate": 96000,
                    "channels": 2,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "devParams": [
                        {
                            "name": "frequency",
                            "schedule": {
                                "type": "constant",
                                "value": 150.048
                            }
                        }
                    ],
    

    The "rate" setting (blue section) says to sample the funcube signal at 96000 Hz, which allows detection of pulses from transmitters up to 48 kHz away from the central frequency.  This setting will detect pulses from transmitters in the range 150.000 MHz to 150.096 MHz, although frequencies very close to the endpoints will not be detected reliably.

    If you're only watching one tag at a time, you can set the rate to the usual 48000 for higher-quality estimation of transmitter frequency, in which case pulses can only be detected out to +/- 24 kHz; i.e. in the range 150.024 to 150.072 MHz  (Technical point:  the funcube provides an I/Q pair which allows us to distinguish + from - frequencies, so -30kHz is distinct from +30kHz). 

    The central "frequency" (purple section) is constant at 150.048 MHz .  You can also change this frequency from the web interface (as of software release 17 May 2013).

    Frequency-switching on a schedule for tags with a broader range of transmit frequencies

    The settings here are good for monitoring a set of tags whose range of frequencies (highest - lowest) is 96 kHz or more. kHz (i.e. 0.048 MHz)

    Look for the portion of the deployment.txt file beginning with "plans":

            "plans": [
                {
                    "key": {
                        "port": ".*",
                        "devType": "funcube.*"
                    },
                    "rate": 96000,
                    "channels": 2,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "devParams": [
                        {
                            "name": "frequency",
                            "schedule": {
                                "type": "periodic",
                                "states": [
                                    150.048,
                                    150.128,
                                    150.208,
                                    150.288
                                ],
                                "periods": 10
                            }
                        }
                    ],
    

    Here, the central frequency cycles through a list.  The "states" field gives the sequence of frequencies, in MHZ, and the "periods" field gives the length of time to spend at each frequency.  In this case, we want the receiver to spend 10 seconds at each of the four frequencies in sequence, then go back to the first one.    Although the theoretical limit at each central frequency is +/- 48kHz, we overlap the intervals a bit because extreme frequencies are harder to detect; i.e. instead of spacing central frequencies 96 kHz apart, we space them 80 kHz apart.  It is also possible to specify a period value for each frequency, like this:

                            "schedule": {
                                "type": "periodic",
                                "states": [
                                    150.048,
                                    150.128,
                                    150.208,
                                    150.288
                                ],
                                "periods": [10, 20, 20, 10]
                            }
    

    In this case, 10 seconds are spent at 150.048, then 20 seconds at 150.128, then 20 seconds at 150.208, then 10 seconds at 150.288, and then the pattern repeats from the start.  If the number of periods does not match the number of frequencies, the period values are re-used in sequence.  The field "periods" can be either a simple number or a list in square brackets.

    The web-interfaced frequency setting is not "sticky": any scheduled frequency changes still take effect, overriding the temporary web setting.

    Reducing the minimum SNR for pulses to increase detection range

    By default, the VHF telemetry plugin uses a signal to noise ratio (SNR) of 5 dB as the threshold for
    filtering pulses.  You can reduce this, to potentially increase detection range, but at a cost of larger
    data files, since more pulse are recorded. 

    Warning:  if you decide to change this threshold, make sure to do a field trial to estimate your
    storage requirements; even a small change in the threshold can lead to a large increase in file sizes!

    The minimum SNR is a parameter to the findpulsefdbatch plugin which looks for pulses in the raw
    signal coming from the funcubedongle; you can specify a lower value by changing the default
    deployment.txt file like so:

                    "plugins": [
                        {
                            "library": "lotek-plugins.so",
                            "name": "findpulsefdbatch",
                            "outputID": "pulses",
                            "params": [
                                {
                                    "name": "plen",
                                    "value": 2.5
                                },
                                {
                                    "name": "minfreq",
                                    "value": 2
                                },
                                {
                                    "name": "maxfreq",
                                    "value": 24
                                },
                                {
                                    "name": "minsnr",
                                    "value": 3    
                                }                                                         
                            ]                           
                        }
                    ]
    

    The portions highlighted in blue, including the new comma at the beginning, can be added to the
    default deployment.txt file to lower the minimum SNR ratio from its default of 5 dB to 3 dB.  This
    means a pulse only has to be 3 dB stronger than the background noise level to be detected.
    In theory, this reduction from 5 dB to 3 dB should allow a 26% increase in detection range.  A reduction
    from 5 dB to 2 dB would allow a 41% increase in detection range, but would likely use up storage much more quickly.
    Warning: Do a field test before committing to such a change for a long-term deployment!

    Changing the .WAV file size

    Here is a later portion of the deployment.txt file which applies to acoustic monitoring:

                {
                    "key": {
                        "port": ".*",
                        "devType": "usbAudio"
                    },
                    "rate": 48000,
                    "channels": 1,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "raw": {
                        "enabled": true,
                        "chunkMinutes": 60
                    }
                }

    This specifies that any USB audio device (a microphone, presumably) attached to any USB port should be sampled at 48000 Hz in mono, and should always be on.  Raw .wav files are to be recorded, with each file consisting of a 60 minute chunk of audio.  To change the size of the recorded files, replace the 60 with whatever value you prefer (the number can have a fractional part, e.g 2.5). 

    Using a stereo microphone

    The default deployment.txt file treats all USB microphones as if they provide a single channel.  For stereo microphones such as the Blue Yeti,
    you'll need to tell the sensorgnome to open 2 channels on the microphone:

                {
                    "key": {
                        "port": ".*",
                        "devType": "usbAudio"
                    },
                    "rate": 48000,
                    "channels": 2,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "raw": {
                        "enabled": true,
                        "chunkMinutes": 60
                    }
                }

    (Eventually, we'll make this less painful, but for now, the software demands that you specify the correct number of channels for the underlying hardware.)  Changing the deployment.txt file this way means only stereo microphones will work with that sensorgnome.  To allow for some flexibility,
    you might want to designate some USB hub ports for mono and others for stereo.  To do that, replace the above portion of deployment.txt with
    something like this:
     

                {
                    "key": {
                        "port": "[1-3]",
                        "devType": "usbAudio"
                    },
                    "rate": 48000,
                    "channels": 1,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "raw": {
                        "enabled": true,
                        "chunkMinutes": 60
                    }
                },              
                {
                    "key": {
                        "port": "[4-7]",
                        "devType": "usbAudio"
                    },
                    "rate": 48000,
                    "channels": 2,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "raw": {
                        "enabled": true,
                        "chunkMinutes": 60
                    }
                }

    This duplicates the audio specification section, and changes the keys.  The first section says
    "if you find a usb audio device in ports 1 to 3, open it in mono".  The second section says
    "if you find a usb audio device in ports 4 to 7, open it in stereo".
     

    Recording Raw Radio Signal

    Occasionally, we need to obtain raw signal from a funcubedongle radio receiver, for example to characterize the signal from a transmitter.  To do this,
    we specify the "plans" portion of the deployment.txt file like so (only the blue portion differs from the standard telemetry deployment file):

            "plans": [
                {
                    "key": {
                        "port": ".*",
                        "devType": "funcube.*"
                    },
                    "rate": 48000,
                    "channels": 2,
                    "schedule": {
                        "type": "AlwaysOn"
                    },
                    "devParams": [
                        {
                            "name": "frequency",
                            "schedule": {
                                "type": "Constant",
                                "value": 166.376
                            }
                        }
                    ],
                    "raw": {
                        "enabled": true,
                        "chunkMinutes": 5
                    }
                }               
            ]
    

    Note: use 96000 instead of 48000 in the above if using the older funcubedongle Pro (rather than funcubedongle Pro Plus).

    This specifies to record raw signal from each funcube receiver, and to store this as a sequence of 5-minute-long .WAV files.  Each .WAV file is stereo with a sampling rate of 96000 Hz.  The full deployment file for recording raw radio signal from all funcubes is attached below as deployment_rawfcd.txt  To use it, you will need to save it onto your SG's boot drive, and rename it to deployment.txt

    Note: when using the SG to make a registration recording of a telemetry tag, use only a single funcubedongle.  Otherwise, the amount of raw data being recorded might overwhelm the SG's capacity to write to the micro SD card or even to a USB hard drive.

    Schedule USB Device Operation

    2014 May 5 NOT YET WORKING  this currently causes vamp-alsa-host to crash after a few minutes, after operating with a possible slow memory leak, but without reaching catastrophic memory usage.  Hmmm....

    Rather than recording audio or listening for VHF pulses continuously, you might want your sensorgnome to record audio for only 6 hours per day.
    Here's how to tell it:

            "plans": [
                {
                    "key": {
                        "port": ".*",
                        "devType": "usbAudio.*"
                    },
                    "rate": 48000,
                    "channels": 1,
                    "schedule": {
                        "type": "periodic",
                        "states":  [ "on", "off" ],
                        "periods": [ 21600, 64800]
                    },
                    "raw": {
                        "enabled": true,
                        "chunkMinutes": 25
                    }
                }               
            ]
    

    Any microphone detected will be turned on for 21600 seconds (6 hours) and then off for the next 64800 seconds (18 hours), repeatedly.  While on, audio files arel written in 25 minute chunks, but the last chunk will be short because the device will turn off.  Such short files have incorrect sizes specified in the header, but any reasonable audio processing software should still be able to read them.  In general, it will be impossible to avoid having short files at the end of each "on" period, even if you try to match the chunk size with the period length; recording and device control are performed by separate processes and can't be precisely synchronized.  However, the discrepancy should be at most a few seconds. 

    The example above provides a crude form of daily schedule, which may drift somewhat over time.  A time-of-day approach (including pinning to sunrise and sunset) will be coming.

    Please not that a device schedule does not power down the Sensorgnome itself during the "off" periods.  However, it does stop the specified USB device, which in the case of a funcubedongle, should reduce power consumption by approximately 1 Watt or more when the device is off.

     

    Reduce File Sizes at Sites with High Radio Noise

    If your daily raw telemetry data is > 10 Megabytes per day in total (or > 100 Megabytes per day
    at a colony of tagged organisms),  your site may have high levels of radio noise.  To reduce file
    sizes, you can tighten the filtering criteria used by the SensorGnome to decide which pulses
    to retain.  The following snippet of deployment.txt file shows how.  Generally, Lotek coded
    ID tags will have frequency offsets in the range 2 kHz to 8kHz when the receiver is set to
    4 kHz below nominal as recommended (e.g. for tags at 166.380 MHz, if the receiver is set
    to listen at 166.376 MHz):

                    "plugins": [
                        {
                            "library": "lotek-plugins.so",
                            "name": "findpulsefdbatch",
                            "outputID": "pulses",
                            "params": [
                                {
                                    "name": "plen",
                                    "value": 2.5
                                },
                                {
                                    "name": "minfreq",
                                    "value": 2
                                },
                                {                      
                                    "name": "maxfreq", 
                                    "value": 8         
                                },                     
                                {
                                    "name": "minsnr",
                                    "value": 5    
                                }                                                         
                            ]                           
                        }
                    ]
                    
                    

    Change the Pulse Length for Beeper or other Tags

    Beeper tags often have longer pulse lengths than coded tags, to make it easier to distinguish their signal from background noise. 
    Some coded tags might also use user pulse lengths other than the default 2.5 milliseconds.  If your tags have a pulse length other than
    2.5 milliseconds, you must specify the pulse length in milliseconds in the deployment.txt.  Here is an example for tags with a pulse
    length of 15 milliseconds:

                    "plugins": [
                        {
                            "library": "lotek-plugins.so",
                            "name": "findpulsefdbatch",
                            "outputID": "pulses",
                            "params": [
                                {
                                    "name": "plen",
                                    "value": 15.0
                                },
                                {
                                    "name": "minfreq",
                                    "value": 2
                                },
                                {                      
                                    "name": "maxfreq", 
                                    "value": 8         
                                },                     
                                {
                                    "name": "minsnr",
                                    "value": 5    
                                }                                                         
                            ]                           
                        }
                    ]
                    

    Warning: specifying the wrong pulse length for your tag can result in no detections at all!

    Was this page helpful?
    Tags: (Edit tags)
    • No tags
    FileSizeDateAttached by 
    defaultDeployment.txt
    latest defaultDeployment.txt; this can be saved as \\192.168.7.2\boot\deployment.txt if your deployment.txt file is broken
    3.12 kB18:49, 17 May 2013johnActions
    deployment_1MHz_coverage.txt
    a frequency-switching deployment covering the range 150.000 to 150.976 MHz in 12 frequency steps lasting 12 seconds each. To use this file, save it on your SensorGnome as \\192.168.7.2\boot\deployment.txt
    3.73 kB18:49, 17 May 2013johnActions
    deployment_rawfcd.txt
    newer version for use with post-2013 funcubedongles (i.e. Pro Plus)
    2026 bytes15:13, 10 Jun 2016adminActions
    Comments (0)

     
    Powered by MindTouch Core