@sixclear/ofg-hypermag
OFG Hypermag v1.0.0

Overview

The OFG Hypermag plugin integrates The Ocean Floor Geophysics (OFG) Hypermag system is a subsea magnetometer sensor array that can be combined with a proprietary software algorithm to enable real time magnetic field data to be compensated for the effects of the host vehicle or platform. Compensated effects include the bulk response of a host vehicle, individual electrical currents and/or servo motor disturbances. Data are synchronously sampled from each individual sensor within a ‘panel’ of either two or four magnetometers to record gradiometer measurements in real-time.

User Interface

HyperMag Commands

The following commands are supported by the HyperMag. We do not show the trailing carriage return and line feed characters below as those are automatically appended by the plugin when commands are sent.

BeginComp

This message tells the application to begin collecting data for the compensation maneuver. This data will be used to calculate the compensation coefficients.

Message Format

$POFG,Cmd,BeginComp,[Suffix]

  • [Suffix] = Optional character string (8 alphanumeric characters only). Valid characters are A-Z, a-z, 0- 9 only (no spaces). If the suffix is invalid, the file will be created but the suffix will be ignored. If the suffix is omitted, the trailing comma is optional.

Examples

  • $POFG,Cmd,BeginComp,
  • $POFG,Cmd,BeginComp
  • $POFG,Cmd,BeginComp,test1
  • NOTE: A BeginComp message followed by another BeginComp message just restarts the compensation routine and is not considered an error.

EndComp

This message tells the application to stop collecting compensation data and calculate the coefficients. This message should only be sent after a matching BeginComp message.

Message Format

$POFG,Cmd,EndComp

  • NOTE: An unmatched EndComp is an error. The program will output an error message and continue in the current state.

NewFile

This message tells the application to close the existing data log file and starts a new one with an optional line number and line tag.

Message Format

$POFG,Cmd,NewFile,[LineNo],[LineTag]

  • [LineNo] = Optional 4-digit line number. Valid characters are 0-9 only (no spaces). If the line number is invalid, the file will be created but the line number will be ignored. If the line number is omitted, the separating comma may or may not be present.
  • [LineTag] = Optional character string (8 alphanumeric characters only). Valid characters are A-Z, a-z, and 0-9 only (no spaces). If the string is invalid, the file will be created but the string will be ignored. If the line tag is omitted, the separating comma may or may not be present. If the line tag is included, there should be a matching valid line number; however, if there isn’t, the line tag should still be used in the new filename.

Examples

  • $POFG,Cmd,NewFile,
  • $POFG,Cmd,NewFile
  • $POFG,Cmd,NewFile,0001
  • $POFG,Cmd,NewFile,0001,uxo_n
  • $POFG,Cmd,NewFile,0037,pipe_w

NewPath

This message tells the application to close all open log files and starts new ones in the new location specified (the path can be absolute or relative). When creating the new file, it:

  • creates the path if it does not exist.
  • New files obey the existing rules for naming (i.e., time stamped with time of creation).
  • If the path specification is invalid, the current logging path is left unchanged and an error message is output (to console, UDP broadcast and HyperMagCMDLog file).

Message Format

$POFG,Cmd,NewPath,[Path]
[Path] = Valid Windows path specification. Limited to 255 total characters.

Examples

  • $POFG,Cmd,NewPath,C:\Hugin\Missions\Norway\Horten\Holmestrand
  • $POFG,Cmd,NewPath,E:\OFG\Missions\Test1
  • $POFG,Cmd,NewPath,..\Test2

INI File Values

A.2.1 [Network]

The [Network] section provides all the configuration parameters for configuring the network and communications.

Sensor_Data_UDP_port

  • Default: 5555
  • Values: 1025-65534
  • Description: UDP port used to send commands to the SIB
  • Example: Sensor_Data_UDP_port=5555

Sensor_Command_UDP_port

  • Default: 5556
  • Values: 1025-65534
  • Description: UDP port used to send commands to the SIB
  • Example: Sensor_Command_UDP_port=5556

Host_Command_UDP_port

  • Default: 57001
  • Values: 1025-65534
  • Description: Defines the UDP port which the ofg_hm.exe application receives commands and data from the host PC.
  • Example: Host_Command_UDP_port=57001

Host_Log_UDP_port

  • Default: 57002
  • Values: 1025-65534
  • Description: UDP to which the log messages are repeated to.
  • Example: Host_Log_UDP_port=5565

Host_Raw_UDP_port

  • Default: 57003
  • Values: 1025-65534
  • Description: UDP to which the raw $HMDAT messages are repeated.
  • Example: Host_Raw_UDP_port=57003

Host_Comp_UDP_port

  • Default: 57004
  • Values: 1025-65534
  • Description: UDP to which the compensated data $HMCOM messages are repeated.
  • Example: Host_Comp_UDP_port=57004

Host_Stack_UDP_port

  • Default: 57005
  • Values: 1025-65534
  • Description: UDP to which the stacked compensated data $HMSTK messages are repeated.
  • Example: Host_Stack_UDP_port=57005

HostIP

  • Default: 127.0.0.1
  • Values: <0 - 255>.<0 – 255>.<0 – 255>.<0 – 255>
  • Description: Defines the IP Address which the ofg_hm.exe application outputs the compensated data to. Follows standard socket rules. This can be left as the default 127.0.0.1 to have the data broadcast only to localhost. Alternatively, can set to broadcast to a specific subnet by leaving the last field as 255.
  • Example: HostIP=192.168.1.255

