Skip to content

DVL A100/A250 serial protocol๐Ÿ”—

Describes the Water Linked DVL serial protocol for DVL A100 and DVL A250. For PD0, PD4, and PD6 output formats, see PD formats.

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 serial protocol version 3.1.x (major.minor.patch):

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

Version history overview๐Ÿ”—

Software release Serial protocol version Main protocol improvements
3.3.0 3.1.0 Add serial time API. Add water tracking mode. Remove deprecated protocol "WL - Serial V1 and V2".
3.2.0 3.0.0 Initial public release.

Serial protocol๐Ÿ”—

Overview๐Ÿ”—

The default serial communication format is 115200 8-N-1 (no hardware flow control). Different baud rates can be configured through the web GUI.

DVL A100 and DVL A250 use RS232. See DVL A100/A250 serial interface.

Serial output is disabled by default

DVL A100 and DVL A250 do not send velocity, transducer, or dead reckoning reports over serial until the serial output is enabled. Enable it in the web GUI or with the wcp command over serial. It cannot be enabled over the TCP JSON API. Serial commands and their replies work regardless of this setting, so wcp can be sent from the serial port itself.

Packets sent to and received from the DVL start with a w and end with LF or CR+LF. The packet format is:

Start byte Direction Command Options (0 to many) Checksum End byte
w c or r x ,[option] *xx \n or \r\n

Direction is c (short for 'command') for packets sent to the DVL, and r (short for 'response') for packets sent from the DVL. The DVL always replies with CR+LF as the line ending. The commands can be sent from a terminal program that supports sending a full line at a time. The timeout between characters is approximately 10 ms.

Note

Please verify the baud rate configuration in the web GUI if you are unable to communicate with the default baud rate.

Note

The checksum is optional when sending commands to the DVL. The DVL always returns a checksum. The checksum algorithm is CRC-8 and it is formatted as a hexadecimal number using 2 lower-case characters (ex: *c3). See below for details.

Command overview๐Ÿ”—

The commands in the table are shown without the checksum and without the mandatory line ending (\n or \r\n) for readability. In all cases, the response to a submitted command may be wrn, wr?, or wr! (see below for details), but only the format of a successful response is listed.

Command Description Response Description
wcv Get protocol version wrv,[major],[minor],[patch] Protocol version. eg: wrv,3.1.0
wcw Get product detail wrw,[name],[version],[chipID],[IP address] Where type is dvl, name is product name, version is software version, chip ID is the chip ID and optionally the IP address if connected to DHCP server: eg: wrw,dvl-a250,3.4.0,0xfedcba98765432 or wrw,dvl-a250,3.4.0,0xfedcba98765432,10.11.12.140
wcs,[configuration parameters] Set configuration parameters wra Successfully set the specified configuration parameters. See Configuration for details
wcc Get current configuration wrc,[configuration parameters] Entire current configuration. See Configuration for details
wcr Reset dead reckoning wra Successfully started a new dead reckoning run
wcx Trigger ping wra Successfully queued a ping
wcg Calibrate gyro wra Successfully calibrated gyro
wcp Change serial output protocol wra Successfully changed output protocol
wcn,[ntp_address] Set NTP server configuration. ntp_address is an address, or "auto" wra Successfully set NTP server
wcN Get NTP address configuration wrN,[ntp_address] Configured NTP server address, or "auto"
wcm,[timestamp] Set manual time, where timestamp is UTC epoch time in microseconds wra Successfully set manual time
wct Get time status wrs,[details below] Time status
wcT,[timeout_seconds] Force NTP sync within given timeout wrT,[success] Where success is y if sync was achieved within timeout, and n otherwise
wrz,[details below] Velocities calculated
wrs,[details below] Velocities calculated during water tracking
wru,[details below] Transducer information
wrp,[details below] Dead reckoning report
wr? Malformed request: packet cannot be understood or no newline received before timeout
wr! Malformed request: packet does not match the given checksum
wrn Not acknowledged (nack): an error occurred when handling the packet

wrs is used for two different reports

The wrs prefix is used for both the time status response and the water tracking velocity report. You must inspect the fields after the prefix to tell them apart: a water tracking velocity report begins with a decimal velocity (e.g. wrs,0.120,...), while a time status report begins with an integer epoch timestamp (e.g. wrs,1776409079,...).

Time status (wrs)๐Ÿ”—

Time status is returned by the command wct.

The report has the following format: wrs,[system_time],[ntp_synced],[ntp_synced_to],[ntp_seconds_since_last_sync]

