Appendix F: Programming API

API Compatibility: S500 communication uses a binary packet format compatible with the Blue Robotics Ping-Protocol. It supports most of the Blue Robotics Ping1 packet types.

Documentation: The generic packet format is documented below, as are the specific payloads. These packet types are recommended for new applications targeting the S500 sounder.

Apology: The terms "altitude," "distance," and "depth" are used somewhat interchangeably here. They all mean the sensed distance from the device to some object, which in many applications is "the bottom."

Packet Format

Byte	Data Type	Name	Description
0 to 1	char[2]	start_of_packet	2 byte ASCII string "BR" marks start of packet
2 to 3	u16	payload_length	number of bytes in payload
4 to 5	u16	packet_id	corresponds to ID field in packet payload definitions below
6	u8	reserved	set to 0
7	u8	reserved	set to 0
8 to n	u8[]	payload	payload message. Format varies with packet id per payload definitions below
(n+1) to (n+2)	u16	checksum	sum of all the bytes in the packet. Truncated to 16 bits

Packet Payload Definitions

General

Name	ID	Data Type	Name	Description
nop	0		none	clients may ignore. Sometimes useful to keep things awake
ack	1	u16	id	id being acked
nack	2	u16	id	id being nacked
		char[]	msg	optional ascii text message describing error*
ascii_text	3	char[]	msg	any ascii text string*
general_request	6	u16	id	request client to respond with packet id type

*STR_LEN: Length of the string determined based on payload_length in packet header.

Request Info Response Packets

These are the responses that the device will send to the host in response to a general_request packet (id = 6, see above). Alternatively, host may send any one of these packet ids with no payload and device will respond with same id and the payload indicated here.

Name	ID	Data Type	Name	Description
fw_version	1200	u8	device_type
		u8	device_model
		u16	version_major
		u16	version_minor
speed_of_sound	1203	u32	sos_mm_per_sec	current speed of sound setting in mm/sec default is 1500 m/sec
range	1204	u32	start_mm	normally 0
		u32	length_mm	start_mm + length_mm is max range
ping_rate_msec	1206	u16	msec_per_ping	minimum time between successive pings. Can be longer depending on range
gain_index	1207	u32	gain_index	current gain index setting
altitude	1211	u32	altitude_mm	result of most recent calculated distance from device to bottom (or other target)
		u8	quality	measure of confidence of altitude measure 0 (no idea) to 100 (quite sure)
processor_degC	1213	u32	centi_degC	device CPU temperature degrees C * 100

Commands

Name	ID	Data Type	Name	Description
set_speed_of_sound	1002	u32	sos_mm_per_sec	default value is 15000000 mm/sec (1500 meters/sec)
set_ping_params	1015	u32	start_mm	start of ping range, normally 0
		u32	length_mm	length of the returned profile. so end of range = start_mm + length_mm. Set to 0 for auto range.
		i16	gain_index	set to -1 for auto gain, otherwise 0-13 sets gain for manual gain
		i16	msec_per_ping	set to -1 to start a single ping. Otherwise sets minimum ping interval
		u16	pulse_len_usec	0 for auto mode. currently ignored and auto duration always used
		u16	report_id	the ID of the packet type that you would like in response. Options are: distance2 (1223), profile6 (1308), or zero. Zero disables pinging.
		u16	reserved	Set to 0.
		u8	chirp	set to 1 for chirp, 0 for monotone ping
		u8	decimation	set to 0 for auto range resolution in chirp mode.

Ping Response Packets

These packet types can be returned after each ping by specifying their packet id in the report_id field of the set_ping_params packet described above.

distance2 reports a simple distance measurement.

profile6_t report a measure of signal strength at all depths within the ping range. This could be used to present a "waterfall" type display similar to a commercial marine depth sounder or fish finder. The Cerulean SonarView app uses profile6_t to do just that.

The native number of results reported for the profile6_t is 1024 for monotone pings. For chirp pings, the range resolution is affected by the "decimation" field in the set_ping_params command. If decimation is set to 0, the device will vary decimation depending on range. The smallest decimation will be used that does not exceed 6000 reported data elements.

Keep in mind the bandwidth of the communication channel in use when considering which profile report to use. For example, profile6_t can generate a lot of data, and is probably best used with the USB or Ethernet interface.

Name	ID	Data Type	Name	Description
distance2	1223	u32	this ping distance mm	most recent ping
		u32	averaged distance mm	average over last 20 pings
		u16	reserved
		u8	this ping confidence	0 to 100
		u8	confidence of averaged distance	0 to 100
		u32	timestamp	msec
profile6_t	1308	u32	ping_number	sequentially assigned from 0 at power up
		u32	start_mm
		u32	length_mm
		u32	start_ping_hz
		u32	end_ping_hz
		u32	adc_sample_hz
		u32	timestamp_msec
		u32	spare2
		float	pulse_duration_sec
		float	analog_gain
		float	max_pwr_db
		float	min_pwr_db
		float	this_ping_depth_m	depth in meters as calculated from the most recent ping
		float	smooth_depth_m	smoothed calculated depth
		float	fspare2	0
		u8	this ping depth measurement confidence	depth measurement confidence (0-100) based on most recent ping
		u8	gain_index
		u8	decimation
		u8	smoothed depth measurement confidence (0-100)	0
		u16	num_results
		u16	pwr_results[]	power results scaled from min_pwr to max_pwr. num_results entries