https://github.com/bluerobotics/ping-python
Python scripts and examples for the Ping sonar.
https://github.com/bluerobotics/ping-python
echosounder library ping rangefinder sonar
Last synced: 3 months ago
JSON representation
Python scripts and examples for the Ping sonar.
- Host: GitHub
- URL: https://github.com/bluerobotics/ping-python
- Owner: bluerobotics
- License: mit
- Created: 2016-11-08T14:56:47.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2026-01-17T11:51:30.000Z (5 months ago)
- Last Synced: 2026-01-17T14:36:17.456Z (5 months ago)
- Topics: echosounder, library, ping, rangefinder, sonar
- Language: Python
- Size: 5.2 MB
- Stars: 54
- Watchers: 6
- Forks: 38
- Open Issues: 47
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ping-python
[](https://travis-ci.org/bluerobotics/ping-python)
[](https://gitter.im/bluerobotics/discussion/)
[](https://badge.fury.io/py/bluerobotics-ping)
Python library for the Ping sonar. Ping is the simple, affordable, and compact ultrasonic altimeter for any aquatic project.
This library exposes all functionality of the device, such as getting profiles, controlling parameters, switching modes, or just simply reading in the distance measurement.
[Available here](https://www.bluerobotics.com/store/sensors-sonars-cameras/sonar/ping-sonar-r2-rp/)
## Resources
* [API Reference](https://docs.bluerobotics.com/ping-python/)
* [Device Specifications](https://www.bluerobotics.com/store/sensors-sonars-cameras/sonar/ping-sonar-r2-rp/#tab-technical-details)
* [Communication Protocol](https://github.com/bluerobotics/ping-protocol)
* [Support](https://gitter.im/bluerobotics/discussion)
* [License](https://github.com/bluerobotics/ping-python/blob/master/LICENSE)
## Installing
### pip
```sh
$ pip install --user bluerobotics-ping --upgrade
```
### From source
```sh
$ git clone --single-branch --branch deployment https://github.com/bluerobotics/ping-python.git
$ cd ping-python
$ python setup.py install --user
```
The library is ready to use: `import brping`. If you would like to use the command line [examples](/examples) or [tools](/tools) provided by this package, follow the notes in python's [installing to user site](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site) directions (eg `export PATH=$PATH:~/.local/bin`).
#### From master branch
If you wish to build from scratch the project using master branch or wip pull requests to test, you should compile and generate the definitions file:
```sh
$ git clone https://github.com/bluerobotics/ping-python.git
$ pip install jinja2
$ cd ping-python
$ git submodule update --init
$ python generate/generate-python.py --output-dir=brping
$ python setup.py install --user
$ python -c "import brping" # It works!
```
## Quick Start
The `bluerobotics-ping` package installs a `simplePingExample.py` script to get started. Place your device's file descriptor (eg. `/dev/ttyUSB0`, `COM1`) after the --device option.
`$ simplePingExample.py --device `
It's also possible to connect via UDP server using the `--udp` option with IP:PORT as input (e.g `192.168.2.2:9090`).
## Usage
The [Ping1D](https://docs.bluerobotics.com/ping-python/classPing_1_1Ping1D_1_1Ping1D.html) class provides an easy interface to configure a Ping device and retrieve data.
A Ping1D object must be initialized with the serial device path and the baudrate.
```py
from brping import Ping1D
myPing = Ping1D()
myPing.connect_serial("/dev/ttyUSB0", 115200)
# For UDP
# myPing.connect_udp("192.168.2.2", 9090)
```
Call initialize() to establish communications with the device.
```py
if myPing.initialize() is False:
print("Failed to initialize Ping!")
exit(1)
```
Use [`get_`](https://github.com/bluerobotics/ping-protocol#get) to request data from the device. The data is returned as a dictionary with keys matching the names of the message payload fields. The messages you may request are documented in the [ping-protocol](https://github.com/bluerobotics/ping-protocol).
```py
data = myPing.get_distance()
if data:
print("Distance: %s\tConfidence: %s%%" % (data["distance"], data["confidence"]))
else:
print("Failed to get distance data")
```
Use the [`set_*`](https://github.com/bluerobotics/ping-protocol#set) messages (eg. [set_speed_of_sound()](https://docs.bluerobotics.com/ping-python/classPing_1_1Ping1D_1_1Ping1D.html#a79a3931e5564644187198ad2063e5ed9)) to change settings on the Ping device.
```py
# set the speed of sound to use for distance calculations to
# 1450000 mm/s (1450 m/s)
myPing.set_speed_of_sound(1450000)
```
See the [doxygen](https://docs.bluerobotics.com/ping-python/) documentation for complete API documentation.