Variable Description
system_time UTC epoch time in microseconds
ntp_synced y if synchronized, n if not
ntp_synced_to NTP server address the DVL is synced to
ntp_seconds_since_last_sync Seconds since last sync if synced

Examples:

wrs,1776409079,n,,
wrs,1776409079,y,192.168.0.10,45

Velocity report (wrz)๐Ÿ”—

A velocity report is output 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 report has the following format: wrz,[vx],[vy],[vz],[valid],[altitude],[fom],[covariance],[time_of_validity],[time_of_transmission],[time],[status]

Variable Description
vx Velocity in x direction (m/s)
vy Velocity in y direction (m/s)
vz Velocity in z direction (m/s)
valid If y, the DVL has a lock on the reflecting surface, and the altitude and velocities are valid (y/n)
altitude Measured altitude to the bottom (m)
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. 9 entries ((m/s)^2) separated by ;
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)
time Milliseconds since last velocity report (ms)
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.

Example where all velocities are valid:

wrz,0.120,-0.400,2.000,y,1.30,1.855,1e-07;0;1.4;0;1.2;0;0.2;0;1e+09,7,14,123.00,1*50

Velocity report (wrs)๐Ÿ”—

A velocity report is output for each velocity calculation of the DVL in this format when water tracking is activated. The update rate will be 2 Hz.

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 report has the following format: wrs,[vx],[vy],[vz],[valid],[fom],[covariance],[time_of_validity],[time_of_transmission],[time],[status]

Variable Description
vx Velocity in x direction (m/s)
vy Velocity in y direction (m/s)
vz Velocity in z direction (m/s)
valid If y, the DVL has a lock on the reflecting surface, and the velocities are valid (y/n)
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. 9 entries ((m/s)^2) separated by ;
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)
time Milliseconds since last velocity report (ms)
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.

Example where all velocities are valid:

wrs,0.120,-0.400,2.000,y,1.855,1e-07;0;1.4;0;1.2;0;0.2;0;1e+09,7,14,123.00,1*7b

Water tracking is enabled by setting range_mode to wt:

wcs,,,,,wt,,

Transducer report (wru)๐Ÿ”—

A transducer report is output for each of the four transducers of the DVL for each velocity calculation of the DVL. The rate will be the same as that of the velocity report. If the transducer did not receive a signal that could be successfully decoded, distance will be set to -1, and velocity will be set to 0. RSSI and NSD will be output in all cases.

The report has the following format: wru,[id],[velocity],[distance],[rssi],[nsd]

Variable Description
id Zero-based transducer id, from 0 to 3
velocity Velocity in the direction of the transducer (m/s)
distance Distance (parallel to the transducer beam, i.e. not the vertical distance) to the reflecting surface from this transducer (m)
rssi Received signal strength indicator: strength of the signal received by this transducer (dBm)
nsd Noise spectral density: strength of the background noise received by this transducer (dBm)

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 where all data is valid:

wru,0,0.070,1.10,-40,-95*9c
wru,1,-0.500,1.25,-62,-104*f0
wru,2,2.200,1.40,-56,-98*18
wru,3,1.800,1.35,-58,-96*a3

Dead reckoning report (wrp)๐Ÿ”—

Note

The wrp report is not sent by the DVL versions without dead reckoning, such as the DVL A100 and DVL A250 4,000 m versions.

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.

The format is: wrp,[time_stamp],[x],[y],[z],[pos_std],[roll],[pitch],[yaw],[status]

Variable Description
time_stamp 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)
pos_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)
status Reports if there are any issues with the DVL (0 if no errors, 1 otherwise)

Example:

wrp,49056.809,0.41,0.15,1.23,0.4,53.9,13.0,19.3,0*de
wrp,49057.269,0.39,0.18,1.23,0.4,53.9,13.0,19.3,0*e2

Reset dead reckoning (wcr)๐Ÿ”—

Dead reckoning can be reset by issuing the wcr command. The reply will be an ack (wra) if the reset is successful, and a nak (wrn) if not.

Calibrate gyro (wcg)๐Ÿ”—

Gyro calibration is not available yet on DVL A100/A250 and will be added in a future software release. The command is already accepted, but it currently has no effect on dead reckoning.

The wcg command is still accepted. The reply will be an ack (wra) if the calibration is successful, and a nak (wrn) if not.

Trigger ping (wcx)๐Ÿ”—

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 = n the pinging of the DVL can be externally controlled. Up to 15 external trigger commands can be queued by issuing the wcx 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.

