Getting Started With Ping-Python

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

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.

myOS450 = Omniscan450()

The Omniscan450 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/omniscan )

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.

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

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

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:

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:

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.

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

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:

pwr_db = myOS450.scale_power(data)

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

first_element = pwr_db[0]

To stop pinging on the Omniscan:

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:

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

myOS450.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 simpleOSExample.py

3KB

simpleOSExample.py

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.