# 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 `Surveyor240` and `definitions` modules can be imported like this:

```python
from brping import Surveyor240
from brping import definitions
```

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

### Initialization

A `Surveyor240` object can be created with the `Surveyor240` class.

```python
mySurveyor240 = Surveyor240()
```

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

```python
mySurveyor240 = Surveyor240(logging=True, log_directory="logs/surveyor")
```

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

```python
ip = "192.168.2.86"
port = 62312
mySurveyor240.connect_tcp(ip, port)
```

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

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

### Controlling The Device

The `Surveyor240` object contains several methods related to controlling and processing data. To set Surveyor 240 parameters, the device needs an `set_ping_parameters` packet as described [here](https://docs.ceruleansonar.com/c/surveyor-240-16/application-programming-interface/set_ping_parameters). The methods titled `control_<message_name>` will send the device a packet. Each of the parameters in `set_ping_parameters` contains a default value that can be changed by assigning that variable.

```python
mySurveyor240.control_set_ping_parameters(
    end_mm=0,       # Set to 0 to let Surveyor track range dynamically
    msec_per_ping=my_msec_per_ping,
    ping_enable=1,
    enable_atof_data=1
)
```

The `Surveyor240` 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 = Surveyor240.calc_msec_per_ping(ping_rate)
```

### Receiving Packets

Packets are received through the `wait_message()` method. While packets can be requested through the `get_<method_name>()` methods, this is not the recommended way as the Surveyor 240 will continually send packets after pinging is enabled.

```python
data = mySurveyor240.wait_message([definitions.SURVEYOR240_ATOF_POINT_DATA])
```

`wait_message()` returns a `PingMessage` object, which has the payload fields as its attributes. The payload fields are defined [here](https://docs.ceruleansonar.com/c/surveyor-240-16/application-programming-interface). For example, to access the `ping_number` field the corresponding attribute can be accessed like so:

```python
data.ping_number
```

To continually receive packets from the Surveyor 240, 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 = mySurveyor240.wait_message([definitions.SURVEYOR240_ATOF_POINT_DATA])
        if data:
            # Access packet fields like any other attribute
            print(f"Ping Number: {data.ping_number}")
        else:
            print("Bad packet")
    except KeyboardInterrupt:
        break
```

The `atof_point_data` packet also contains an array of atof\_t structs that can be unpacket properly using the `create_atof_list()` method:

```python
atof_list = mySurveyor240.create_atof_list(data)
```

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

```python
print(f"atof_list[0] = {atof_list[0]}")
```

To stop pinging on the Surveyor 240:

```python
mySurveyor240.control_set_ping_parameters(ping_enable=0)
```

### Logging

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

```python
mySurveyor240.start_logging()
```

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

* `new_log`
  * If `True`, creates a new `.svlog` file
  * If `False`, appends to the most recent `.svlog` file created by that `Surveyor240` 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
mySurveyor240.stop_logging()
```

### Example Code

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

Copy

```bash
$ python simpleSurveyorExample.py
```

{% file src="<https://2416497028-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOPPBWdanG78xVyb6w4vq%2Fuploads%2FALlYbQpC0B0l33GJdBla%2FsimpleSurveyorExample.py?alt=media&token=33fef304-2b1e-4efb-9c64-8d1d79d57447>" %}

### More Examples

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