Getting Started With Ping-Python

Ping-Python is a library that allows for interfacing with the Sounder S500 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 S500 and definitions modules can be imported like this:

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.

myS500 = S500()

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

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

The Sounder S500 can communicate in a few ways which are detailed here. 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.

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.

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

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

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:

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.

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

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.

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:

pwr_db = myS500.scale_power(data)

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

first_element = pwr_db[0]

To stop pinging on the Sounder S500:

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:

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

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:

python -m venv venv
source venv/bin/activate

Install dependencies:

pip install -e.
pip install pyserial

Then run the program:

python simpleS500Example.py

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