SensorIP

  • Default: 10.10.103.10
  • Values: <0 - 255>.<0 – 255>.<0 – 255>.<0 – 255>
  • Description: Must be set to the IP address of the SIB to allow the application to query the SIB’s settings and check the license.
  • Example: SensorIP=10.10.103.10

Raw_output

Default: 1
Values: 0-1
Description: Turns the raw output UDP messages on (1) or off (0) to allow for network utilization optimization. Also controls message output to stdout.
Example: Raw_output=1

Comp_output

  • Default: 1
  • Values: 0-1
  • Description: Turns the compensated output UDP messages on (1) or off (0) to allow for network utilization optimization. Also controls message output to stdout.
  • Example: Comp_output=1

Stack_output

  • Default: 0
  • Values: 0-1
  • Description: Turns the stacked output UDP messages on (1) or off (0) to allow for network utilization optimization. Also controls message output to stdout.
  • Example: Stack_output=1

Stack_size_output

  • Default: 25
  • Values: 2-1000
  • Description: Sets the stack size for the UDP stack message output. The stacked output is generated from the median total field value over the specified number of samples (stack size) from a given channel. Refer to the $HMSTK format definition for more details.
  • Example: Stack_size_output=51

A.2.2 [Serial]

The [Serial] section provides all the configuration parameters for configuring the serial connection. In general, the serial connection should be 115200 8N1.

Serial_Port

  • Default: COM8
  • Values: string of max length 2048.
  • Description: Sets the COM port name assigned by windows to the device that is attached to the SIB. This value can be determined by looking at the device manager.
  • Example: Serial_Port=COM1

Serial_Baud

  • Default: 115200
  • Values: 300, 1200 ,2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, 115200
  • Description: Sets baud rate for the serial connection. This must match the setting on the SIB.
  • Example: Serial_Baud=115200

Serial_Bits

  • Default: 8
  • Values: 7, 8
  • Description: Sets the bits for the serial connection. Should be left to 8 typically and must match the SIB.
  • Example: Serial_Bits=8

Serial_Parity

  • Default: 0
  • Values: 0
  • Description: Sets parity for serial connection. Not able to be changed.
  • Example: Serial_Parity=0

Serial_Stopbits

  • Default: 1
  • Values: 0,1
  • Description: Sets the stop bits for the serial connection. Should be left to 1 and must match the SIB.
  • Example: Serial_Stopbits=1

Serial_Retries

  • Default: 5
  • Values: 1-10
  • Description: Number of times to try open the serial port before giving up.
  • Example: Serial_Retries=5

A.2.3 [Sensor]

The [Sensor] section provides all the configuration parameters to notify the ofg_hm.exe application which sensor is attached and how it is configured.

Data_Mode

  • Default: 1
  • Values: 0, 1
  • Description: 0-Serial, 1-Ethernet, Sets the expectation of where the ofg_hm application to receive data. Must match the configuration of the SIB comms setting for proper operation.
  • Example: Data_Mode=1

Append_Timestamp

  • Default: 0
  • Values: 0, 1
  • Description: When enabled by setting to ‘1’ appends a timestamp to the end of HMCOM and HMSTK messages.
  • Example: Append_Timestamp=1

Auto_Restart

  • Default: 0
  • Values: 0, 1
  • Description: When enabled by setting to ‘1’ automatically attempts to start and then restart the SIB data stream by sending a OFG,start and then OFG,reset if the data times out. This option should be disabled if attempting to change settings on the SIB since it will automatically attempt to restart the data feed if an OFG,stop command is issued.
  • Example: Auto_Restart=0

DisplayRate

  • Default: 100
  • Values: -1, 100-9999
  • Description: Controls the repetition of $HMDAT, $HMCOM, and $HMSTK to stdout. Value has units of milliseconds and is the periodicity of repetition. A value of -1 disables messages to stdout.
  • Example: Model=OFG_HM

Split_output_by_MB

  • Default: 50
  • Values: 0-10000
  • Description: When greater than ‘0’ this setting will split the HyperMag and CompHyperMag files every time the HyperMag file grows larger than the set value in MegaBytes. A value of ‘0’ disables this feature.
  • Example: Split_output_by_MB=1

A.2.4 [Logging]

The [Logging] section sets the logging path,

Path
Default: “./”
Values: string of max length 2048
Description: Path to logging directory. It can be the full path name or the relative name.
Network paths are supported (e.g., \192.168.10.34\Data\MagLogs). If the specified folder does not exist, the application will try to create it. The folder must have the correct permissions to allow the application to create folders and write data.
Example: Path=.\HMlogs

A.2.5 [License]

The [License] section provides the configuration parameter to identify where the licensing file is located.

License

  • Default: “license.txt”
  • Values: string of max length 2048
  • Description: Path to the file containing the license key. It can be the full path name or the relative name.
  • Example: License=.\license.txt

A.2.6 [Coefficient Generation]

The [Coefficient Generation] section provides all the configuration parameters for the coefficient generation and the stacking algorithm.

stack_coefficient_generation

  • Default: 0
  • Values: 0-1
  • Description: If set to ‘1’, will stack the data used for coefficient generation using a median stacking algorithm. If set to ‘0’, coefficient generation will use the full data rate compensation maneuver data.
  • Example: stack_coefficient_generation=1

magnetic_reference_type

  • Default: 0
  • Values: 0-2
  • Description: Defines the way the magnetic background is applied during the coefficient generation. 0 – Uses the average across the panel. This will normalize the amplitudes of all of the sensors to each other. This setting is recommended for normal operation. 1 – Uses the value from magnetic_background in hm_prefs.ini. 2 – Uses individual sensor averages.
  • Example: magnetic_reference_type=0

