# Getting Started With Ping-Python

## Installation

### [Ping-Python GitHub Page](https://github.com/bluerobotics/ping-python)

To get started,  install the library either using pip (recommended) or from source. The library can be installed with pip like this:

```bash
$ pip install --user bluerobotics-ping --upgrade
```

Or from source like this:

```bash
$ git clone --single-branch --branch deployment https://github.com/bluerobotics/ping-python.git
$ cd ping-python
$ python setup.py install --user
```

More detailed instructions can be found on the GitHub page.

## Getting Started Guide

### Imports

Once the library is installed, the `Omniscan450` and `definitions` modules can be imported like this:

```python
from brping import Omniscan450
from brping import definitions
```

`Omniscan450` contains the relevant class and methods for controlling the device. `definitions` contains packet definitions needed for sending and receiving packets.

### Initialization

An `Omniscan450` object can be created with the `Omniscan450` class.

```python
myOS450 = Omniscan450()
```

The `Omniscan450` class allows for logging to the [SonarView log file format](/c/sonarview/replaying-saved-sonar-files.md). Logging can be enabled and log directory can be set during initialization. (Note: When no log directory is specified, it defaults to `../logs/omniscan` )

```python
myOS450 = Omniscan450(logging=True, log_directory="logs/omniscan")
```

Typically, Omniscan communication happens through TCP which requires an IP address and port number. The default IP address for the Omniscan is `192.168.2.92` and the port number is `51200` . Both `connect_tcp()` and `connect_udp()` expect a string IP address and an integer port number. TCP is recommended.

```python
ip = "192.168.2.92"
port = 51200
myOS450.connect_tcp(ip, port)
```

The last step in initializing the Omniscan 450 is to call the `initialize()` method. This method will request a [device information packet](/c/cerulean-ping-protocol/general-packet-definitions/device_information.md) and set up logging if it's enabled. It returns `True` if a response packet is returned or `False` otherwise.

```python
if myOS450.initialize() is False:
    exit(1)
```

### Controlling The Device

The `Omniscan450` object contains several methods related to controlling and processing data. To set Omniscan 450 parameters, the device needs an `os_ping_params` packet as described [here](/c/omniscan-450/application-programming-interface.md#commands). The methods titled `control_<message_name>`  will send the device a packet. Each of the parameters in `os_ping_params` contains a default value that can be changed by assigning that variable.

```python
myOS450.control_os_ping_params(
    start_mm=0,
    length_mm=5000,                     # Set range to 5m
    msec_per_ping=my_msec_per_ping, 
    pulse_len_percent=my_pulse_length,  
    gain_index=-1,                      # Auto gain
    enable=1                            # Enable pinging
)
```

The `Omniscan450` class also contains several static methods that allow for related data calculations.

To calculate the milliseconds per ping from a ping rate:

```python
ping_rate = 10 # 10 pings per second
my_msec_per_ping = Omniscan450.calc_msec_per_ping(ping_rate)
```

To calculate the pulse length percent from a percent value:

```python
percent = 0.2 # 0.2%
my_pulse_length = Omniscan450.calc_pulse_length_pc(percent)
```

### Receiving Packets

Packets are received through the `wait_message()` method. While packets can be requested through the `get_os_mono_profile()` method, this is not the recommended way as the Omniscan 450 will continually send packets after pinging is enabled.

```python
data = myOS450.wait_message([definitions.OMNISCAN450_OS_MONO_PROFILE])
```

`wait_message()` returns a `PingMessage` object, which has the payload fields as its attributes. The payload fields are defined [here](/c/omniscan-450/application-programming-interface.md#ping-response-packets). For example, to access the `ping_number` field the corresponding attribute can be accessed like so:&#x20;

```python
data.ping_number
```

To continually receive packets from the Omniscan 450, a `while True` block can be used. The try/except blocks allow for the loop to keep going until the user enters CTRL-C.

```python
while True:
    try:
        data = myOS450.wait_message([definitions.OMNISCAN450_OS_MONO_PROFILE])
        if data:
            print(f"Ping Number: {data.ping_number}")
        else:
            print("Bad packet")
    except KeyboardInterrupt:
        break
```

The `os_mono_profile` packet contains power data that is scaled to fit into 16 bit values. The Omniscan class contains a method for converting this data to dB values:

```python
pwr_db = myOS450.scale_power(data)
```

Elements of this list can be accessed with normal list operations:

```python
first_element = pwr_db[0]
```

To stop pinging on the Omniscan:

```python
myOS450.control_os_ping_params(enable=0)
```

### Logging

The `Omniscan450` class provides methods to start and stop logging. Logging occurs after `wait_message()` receives a message. To enable logging, use:

```python
myOS450.start_logging()
```

The `start_logging()` method takes two optional parameters:

* `new_log`&#x20;
  * If `True`, creates a new `.svlog` file
  * If `False`, appends to the most recent `.svlog` file created by that `Omniscan450` instance
* `log_directory`
  * A string that specifies the path of a directory where the log file will be saved. Defaults to the instance's configured log directory.

To stop logging, use:

```python
myOS450.stop_logging()
```

### Example Code

The full example is provided below and can be run like this:

```bash
$ python simpleOSExample.py
```

{% file src="/files/VsLfYYt3LVz8d289Z98f" %}

### More Examples

The [GitHub repository](https://github.com/bluerobotics/ping-python/blob/master/examples/omniscan450Example.py) contains a more detailed example which demonstrates more features like command-line arguments, signal handlers, and replaying from `.svlog` files.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ceruleansonar.com/c/omniscan-450/getting-started-with-ping-python.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.