Configuration file guide

Guide for creating and modifying necessary configuration files

Running agate requires configuration files. Each of these are plain text files that end with .cnf and can be edited in any text editor or in MATLAB’s Editor window.

1. An overview mission configuration file is required for all agate processes. A different mission configuration file is created for each glider and mission and it contains settings for glider metadata, paths, acoustic system settings, and plotting options.
2. A basestation configuration file with SSH login info - only required if using agate to interact directly with the basestation. This is a separate configuration file because it does not change between missions and should be stored in a secure directory on your local computer and not shared with others.

Mission configuration file

An example configuration file is located in the agate/settings folder: agate_config_example.cnf

The configuration file has settings for the glider and mission, paths to relevant input and output folders, map extent and plotting settings, and acoustic system settings. Lines starting with % are comments.

The top section is required to initialize agate and use the most basic functions. The remaining sections are optional depending on what agate functionality is desired, including interfacing with the basestation, working with acoustic data outputs, and plotting maps. Save this file with a unique name for each glider and mission. Descriptions of each configuration item are included in the example file as comments.

To suggest additional configuration items, please open an issue.

_{Back to top}

Required configuration settings

The top section % %%%% REQUIRED CONFIG PARAMETERS %%%%%%%%%%% is required to initialize agate and use the most basic functions. Explanations for each parameter are in the example configuration file as comments.

CONFIG.glider = 'sgXXX'; % glider serial number
CONFIG.mission = 'Location_Mon20XX'; % mission identifier defined in sg_calib_constants.m 
CONFIG.sgVer = XX.XX; % 66.12, 66.14, 67.00 or 67.1, firmware version displayed on glider start up
CONFIG.tmd = XX; % target mission duration in days

% define paths
% mission path - path to umbrella folder that either contains previously 
%                downloaded basestation and output files or will contain 
%                downloaded and processed/produced files and figures
CONFIG.path.mission = 'C:\Users\User.Name\Desktop\sgXXX_Location_Mon20XX\';
% analysis path - optional path to an 'analysis' folder that would typically
%                 contain the outputs of acoustic analyses (e.g., Pamguard
%                 or Triton)
CONFIG.path.analysis = 'C:\Users\User.Name\project\analysis';

Optional basestation settings

