Getting Started With Ping-Python

Ping-Python is a library that allows for interfacing with the Surveyor 240 in Python.

Installation

Ping-Python GitHub page

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

pip install --user bluerobotics-ping --upgrade

Or from source like this:

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

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.

mySurveyor240 = Surveyor240()

The Surveyor240 class allows for logging to the SonarView log file format. Logging can be enabled and log directory can be set during initialization. (Note: When no log directory is specified, it defaults to ../logs/surveyor )

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.

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 and set up logging if it's enabled. It returns True if a response packet is returned or False otherwise.

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

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:

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.

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. For example, to access the ping_number field the corresponding attribute can be accessed like so:

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.

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:

atof_list = mySurveyor240.create_atof_list(data)

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

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

To stop pinging on the Surveyor 240:

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:

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:

mySurveyor240.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:

python -m venv venv
source venv/bin/activate

Install dependencies:

pip install -e.
pip install pyserial

Then run the program:

python simpleSurveyorExample.py

simpleSurveyorExample.py

2KB

Open

More Examples

The GitHub repository contains a more detailed example which demonstrates more features like command-line arguments, signal handlers, and replaying from .svlog files.