Definition of and code generation utilities for Ping Protocol, a binary message format for sonar devices.
Branch: master
Clone or download
jaxxzer pingmessage.py: bugfix payload_length during unpack
payload_length only needs to be updated before packing buffer
Latest commit 4571187 Feb 6, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example example: Simplify code to test in CI May 17, 2018
src/protocol pingmessage.py: bugfix payload_length during unpack Feb 7, 2019
test generate-json.py: Update for new structure Nov 12, 2018
tools
.appveyor.yml appveyor: Use new Qt 5.11 Aug 16, 2018
.gitignore
.travis.yml
README.md
ping.pri remove link files from submodule Sep 11, 2018

README.md

Ping Protocol

Travis Build Status Build status Last Releases Discuss

Table of Contents

Format

Byte Type Name Description
0 u8 start1 'B'
1 u8 start2 'R'
2-3 u16 payload_length Number of bytes in payload.
4-5 u16 message_id The message id.
6 u8 src_device_id The device ID of the device sending the message.
7 u8 dst_device_id The device ID of the intended recipient of the message.
8-n u8[] payload The message payload.
(n+1)-(n+2) u16 checksum The message checksum. The checksum is calculated as the sum of all the non-checksum bytes in the message.

ping1D Messages

general

0 undefined

No payload.

1 ack

Acknowledged.

Type Name Description Units
u16 acked_id The message ID that is ACKnowledged.

2 nack

Not acknowledged.

Type Name Description Units
u16 nacked_id The message ID that is Not ACKnowledged.
char[] nack_message ASCII text message indicating NACK condition. Length is derived from payload_length in the header.

3 ascii_text

A message for transmitting text data.

Type Name Description Units
char[] ascii_message NULL terminated ASCII text message. Length is derived from payload_length in the header.

set

1000 set_device_id

Set the device ID.

Type Name Description Units
u8 device_id Device ID (0-254). 255 is reserved for broadcast messages.

1001 set_range

Set the scan range for acoustic measurements.

Type Name Description Units
u32 scan_start mm
u32 scan_length The length of the scan range. mm

1002 set_speed_of_sound

Set the speed of sound used for distance calculations.

Type Name Description Units
u32 speed_of_sound The speed of sound in the measurement medium. ~1,500,000 mm/s for water. mm/s

1003 set_mode_auto

Set automatic or manual mode. Manual mode allows for manual selection of the gain and scan range.

Type Name Description Units
u8 mode_auto 0: manual mode. 1: auto mode.

1004 set_ping_interval

The interval between acoustic measurements.

Type Name Description Units
u16 ping_interval The interval between acoustic measurements. ms

1005 set_gain_index

Set the current gain setting.

Type Name Description Units
u8 gain_index The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144

1006 set_ping_enable

Enable or disable acoustic measurements.

Type Name Description Units
u8 ping_enabled 0: Disable, 1: Enable.

get

1200 firmware_version

Device information

Type Name Description Units
u8 device_type Device type. 0: Unknown; 1: Echosounder
u8 device_model Device model. 0: Unknown; 1: Ping1D
u16 firmware_version_major Firmware version major number.
u16 firmware_version_minor Firmware version minor number.

1201 device_id

The device ID.

Type Name Description Units
u8 device_id The device ID (0-254). 255 is reserved for broadcast messages.

1202 voltage_5

The 5V rail voltage.

Type Name Description Units
u16 voltage_5 The 5V rail voltage. mV

1203 speed_of_sound

The speed of sound used for distance calculations.

Type Name Description Units
u32 speed_of_sound The speed of sound in the measurement medium. ~1,500,000 mm/s for water. mm/s

1204 range

The scan range for acoustic measurements. Measurements returned by the device will lie in the range (scan_start, scan_start + scan_length).

Type Name Description Units
u32 scan_start The beginning of the scan range in mm from the transducer. mm
u32 scan_length The length of the scan range. mm

1205 mode_auto

The current operating mode of the device. Manual mode allows for manual selection of the gain and scan range.

Type Name Description Units
u8 mode_auto 0: manual mode, 1: auto mode

1206 ping_interval

The interval between acoustic measurements.

Type Name Description Units
u16 ping_interval The minimum interval between acoustic measurements. The actual interval may be longer. ms

1207 gain_index

The current gain setting.

Type Name Description Units
u32 gain_index The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144

1208 pulse_duration

The duration of the acoustic activation/transmission.

Type Name Description Units
u16 pulse_duration Acoustic pulse duration. microseconds

1210 general_info

General information.

Type Name Description Units
u16 firmware_version_major Firmware major version.
u16 firmware_version_minor Firmware minor version.
u16 voltage_5 Device supply voltage. mV
u16 ping_interval The interval between acoustic measurements. ms
u8 gain_index The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144
u8 mode_auto The current operating mode of the device. 0: manual mode, 1: auto mode

1211 distance_simple

The distance to target with confidence estimate.

Type Name Description Units
u32 distance Distance to the target. mm
u8 confidence Confidence in the distance measurement. %

1212 distance

The distance to target with confidence estimate. Relevant device parameters during the measurement are also provided.

Type Name Description Units
u32 distance The current return distance determined for the most recent acoustic measurement. mm
u16 confidence Confidence in the most recent range measurement. %
u16 pulse_duration The acoustic pulse length during acoustic transmission/activation. us
u32 ping_number The pulse/measurement count since boot.
u32 scan_start The beginning of the scan region in mm from the transducer. mm
u32 scan_length The length of the scan region. mm
u32 gain_index The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144

1213 processor_temperature

Temperature of the device cpu.

Type Name Description Units
u16 processor_temperature The temperature in centi-degrees Centigrade (100 * degrees C). cC

1214 pcb_temperature

Temperature of the on-board thermistor.

Type Name Description Units
u16 pcb_temperature The temperature in centi-degrees Centigrade (100 * degrees C). cC

1215 ping_enable

Acoustic output enabled state.

Type Name Description Units
u8 ping_enabled The state of the acoustic output. 0: disabled, 1:enabled

1300 profile

A profile produced from a single acoustic measurement. The data returned is an array of response strength at even intervals across the scan region. The scan region is defined as the region between <scan_start> and <scan_start + scan_length> millimeters away from the transducer. A distance measurement to the target is also provided.

Type Name Description Units
u32 distance The current return distance determined for the most recent acoustic measurement. mm
u16 confidence Confidence in the most recent range measurement. %
u16 pulse_duration The acoustic pulse length during acoustic transmission/activation. us
u32 ping_number The pulse/measurement count since boot.
u32 scan_start The beginning of the scan region in mm from the transducer. mm
u32 scan_length The length of the scan region. mm
u32 gain_index The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144
u16 profile_data_length The length of the proceeding vector field
u8[] profile_data An array of return strength measurements taken at regular intervals across the scan region.

5 protocol_version

The protocol version

Type Name Description Units
u32 protocol_version The protocol version

control

1100 goto_bootloader

Send the device into the bootloader. This is useful for firmware updates.

No payload.

1400 continuous_start

Command to initiate continuous data stream of profile messages.

Type Name Description Units
u16 id The message id to stream. 1300: profile

1401 continuous_stop

Command to stop the continuous data stream of profile messages.

Type Name Description Units
u16 id The message id to stop streaming. 1300: profile