For DVL A100 and DVL A250 hardware triggering, sending a NUL character at 115200 baud over the RS232 RX line triggers a ping. The DVL recognizes the 78.1 ยตs ยฑ 4.3 ยตs positive pulse on the wire and triggers the ping when the pulse ends. Hardware triggering must be enabled with hardware_trigger_enabled first, otherwise the pulses are ignored. See Hardware triggering for the pulse timing and a drawing.

The reply will be an ack (wra) if the command is successful, and a nak (wrn) if queue is full.

Change serial output protocol (wcp)๐Ÿ”—

The serial output protocol in use can be configured by issuing the wcp command. The selected protocol is persistent over reboots.

wcp,[protocol number]

The supported protocols are:

Protocol number Name Description
0 Output disabled No output on serial. Recommended if serial port is not used to lower latency on Ethernet protocols.
1 Not used Not used
2 PD6 PD6 format output. See PD6 format description
3 WL - Serial V2 All Water Linked serial output, including velocity, transducer, and dead reckoning reports.
4 Not used Not used
5 Not used Not used
6 PD4 PD4 format output. See PD4 format description

The reply will be an ack (wra) if the protocol change is successful, and a nak (wrn) if not.

Example setting configuring output to use protocol number 3:

wcp,3

The serial output is disabled (protocol number 0) by default on DVL A100 and DVL A250. The same setting is available in the web GUI, but not over the TCP JSON API.

Protocol number 0 only stops the stream of reports from the DVL. The DVL still receives serial commands and replies to them, and hardware triggering over the RS232 RX line still works.

Configuration over serial๐Ÿ”—

Configuration parameters๐Ÿ”—

Variable Description
speed_of_sound Speed of sound (1000-2000 m/s). Float
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). Float
acoustic_enabled y for normal operation of the DVL,n 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 n when the LED operates as normal. y for no blinking of LED (e.g. if the LED is interfering with a camera)
range_mode auto when operating as normal, otherwise see range mode configuration or activate water tracking
periodic_cycling_enabled y to enable periodic cycling, n to disable it. See Configuration over TCP JSON API for details
hardware_trigger_enabled y to enable hardware triggering, n to disable

Note

For backward compatibility the range_mode and periodic_cycling_enabled parameters are optional when setting the configuration. They will always be returned when reading the configuration (wcc).

Fetching current configuration๐Ÿ”—

The current configuration of the DVL can be obtained by issuing the wcc command.

If the configuration is successfully fetched, the response will be in the following format. If not, a nak wrn will be returned.

wrc,[speed_of_sound],[mounting_rotation_offset],[acoustic_enabled],[dark_mode_enabled],[range_mode],[periodic_cycling_enabled],[hardware_trigger_enabled]

Setting configuration parameters๐Ÿ”—

Setting of configuration parameters can be carried out by issuing the wcs command in the following format.

wcs,[speed_of_sound],[mounting_rotation_offset],[acoustic_enabled],[dark_mode_enabled],[range_mode],[periodic_cycling_enabled],[hardware_trigger_enabled]

Those parameters which are not to be set can be left blank.

Example for setting dark mode without changing the other parameters:

wcs,,,,y,,,

Example of setting water tracking:

Water tracking is enabled by setting range_mode to wt:

wcs,,,,,wt,,

Example for setting speed of sound to 1450 m/s and disabling acoustics, without changing the other parameters:

wcs,1450,,n,,,,

The response will be an ack wra if the parameters are successfully set, a nak wrn if the command was successfully parsed but the parameters were not successfully set, and a malformed request wr? if the command was not successfully parsed, e.g. if the wrong number of parameters was used, or either speed_of_sound or mounting_rotation_offset was not a float.

The new configuration will not be returned in the response, but can be obtained by issuing a wcc command as above.

Checksum๐Ÿ”—

The checksum algorithm is CRC-8 (Polynomal: 0x07, Init: 0x00, RefIn/RefOut: false, XorOut: 0x00, Check: 0xf4). Checksum is formatted as a hexadecimal number using 2 lower-case characters (ex: *c3).

Compatible implementations:

Example for how to verify checksum using Python 3 and crcmod:

crc = crcmod.predefined.mkPredefinedCrcFun("crc-8")
sentence = b"wrz,0.120,-0.400,2.000,y,1.30,1.855,1e-07;0;1.4;0;1.2;0;0.2;0;1e+09,7,14,123.00,1*50"
data, checksum = sentence.split(b"*")

if crc(data) == int(checksum, 16):
    print("CRC valid")
else:
    print("CRC invalid")

The crcmod python package can generate code in other languages. Here is an example (subject to the MIT License) for C which should be straightforward to adapt to other languages.

