# Application Programming Interface

Omniscan communication uses a packet protocol common to several Cerulean Sonar products. Please refer to the [Cerulean Ping Protocol](https://docs.ceruleansonar.com/c/cerulean-ping-protocol) document for the canonical packet format and other background information

## **Packet Payload Definitions**

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

### Commands

<table data-header-hidden><thead><tr><th width="211"></th><th></th><th></th><th width="174"></th><th></th></tr></thead><tbody><tr><td><br>Name</td><td>ID</td><td>Data Type</td><td>Name</td><td>Description</td></tr><tr><td>set_speed_of_sound</td><td>116</td><td>u32</td><td>sos_mm_per_sec</td><td>default value is 15000000 mm/sec (1500 meters/sec)</td></tr><tr><td>os_ping_params</td><td>2197</td><td>u32</td><td>start_mm</td><td>start of ping range, set to 0</td></tr><tr><td>​</td><td>​</td><td>u32</td><td>length_mm</td><td>length of the returned profile. so end of range = start_mm + length_mm. </td></tr><tr><td>​</td><td>​</td><td>u32</td><td>msec_per_ping</td><td>normally set to 0 for best ping rate. set value to limit ping rate</td></tr><tr><td></td><td></td><td>float</td><td>reserved</td><td>set to 0</td></tr><tr><td></td><td></td><td>float</td><td>reserved</td><td>set to 0</td></tr><tr><td></td><td></td><td>float</td><td>pulse_len_percent</td><td>% of total ping time for current range. 0.002 typical</td></tr><tr><td></td><td></td><td>float</td><td>filter_duration_percent</td><td>0.0015 typical</td></tr><tr><td>​</td><td>​</td><td>i16</td><td>gain_index</td><td>set to -1 for auto gain, otherwise 0-7 sets gain</td></tr><tr><td>​</td><td>​</td><td>u16</td><td>number of signal data points in resulting profile</td><td>200-1200. 600 typical</td></tr><tr><td>​</td><td>​</td><td>u8</td><td>enable</td><td>1 or 0 to enable or disable pinging</td></tr><tr><td>​</td><td>​</td><td>u8</td><td>reserved</td><td>set to 0</td></tr><tr><td></td><td></td><td>u8</td><td>reserved</td><td>set to 0</td></tr><tr><td></td><td></td><td>u8</td><td>reserved</td><td>set to 0</td></tr></tbody></table>

### 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.

<table><thead><tr><th width="150">Name</th><th width="80">ID</th><th width="150">Data Type</th><th width="196">Name</th><th>Description</th></tr></thead><tbody><tr><td>os_mono_profile</td><td>2198</td><td>u32</td><td>ping_number</td><td>sequentially assigned from 0 at power up</td></tr><tr><td></td><td></td><td>u32</td><td>start_mm</td><td></td></tr><tr><td></td><td></td><td>u32</td><td>length_mm</td><td></td></tr><tr><td></td><td></td><td>u32</td><td>timestamp_ms</td><td>msec since power up at time of ping</td></tr><tr><td></td><td></td><td>u32</td><td>ping_hz</td><td>450000</td></tr><tr><td></td><td></td><td>u16</td><td>gain_index</td><td>0-7</td></tr><tr><td></td><td></td><td>u16</td><td>num_results</td><td>length of pwr_results array</td></tr><tr><td></td><td></td><td>u16</td><td>sos_dmps</td><td>speed of sound, decimeters/sec</td></tr><tr><td></td><td></td><td>u8</td><td>channel_number</td><td>0</td></tr><tr><td></td><td></td><td>u8</td><td>reserved</td><td>0</td></tr><tr><td></td><td></td><td>float</td><td>pulse_duration_sec</td><td></td></tr><tr><td></td><td></td><td>float</td><td>analog_gain</td><td></td></tr><tr><td></td><td></td><td>float</td><td>max_pwr_db</td><td></td></tr><tr><td></td><td></td><td>float</td><td>min_pwr_db</td><td></td></tr><tr><td></td><td></td><td>float</td><td>transducer_heading_deg</td><td></td></tr><tr><td></td><td></td><td>float</td><td>vehicle_heading_deg</td><td></td></tr><tr><td></td><td></td><td>u16</td><td>pwr_results[]</td><td>power results scaled from min_pwr_db to max_pwr_db</td></tr></tbody></table>