The protocol is designed for synchronous communications in a master->slave network. The slave will only send data when requested by the master. This allows the protocol to be used on a half-duplex bus like RS485. Some devices may also provide facilities to allow asynchronous communication.
+Each message consists of a header, optional payload, and checksum. The binary format is specified as follows:
+| Byte | +Type | +Name | +Description | +
|---|---|---|---|
| 0 | +u8 | +start1 | +Start frame identifier, ASCII 'B' | +
| 1 | +u8 | +start2 | +Start frame identifier, ASCII '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. | +
Messages are divided into 4 categories:
+general_request from the host. These messages are designed to read data from the device.There are a some messages that are implemented by all devices, referred to as the 'common' message set. Message ids # 0~999 are reserved for the common messages. The request message is a special message in the common set that is used to request the device to respond with a message from the get category. Each device must also define it's own message set specific to the operation of the particular device.
+If necessary, Ping Protocol enabled devices may be discovered and identified by the host as follows:
+Here we demonstrate a byte-by-byte breakdown of some messages sent between the host application (master) and the device (slave). This example illustrates a few points:
+ - how to pack and unpack some message data (the byte-order of a message)
+ - how the request/response mechanism of the protcol works with the general_request message
+ - how to identify the protocol version that the device is using
Establishing communication with a sensor using the ping-protocol should begin with negotiating the protocol version. This negotiation process consists of two steps:
+ - the host application requests a protocol_version message from the device
+ - the device responds with a protocol_version message
++Before reading these examples, you should be familiar with the message format specification.
+
In order to receive a protocol_version message from the device, we will first send a general_request message to the device to ask for the message. The general_request message has a single payload field, requested_id. We populate this field with a value of 5 to indicate that we want the sensor to respond with a protocol_version message:
| Byte | +Value (hex) | +Value (decimal) | +Type | +Name | +Description | +
|---|---|---|---|---|---|
| 0 | +0x42 ('B') | +66 | +u8 | +start1 | +This is a message start identifier, an ascii letter 'B' | +
| 1 | +0x52 ('R') | +82 | +u8 | +start2 | +This is a message start identifier, an ascii letter 'R' | +
| 2-3 | +0x0002 | +2 | +u16 | +payload_length | +The number of bytes in the general_request payload |
+
| 4-5 | +0x0006 | +6 | +u16 | +message_id | +This message is a general_request (id pingmessage-common#6) message |
+
| 6 | +0x00 | +0 | +u8 | +src_device_id | +The device ID of the device sending the message. This field is not currently implemented and should be populated with a value of zero | +
| 7 | +0x00 | +0 | +u8 | +dst_device_id | +The device ID of the intended recipient of the message. This portion is not currently implemented and should be populated with a value of zero | +
| 8-9 | +0x0005 | +5 | +u16 | +requested_id | +This is the message id that we would like the device to transmit to us. Valid ids are those in the get category of messages |
+
| 10-11 | +0x00a1 | +161 | +u16 | +checksum | +The message checksum. The checksum is calculated as the sum of all the non-checksum bytes in the message: 66 + 82 + 2 + 6 + 0 + 0 + 5 = 161 |
+
The bytes should be transmitted in this order:
+0x42, 0x52, 0x02, 0x00, 0x06, 0x00, 0x00, 0x00, 0x05, 0x00, 0xa1, 0x00
++Note that the messages are transmitted in little-endian format (observe the byte-order of the 16 bit fields)
+
If everything is right, the sensor will respond to our request with a protocol_version message. The protocol_version message has 4 bytes in the payload: version_major, version_minor, version_patch, and reserved.
In this example, the device is using (a hypothetical) protocol version 1.2.3: + - version_major = 1 + - version_minor = 2 + - version_patch = 3
+| Byte | +Value (hex) | +Value (decimal) | +Type | +Name | +Description | +
|---|---|---|---|---|---|
| 0 | +0x42 ('B') | +66 | +u8 | +start1 | +This is a message start identifier, an ascii letter 'B' | +
| 1 | +0x52 ('R') | +82 | +u8 | +start2 | +This is a message start identifier, an ascii letter 'R' | +
| 2-3 | +0x0004 | +4 | +u16 | +payload_length | +The number of bytes in the protocol_version payload |
+
| 4-5 | +0x0005 | +5 | +u16 | +message_id | +This message is a protocol_version (id #5) message |
+
| 6 | +0x00 | +0 | +u8 | +src_device_id | +The device ID of the device sending the message. This field is not currently implemented and should be populated with a value of zero | +
| 7 | +0x00 | +0 | +u8 | +dst_device_id | +The device ID of the intended recipient of the message. This field is not currently implemented and should be populated with a value of zero | +
| 8 | +0x01 | +1 | +u8 | +version_major | +This is the protocol major version, the first digit in our example: v1.2.3 | +
| 9 | +0x02 | +2 | +u8 | +version_minor | +This is the protocol minor version, the second digit in our example: v1.2.3 | +
| 10 | +0x03 | +3 | +u8 | +version_patch | +This is the protocol patch version, the third digit in our example: v1.2.3 | +
| 11 | +0x00 | +0 | +u8 | +reserved | +This byte is unused and will normally be zero (but it might be any value) | +
| 12-13 | +0x00a3 | +163 | +u16 | +checksum | +The message checksum. The checksum is calculated as the sum of all the non-checksum bytes in the message: 66 + 82 + 4 + 5 + 0 + 0 + 1 + 2 + 3 + 0 = 163 |
+
The bytes will be received in this order:
+0x42, 0x52, 0x04, 0x00, 0x05, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x00, 0xa3, 0x00
++ + + + + + +Note that the messages are transmitted in little-endian format (observe the byte-order of the 16 bit fields)
+
Acknowledged.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +acked_id | +The message ID that is ACKnowledged. | ++ |
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. (not necessarily NULL terminated) Length is derived from payload_length in the header. | ++ |
A message for transmitting text data.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| char[] | +ascii_message | +ASCII text message. (not necessarily NULL terminated) Length is derived from payload_length in the header. | ++ |
Requests a specific message to be sent from the sonar to the host. Command timeout should be set to 50 msec.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +requested_id | +Message ID to be requested. | ++ |
Device information
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +device_type | +Device type. 0: Unknown; 1: Ping Echosounder; 2: Ping360 | ++ |
| u8 | +device_revision | +device-specific hardware revision | ++ |
| u8 | +firmware_version_major | +Firmware version major number. | ++ |
| u8 | +firmware_version_minor | +Firmware version minor number. | ++ |
| u8 | +firmware_version_patch | +Firmware version patch number. | ++ |
| u8 | +reserved | +reserved | ++ |
The protocol version
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +version_major | +Protocol version major number. | ++ |
| u8 | +version_minor | +Protocol version minor number. | ++ |
| u8 | +version_patch | +Protocol version patch number. | ++ |
| u8 | +reserved | +reserved | ++ |
Set the device ID.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +device_id | +Device ID (1-254). 0 is unknown and 255 is reserved for broadcast messages. | ++ |
Set the speed of sound.
+| 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 | +
| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u32 | +start_mm | ++ | + |
| u32 | +length_mm | ++ | + |
| u32 | +msec_per_ping | ++ | + |
| float | +reserved | ++ | + |
| float | +reserved | ++ | + |
| float | +pulse_len_percent | ++ | + |
| float | +filter_duration_percent | ++ | + |
| i16 | +gain_index | ++ | + |
| u16 | +num_results | ++ | + |
| u8 | +enable | ++ | + |
| u8 | +reserved | ++ | + |
A profile produced from a single acoustic measurement. The data returned is an array of response strength, in dB, at even intervals across the scan region. The scan region is defined as the region between
| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u32 | +ping_number | +sequentially assigned from 0 at power up | ++ |
| u32 | +start_mm | +The beginning of the scan region in mm from the transducer. | +mm | +
| u32 | +length_mm | +The length of the scan region. | +mm | +
| u32 | +timestamp_ms | +msec since power up at time of ping | +ms | +
| u32 | +ping_hz | +Frequency of acoustic signal | +hz | +
| u16 | +gain_index | +0-7 | ++ |
| u16 | +num_results | +length of pwr_results array | ++ |
| u16 | +sos_dmps | +speed of sound, decimeters/sec | ++ |
| u8 | +channel_number | ++ | + |
| u8 | +reserved | ++ | + |
| float | +pulse_duration_sec | ++ | + |
| float | +analog_gain | ++ | + |
| float | +max_pwr_db | ++ | + |
| float | +min_pwr_db | ++ | + |
| float | +transducer_heading_deg | ++ | + |
| float | +vehicle_heading_deg | ++ | + |
| u16[] | +pwr_results | +An array of return strength measurements taken at regular intervals across the scan region. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range. power results scaled from min_pwr_db to max_pwr_db Length is derived from payload_length in the header. | ++ |
Set the device ID.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +device_id | +Device ID (0-254). 255 is reserved for broadcast messages. | ++ |
Set the scan range for acoustic measurements.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u32 | +scan_start | ++ | mm | +
| u32 | +scan_length | +The length of the scan range. Minimum 1000. | +mm | +
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 | +
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. | ++ |
The interval between acoustic measurements.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +ping_interval | +The interval between acoustic measurements. | +ms | +
Set the current gain setting.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +gain_setting | +The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144 | ++ |
Enable or disable acoustic measurements.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +ping_enabled | +0: Disable, 1: Enable. | ++ |
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. | ++ |
The device ID.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +device_id | +The device ID (0-254). 255 is reserved for broadcast messages. | ++ |
The 5V rail voltage.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +voltage_5 | +The 5V rail voltage. | +mV | +
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 | +
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 | +
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 | ++ |
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 | +
The current gain setting.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u32 | +gain_setting | +The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144 | ++ |
The duration of the acoustic activation/transmission.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +transmit_duration | +Acoustic pulse duration. | +microseconds | +
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_setting | +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 | ++ |
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. | +% | +
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 | +transmit_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_setting | +The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144 | ++ |
Temperature of the device cpu.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +processor_temperature | +The temperature in centi-degrees Centigrade (100 * degrees C). | +cC | +
Temperature of the on-board thermistor.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +pcb_temperature | +The temperature in centi-degrees Centigrade (100 * degrees C). | +cC | +
Acoustic output enabled state.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +ping_enabled | +The state of the acoustic output. 0: disabled, 1:enabled | ++ |
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
| 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 | +transmit_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_setting | +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. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range. | ++ |
Send the device into the bootloader. This is useful for firmware updates.
+No payload.
+Command to initiate continuous data stream of profile messages.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +id | +The message id to stream. 1300: profile | ++ |
Command to stop the continuous data stream of profile messages.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u16 | +id | +The message id to stop streaming. 1300: profile | ++ |
Change the device id
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +id | +Device ID (1-254). 0 and 255 are reserved. | ++ |
| u8 | +reserved | +reserved | ++ |
This message is used to communicate the current sonar state. If the data field is populated, the other fields indicate the sonar state when the data was captured. The time taken before the response to the command is sent depends on the difference between the last angle scanned and the new angle in the parameters as well as the number of samples and sample interval (range). To allow for the worst case reponse time the command timeout should be set to 4000 msec.
+| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +mode | +Operating mode (1 for Ping360) | ++ |
| u8 | +gain_setting | +Analog gain setting (0 = low, 1 = normal, 2 = high) | ++ |
| u16 | +angle | +Head angle | +gradians | +
| u16 | +transmit_duration | +Acoustic transmission duration (1~1000 us) | +microseconds | +
| u16 | +sample_period | +Time interval between individual signal intensity samples in 25 ns increments (80 to 40000 == 2 to 1000 us) | +eicosapenta-nanoseconds | +
| u16 | +transmit_frequency | +Acoustic operating frequency (500~1000 kHz). It is only practical to use say 650 to 850 kHz due to the narrow bandwidth of the acoustic receiver. | +kilohertz | +
| u16 | +number_of_samples | +Number of samples per reflected signal (supported values: 200~1200) | +samples | +
| u16 | +data_length | +The length of the proceeding vector field | ++ |
| u8[] | +data | +An array of return strength measurements taken at regular intervals across the scan region. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range. | ++ |
NEW (v1.1.0) Extended version of device_data with auto_transmit information. The sensor emits this message when in auto_transmit mode.
| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +mode | +Operating mode (1 for Ping360) | ++ |
| u8 | +gain_setting | +Analog gain setting (0 = low, 1 = normal, 2 = high) | ++ |
| u16 | +angle | +Head angle | +gradians | +
| u16 | +transmit_duration | +Acoustic transmission duration (1~1000 us) | +microseconds | +
| u16 | +sample_period | +Time interval between individual signal intensity samples in 25 ns increments (80 to 40000 == 2 to 1000 us) | +eicosapenta-nanoseconds | +
| u16 | +transmit_frequency | +Acoustic operating frequency (500~1000 kHz). It is only practical to use say 650 to 850 kHz due to the narrow bandwidth of the acoustic receiver. | +kilohertz | +
| u16 | +start_angle | +Head angle to begin scan sector for autoscan (0~399 = 0~360 degrees). | +gradians | +
| u16 | +stop_angle | +Head angle to end scan sector for autoscan (0~399 = 0~360 degrees). | +gradians | +
| u8 | +num_steps | +Number of 0.9 degree motor steps between pings for auto scan (1~10 = 0.9~9.0 degrees) | +gradians | +
| u8 | +delay | +An additional delay between successive transmit pulses (0~100 ms). This may be necessary for some programs to avoid collisions on the RS485 USRT. | +milliseconds | +
| u16 | +number_of_samples | +Number of samples per reflected signal (supported values: 200~1200) | +samples | +
| u16 | +data_length | +The length of the proceeding vector field | ++ |
| u8[] | +data | +An array of return strength measurements taken at regular intervals across the scan region. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range. | ++ |
Reset the sonar. The bootloader may run depending on the selection according to the bootloader payload field. When the bootloader runs, the external LED flashes at 5Hz. If the bootloader is not contacted within 5 seconds, it will run the current program. If there is no program, then the bootloader will wait forever for a connection. Note that if you issue a reset then you will have to close all your open comm ports and go back to issuing either a discovery message for UDP or go through the break sequence for serial comms before you can talk to the sonar again.
| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +bootloader | +0 = skip bootloader; 1 = run bootloader | ++ |
| u8 | +reserved | +reserved | ++ |
The transducer will apply the commanded settings. The sonar will reply with a device_data message. If the transmit field is 0, the sonar will not transmit after locating the transducer, and the data field in the device_data message reply will be empty. If the transmit field is 1, the sonar will make an acoustic transmission after locating the transducer, and the resulting data will be uploaded in the data field of the device_data message reply. To allow for the worst case response time the command timeout should be set to 4000 msec.
| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +mode | +Operating mode (1 for Ping360) | ++ |
| u8 | +gain_setting | +Analog gain setting (0 = low, 1 = normal, 2 = high) | ++ |
| u16 | +angle | +Head angle | +gradians | +
| u16 | +transmit_duration | +Acoustic transmission duration (1~1000 us) | +microseconds | +
| u16 | +sample_period | +Time interval between individual signal intensity samples in 25 ns increments (80 to 40000 == 2 to 1000 us) | +eicosapenta-nanoseconds | +
| u16 | +transmit_frequency | +Acoustic operating frequency (500~1000 kHz). It is only practical to use say 650 to 850 kHz due to the narrow bandwidth of the acoustic receiver. | +kilohertz | +
| u16 | +number_of_samples | +Number of samples per reflected signal (supported values: 200~1200) | +samples | +
| u8 | +transmit | +0 = do not transmit; 1 = transmit after the transducer has reached the specified angle | ++ |
| u8 | +reserved | +reserved | ++ |
NEW (v1.1.0) Extended transducer message with auto-scan function. The sonar will automatically scan the region between start_angle and end_angle and send auto_device_data messages as soon as new data is available. Send a line break to stop scanning (and also begin the autobaudrate procedure). Alternatively, a motor_off message may be sent (but retries might be necessary on the half-duplex RS485 interface).
| Type | +Name | +Description | +Units | +
|---|---|---|---|
| u8 | +mode | +Operating mode (1 for Ping360) | ++ |
| u8 | +gain_setting | +Analog gain setting (0 = low, 1 = normal, 2 = high) | ++ |
| u16 | +transmit_duration | +Acoustic transmission duration (1~1000 us) | +microseconds | +
| u16 | +sample_period | +Time interval between individual signal intensity samples in 25 ns increments (80 to 40000 == 2 to 1000 us) | +eicosapenta-nanoseconds | +
| u16 | +transmit_frequency | +Acoustic operating frequency (500~1000 kHz). It is only practical to use say 650 to 850 kHz due to the narrow bandwidth of the acoustic receiver. | +kilohertz | +
| u16 | +number_of_samples | +Number of samples per reflected signal (supported values: 200~1200) | +samples | +
| u16 | +start_angle | +Head angle to begin scan sector for autoscan (0~399 = 0~360 degrees). | +gradians | +
| u16 | +stop_angle | +Head angle to end scan sector for autoscan (0~399 = 0~360 degrees). | +gradians | +
| u8 | +num_steps | +Number of 0.9 degree motor steps between pings for auto scan (1~10 = 0.9~9.0 degrees) | +gradians | +
| u8 | +delay | +An additional delay between successive transmit pulses (0~100 ms). This may be necessary for some programs to avoid collisions on the RS485 USRT. | +milliseconds | +
The sonar switches the current through the stepper motor windings off to save power. The sonar will send an ack message in response. The command timeout should be set to 50 msec. If the sonar is idle (not scanning) for more than 30 seconds then the motor current will automatically turn off. When the user sends any command that involves moving the transducer then the motor current is automatically re-enabled.
+No payload.
+ + + + + + +The protocol is designed for synchronous communications in a master->slave network. The slave will only send data when requested by the master. This allows the protocol to be used on a half-duplex bus like RS485. Some devices may also provide facilities to allow asynchronous communication.
"},{"location":"#message-format","title":"Message Format","text":"Each message consists of a header, optional payload, and checksum. The binary format is specified as follows:
Byte Type Name Description 0 u8 start1 Start frame identifier, ASCII 'B' 1 u8 start2 Start frame identifier, ASCII '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."},{"location":"#scheme","title":"Scheme","text":"Messages are divided into 4 categories:
general_request from the host. These messages are designed to read data from the device.There are a some messages that are implemented by all devices, referred to as the 'common' message set. Message ids # 0~999 are reserved for the common messages. The request message is a special message in the common set that is used to request the device to respond with a message from the get category. Each device must also define it's own message set specific to the operation of the particular device.
"},{"location":"#message-definitions","title":"Message Definitions","text":"If necessary, Ping Protocol enabled devices may be discovered and identified by the host as follows:
Here we demonstrate a byte-by-byte breakdown of some messages sent between the host application (master) and the device (slave). This example illustrates a few points: - how to pack and unpack some message data (the byte-order of a message) - how the request/response mechanism of the protcol works with the general_request message - how to identify the protocol version that the device is using
Establishing communication with a sensor using the ping-protocol should begin with negotiating the protocol version. This negotiation process consists of two steps: - the host application requests a protocol_version message from the device - the device responds with a protocol_version message
Before reading these examples, you should be familiar with the message format specification.
"},{"location":"#request-protocol-version","title":"Request protocol version","text":"In order to receive a protocol_version message from the device, we will first send a general_request message to the device to ask for the message. The general_request message has a single payload field, requested_id. We populate this field with a value of 5 to indicate that we want the sensor to respond with a protocol_version message:
general_request payload 4-5 0x0006 6 u16 message_id This message is a general_request (id pingmessage-common#6) message 6 0x00 0 u8 src_device_id The device ID of the device sending the message. This field is not currently implemented and should be populated with a value of zero 7 0x00 0 u8 dst_device_id The device ID of the intended recipient of the message. This portion is not currently implemented and should be populated with a value of zero 8-9 0x0005 5 u16 requested_id This is the message id that we would like the device to transmit to us. Valid ids are those in the get category of messages 10-11 0x00a1 161 u16 checksum The message checksum. The checksum is calculated as the sum of all the non-checksum bytes in the message: 66 + 82 + 2 + 6 + 0 + 0 + 5 = 161 The bytes should be transmitted in this order: 0x42, 0x52, 0x02, 0x00, 0x06, 0x00, 0x00, 0x00, 0x05, 0x00, 0xa1, 0x00
Note that the messages are transmitted in little-endian format (observe the byte-order of the 16 bit fields)
"},{"location":"#receive-protocol-version","title":"Receive protocol version","text":"If everything is right, the sensor will respond to our request with a protocol_version message. The protocol_version message has 4 bytes in the payload: version_major, version_minor, version_patch, and reserved.
In this example, the device is using (a hypothetical) protocol version 1.2.3: - version_major = 1 - version_minor = 2 - version_patch = 3
Byte Value (hex) Value (decimal) Type Name Description 0 0x42 ('B') 66 u8 start1 This is a message start identifier, an ascii letter 'B' 1 0x52 ('R') 82 u8 start2 This is a message start identifier, an ascii letter 'R' 2-3 0x0004 4 u16 payload_length The number of bytes in theprotocol_version payload 4-5 0x0005 5 u16 message_id This message is a protocol_version (id #5) message 6 0x00 0 u8 src_device_id The device ID of the device sending the message. This field is not currently implemented and should be populated with a value of zero 7 0x00 0 u8 dst_device_id The device ID of the intended recipient of the message. This field is not currently implemented and should be populated with a value of zero 8 0x01 1 u8 version_major This is the protocol major version, the first digit in our example: v1.2.3 9 0x02 2 u8 version_minor This is the protocol minor version, the second digit in our example: v1.2.3 10 0x03 3 u8 version_patch This is the protocol patch version, the third digit in our example: v1.2.3 11 0x00 0 u8 reserved This byte is unused and will normally be zero (but it might be any value) 12-13 0x00a3 163 u16 checksum The message checksum. The checksum is calculated as the sum of all the non-checksum bytes in the message: 66 + 82 + 4 + 5 + 0 + 0 + 1 + 2 + 3 + 0 = 163 The bytes will be received in this order: 0x42, 0x52, 0x04, 0x00, 0x05, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x00, 0xa3, 0x00
Note that the messages are transmitted in little-endian format (observe the byte-order of the 16 bit fields)
"},{"location":"pingmessage-common/","title":"Common messages","text":""},{"location":"pingmessage-common/#general","title":"general","text":""},{"location":"pingmessage-common/#1-ack","title":"1 ack","text":"Acknowledged.
Type Name Description Units u16 acked_id The message ID that is ACKnowledged."},{"location":"pingmessage-common/#2-nack","title":"2 nack","text":"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. (not necessarily NULL terminated) Length is derived from payload_length in the header."},{"location":"pingmessage-common/#3-ascii_text","title":"3 ascii_text","text":"A message for transmitting text data.
Type Name Description Units char[] ascii_message ASCII text message. (not necessarily NULL terminated) Length is derived from payload_length in the header."},{"location":"pingmessage-common/#6-general_request","title":"6 general_request","text":"Requests a specific message to be sent from the sonar to the host. Command timeout should be set to 50 msec.
Type Name Description Units u16 requested_id Message ID to be requested."},{"location":"pingmessage-common/#get","title":"get","text":""},{"location":"pingmessage-common/#4-device_information","title":"4 device_information","text":"Device information
Type Name Description Units u8 device_type Device type. 0: Unknown; 1: Ping Echosounder; 2: Ping360 u8 device_revision device-specific hardware revision u8 firmware_version_major Firmware version major number. u8 firmware_version_minor Firmware version minor number. u8 firmware_version_patch Firmware version patch number. u8 reserved reserved"},{"location":"pingmessage-common/#5-protocol_version","title":"5 protocol_version","text":"The protocol version
Type Name Description Units u8 version_major Protocol version major number. u8 version_minor Protocol version minor number. u8 version_patch Protocol version patch number. u8 reserved reserved"},{"location":"pingmessage-common/#set","title":"set","text":""},{"location":"pingmessage-common/#100-set_device_id","title":"100 set_device_id","text":"Set the device ID.
Type Name Description Units u8 device_id Device ID (1-254). 0 is unknown and 255 is reserved for broadcast messages."},{"location":"pingmessage-omniscan450/","title":"Omniscan450 messages","text":""},{"location":"pingmessage-omniscan450/#control","title":"control","text":""},{"location":"pingmessage-omniscan450/#1002-set_speed_of_sound","title":"1002 set_speed_of_sound","text":"Set the speed of sound.
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"},{"location":"pingmessage-omniscan450/#2197-os_ping_params","title":"2197 os_ping_params","text":"Type Name Description Units u32 start_mm u32 length_mm u32 msec_per_ping float reserved float reserved float pulse_len_percent float filter_duration_percent i16 gain_index u16 num_results u8 enable u8 reserved"},{"location":"pingmessage-omniscan450/#get","title":"get","text":""},{"location":"pingmessage-omniscan450/#2198-os_mono_profile","title":"2198 os_mono_profile","text":"A profile produced from a single acoustic measurement. The data returned is an array of response strength, in dB, at even intervals across the scan region. The scan region is defined as the region between and millimeters away from the transducer. Note that the amplitude of the results are in dB. This is just to keep high dynamic range in the u16 sized data elements. Normally these are converted back to linear power or signal levels. Type Name Description Units u32 ping_number sequentially assigned from 0 at power up u32 start_mm The beginning of the scan region in mm from the transducer. mm u32 length_mm The length of the scan region. mm u32 timestamp_ms msec since power up at time of ping ms u32 ping_hz Frequency of acoustic signal hz u16 gain_index 0-7 u16 num_results length of pwr_results array u16 sos_dmps speed of sound, decimeters/sec u8 channel_number u8 reserved float pulse_duration_sec float analog_gain float max_pwr_db float min_pwr_db float transducer_heading_deg float vehicle_heading_deg u16[] pwr_results An array of return strength measurements taken at regular intervals across the scan region. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range. power results scaled from min_pwr_db to max_pwr_db Length is derived from payload_length in the header."},{"location":"pingmessage-ping1d/","title":"Ping1d messages","text":""},{"location":"pingmessage-ping1d/#set","title":"set","text":""},{"location":"pingmessage-ping1d/#1000-set_device_id","title":"1000 set_device_id","text":"
Set the device ID.
Type Name Description Units u8 device_id Device ID (0-254). 255 is reserved for broadcast messages."},{"location":"pingmessage-ping1d/#1001-set_range","title":"1001 set_range","text":"Set the scan range for acoustic measurements.
Type Name Description Units u32 scan_start mm u32 scan_length The length of the scan range. Minimum 1000. mm"},{"location":"pingmessage-ping1d/#1002-set_speed_of_sound","title":"1002 set_speed_of_sound","text":"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"},{"location":"pingmessage-ping1d/#1003-set_mode_auto","title":"1003 set_mode_auto","text":"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."},{"location":"pingmessage-ping1d/#1004-set_ping_interval","title":"1004 set_ping_interval","text":"The interval between acoustic measurements.
Type Name Description Units u16 ping_interval The interval between acoustic measurements. ms"},{"location":"pingmessage-ping1d/#1005-set_gain_setting","title":"1005 set_gain_setting","text":"Set the current gain setting.
Type Name Description Units u8 gain_setting The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144"},{"location":"pingmessage-ping1d/#1006-set_ping_enable","title":"1006 set_ping_enable","text":"Enable or disable acoustic measurements.
Type Name Description Units u8 ping_enabled 0: Disable, 1: Enable."},{"location":"pingmessage-ping1d/#get","title":"get","text":""},{"location":"pingmessage-ping1d/#1200-firmware_version","title":"1200 firmware_version","text":"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."},{"location":"pingmessage-ping1d/#1201-device_id","title":"1201 device_id","text":"The device ID.
Type Name Description Units u8 device_id The device ID (0-254). 255 is reserved for broadcast messages."},{"location":"pingmessage-ping1d/#1202-voltage_5","title":"1202 voltage_5","text":"The 5V rail voltage.
Type Name Description Units u16 voltage_5 The 5V rail voltage. mV"},{"location":"pingmessage-ping1d/#1203-speed_of_sound","title":"1203 speed_of_sound","text":"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"},{"location":"pingmessage-ping1d/#1204-range","title":"1204 range","text":"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"},{"location":"pingmessage-ping1d/#1205-mode_auto","title":"1205 mode_auto","text":"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"},{"location":"pingmessage-ping1d/#1206-ping_interval","title":"1206 ping_interval","text":"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"},{"location":"pingmessage-ping1d/#1207-gain_setting","title":"1207 gain_setting","text":"The current gain setting.
Type Name Description Units u32 gain_setting The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144"},{"location":"pingmessage-ping1d/#1208-transmit_duration","title":"1208 transmit_duration","text":"The duration of the acoustic activation/transmission.
Type Name Description Units u16 transmit_duration Acoustic pulse duration. microseconds"},{"location":"pingmessage-ping1d/#1210-general_info","title":"1210 general_info","text":"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_setting 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"},{"location":"pingmessage-ping1d/#1211-distance_simple","title":"1211 distance_simple","text":"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. %"},{"location":"pingmessage-ping1d/#1212-distance","title":"1212 distance","text":"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 transmit_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_setting The current gain setting. 0: 0.6, 1: 1.8, 2: 5.5, 3: 12.9, 4: 30.2, 5: 66.1, 6: 144"},{"location":"pingmessage-ping1d/#1213-processor_temperature","title":"1213 processor_temperature","text":"Temperature of the device cpu.
Type Name Description Units u16 processor_temperature The temperature in centi-degrees Centigrade (100 * degrees C). cC"},{"location":"pingmessage-ping1d/#1214-pcb_temperature","title":"1214 pcb_temperature","text":"Temperature of the on-board thermistor.
Type Name Description Units u16 pcb_temperature The temperature in centi-degrees Centigrade (100 * degrees C). cC"},{"location":"pingmessage-ping1d/#1215-ping_enable","title":"1215 ping_enable","text":"Acoustic output enabled state.
Type Name Description Units u8 ping_enabled The state of the acoustic output. 0: disabled, 1:enabled"},{"location":"pingmessage-ping1d/#1300-profile","title":"1300 profile","text":"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 and 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 transmit_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_setting 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. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range."},{"location":"pingmessage-ping1d/#control","title":"control","text":""},{"location":"pingmessage-ping1d/#1100-goto_bootloader","title":"1100 goto_bootloader","text":"
Send the device into the bootloader. This is useful for firmware updates.
No payload.
"},{"location":"pingmessage-ping1d/#1400-continuous_start","title":"1400 continuous_start","text":"Command to initiate continuous data stream of profile messages.
Type Name Description Units u16 id The message id to stream. 1300: profile"},{"location":"pingmessage-ping1d/#1401-continuous_stop","title":"1401 continuous_stop","text":"Command to stop the continuous data stream of profile messages.
Type Name Description Units u16 id The message id to stop streaming. 1300: profile"},{"location":"pingmessage-ping360/","title":"Ping360 messages","text":""},{"location":"pingmessage-ping360/#set","title":"set","text":""},{"location":"pingmessage-ping360/#2000-set_device_id","title":"2000 set_device_id","text":"Change the device id
Type Name Description Units u8 id Device ID (1-254). 0 and 255 are reserved. u8 reserved reserved"},{"location":"pingmessage-ping360/#get","title":"get","text":""},{"location":"pingmessage-ping360/#2300-device_data","title":"2300 device_data","text":"This message is used to communicate the current sonar state. If the data field is populated, the other fields indicate the sonar state when the data was captured. The time taken before the response to the command is sent depends on the difference between the last angle scanned and the new angle in the parameters as well as the number of samples and sample interval (range). To allow for the worst case reponse time the command timeout should be set to 4000 msec.
Type Name Description Units u8 mode Operating mode (1 for Ping360) u8 gain_setting Analog gain setting (0 = low, 1 = normal, 2 = high) u16 angle Head angle gradians u16 transmit_duration Acoustic transmission duration (1~1000 us) microseconds u16 sample_period Time interval between individual signal intensity samples in 25 ns increments (80 to 40000 == 2 to 1000 us) eicosapenta-nanoseconds u16 transmit_frequency Acoustic operating frequency (500~1000 kHz). It is only practical to use say 650 to 850 kHz due to the narrow bandwidth of the acoustic receiver. kilohertz u16 number_of_samples Number of samples per reflected signal (supported values: 200~1200) samples u16 data_length The length of the proceeding vector field u8[] data An array of return strength measurements taken at regular intervals across the scan region. The first element is the closest measurement to the sensor, and the last element is the farthest measurement in the scanned range."},{"location":"pingmessage-ping360/#2301-auto_device_data","title":"2301 auto_device_data","text":"NEW (v1.1.0) Extended version of device_data with auto_transmit information. The sensor emits this message when in auto_transmit mode.
Reset the sonar. The bootloader may run depending on the selection according to the bootloader payload field. When the bootloader runs, the external LED flashes at 5Hz. If the bootloader is not contacted within 5 seconds, it will run the current program. If there is no program, then the bootloader will wait forever for a connection. Note that if you issue a reset then you will have to close all your open comm ports and go back to issuing either a discovery message for UDP or go through the break sequence for serial comms before you can talk to the sonar again.
The transducer will apply the commanded settings. The sonar will reply with a device_data message. If the transmit field is 0, the sonar will not transmit after locating the transducer, and the data field in the device_data message reply will be empty. If the transmit field is 1, the sonar will make an acoustic transmission after locating the transducer, and the resulting data will be uploaded in the data field of the device_data message reply. To allow for the worst case response time the command timeout should be set to 4000 msec.
NEW (v1.1.0) Extended transducer message with auto-scan function. The sonar will automatically scan the region between start_angle and end_angle and send auto_device_data messages as soon as new data is available. Send a line break to stop scanning (and also begin the autobaudrate procedure). Alternatively, a motor_off message may be sent (but retries might be necessary on the half-duplex RS485 interface).
The sonar switches the current through the stepper motor windings off to save power. The sonar will send an ack message in response. The command timeout should be set to 50 msec. If the sonar is idle (not scanning) for more than 30 seconds then the motor current will automatically turn off. When the user sends any command that involves moving the transducer then the motor current is automatically re-enabled.
No payload.
"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 00000000..29cbd3e0 --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,28 @@ + +