stacking_value

  • Default: 11
  • Values: 2-10000
  • Description: Defines the number of samples to stack over for the coefficient generation. This setting effectively downsamples the data in the compensation maneuver dataset but the stack amount. The downsampled point in a stacked set is chosen using the median value of the total field.
  • Example: stacking_value=50

magnetic_background

  • Default: 43680
  • Values: 2-99999
  • Description: If the magnetic reference type is set to ‘1’, this value is used as the magnetic background for the compensation coefficient generation.
  • Example: magnetic_background=46380

A.2.7 [De-Spiking]

The [De-Spiking] section provides all the configuration parameters for the rejection filters during coefficient generation. The de-spiking function flags data but still logs and outputs the data. During the compensation coefficient calculation, flagged data will be ignored. Users of this function should exercise care in the application of the de-spiking functions as inappropriate settings may cause excess data to be flagged and invalid compensation coefficients be produced.

check_mag_zeros

  • Default: 0
  • Values: 0-1
  • Description: If set to ‘1’ any flagged zeros are ignored in the coefficient calculation. Otherwise, if set to ‘0’ they will be included.
  • Example: check_mag_zeros=0

check_tmi_bounds

  • Default: 0
  • Values: 0-1
  • Description: If set to ‘1’ any flagged exceeded bounds are ignored in the coefficient calculation. Otherwise, if set to ‘0’ they will be included. Refer to upper_tmi_limit and lower_tmi_limit in the hm_prefs.ini file to determine the bounding limits.
  • Example: check_tmi_bounds=0

check_tmi_differential

  • Default: 0
  • Values: 0-1
  • Description: If set to ‘1’ any flagged exceeded differential TMI are ignored in the coefficient calculation. Otherwise, if set to ‘0’ they will be included. Refer to differential_tmi_limit in the hm_prefs.ini file to determine the differential TMI limit.
  • Example: check_tmi_differential=0

upper_tmi_limit

  • Default: 0
  • Values: 1-150000
  • Description: Defines the upper limit of the raw TMI. This property must be defined if check_tmi_bounds is set to ‘1’. Refer to check_tmi_bounds of the hm_prefs.ini file to enable this limit.
  • Example: upper_tmi_limit=60000

lower_tmi_limit

  • Default: 0
  • Values: 1-150000
  • Description: Defines the lower limit of the raw TMI. This property must be defined if check_tmi_bounds is set to ‘1’ and should be less than upper_tmi_limit. Refer to check_tmi_bounds of the hm_prefs.ini file to enable this limit.
  • Example: lower_tmi_limit=20000

differential_tmi_limit

  • Default: 0
  • Values: 1-100000
  • Description: Defines the differential TMI limit of the difference between the current TMI sample and the previous TMI sample. This property must be defined if check_tmi_differential is set to ‘1’. Refer to check_tmi_differential of the hm_prefs.ini file to enable this limit.
  • Example: differential_tmi_limit=1000

Configuration Example


Configuration Details