static const uint8_t lookup_table[256] = {
    0x00U,0x07U,0x0EU,0x09U,0x1CU,0x1BU,0x12U,0x15U,
    0x38U,0x3FU,0x36U,0x31U,0x24U,0x23U,0x2AU,0x2DU,
    0x70U,0x77U,0x7EU,0x79U,0x6CU,0x6BU,0x62U,0x65U,
    0x48U,0x4FU,0x46U,0x41U,0x54U,0x53U,0x5AU,0x5DU,
    0xE0U,0xE7U,0xEEU,0xE9U,0xFCU,0xFBU,0xF2U,0xF5U,
    0xD8U,0xDFU,0xD6U,0xD1U,0xC4U,0xC3U,0xCAU,0xCDU,
    0x90U,0x97U,0x9EU,0x99U,0x8CU,0x8BU,0x82U,0x85U,
    0xA8U,0xAFU,0xA6U,0xA1U,0xB4U,0xB3U,0xBAU,0xBDU,
    0xC7U,0xC0U,0xC9U,0xCEU,0xDBU,0xDCU,0xD5U,0xD2U,
    0xFFU,0xF8U,0xF1U,0xF6U,0xE3U,0xE4U,0xEDU,0xEAU,
    0xB7U,0xB0U,0xB9U,0xBEU,0xABU,0xACU,0xA5U,0xA2U,
    0x8FU,0x88U,0x81U,0x86U,0x93U,0x94U,0x9DU,0x9AU,
    0x27U,0x20U,0x29U,0x2EU,0x3BU,0x3CU,0x35U,0x32U,
    0x1FU,0x18U,0x11U,0x16U,0x03U,0x04U,0x0DU,0x0AU,
    0x57U,0x50U,0x59U,0x5EU,0x4BU,0x4CU,0x45U,0x42U,
    0x6FU,0x68U,0x61U,0x66U,0x73U,0x74U,0x7DU,0x7AU,
    0x89U,0x8EU,0x87U,0x80U,0x95U,0x92U,0x9BU,0x9CU,
    0xB1U,0xB6U,0xBFU,0xB8U,0xADU,0xAAU,0xA3U,0xA4U,
    0xF9U,0xFEU,0xF7U,0xF0U,0xE5U,0xE2U,0xEBU,0xECU,
    0xC1U,0xC6U,0xCFU,0xC8U,0xDDU,0xDAU,0xD3U,0xD4U,
    0x69U,0x6EU,0x67U,0x60U,0x75U,0x72U,0x7BU,0x7CU,
    0x51U,0x56U,0x5FU,0x58U,0x4DU,0x4AU,0x43U,0x44U,
    0x19U,0x1EU,0x17U,0x10U,0x05U,0x02U,0x0BU,0x0CU,
    0x21U,0x26U,0x2FU,0x28U,0x3DU,0x3AU,0x33U,0x34U,
    0x4EU,0x49U,0x40U,0x47U,0x52U,0x55U,0x5CU,0x5BU,
    0x76U,0x71U,0x78U,0x7FU,0x6AU,0x6DU,0x64U,0x63U,
    0x3EU,0x39U,0x30U,0x37U,0x22U,0x25U,0x2CU,0x2BU,
    0x06U,0x01U,0x08U,0x0FU,0x1AU,0x1DU,0x14U,0x13U,
    0xAEU,0xA9U,0xA0U,0xA7U,0xB2U,0xB5U,0xBCU,0xBBU,
    0x96U,0x91U,0x98U,0x9FU,0x8AU,0x8DU,0x84U,0x83U,
    0xDEU,0xD9U,0xD0U,0xD7U,0xC2U,0xC5U,0xCCU,0xCBU,
    0xE6U,0xE1U,0xE8U,0xEFU,0xFAU,0xFDU,0xF4U,0xF3U,
};

uint8_t crc8(uint8_t *message, int message_length) {
    uint8_t checksum = 0;
    while (message_length > 0) {
        checksum = lookup_table[*message ^ checksum];
        message++;
        message_length--;
    }
    return checksum;
}

PD0 format๐Ÿ”—

PD0 is planned for DVL A100 and DVL A250. It is not available yet.

When ready, PD0 is planned for both TCP and serial output.

See PD formats.

PD6 format (TCP/Serial)๐Ÿ”—

PD6 is supported over serial and TCP for all DVL models.

See the canonical PD6 format description.

PD4 format (TCP/Serial)๐Ÿ”—

PD4 is supported over serial and TCP for all DVL models.

See the canonical PD4 format description.