% %%%% OPTIONAL - basestation %%%%%%%%%%%%%%%
% specify basestation configuration file
CONFIG.bs.cnfFile = 'C:\Users\User.Name\Documents\gliders\basestation.cnf';
% specify path to store downloaded basestation files
CONFIG.path.bsLocal = fullfile(CONFIG.path.mission, 'basestationFiles\');
% specify path to remote files (e.g., glider's current/mission folder)
CONFIG.path.bsRemote = '/home/jails/group/gliderjail/home/sgXXX/current';

Optional acoustics settings

Various settings required to operate an acoustic system or to process acoustic data after a mission is over. Depending on which acoustic system is installed, only PMAR or WISPR settings are needed. Unneeded lines can be deleted or ignored by adding a % at the start of the line.

% %%%% OPTIONAL - acoustics %%%%%%%%%%%%%%%%%

For PMAR, some settings are required during a mission to track remaining memory available. The conversion settings are only required after a mission is complete to convert .dat to .wav and should be turned off after conversion is done. The processing and analysis settings are only needed after a mission is complete.

% PMAR settings
CONFIG.pm.loggers = 0; % 1 for active, 0 for inactive
CONFIG.pm.activeCard = 0; % current active card; optional for sgVer 66.12 
                          % (will be updated in log file automatically);
                          % necessary to update throughout mission for sgVer 67.0
CONFIG.pm.numCards = 4; % total number loaded SD cards
% after mission is complete, set below for raw .dat file conversion
CONFIG.pm.convert = 0; % 0 during mission or analysis, set 1 to run conversion
CONFIG.pm.convCnfFile = fullfile(CONFIG.path.mission, 'PMARConvert_sgXXX_Location_MonYYYY.cnf');
% after mission is complete, set below for data processing/analysis
CONFIG.pm.fileLength = 600; % in seconds
CONFIG.pm.sampleRate = 180260; % sample rate
CONFIG.pm.dateFormat = 'yyMMdd-HHmmss.SSS';
CONFIG.pm.dateStart = 19; % what character of file name starts the date format
% example file name: sg639_MHI_Apr2023_230411-185050.484.wav

WISPR settings are only required for processing and analysis after a mission is complete; there is no agate-based piloting interaction with the WISPR system at this time. The settings define input and output paths and extensions for file conversion and the format of the timestamp in filenames for needed for summarizing recording effort in time and space.

% WISPR settings
% only needed after mission is complete (no piloting functionality for WISPR)
CONFIG.ws.loggers = 0; % 1 for active, 0 for inactive
CONFIG.ws.inDir = 'D:\sgXXX_Location_Mon20XX_raw_acoustic_data';   % path to raw .dat files
CONFIG.ws.outDir = 'E:\sgXXX_Location_Mon20XX\flac';   % path to save converted files
CONFIG.ws.outExt = '.flac';   % determines output format
CONFIG.ws.fileLength = 60; % in seconds
CONFIG.ws.dateFormat = 'yyMMdd_HHmmss'; % format of timestamp in filename
CONFIG.ws.dateStart = 7; % character of filename where date starts
% example file name: WISPR_230504_202206.flac

Optional plotting settings

If using agate for plotting during a mission or for analysis and processing after, it is useful to set some plot settings and paths so they don’t have to be repeatedly manually modified.

% %%%% OPTIONAL - plotting %%%%%%%%%%%%%%%%%%

For mapping:

% maps
% path to basemap files (land shape files and bathymetry rasters)
CONFIG.path.shp = 'C:\Users\User.Name\Documents\GIS\';
% optional: can specify full path to bathymetry file, otherwise agate 
% will prompt to select file
CONFIG.map.bathyFile =  'C:\Users\User.Name\Documents\GIS\etopo\etopo1_ice_g_i2.bin';
% define map extents and location of map elements
CONFIG.map.latLim = [000.00 000.00];
CONFIG.map.lonLim = [-000.00 -000.00];
CONFIG.map.naLat = 00.00; % optional arguments for north arrow location on map; 
                          % leave empty '[]' for no north arrow
CONFIG.map.naLon = 000.00;
CONFIG.map.scalePos = [0 0]; % optional arguments for scale bar location 
                             % and ticks, leave empty '[]' for no scale bar
CONFIG.map.scaleMajor = [0:50:100];
CONFIG.map.scaleMinor = [0:12.5:25];

For piloting related plots:

If piloting plots are being regenerated after each dive, it can be useful to assign them each figure numbers and locations so they are just ‘refreshed’ rather than having new plots created each time resulting in a very cluttered desktop! Each piloting plot has a default order that can be modified with the [0 1 2 3 4 5 6 7 8 9] section of the CONFIG.plots.figNumList. The The position of each plot can also be defined and loaded (allowing for these positions to be saved between missions or to have options when viewing on a laptop or multiple screens). For help setting up a figPositions.mat see the Plotting page.

% piloting plot settings
% pre allocate fig numbers so figures are updated rather than created new
CONFIG.plots.figSeed = 111; % suggest using the glider serial e.g., 639
CONFIG.plots.figNumList = CONFIG.plots.figSeed + [0 1 2 3 4 5 6 7 8 9]; 
% figNumList (1) = battery, (2) = voltagePackUse, (3) = humidity
% and pressure, (4) = map, (5) = zoomed map, (6) = minimum voltage, 
% (7) = voltage normalized, (8) = ERMA detections, (9) = ERMA reference

% load plot positions 
% load('C:\Users\User.Name\Documents\gliders\figPositions.mat');
% CONFIG.plots.positions = positions;

_{Back to top}

Basestation configuration file

The path and file name for basestation configuration file is specified with CONFIG.bs.cnfFile in the mission configuration file. An example is located in the agate/settings folder: basestation_example.cnf.

This is a separate configuration file because it typically does not change between missions and gliders and contains potentially sensitive information for the SSH connection to a research group’s basestation. This file should be stored somewhere central and safe, preferably outside of the GitHub repository for security reasons. This file must contain the below lines, with the inputs updated for a particular basestation. It can work with basestation access via a username and password or a username and SSH key pair to authenticate; the one not used should just be excluded or commented out with a %.

CONFIG.bs.host = 'url.com';
CONFIG.bs.username = 'pilot';

% authenticate via password
CONFIG.bs.password = 'PsWrD';
% OR key pair
CONFIG.bs.publicKeyFile  = 'C:/Users/User.Name/.ssh/myPublicKey.pub';
CONFIG.bs.privateKeyFile = 'C:/Users/User.Name/.ssh/myPrivateKey';

_{Back to top}

_{Back to top}