ROOT object
This top level object holds all configuration information for a OFG HyperMag plugin instance.
Required: true
Default: (not specified; see any element defaults within)
options object
Configuration options specific to the OFG HyperMag plugin.
Required: true
Default: (not specified; see any element defaults within)
options.simulationEnable boolean
Whether to look for and parse expressions in the writeCommand.
Required: true
Default: true
options.shutdownCheckPeriod integer
The delay between checking if the plugin has recieved an asynchronous shutdown signal from the JADE Supervisor.
Required: true
Default: 100
options.publishEnable boolean
Whether to enable publishing data. The data published is the raw x, y, z data values for all 4 sensors.
Required: true
Default: false
options.publishDataDecimationFactor integer
The decimation factor to apply to published data. If this is set to 100 only 1 of every 100 data values is published.
Required: true
Default: 100
options.udpCommonParameters object
The general connection parameters to use for all UDP connections opened in this plugin.
Required: true
Default: (not specified; see any element defaults within)
options.udpCommonParameters.datagramMaxSize integer
The largest expected datagram size. The absolute maximum size of an IPv4 datagram is 65,535 bytes. This is a hard limit defined by the 16-bit 'Total Length' field in the IP header (UDP header size = 8 bytes, min IP header = 20 bytes, max payload = 65,507 bytes). However, standard ethernet MTUs usually max out around 1500 bytes per datagram. Regardless, this value must be greater than or equal to the largest datagram size that will be received.
Required: true
Default: 4096
options.udpCommonParameters.timeout integer
The amount of time in milliseconds that UPD Read operations will wait for incoming data before looping back around to check again. This parameter helps keep UDP read loops responsive to asynchronous shutdown. Do not set this value too high or the plugin will potentially take up to that amount of time to shut down. Also do not set this value too low, or the read loop may waste CPU cycles by spinnkng faster than is necessary to handle incoming data.
Required: true
Default: 2000
options.udpCommonParameters.computerIpAddressForHmComm string
This is a valid IP address of your computer used with UDP Open functions when communicating with ofg_hm.exe, and should very likely be 127.0.0.1. If ofg_hm.exe is running locally, it is almost certainly configured to use HostIP=127.0.0.1 which falls into the special case where both sides of the UDP communication can use that same IP address. If for any reason the HostIP configured for ofg_hm.exe changes to a non-localhost IP (other than 127.0.0.1), then the computerIpAddressForHyperMagCommunication setting will probably need to change to either 0.0.0.0 (which means listen for the port specified on the UDP Open operation, and do so on all network interfaces available) or the computer's actual IP address on the same network and subnet as ofg_hm.exe. In that latter case, ofg_hm.exe would probably broadcast (i.e. using 255 as the last ip address part when it sends data) because it doesn't even have a configurable destination address like the SIB (i.e. a place where it assumes it can send messages to be received by the computer). The lack of destination address in this context is another reason why it's likely that ofg_hm.exe - and this setting - will always simply use 127.0.0.1.
Required: true
Default: "127.0.0.1"
options.streams object
undefined
Required: true
Default: (not specified; see any element defaults within)
options.streams.raw object
Configuration for handling and displaying the raw $HMDAT data stream received from ofg_hm.exe over the configured ofgIniPreferences.Network.Host_Raw_UDP_port.
Required: true
Default: (not specified; see any element defaults within)
options.streams.raw.enable boolean
Whether to enable this stream. If disabled, the corresponding UDP port will not be opened and data for this stream will not be displayed.
Required: true
Default: true
options.streams.raw.synchronizeChartXScales boolean
Whether to synchronize the x-scales of the charts. If true, changing range of one chart changes the range for all charts.
Required: true
Default: true
options.streams.raw.decimationFactor integer
The decimation factor to apply to incoming data. This reduces the amount of data displayed and may help improve performance depending on the configured HyperMag sampling rate and your computer's specifications.
Required: true
Default: 100
options.streams.raw.sampleAggregation integer
The number of samples to aggregate before processing or rendering to display.
Required: true
Default: 500
options.streams.raw.envelopeFilter object
Settings to configure how the envelope filter behaves.
Required: true
Default: (not specified; see any element defaults within)
options.streams.raw.envelopeFilter.bandpassLowCutoff number
Lower cutoff frequency of the carrier band. Constraint: 0 < bandpassLowCutoff < bandpassHighCutoff < samplingRate/2, where samplingRate is the sampling frequency (set in sibParameters.sample).
Required: true
Default: 100
options.streams.raw.envelopeFilter.bandpassHighCutoff number
Upper cutoff frequency of the carrier band. Constraint: 0 < bandpassLowCutoff < bandpassHighCutoff < samplingRate/2, where samplingRate is the sampling frequency (set in sibParameters.sample).
Required: true
Default: 500
options.streams.raw.envelopeFilter.bandpassOrder integer
The order of the bandpass filter.
Required: true
Default: 2
options.streams.raw.envelopeFilter.lowpassEnvelopeCutoff number
Lowpass cutoff controlling how fast the envelope can change. Constraint: 0 < lowpassEnvelopeCutoff < samplingRate/2, where samplingRate is the sampling frequency (set in sibParameters.sample). Guidance: Choose based on expected amplitude variation rate, not carrier frequency. Typical values: 5-20 Hz.
Required: true
Default: 500
options.streams.raw.envelopeFilter.lowpassOrder integer
The order of the lowpass filter.
Required: true
Default: 2
options.streams.compensated object
Configuration for handling and displaying either the $HMDCOM or $HMSTK data stream (depending on the selection of 'source' here) received from ofg_hm.exe over the configured ofgIniPreferences.Network.Host_Comp_UDP_port or ofgIniPreferences.Network.Host_Stack_UDP_port respectively.
Required: true
Default: (not specified; see any element defaults within)
options.streams.compensated.enable boolean
Whether to enable this stream.
Required: true
Default: true
options.streams.compensated.synchronizeChartXScales boolean
Whether to synchronize the x-scales of the charts. If true, changing range of one chart changes the range for all charts.
Required: true
Default: true
options.streams.compensated.source enum (string)
$HMCOM data is the full compensated data. $HMSTCK data is composed of the compensated values selected using the median total magnetic field value for each sensor across the number of input lines. This process effectively performs a simple median selection on the data and downsamples before it is sent over the UDP port. The amount of downsampling is set by the option ofgIniPreferences.Network.Stack_size_output. For example, if the option ofgIniPreferences.Network.Stack_size_output is set to 10, then the UDP port will receive only 1 datagram for every 10 samples (the median of those 10 samples, as described above). This downsampling is completely independent of the configurable decimationFactor here; the decimationFactor applies on top of the already downsampled data. Set the decimationFactor to 1 to prevent further downsampling / decimation of the data. Unless viewing all compensated data is necessary, the $HMSTK source is preferred here because it downsampled data at the source and therefore is less computationally expensive to process.
Required: true
Default: "$HMSTK"
Enum Items: "$HMCOM" | "$HMSTK"
options.streams.compensated.decimationFactor integer
The decimation factor to apply to incoming data. This reduces the amount of data displayed and may help improve performance depending on the configured HyperMag sampling rate and your computer's specifications. Note that for the stacked stream, the ofgIniPreferences.Network.Stack_size_output option here will effectively decimate the data at the source, before it is transmitted over UPD. The HyperMag does not provide this source decimation feature for other streams.
Required: true
Default: 1
options.streams.compensated.sampleAggregation integer
The number of samples to aggregate before processing or rendering to display.
Required: true
Default: 500
options.streams.log object
Configuration for handling and displaying log messages received from ofg_hm.exe over the configured ofgIniPreferences.Network.Host_Log_UDP_port. This includes any commands sent to ofg_hm.exe (ex. BeginComp), device errors, and even the $HMCOF coefficient message which is sent 1. after new compensation coefficients are calculated and 2. at the initial start of the application if there are coefficients retained from a prior compensation maneuver in the coefficients.txt file. Notably, NEMA style $HMCOF data arrvies for each of 4 sensors in the form `$HMCOF[N],[MagDate]-[MagTime],[Cof1],[Cof2],...,[Cof16]*[checksum][CR][LF]` where `[N]` in `$HMCOF[N]` will be an integer sensor number in the range 1 to 4. Note that in simulation mode, simulated logs are generated every 2 seconds.
Required: true
Default: (not specified; see any element defaults within)
options.streams.log.enable boolean
Whether to enable this stream.
Required: true
Default: true
options.streams.log.decimationFactor integer
The decimation factor to apply to incoming data, to reduce the number of messages displayed. Typically we do not want to supress log messages, hence the default value of 1.
Required: true
Default: 1
options.streams.log.filterRegex string
Regex pattern to filter log messages. To disable filtering, set the filterRegex to an empty string.
Required: true
Default: ""
options.ofgHmExePath string
The absolute file path to the ofg_hm.exe file required to run this plugin.
Required: true
Default: "ofg_hm.exe"
options.ofgHmExeShutdownTimeout integer
The number of milliseconds to wait for ofg_hm.exe to shut down.
Required: true
Default: 1000
options.ofgHmExeShutdownFileCloseGracePeriod integer
The number of milliseconds to wait for ofg_hm.exe to close data log files.
Required: true
Default: 500
options.hmPreferences object
These preferences correspond precisely to the entries of the hm_prefs.ini file. These preferences will be used when ofg_hm.exe is launched by this plugin. The first time the plugin runs, we save a backup copy of hm_prefs.ini named ofg_prefs.backup.ini and create a new hm_prefs.ini file with the settings herein so those settings apply when ofg_hm.exe is run. On subsequent runs, we'll detect the existence of ofg_prefs.backup.ini and simply replace hm_prefs.ini.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.Network object
The [Network] section provides all the configuration parameters for configuring the network and communications.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.Network.Sensor_Data_UDP_port integer
UDP port used to send commands to the SIB.
Required: true
Default: 5555
options.hmPreferences.Network.Sensor_Command_UDP_port integer
UDP port used to send commands to the SIB.
Required: true
Default: 5556
options.hmPreferences.Network.Host_Command_UDP_port integer
Defines the UDP port which the ofg_hm.exe application receives commands and data from the host PC.
Required: true
Default: 57001
options.hmPreferences.Network.Host_Log_UDP_port integer
UDP to which the log messages are repeated to.
Required: true
Default: 57002
options.hmPreferences.Network.Host_Raw_UDP_port integer
UDP to which the raw $HMDAT messages are repeated.
Required: true
Default: 57003
options.hmPreferences.Network.Host_Comp_UDP_port integer
UDP to which the compensated data $HMCOM messages are repeated.
Required: true
Default: 57004
options.hmPreferences.Network.Host_Stack_UDP_port integer
UDP to which the stacked compensated data $HMSTK messages are repeated.
Required: true
Default: 57005
options.hmPreferences.Network.HostIP string
Defines the IP Address which the ofg_hm.exe application outputs the compensated data to. Follows standard socket rules.
Required: true
Default: "127.0.0.1"
options.hmPreferences.Network.SensorIP string
Must be set to the IP address of the SIB to allow the application to query the SIB's settings and check the license.
Required: true
Default: "10.10.103.10"
options.hmPreferences.Network.Raw_output integer
Turns the raw output UDP messages on (1) or off (0) to allow for network utilization optimization. Also controls message output to stdout.
Required: true
Default: 1
Enum Items: 0 | 1
options.hmPreferences.Network.Comp_output integer
Turns the compensated output UDP messages on (1) or off (0) to allow for network utilization optimization. Also controls message output to stdout.
Required: true
Default: 1
Enum Items: 0 | 1
options.hmPreferences.Network.Stack_output integer
Turns the stacked output UDP messages on (1) or off (0) to allow for network utilization optimization. Also controls message output to stdout.
Required: true
Default: 0
Enum Items: 0 | 1
options.hmPreferences.Network.Stack_size_output integer
Sets the stack size for the UDP stack message output. The stacked output is generated from the median total field value over the specified number of samples.
Required: true
Default: 25
options.hmPreferences.Serial object
The [Serial] section provides all the configuration parameters for configuring the serial connection. In general, the serial connection should be 115200 8N1.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.Serial.Serial_Port string
Sets the COM port name assigned by windows to the device that is attached to the SIB.
Required: true
Default: "COM22"
options.hmPreferences.Serial.Serial_Baud integer
Sets baud rate for the serial connection. This must match the setting on the SIB.
Required: true
Default: 115200
Enum Items: 300 | 1200 | 2400 | 4800 | 9600 | 14400 | 19200 | 28800 | 38400 | 57600 | 115200
options.hmPreferences.Serial.Serial_Bits integer
Sets the bits for the serial connection. Should be left to 8 typically and must match the SIB.
Required: true
Default: 8
Enum Items: 7 | 8
options.hmPreferences.Serial.Serial_Parity integer
Sets parity for serial connection. Not able to be changed.
Required: true
Default: 0
options.hmPreferences.Serial.Serial_Stopbits integer
Sets the stop bits for the serial connection. Should be left to 1 and must match the SIB.
Required: true
Default: 1
Enum Items: 0 | 1
options.hmPreferences.Serial.Serial_Retries integer
Number of times to try open the serial port before giving up.
Required: true
Default: 5
options.hmPreferences.Sensor object
The [Sensor] section provides all the configuration parameters to notify the ofg_hm.exe application which sensor is attached and how it is configured.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.Sensor.Data_Mode integer
0-Serial, 1-Ethernet. Defines where ofg_hm.exe will receive data.
Required: true
Default: 1
Enum Items: 0 | 1
options.hmPreferences.Sensor.Append_Timestamp integer
When enabled by setting to '1' appends a timestamp to the end of HMCOM and HMSTK messages.
Required: true
Default: 0
Enum Items: 0 | 1
options.hmPreferences.Sensor.Auto_Restart integer
When enabled by setting to '1' automatically attempts to start and then restart the SIB data stream if the data times out.
Required: true
Default: 0
Enum Items: 0 | 1
options.hmPreferences.Sensor.DisplayRate integer
Controls the repetition of $HMDAT, $HMCOM, and $HMSTK to stdout. Value in ms. -1 disables output.
Required: true
Default: 100
options.hmPreferences.Sensor.Split_output_by_MB integer
Splits the HyperMag and CompHyperMag files every time the file grows larger than the set value in MB. 0 disables.
Required: true
Default: 50
options.hmPreferences.Logging object
The [Logging] section sets the logging path.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.Logging.Path string
Path to logging directory. It can be the full path name or the relative name.
Required: true
Default: "[Desktop]\\JADE_LOGS\\@VAR{instanceName}"
options.hmPreferences.License object
The [License] section provides the configuration parameter to identify where the licensing file is located.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.License.License string
Path to the file containing the license key.
Required: true
Default: ".\\license.txt"
options.hmPreferences.Coefficient Generation object
The [Coefficient Generation] section provides all the configuration parameters for the coefficient generation and the stacking algorithm.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.Coefficient Generation.stack_coefficient_generation integer
If set to '1', will stack the data used for coefficient generation using a median stacking algorithm.
Required: true
Default: 1
Enum Items: 0 | 1
options.hmPreferences.Coefficient Generation.magnetic_reference_type integer
Defines the way the magnetic background is applied during the coefficient generation. 0-Average, 1-Manual Background, 2-Individual Sensor Averages.
Required: true
Default: 0
options.hmPreferences.Coefficient Generation.stacking_value integer
Defines the number of samples to stack over for the coefficient generation.
Required: true
Default: 11
options.hmPreferences.Coefficient Generation.magnetic_background integer
If the magnetic reference type is set to '1', this value is used as the magnetic background.
Required: true
Default: 43680
options.hmPreferences.De-Spiking object
The [De-Spiking] section provides all the configuration parameters for the rejection filters during coefficient generation. The de-spiking function flags data but still logs and outputs the data. During the compensation coefficient calculation, flagged data will be ignored. Users of this function should exercise care in the application of the de-spiking functions as inappropriate settings may cause excess data to be flagged and invalid compensation coefficients be produced.
Required: true
Default: (not specified; see any element defaults within)
options.hmPreferences.De-Spiking.check_mag_zeros integer
If set to '1' any flagged zeros are ignored in the coefficient calculation.
Required: true
Default: 0
Enum Items: 0 | 1
options.hmPreferences.De-Spiking.check_tmi_bounds integer
If set to '1' any flagged exceeded bounds are ignored in the coefficient calculation.
Required: true
Default: 0
Enum Items: 0 | 1
options.hmPreferences.De-Spiking.check_tmi_differential integer
If set to '1' any flagged exceeded differential TMI are ignored in the coefficient calculation.
Required: true
Default: 0
Enum Items: 0 | 1
options.hmPreferences.De-Spiking.upper_tmi_limit integer
Defines the upper limit of the raw TMI. Required if check_tmi_bounds is 1. AI explanation of limits: Look up the IGRF (International Geomagnetic Reference Field) value for your survey location. Set limits roughly ±10,000 nT from that base value. Example: If you are surveying in the Gulf of Mexico where the field is ~45,000 nT, you might set your lower limit to 35,000 and your upper to 55,000.
Required: true
Default: 60000
options.hmPreferences.De-Spiking.lower_tmi_limit integer
Defines the lower limit of the raw TMI. Required if check_tmi_bounds is 1. Defines the upper limit of the raw TMI. Required if check_tmi_bounds is 1. AI explanation of limits: Look up the IGRF (International Geomagnetic Reference Field) value for your survey location. Set limits roughly ±10,000 nT from that base value. Example: If you are surveying in the Gulf of Mexico where the field is ~45,000 nT, you might set your lower limit to 35,000 and your upper to 55,000.
Required: true
Default: 20000
options.hmPreferences.De-Spiking.differential_tmi_limit integer
Defines the differential TMI limit between samples. Required if check_tmi_differential is 1. AI Explanation: This is used to 'spike reject' electrical interference or high-frequency noise. Common values are in the range 100 nT to 500 nT. If your SIB is sampling at 20 Hz (every 50ms), the TMI should not naturally jump by 1,000 nT in a single step unless the sensor literally hit a steel pipe. Tight Filter (100 nT): Used for clean 'Deep Tow' surveys far away from ROV noise. Loose Filter (500 nT+): Used when mounting sensors directly on a 'noisy' ROV where magnetic interference from the motors is expected.
Required: true
Default: 1000
options.sibParameters object
This section has configuration for parameters for the Sensor Interface Bottle (SIB). These parameters are set initially, before ofg_hm.exe is launch and used to receive data over UDP. The following parameters are read-only as we use them to communicate with the SIB itself: ipaddr, subnet, gateway, txport, rxport. We set all but the read-only parameters on the SIB here to maintain full control over the configuration here. We also log these settings and settings returned from the SIB itself for visility into what was set. To make changes to read-only parameters, see the HyperMag User Manual regarding connecting and sending command via a serial port vs UDP.
Required: true
Default: (not specified; see any element defaults within)
options.sibParameters.sample integer
The sample rate frequency. Has restrictions on which values may be set based on the binary and comms settings. If the value cannot be changed the SIB responds with an Error and the value in flash remains unchanged. Values 10, 20, 30 Can always be set. Values 40, 50, 60 in serial modes can only set with binary formats but can always be set in ethernet modes. Values 80, 100, 120, 150, 160, 200, 240, 300, 320, 400, 480, 600 can only be set in ethernet modes but can be either ASCII or binary format. Values 800, 960, 1200, 1600, 2400 can only be set in ethernet modes with binary format.
Required: true
Default: 100
Enum Items: 10 | 20 | 30 | 40 | 50 | 60 | 80 | 100 | 120 | 150 | 160 | 200 | 240 | 300 | 320 | 400 | 480 | 600 | 800 | 960 | 1200 | 1600 | 2400
options.sibParameters.gainICP integer
Gain setting for iCP digitizers if installed and enabled.
Required: true
Default: 128
Enum Items: 1 | 2 | 4 | 8 | 16 | 32 | 64 | 128
options.sibParameters.device1 integer
Port 1 sensor: 0=None, 1=Mag 60uT, 2=ICP, 3=Mag 100uT.
Required: true
Default: 1
Enum Items: 0 | 1 | 2 | 3
options.sibParameters.device2 integer
Port 2 sensor: 0=None, 1=Mag 60uT, 2=ICP, 3=Mag 100uT.
Required: true
Default: 1
Enum Items: 0 | 1 | 2 | 3
options.sibParameters.device3 integer
Port 3 sensor: 0=None, 1=Mag 60uT, 2=ICP, 3=Mag 100uT.
Required: true
Default: 1
Enum Items: 0 | 1 | 2 | 3
options.sibParameters.device4 integer
Port 4 sensor: 0=None, 1=Mag 60uT, 2=ICP, 3=Mag 100uT.
Required: true
Default: 1
Enum Items: 0 | 1 | 2 | 3
options.sibParameters.device5 integer
Configures device5 for an ICP device: 0=None, 2=ICP.
Required: true
Default: 0
Enum Items: 0 | 2
options.sibParameters.device6 integer
Configures device6 for an ICP device: 0=None, 2=ICP.
Required: true
Default: 0
Enum Items: 0 | 2
options.sibParameters.comms integer
Output communication channel: 0=Serial (RS232), 1=Ethernet (UDP).
Required: true
Default: 1
Enum Items: 0 | 1
options.sibParameters.license integer
Configures the license output string appended to every line. 0=Disabled, 1=Enabled.
Required: true
Default: 0
Enum Items: 0 | 1
options.sibParameters.ipaddr string
Configures the SIB's IP address.
Required: true
Default: "10.10.103.10"
options.sibParameters.subnet string
Configures the SIB's subnet mask.
Required: true
Default: "255.255.255.0"
options.sibParameters.gateway string
Configures the SIB's default gateway.
Required: true
Default: "10.10.103.100"
options.sibParameters.destip string
IP address of the consumer of the sensor data (i.e. this computer).
Required: true
Default: "10.10.103.100"
options.sibParameters.ntpip string
IP address of the NTP server (UDP port 123).
Required: true
Default: "10.10.103.106"
options.sibParameters.txport integer
UDP Transmit port for mag data and command responses.
Required: true
Default: 5555
options.sibParameters.rxport integer
UDP Receive port for commands.
Required: true
Default: 5556
options.sibParameters.timeport integer
UDP Transmit port for NTPST messages.
Required: true
Default: 5557
options.sibParameters.ser1baud integer
RS232 serial port 1 baud rate.
Required: true
Default: 115200
Enum Items: 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200
options.sibParameters.ser2baud integer
RS232 serial port 2 baud rate.
Required: true
Default: 115200
Enum Items: 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200
options.sibParameters.binary integer
Data line format: 0=ASCII, 2=Binary (Base64). High rates require Binary.
Required: true
Default: 0
Enum Items: 0 | 2
options.sibParameters.zero_latency integer
0=Disable, 1=Enable. Enabling creates flat magnitude response but increases noise floor by 2X.
Required: true
Default: 0
Enum Items: 0 | 1
options.sibParameters.ppm integer
The Parts Per Million frequency difference between the SIB and NTP server.
Required: true
Default: -58
options.sibParameters.ntp_kp integer
Proportional gain of the NTP client.
Required: true
Default: 100
options.sibParameters.ntp_ki integer
Integral gain of the NTP client.
Required: true
Default: 1000
options.sibParameters.ntp_max_reach integer
Maximum reach allowed by the NTP client to reduce gain over time.
Required: true
Default: 2
Enum Items: 2 | 4 | 8 | 16 | 32 | 64 | 128
options.logger object
Defines the standard logger for this plugin. Note that a LOG variable space is provided here, as well as the VAR variable space. Available variables are: @LOG{LOGGERNAME}, @LOG{TIMESTAMP}, @LOG{LOGMESSAGE}, @LOG{ERRORMESSAGE}, @VAR{instanceName}, @VAR{timestamp}, and @VAR{acquisition} which contains the entire acquisition object meaning you can index out individual properties such as @VAR{acquisition.sampling.readSamplesPerChannel} are available variables. Note: @LOG{LOGGERNAME} is equal to the @VAR{instanceName} here.
Required: true
Default: (not specified; see any element defaults within)
options.logger.Enable boolean
Whether to enable the logger.
Required: true
Default: true
options.logger.Start enum (string)
When to start logging.
Required: false
Default: "Immediate"
Enum Items: "Immediate" | "User"
options.logger.LogFolder string
The folder in which to write log files.
Required: true
Default: "[Desktop]\\JADE_LOGS\\@VAR{instanceName}"
options.logger.FileNameFormat string
The filename to use when creating log files. Note: if the filesize limit is reached new files will be created with enumerated suffixes such as: MyLogFile-1.txt, MyLogFile-2.txt, etc.
Required: true
Default: "@VAR{instanceName}-@LOG{TIMESTAMP}.log"
options.logger.ErrorsOnly boolean
Whether to log only errors.
Required: true
Default: true
options.logger.DiskThrashPeriod integer
The period in milliseconds with which to flush the file buffer to ensure it's committed to the hard drive. Note: This is a performance consideration to prevent writing to disk too frequently.
Required: true
Default: 1000
options.logger.FileSizeLimit integer
The file size at which to create new files.
Required: true
Default: 1000000
options.logger.StartLogFormat string
The initial string to put into the log file when opened for the first time.
Required: true
Default: "**** START LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.logger.EndLogFormat string
The final string to put in the log file when closed.
Required: true
Default: "\n\n**** END LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.logger.LogEntryFormat string
The format to use when writing log entries when errors are not present.
Required: true
Default: "\n\n@LOG{LOGMESSAGE}"
options.logger.ErrorLogEntryFormat string
The message format used to construct error log entries.
Required: true
Default: "\n\n@LOG{ERRORMESSAGE}"
options.logger.TimestampFormat string
The format used by the @LOG{TIMESTAMP} variable.
Required: true
Default: "%Y-%m-%d %H-%M-%S%3u"
panel object
Required: false
Default: (not specified; see any element defaults within)
panel.open boolean
Whether to open the front panel immediately when run.
Required: true
Default: true
panel.state enum (string)
The state in which the window will open.
Required: true
Default: "Standard"
Enum Items: "Standard" | "Hidden" | "Closed" | "Minimized" | "Maximized"
panel.transparency integer
The transparency of the window. 0 = opaque, 100 = invisible.
Required: true
Default: 0
panel.title string
The title of the plugin window when it runs. Note that the variable 'instanceName' is provided here in a VAR variable container.
Required: true
Default: "@VAR{instanceName}"
panel.titleBarVisible boolean
Whether the window title bar is visible.
Required: true
Default: true
panel.showMenuBar boolean
Whether the menu bar is visible.
Required: true
Default: false
panel.showToolBar boolean
Whether the toolbar is visible.
Required: true
Default: false
panel.makeActive boolean
Whether the window becomes active when opened.
Required: true
Default: false
panel.bringToFront boolean
Whether the window is brought to the front / top of other windows when opened.
Required: true
Default: false
panel.minimizable boolean
Whether the window is minimizable.
Required: true
Default: true
panel.resizable boolean
Whether the window is resizable.
Required: true
Default: true
panel.closeable boolean
Whether the window is closeable.
Required: true
Default: true
panel.closeWhenDone boolean
Whether to close the window when complete.
Required: true
Default: true
panel.center boolean
Whether to center the window when opened. Note: this property overrides the 'position' property.
Required: true
Default: false
panel.position object
The position of the window when opened the first time.
Required: true
Default: (not specified; see any element defaults within)
panel.position.top integer
The vertical position of the window in pixels from the top edge of the viewport. Note: this property is overriden by the 'center' property.
Required: true
Default: 100
panel.position.left integer
The horizontal position of the window in pixels from the left edge of the viewport. Note: this property is overriden by the 'center' property.
Required: true
Default: 100
panel.size object
The size of the window when opened the first time.
Required: false
Default: (not specified; see any element defaults within)
panel.size.width integer
The width of the window in pixels. -1 means use the default width for the panel. Note that depending on panel features exposed, there may be a limit to how small a panel can become.
Required: true
Default: -1
panel.size.height integer
The height of the window in pixels. -1 means use the default height for the panel. Note that depending on panel features exposed, there may be a limit to how small a panel can become.
Required: true
Default: -1
channel object
The communication channel definition used by this plugin. Note: this section rarely needs modifications. In many cases, the underlying plugin implementation depends on at least some of these settings having the values below. Consult with a JADE expert before making changes to this section if you are unfamiliar with the implications of changes to this section.
Required: false
Default: (not specified; see any element defaults within)
channel.SendBreakTimeout integer
The timeout duration in milliseconds to wait for sending messages.
Required: true
Default: 1000
channel.WaitOnBreakTimeout integer
The timeout duration in milliseconds to wait for receiving messages. Note: -1 means wait indefinitely or until shutdown is signalled.
Required: true
Default: -1
channel.WaitOnShutdownTimeout integer
The timeout duration in milliseconds to wait for shutdown acknowledgment.
Required: true
Default: 2000
channel.ThrowTimeoutErrors boolean
Whether to throw timeout errors vs simply returning a boolean indicating whether a timeout occurred.
Required: true
Default: false
channel.ThrowShutdownUnacknowledgedErrors boolean
Whether to throw 'shutdown unacknowledged' errors.
Required: true
Default: true
channel.QueueSize integer
The size of the underlying communication queue in bytes. Note: -1 means unbounded (i.e. grow as needed with available memory).
Required: true
Default: 100
channel.SendBreakEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for standard messages.
Required: true
Default: "LossyEnqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendErrorEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for error messages.
Required: true
Default: "LossyEnqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendShutdownEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for the shutdown message.
Required: true
Default: "LossyEnqueueAtFront"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.FlushQueueBeforeWaitingOnBreak boolean
Whether to flush the queue upon waiting for new messages (i.e. whether to clear the queue and wait for the next 'new' message; this has the effect of removing old messages and waiting for the next message.
Required: true
Default: false
channel.FlushQueueAfterBreaking boolean
Whether to flush the queue after receiving a new message (i.e. whether to handle the next message coming in the queue and then flush; this has the effect of handling the oldest message (if it exsits) or the next message before flushing the queue.
Required: true
Default: false