Appendix A: Programming API

API Compatibility: Omniscan communication uses the same binary packet format (described below) as the Cerulean S500 Sounder, the Insight 240 Forward Looking Sonar and the Blue Robotics Ping and Ping360 sonars.

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

These are the Omniscan-specific packet payload formats. Note on os_ping_params: send once to start or stop pinging.

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)
os_ping_params	2197	u32	start_mm	start of ping range, set to 0
​	​	u32	length_mm	length of the returned profile. so end of range = start_mm + length_mm.
​	​	u32	msec_per_ping	normally set to 0 for best ping rate. set value to limit ping rate
		float	reserved	set to 0
		float	reserved	set to 0
		float	pulse_len_percent	% of total ping time for current range. 0.002 typical
		float	filter_duration_percent	0.0015 typical
​	​	i16	gain_index	set to -1 for auto gain, otherwise 0-7 sets gain
​	​	u16	number of signal data points in resulting profile	200-1200. 600 typical
​	​	u8	enable	1 or 0 to enable or disable pinging
​	​	u8	reserved	set to 0

Ping Response Packets

For os_mono_profile, 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.

Name	ID	Data Type	Name	Description
os_mono_profile	2198	u32	ping_number	sequentially assigned from 0 at power up
		u32	start_mm
		u32	length_mm
		u32	timestamp_ms	msec since power up at time of ping
		u32	ping_hz	450000
		u16	gain_index	0-7
		u16	num_results	length of pwr_results array
		u16	sos_dmps	speed of sound, decimeters/sec
		u8	channel_number	0
		u8	reserved	0
		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[]	power results scaled from min_pwr_db to max_pwr_db