> For the complete documentation index, see [llms.txt](https://docs.ceruleansonar.com/c/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ceruleansonar.com/c/s-500-sounder/getting-started-with-ping-python.md).

# 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

```

More detailed instructions can be found on the GitHub page.

## Getting Started Guide

### Imports

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

```python
from brping import S500
from brping import definitions
```

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

### Initialization

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

```python
myS500 = S500()
```

The `S500` 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/s500`)

```python
myS500 = S500(logging=True, log_directory="logs/s500")
```

The Sounder S500 can communicate in a few ways which are detailed [here](/c/s-500-sounder/communicating-with-the-sounder-s500.md). Ping-Python supports communication through Serial, UDP, and TCP. This guide will show TCP. Setting up UDP with Ping-Python is almost identical to setting up TCP, and serial is explained in the 'Usage' section on the [Ping-Python GitHub repository](https://github.com/bluerobotics/ping-python/tree/master).

The default IP address for the S500 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.

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

The last step in initializing the Sounder S500 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 myS500.initialize() is False:
    exit(1)
```

### Controlling The Device

The `S500` object contains several methods related to controlling and processing data. To set Sounder S500 parameters, the device needs a `set_ping_params` packet as described [here](/c/s-500-sounder/technical-details/programming-api.md#commands). The methods titled `control_<message_name>` will send the device a packet. Each of the parameters in `set_ping_params` contains a default value that can be changed by assigning that variable.

```python
myS500.control_set_ping_params(
    start_mm=0,
    length_mm=5000,     # Set range to 5m
    gain_index=-1,
    msec_per_ping=my_msec_per_ping,
    report_id=definitions.S500_PROFILE6_T,  # Request profile6_t packet
    chirp=1,            # Turn on chirp
    decimation=0        # Auto range resolution
)
```

The `S500` class also contains 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 = S500.calc_msec_per_ping(ping_rate)
```

### Receiving Packets

Packets are received through the `wait_message()` method. While packets can be requested through the `get_<message_name>()` methods, this is not the recommended way as the Sounder S500 will continually send packets after pinging is enabled.&#x20;

```python
 data = myS500.wait_message([definitions.S500_PROFILE6_T])
```

`wait_message()` returns a `PingMessage` object, which has the payload fields as its attributes. The payload fields are defined [here](/c/s-500-sounder/technical-details/programming-api.md#ping-response-packets). For example, to access the `ping_number` field in the `profile6_t` packet, the corresponding attribute can be accessed like so:

```python
data.ping_number
```

To continually receive packets from the Sounder S500, 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 = myS500.wait_message([definitions.S500_PROFILE6_T])
        if data:
            print(f"Ping Number: {data.ping_number}")
        else:
            print("Bad packet")
    except KeyboardInterrupt:
        break
```

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

```python
pwr_db = myS500.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 Sounder S500:

```python
myS500.control_set_ping_params(report_id=0)
```

### Logging

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

```python
myS500.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 `S500` 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
S500.stop_logging()
```

### Example Code

The full example is provided below. Place into your python-ping directory and to run it do these steps.

Create a python virtual environment (venv) and then activate it:

```bash
python -m venv venv
source venv/bin/activate
```

Install dependencies:

```bash
pip install -e.
pip install pyserial
```

Then run the program:

```bash
python simpleS500Example.py
```

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

## More Examples

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