DVL A100/A250 TCP JSON API

The DVL TCP JSON API sends JSON messages over TCP on port 16171. This page applies to DVL A100 and DVL A250.

Terminology

• DVL - Doppler Velocity Log - Uses hydro-acoustic beams to measure the velocity at which the DVL is moving across a surface (typically an unmoving one such as the sea bottom), and the distance to this surface.
• ACK - Acknowledgement. The command issued was successful.
• NAK - Negative acknowledgement. The command issued failed.
• Ping - A pulse of sound sent by the DVL
• Time of validity - Timestamp of the surface reflection ('center of ping')
• Time of transmission - Timestamp taken directly before sending data over the serial or TCP protocols. The difference between time of transmission and time of validity includes both the time for the acoustic wave to travel from the surface from which it was reflected back to the DVL, and the decoding and processing of this signal internally in the DVL.

Version

This document describes TCP JSON API json_v3.1 (major.minor):

• MAJOR version increments represent incompatible API changes
• MINOR version increments represent additional backwards-compatible functionality

Version history overview

Software release	Ethernet protocol version	Main protocol improvements
2.7.1	json_v4	Hardware trigger capabilities added.
2.6.1	json_v3.1	Serial baud rate configurable. Add PD4 format support in serial 'wcp' command. Some serial protocol names changed.
2.5.2	json_v3.1	Add PD4 format support (experimental)
2.4.4	json_v3.1	Change gyro calibration to store persistently. Note: gyro calibration commands now take up to 15 seconds.
2.4.0	json_v3.1	Add ability to trigger pings (TCP JSON API/serial), add configuration for periodic cycling (TCP JSON API/serial)
2.2.1	json_v3	Add serial output protocol configuration, range mode configuration and calibrate gyro command, Fix missing line ending in configuration (TCP JSON API), fix dark mode enabled naming inconsistency (TCP JSON API), change speed of sound and mounting rotation offset from integer to float
2.1.0	json_v3	Add configuration, add time_of_validity/time_of_transmission, add covariance (TCP JSON API)
2.0.8	json_v2	Add position estimation, Add output of orientation angles
1.6.0	-	Initial (velocity only)

TCP JSON API

Overview

The DVL supports sending velocity, transducer, and position updates using the Transmission Control Protocol (TCP). The DVL runs a TCP server on port 16171.

The format of each packet is JSON.

In our measurements, TCP JSON message latency was typically around 4 ms average, with 2 ms standard deviation and an observed maximum of 13 ms. This is not a hard real-time guarantee; actual latency can depend on network setup, host system, load, and integration method. See Integration.

PD formats over TCP

PD4 and PD6 are also supported over TCP for all DVL models. PD0 is planned for DVL A100 and DVL A250 over TCP and serial, but is not available yet. See PD formats for the canonical PD format descriptions.

Velocity-and-transducer report

A velocity-and-transducer report is sent for each velocity calculation of the DVL. The rate depends on the model, altitude, and configuration. See the model page and Range mode for product-specific operating limits.

The X, Y, and Z axes are with respect to the body frame of the DVL, or the vehicle frame if the DVL is mounted on a vehicle at an angle, specified as a mounting rotation offset, from the forward axis of the vehicle.

The messages are delimited by newline.

Variable	Description
time	Milliseconds since last velocity report (ms)
vx	Velocity in x direction (m/s)
vy	Velocity in y direction (m/s)
vz	Velocity in z direction (m/s)
fom	Figure of merit, a measure of the accuracy of the velocities (m/s)
covariance	Covariance matrix for the velocities. The figure of merit is calculated from this (entries in (m/s)^2)
altitude	Distance to the reflecting surface along the Z axis (m)
transducers	Is a list containing information from each transducer: [id, velocity (m/s), distance (m), rssi (dBm), nsd (dBm), beam_valid (True/False)]
velocity_valid	If true, the DVL has a lock on the reflecting surface, and the altitude and velocities are valid (True/False)
status	8 bit status mask. Bit 0 is set to 1 for high temperature and DVL will soon enter thermal shutdown. Remaining bits are reserved for future use.
time_of_validity	Timestamp of the surface reflection, aka 'center of ping' (Unix timestamp in microseconds)
time_of_transmission	Timestamp from immediately before sending of the report over TCP (Unix timestamp in microseconds)
format	Format type and version for this report: json_v3.1
type	Report type: velocity

Transducer numbering and protocol IDs

Mechanical/transducer diagrams number the transducers from 1 to 4. In protocol messages and diagnostic logs, the transducer id uses zero-based numbering from 0 to 3. The id is therefore the transducer number minus 1.

Example of TCP report (indented for legibility)

{
  "time": 106.3935775756836,
  "vx": -3.713480691658333e-05,
  "vy": 5.703703573090024e-05,
  "vz": 2.4990416932269e-05,
  "fom": 0.00016016385052353144,
  "covariance": [
    [
      2.4471841442164077e-08,
      -3.3937477272871774e-09,
      -1.6659699175747278e-09
    ],
    [
      -3.3937477272871774e-09,
      1.4654466085062268e-08,
      4.0409570134514183e-10
    ],
    [
      -1.6659699175747278e-09,
      4.0409570134514183e-10,
      1.5971971523143225e-09
    ]
  ],
  "altitude": 0.4949815273284912,
  "transducers": [
    {
      "id": 0,
      "velocity": 0.00010825289791682735,
      "distance": 0.5568000078201294,
      "rssi": -30.494251251220703,
      "nsd": -88.73271179199219,
      "beam_valid": true
    },
    {
      "id": 1,
      "velocity": -1.4719001228513662e-05,
      "distance": 0.5663999915122986,
      "rssi": -31.095735549926758,
      "nsd": -89.5116958618164,
      "beam_valid": true
    },
    {
      "id": 2,
      "velocity": 2.7863150535267778e-05,
      "distance": 0.537600040435791,
      "rssi": -27.180519104003906,
      "nsd": -96.98075103759766,
      "beam_valid": true
    },
    {
      "id": 3,
      "velocity": 1.9419496311456896e-05,
      "distance": 0.5472000241279602,
      "rssi": -28.006759643554688,
      "nsd": -88.32147216796875,
      "beam_valid": true
    }
  ],
  "velocity_valid": true,
  "status": 0,
  "format": "json_v3.1",
  "type": "velocity",
  "time_of_validity": 1638191471563017,
  "time_of_transmission": 1638191471752336
}

