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:
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:
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:
Water tracking is enabled by setting range_mode to 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.
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:
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:
Example of setting water tracking:
Water tracking is enabled by setting range_mode to wt:
Example for setting speed of sound to 1450 m/s and disabling acoustics, without changing the other parameters:
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:
- Python 3: crcmod
crcmod.predefined.mkPredefinedCrcFun("crc-8") - Golang: github.com/sigurn/crc8
crc8.MakeTable(crc8.CRC8)
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.