Software Interface Guide

This section discusses some scenarios of 3rd party software interface to Surveyor, from just post processing Surveyor svlog files to full Surveyor control during data capture through logging and post processing.

Surveyor communication uses a packet protocol common to Cerulean Sonar products. The canonical packet format is documented in the Cerulean Ping Protocol document as are some other packet formats common to multiple Cerulean sonar products. There are other packet formats specific to Surveyor which are documented in the Application Programming Interface section of this document.

We discuss three scenarios of software interaction with Surveyor

Controlling Surveyor during data collection

If you wish to control Surveyor directly during capture the main interface will be the SET_PING_PARAMETERS packet which your software will send to Surveyor to control its operation. Surveyor has an internal IMU which provides pitch and roll information, but to geolocate the points that Surveyor collects you will need to provide heading and position from other sources.

To synchronize the heading and position data with the Surveyor point data you could log the information in chronological sequence along with the ATTITUDE_REPORT and ATOF_POINT_DATA from Surveyor in any desired file format. Alternatively or in addition, you can provide Surveyor with an NTP server using the SET_NET_INFO packet.

If Surveyor does have a connection to an NTP server the output packets will be time stamped with UTC time. In this case you could log the Surveyor output packets verbatim in one file and record heading and position (also UTC time stamped) in a separate file to be subsequently merged during a post processing step.

Use SonarView to control Surveyor during data collection

SonarView is the Cerulean software application supporting all the Cerulean products as well as a few 3rd party products. In another scenario for software interfacing to Surveyor, SonarView can be used to control Surveyor during data collection while a 3rd party application "listens in" on the output data stream via a web socket connection and provide live view through its own interface.

SonarView is mainly a web app, but there is a server component called SonarLink which handles the h/w interface. They're both bundled into the same application so if SonarView is running, the SonarLink server is also present.

SonarView and SonarLink communicate over a web socket. It is possible to open multiple web sockets to the same device session, so if the 3rd party software opens a web socket to SonarLink it will receive all the device packets over this link exactly as SonarView receives them.

In this scenario SonarView can be used to specify and set up the integration of external sources for position and heading as well as the web socket interface. Here is the documentation on the SonarView session configuration.

The packet handling required in this scenario is the same as required for post processing svlog files as described below.

Post processing svlog files

The simplest application interface would be to read svlog files captured live with SonarView to execute some post processing functions.

Packets you will need to handle coming directly from Surveyor are ATTITUDE_REPORT and ATOF_POINT_DATA.

In addition, heading and position data information will typically be present in "wrapper" packets containing NMEA or MAVLink encoded data. Here are the packet definitions: NMEA_WRAPPER, MAVLINK_WRAPPER.

MAVLink data will be in json format within the MAVLINK_WRAPPER packet. The MAVLink messages are documented in the MAVLink Developer Guide.

NMEA messages will be standard NMEA definition plain text within the NMEA_WRAPPER packet.