bluerobotics / ping-python Goto Github PK

View Code? Open in Web Editor NEW

39.0 9.0 29.0 1.03 MB

Python scripts and examples for the Ping sonar.

License: MIT License

Python 96.46% Shell 3.54%

ping sonar rangefinder echosounder library

ping-python's Introduction

ping-python

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

Resources

Installing

pip

$ pip install --user bluerobotics-ping --upgrade

From source

$ 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 or tools provided by this package, follow the notes in python's installing to 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:

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

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.

if myPing.initialize() is False:
    print("Failed to initialize Ping!")
    exit(1)

Use get_<message_name> 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.

    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_* messages (eg. set_speed_of_sound()) to change settings on the Ping device.

    # 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 documentation for complete API documentation.

ping-python's People

Contributors

Stargazers

Watchers

ping-python's Issues

Firmware compliance test

Add script to test protocol compliance of device firmware - completely

add helper to set serial-usb driver to low latency mode

ping360 example

Is there any ping360 example ? or is it possible to get/find a more detailed documentation ?
How would one interoperate the raw data stream from it ?

Update ping1d class to use official request() message

Get exceptions and deal with it somehow without raising it

From: https://github.com/bluerobotics/companion/pull/295/files#r366465331

API is not consistent, there is snake cases and camel case functions

transmitAngle vs transmit_frequency

ci fails to move some files

Update gh-pages
mv: cannot move '/home/travis/build/bluerobotics/ping-python/doc/html/search' to '/tmp/update-repos/ping-python/search': Directory not empty

seen here: https://travis-ci.org/bluerobotics/ping-python/jobs/486132692#L582

Failed pip install on 0.0.4

$ pip install --user bluerobotics-ping
Collecting bluerobotics-ping
  Downloading https://files.pythonhosted.org/packages/09/31/d6a40a90e1add4148a431e3d14db776d00ed61ae2d4245ce69fecbe8c8b8/bluerobotics-ping-0.0.4.tar.gz
Collecting future (from bluerobotics-ping)
  Downloading https://files.pythonhosted.org/packages/90/52/e20466b85000a181e1e144fd8305caf2cf475e2f9674e797b222f8105f5f/future-0.17.1.tar.gz (829kB)
    100% |████████████████████████████████| 829kB 342kB/s 
Collecting pyserial (from bluerobotics-ping)
  Downloading https://files.pythonhosted.org/packages/0d/e4/2a744dd9e3be04a0c0907414e2a01a7c88bb3915cbe3c8cc06e209f59c30/pyserial-3.4-py2.py3-none-any.whl (193kB)
    100% |████████████████████████████████| 194kB 1.3MB/s 
Building wheels for collected packages: bluerobotics-ping, future
  Running setup.py bdist_wheel for bluerobotics-ping ... error
  Complete output from command /usr/bin/python -u -c "import setuptools, tokenize;__file__='/tmp/pip-build-bCJl1i/bluerobotics-ping/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" bdist_wheel -d /tmp/tmphY4Skipip-wheel- --python-tag cp27:
  /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'long_description_content_type'
    warnings.warn(msg)
  running bdist_wheel
  running build
  running build_py
  creating build
  creating build/lib.linux-armv7l-2.7
  creating build/lib.linux-armv7l-2.7/brping
  copying brping/ping1d.py -> build/lib.linux-armv7l-2.7/brping
  copying brping/__init__.py -> build/lib.linux-armv7l-2.7/brping
  copying brping/pingmessage.py -> build/lib.linux-armv7l-2.7/brping
  running build_scripts
  creating build/scripts-2.7
  copying and adjusting examples/simplePingExample.py -> build/scripts-2.7
  error: file '/tmp/pip-build-bCJl1i/bluerobotics-ping/brping/pingproxy.py' does not exist
  
  ----------------------------------------
  Failed building wheel for bluerobotics-ping
  Running setup.py clean for bluerobotics-ping
  Running setup.py bdist_wheel for future ... done
  Stored in directory: /home/pi/.cache/pip/wheels/0c/61/d2/d6b7317325828fbb39ee6ad559dbe4664d0896da4721bf379e
