Simrad EK80 Subscription

The Echolog Data File Format setting Simrad EK80 Subscription allows Echolog to use Simrad EK80 REST subscriptions to subset or change the resolution of EK80 echogram data. This provides flexiblity for echogram feature analysis (only look at the interesting parts of an echogram) and can improve Echoview responsiveness, during live viewing, through the use of lower resolution data.

Echolog records the subscription data in EK5 survey files and can broadcast the data under live viewing.

Echolog Simrad EK80 Subscription uses a Configuration file to specifiy up to 9 subscriptions that are handled by the API (Application Programming Interface) of Simrad EK80 software.

Configuration file

The Configuration file specifies: computer and Simrad EK80 software API communication settings, output survey-file settings, and EK80 data subscription settings. Under Simrad EK80 Subscription, Echolog outputs survey files with subscription data saved in *.ek5 files, used during live viewing. The Configuration file (*.TOML) uses TOML as the file format.

A Configuration file is required for an instance of Echolog.

File root lines

ek80-server-address = "XXX.X.X.X"

"XXX.X.X.X" is the address required to interface with the Simrad EK80 software API. In practice, the same machine runs Echolog and the Simrad EK80 software. The Simrad EK80 software API doesn't support sending of subscription data to a remote machine. Machine names including 'localhost' are accepted.

The address is displayed under the Simrad EK80 software, Installation, Web API Service settings. While Simrad EK80 software is running, the URL that lists the data sources is: http://localhost:12346/api/sounder/data-output/state/data-sources.

survey-directory = 'Your Configuration file folder'

'Your Configuration file folder' is directory where output *.ek5 files are written. The directory must be a valid, absolute file path to an existing directory.

file-name-prefix = 'YourSurveyFilePrefix_'

The file name prefix prepends to the output *.ek5 survey files. The default name is 'SURVEY_'. The file name requires valid characters.

maximum-file-size = 10

The maximum file size in MB for the ouput *.ek5 file before a new output file is started.. The default file size is 100 MB.

refresh-interval = 1

Time interval in seconds at which Echolog will contact the Simrad EK80 software API for GPS coordinates. The default refresh-interval is 1 second. Received GPS data is recorded and mapped to a position GPS fixes variable. The refresh-interval affects the density of GPS data and is unrelated to the time interval between GPS fixes.

[endpoint] lines

name = 'echolog-1'

Name for the Echolog application seeking to communicate with the Simrad EK80 software API. The name must be a unique name amongst all the (other) applications seeking to interface with the Simrad EK80 sotware API. See also Echolog instance name.

address = 'XXX.X.X.X'

"XXX.X.X.X" is the IPv4 address required to receive subscription data from the Simrad EK80 software API. See Root section line, ek80-server-address = "XXX.X.X.X"

Defaults to the first local IPv4 address for the machine running Echolog.

port = YYYYY

Port used to receive subscription data from the Simrad EK80 software API. Defaults to port 51152.

[[echogram-subscription]] lines

channel-id = "WBT 582170-15 ES200-7C_ES"

The name of the Simrad EK80 channel for the subscription. The Simrad EK80 channel ID may be found under the localhost data-sources settings while Simrad EK80 software is running. Or you can request a subscription to a non-existent channel - the Echolog error message lists the available Channel ID names.

settings = { range-start=0.0, range=100.0, pixel-count=500 }

The subscription specification supports values for ping range start (m), ping range (m) and ping sample count. JSON text attribute-value pairs are the format used and a full JSON string must be on one line. JSON is an open standard data interchange format that uses human-readable text to store and transmit data objects.

Up to 9 subscriptions are supported. Within the EK5 survey file, one trandsucer is shared by all subscriptions (regardless of source transducer or frequency) and one acoustic variable per subscription is recorded. See Survey file.

Combinations of ping range start, ping range and ping sample count can be used to change the resolution of, or form a subset of echogram ping data.

range-start=0.0

range-start represents ping range start in meters. The default range-start value is 0.00 meters. Accepted values are [0.00, 9999.98].

range=100.0

range represents the range of the ping in meters. Accepted values are (0.00, 9999.98].

pixel-count=500

pixel-count represents the number of samples in a ping. Accepted values are [1, 10000].

Example Configuration file

ek80-server-address = "XXX.X.X.X"
survey-directory = 'Your Configuration file folder'
file-name-prefix = 'EchologTest_'
maximum-file-size = 10
refresh-interval = 1

[endpoint]
name = 'echolog-1'
address = 'XXX.X.X.X'
port = YYYYY

[[echogram-subscription]]
channel-id = "WBT 582170-15 ES200-7C_ES"
settings = { range-start=0.0, range=100.0, pixel-count=500 }

[[echogram-subscription]]
channel-id = "WBT 582170-15 ES200-7C_ES"
settings = { range-start=39.8, range=10.1, pixel-count=10000 }

Survey file (*.ek5)

Survey files that record EK80 subscription data have a name and extension as follows:

<prefix>-DYYMMDDTHHmmSS.ek5

Where:

<prefix> is the Configuration file setting, file-name-prefix.

The source EK80 file time provides:

YY, the integer value for the year.

MM, the integer value for the month.

DD, the interger value for the day.

HH, the integer value for hours.

mm, the integer value for minutes.

SS, the integer value seconds.

For each [[echogram-subscription]], Echolog sends an echogram subscription request to the Simrad EK80 software API and records the received datagrams to the survey file.

The survey file maps a single transducer to all the subscription-echogram datagrams (even if they are subscriptions to different transducers with different frequencies). This is seen in Echoview as a single transducer object with variables attached to the transducer.

Each subscription-datagram records the echogram-subscription number in the transducer number field of the datagram. This links the subscription number to the variable. In the case where subscription data originates from other transducers and/or frequencies, use the Dataflow window shortcut menu item New, Transducer to arrange the subscription variables under more appropriate transducers/frequencies.

The nth subscription data for a given instance of Echolog, is written to the variable 'Sv Qn telegrams Tn' and 'Sv Qn telegrams with expanded bottom Tn' in the *ek5 survey file. The Echoview file support for the survey file automatically generates an expanded bottom variable, that is in practice identical to the associated non-expanded variable.

Subscription bottom depth data is written to the variable 'line data sounder detected bottom Tn'. Note, this is the bottom depth in the Echogram datagram, and is distinct from Bottom Detection datagrams in the EK80 API.

Notes:

Some echogram subscription settings are hardcoded within Echolog and can't currently be changed. The most relevant are: TvgFunction = 20, and TvgType = sv.
The limitations of the EK5 file format mean that only nine subscriptions can be supported by a single instance of Echolog. The Simrad EK80 software is not limited in the number of subscriptions it provides. Consequently, further subscriptions from an EK80 echogram could be handled by other instances of Echolog.

Echolog and Simrad EK80 software API interaction

If Echolog can't connect to the Simrad EK80 software API while Echolog is running, Echoview will display errors and wait for new communication on the connection. The assumption behind this behavior is to wait until the original connection is restored when the network issue is resolved. A connection is permanently lost when Simrad EK80 software is restarted. To continue live viewing in Echoview, restart Echolog to establish a new connection to the Simrad EK80 software API.