Dead reckoning report

A dead reckoning report outputs the current speed, position, and orientation of the DVL as calculated by dead reckoning, with respect to a frame defined by the axes of the DVL's body frame, or vehicle frame if a mounting rotation offset is set, at the start of the dead reckoning run. The expected update rate is 5 Hz.

Variable	Description
ts	Time stamp of report (Unix timestamp in seconds)
x	Distance in X direction (m)
y	Distance in Y direction (m)
z	Distance in downward direction (m)
std	Standard deviation (figure of merit) for position (m)
roll	Rotation around X axis (degrees)
pitch	Rotation around Y axis (degrees)
yaw	Rotation around Z axis, i.e. heading (degrees)
type	Report type: position_local
status	Reports if there are any issues with the DVL (0 if no errors, 1 otherwise)
format	Format type and version for this report: json_v3

Example of a dead reckoning report.

{
  "ts": 49056.809,
  "x": 12.43563613697886467,
  "y": 64.617631152402609587,
  "z": 1.767641898933798075,
  "std": 0.001959984190762043,
  "roll": 0.6173566579818726,
  "pitch": 0.6173566579818726,
  "yaw": 0.6173566579818726,
  "type": "position_local",
  "status": 0,
  "format": "json_v3.1"
}

Reset dead reckoning

Dead reckoning can be reset by issuing the reset_dead_reckoning command:

{"command": "reset_dead_reckoning"}

If the request is successfully received the response will have 'success' set to 'true'. The dead reckoning will have a delay of approximately 50ms until the positioning values being zeroed out. If the response is unsuccessful, the 'success' will be 'false' and a non-empty describing text will be returned in 'error_message'.

{
  "response_to":"reset_dead_reckoning",
  "success": true,
  "error_message": "",
  "result": null,
  "format": "json_v3.1",
  "type": "response"
}

Calibrate gyro

Gyro calibration is not needed as a normal setup step for DVL A100/A250.

The gyro can be calibrated by issuing the calibrate_gyro command:

{"command":"calibrate_gyro"}

The response will be as follows if the calibration is successful. If unsuccessful, success will be false, and a non-empty error_message will be provided.

{
  "response_to": "calibrate_gyro",
  "success": true,
  "error_message": "",
  "result": null,
  "format": "json_v3.1",
  "type": "response"
}

Trigger ping

In setups where multiple acoustic sensors are used it can be useful to control the pinging of each acoustic sensor individually. By setting the configuration acoustic_enabled = false the pinging of the DVL can be externally controlled. Up to 15 external trigger commands can be queued by issuing the trigger_ping command. The DVL will execute each ping in quick succession until no more commands are in the queue.

See Integration for guidance on using triggering with other acoustic instruments.

{"command":"trigger_ping"}

The response will be as follows if the command is accepted. If the queue is full, success will be false, and a non-empty error_message will be provided.

{
  "response_to": "trigger_ping",
  "success": true,
  "error_message": "",
  "result": null,
  "format": "json_v3.1",
  "type": "response"
}

Configuration over TCP JSON API

Configuration parameters

Variable	Description
speed_of_sound	Speed of sound (1000-2000 m/s). Integer
mounting_rotation_offset	See the definition of the vehicle frame of the DVL. Typically 0, but can be set to be non-zero if the forward axis of the DVL is not aligned with the forward axis of a vehicle on which it is mounted (0-360 degrees). Integer
acoustic_enabled	true for normal operation of the DVL,false when the sending of acoustic waves from the DVL is disabled (e.g. to save power or slow down its heating up in air)
dark_mode_enabled	false when the LED operates as normal, true for no blinking of the LED (e.g. if the LED is interfering with a camera)
range_mode	auto when operating as normal, otherwise see range mode configuration
periodic_cycling_enabled	true to enable periodic cycling, false to disable it
hardware_trigger_enabled	true to enable hardware triggering, false to disable

Fetching current configuration

The current configuration of the DVL can be obtained by issuing the get_config command:

{"command": "get_config"}

If the configuration is successfully fetched, the response will be in the following format. If not, success will be false, a non-empty error_message string will be provided, and result will be null.

{
  "response_to":"get_config",
  "success":true,
  "error_message":"",
  "result":{
    "speed_of_sound":1475.00,
    "acoustic_enabled":true,
    "dark_mode_enabled":false,
    "mounting_rotation_offset":20.00,
    "range_mode":"auto",
    "periodic_cycling_enabled":true
  },
  "format":"json_v3.1",
  "type":"response"
}

Setting configuration parameters

Setting of configuration parameters can be carried out by issuing a set_config in the following format, including those parameters which are to be set:

{"command":"set_config","parameters":{"speed_of_sound":1480}}

If the parameters are successfully set, the response will be in the following format. If not, success will be false, and a non-empty error_message string will be provided.

{
  "response_to": "set_config",
  "success": true,
  "error_message": "",
  "result" :null,
  "format": "json_v3.1",
  "type": "response"
}