Successfully built future
Failed to build bluerobotics-ping
Installing collected packages: future, pyserial, bluerobotics-ping
  Running setup.py install for bluerobotics-ping ... error
    Complete output from command /usr/bin/python -u -c "import setuptools, tokenize;__file__='/tmp/pip-build-bCJl1i/bluerobotics-ping/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" install --record /tmp/pip-br7RvC-record/install-record.txt --single-version-externally-managed --compile --user --prefix=:
    /usr/lib/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'long_description_content_type'
      warnings.warn(msg)
    running install
    running build
    running build_py
    creating build
    creating build/lib.linux-armv7l-2.7
    creating build/lib.linux-armv7l-2.7/brping
    copying brping/ping1d.py -> build/lib.linux-armv7l-2.7/brping
    copying brping/__init__.py -> build/lib.linux-armv7l-2.7/brping
    copying brping/pingmessage.py -> build/lib.linux-armv7l-2.7/brping
    running build_scripts
    creating build/scripts-2.7
    copying and adjusting examples/simplePingExample.py -> build/scripts-2.7
    error: file '/tmp/pip-build-bCJl1i/bluerobotics-ping/brping/pingproxy.py' does not exist
    
    ----------------------------------------
Command "/usr/bin/python -u -c "import setuptools, tokenize;__file__='/tmp/pip-build-bCJl1i/bluerobotics-ping/setup.py';f=getattr(tokenize, 'open', open)(__file__);code=f.read().replace('\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))" install --record /tmp/pip-br7RvC-record/install-record.txt --single-version-externally-managed --compile --user --prefix=" failed with error code 1 in /tmp/pip-build-bCJl1i/bluerobotics-ping/

No timeout for reading sonar data

in readSonar() there is a chance that it could infinitely loop if the data was not valid, because it will never find a start character. There should be a timeout for this.

Creating a PingMessage instance always causes KeyError exception

In Ping1D's request() method, which is used by virtually every other communication method (including initialize()), you first create an empty PingMessage instance.
However, this causes PingMessage's constructor (init) to assign a message_id of 0, which immediately causes a KeyError in lines 465-480 of pingmessage.py.
As it stands, the Ping1D class is unusable. Please FIX it.
Thank you

James

Update Documentation when Serial Protocol is finalized

Add ci badge to readme

Verify location/permission of script files

pingproxy.py and ping1d-simulation.py perhaps belong in an examples/ or tools/ directory. They are not directly necessary for the library. They should maybe also have +x permissions, however this seems to be taken care of by python during installation, or they are called directly with python.

get_message works with a different api that wait_message

wait_message returns an object, you can access the item via: message.data
get_message returns an dict, you can only access the item via : message['data']

This results in a weird and not consistent api for our users.

Update README install instructions to reflect the new structure

now users should install the deployment branch instead

Bad attribute access in pingproxy

File "/usr/local/lib/python2.7/dist-packages/brping/pingproxy.py", line 95, in
 run                                                                            
    self.device.write(msg.msgData)                                              
AttributeError: 'PingMessage' object has no attribute 'msgData'

pypi deployment on tags is not working

https://travis-ci.org/bluerobotics/ping-python/builds/485966140#L483

error unpacking payload: 'PingMessage' object has no attribute 'payload_field_names'

When running the example, I'm getting the same error as this guy:
https://discuss.bluerobotics.com/t/python-to-access-the-ping-raw-data-on-raspberry-pi/4225/7

 ✘ patrick@pichau  /tmp  ~/.local/bin/simplePingExample.py --device /dev/ttyUSB0
Opening /dev/ttyUSB0 at 115200 bps
error unpacking payload: 'PingMessage' object has no attribute 'payload_field_names'
msg_data: bytearray(b'BBBR\x02\x00\xb2\x04\x00\x00\xc3\x12!\x02'), header: (66, 66, 21058, 2, 178, 4)
Traceback (most recent call last):
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 497, in unpack_msg_data
    payload = struct.unpack(PingMessage.endianess + self.get_payload_format(), self.msg_data[PingMessage.headerLength:PingMessage.headerLength + self.payload_length])                                                                                                                                            
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 540, in get_payload_format
    var_length = self.get_payload_length() - payload_dict[self.message_id]["payload_length"]  # Subtract static length portion from payload length
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 531, in get_payload_length
    return payload_dict[self.message_id]["payload_length"] + len(getattr(self, self.payload_field_names[-1]))
AttributeError: 'PingMessage' object has no attribute 'payload_field_names'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/patrick/.local/bin/simplePingExample.py", line 20, in <module>
    if myPing.initialize() is False:
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/ping1d.py", line 95, in initialize
    if self.request(pingmessage.PING1D_VOLTAGE_5) is None:
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/ping1d.py", line 114, in request
    return self.wait_message(m_id, timeout)
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/ping1d.py", line 126, in wait_message
    msg = self.read()
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/ping1d.py", line 76, in read
    if self.parser.parse_byte(ord(b)) == pingmessage.PingParser.NEW_MESSAGE:
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 664, in parse_byte
    self.rx_msg = PingMessage(msg_data=self.buf)
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 445, in __init__
    self.unpack_msg_data(msg_data)
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 501, in unpack_msg_data
    print("format: %s, buf: %s" % (PingMessage.endianess + self.get_payload_format(), self.msg_data[PingMessage.headerLength:PingMessage.headerLength + self.payload_length]))                                                                                                                                    
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 540, in get_payload_format
    var_length = self.get_payload_length() - payload_dict[self.message_id]["payload_length"]  # Subtract static length portion from payload length
  File "/home/patrick/.local/lib/python3.7/site-packages/brping/pingmessage.py", line 531, in get_payload_length
    return payload_dict[self.message_id]["payload_length"] + len(getattr(self, self.payload_field_names[-1]))
AttributeError: 'PingMessage' object has no attribute 'payload_field_names'

Cannot run simplePingExample.py after pip install

jack@jack-desktop:~$ python -m brping/ping1d
usage: ping1d.pyc [-h] --device DEVICE [--baudrate BAUDRATE]
ping1d.pyc: error: argument --device is required
jack@jack-desktop:~$ python -m simplePingExample.py
/usr/bin/python: No module named simplePingExample
jack@jack-desktop:~$ python simplePingExample.py
python: can't open file 'simplePingExample.py': [Errno 2] No such file or directory

Automatically update gh-pages branch

gh pages is not updating automatically to reflect changes in ping-protocol.

Update examples / doc for ping360

We should have some programming examples for ping360, and update our readme etc.

Wrong 'serial' module present can cause strange errors

The 'serial' package can cause some mistakes.
the correct one is 'pyserial'

error in python2:

python2  simplePingExample.py --device /dev/ttyUSB0 --baudrate 115200
Opening /dev/ttyUSB0 at 115200 bps
Failed to open the given serial port
('\t', AttributeError("'module' object has no attribute 'Serial'",))

Python3:

Failed to open the given serial port
	 module 'serial' has no attribute 'Serial'

get_device_id() returns dict and not int

The function is not clear, the user need to check the documentation to see what is going on.
https://docs.bluerobotics.com/ping-python/classbrping_1_1ping1d_1_1Ping1D.html#aff54fad6b6b55472bd09f31da949f9f6

Add UDP Support

The library should be able to interact with a Ping1D over UDP as well as over serial.

Update readme with generate/deploy instructions

simplePingExample.py: command not found

Instructions fail with a fresh install:

Error Ping on simulation

python tools/ping1d-simulation.py

Traceback (most recent call last):
  File "tools/ping1d-simulation.py", line 162, in <module>
    sim.sendMessage(PING1D_PROFILE)
  File "tools/ping1d-simulation.py", line 76, in sendMessage
    msg.pack_msg_data()
  File "/Users/senceryazici/Local Documents/auv/ping-python/brping/pingmessage.py", line 487, in pack_msg_data
    self.msg_data = bytearray(struct.pack(msg_format, *values))
struct.error: argument for 's' must be a string

Ping

Add CI

And add pip deployment for tagged releases

Identify connection problems properly

When a connection fail, there is an unfriendly error message about mode.
https://discuss.bluerobotics.com/t/ping-python-problem-ping360-object-has-no-attribute-mode/8268

Deploy package for python3 only in pypi

Add support for indicating serial file descriptor in command line argument

deal with in_waiting/inWaiting() changes in PySerial

Brian had this issue.
We should either work with both versions or require the newer one, might be good the check how available is the newer version.

simplePingExample.py hangs on init if wrong device is specified

We need a timeout here.

Improve examples to teach how to use the profile data

We should show users how to turn device_data and profile data into human-readable formats or visual representations as the ones we have in Ping-Viewer.

Installing with --user according to instructions renders scripts unavailable

More info here: https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site

"ImportError: No module named builtins" when running with Python2 in a pipenv

➜  teste2   pipenv run python  simplePingExample.py --device /dev/ttyUSB0 --baudrate 115200            
Traceback (most recent call last):
  File "simplePingExample.py", line 8, in <module>
    from builtins import input
ImportError: No module named builtins

don't document 'private' members

Doxygen outputting a tad TMI.

Error on unknown message id.

$ pingproxy.py --device /dev/serial/ping/Ping1D-id-1-t-1-m-1-v-3.26 
error unpacking payload: 6
msg_data: BR����P�, header: (66, 82, 2, 6, 0, 0)
Traceback (most recent call last):
  File "/usr/local/bin/pingproxy.py", line 112, in <module>
    proxy.run()
  File "/usr/local/bin/pingproxy.py", line 76, in run
    if e.errno == errno.EAGAIN:
AttributeError: 'exceptions.KeyError' object has no attribute 'errno'

Pypi deployment failed on 0.0.5

https://travis-ci.org/bluerobotics/ping-python/builds/486132691#L690

Add instructions on generating new Ping device type

There are some users interested in extending Ping-Protocol to support other devices with new messages. I just tested what it would take for a normal user to do that and here are instructions:

Copy message definitions and template from a similar device.

cd lib/ping-protocol/src/definitions
cp ping1d.json pinghf.json
cd ../../../../generate
cp ping1d.py.in pinghf.py.in

Open generate-python.py and add the following to the end:

definitionFile = "%s/pinghf.json" % definitionPath
templateFile = "%s/pinghf.py.in" % templatePath
f = open("%s/pinghf.py" % args.output_directory, "w")
f.write(g.generate(definitionFile, templateFile, {"structToken": struct_token}))
f.close()

Generate the new files:

python3 generate/generate-python.py --output-directory brping

Now in python3 you can from brping import pinghf.

Library exit without raising issue

Auto-detect device

Update gain values in the API Reference

The table for getGain() and setGain() in the API Reference is incorrect.

Learning django.

Learning django ❤️

How to scan as fast as ping-viewer in python

From my experiment, in Ping-viewer, Ping360 can scan 20 beams for one second. While when I keep all the parameters the same, and use transmitAngle(self, angle) in python, I can only scan 11 beams for one second.
I guess the reason is "in ping-viewer" we only have one command to scan a certain area. While in transmitAngle, we have arbitrary scan direction which have one command for each direction. Thus an arbitrary scan will have more delay.
So I wonder whether my guess is correct and how I can scan as fast as in ping-viewer (only scan certain area in the front of sonar)?
I appreciate your kindly help.
Thanks.

$ pip search bluerobotics-ping | grep bluerobotics-ping
bluerobotics-ping (0.0.3)               - A python module for the Blue Robotics Ping1D echosounder

pip install says the latest available is 0.0.2

$ pip install bluerobotics-ping==
Collecting bluerobotics-ping==
  Could not find a version that satisfies the requirement bluerobotics-ping== (from versions: 0.0.1.dev4, 0.0.1.dev5, 0.0.1, 0.0.2)
No matching distribution found for bluerobotics-ping==

setup.py says 0.0.1: https://github.com/bluerobotics/ping-python/blob/master/setup.py#L9

Let's cut a new release and clean up this situation (we must leave the current versions in pypi for now, as companion depends on 0.0.2).