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 |
Last updated