# Getting Started With Ping-Python ## Installation ### [Ping-Python GitHub Page](https://github.com/bluerobotics/ping-python) To get started, install the library either using pip (recommended) or from source. The library can be installed with pip like this: ```bash $ pip install --user bluerobotics-ping --upgrade ``` Or from source like this: ```bash $ git clone --single-branch --branch deployment https://github.com/bluerobotics/ping-python.git $ cd ping-python $ python setup.py install --user ``` 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: ```python 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. ```python myOS450 = Omniscan450() ``` The `Omniscan450` class allows for logging to the [SonarView log file format](https://app.gitbook.com/s/SYkdyxXfSDQsVcrx8VV1/replaying-saved-sonar-files). Logging can be enabled and log directory can be set during initialization. (Note: When no log directory is specified, it defaults to `../logs/omniscan` ) ```python 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. ```python 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](https://app.gitbook.com/s/CUzqaVB5SQQXiVUDPFqi/general-packet-definitions/device_information) and set up logging if it's enabled. It returns `True` if a response packet is returned or `False` otherwise. ```python 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](https://docs.ceruleansonar.com/c/omniscan-450/application-programming-interface#commands). The methods titled `control_` 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. ```python 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: ```python 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: ```python 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. ```python 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](https://docs.ceruleansonar.com/c/omniscan-450/application-programming-interface#ping-response-packets). For example, to access the `ping_number` field the corresponding attribute can be accessed like so: ```python 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. ```python 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: ```python pwr_db = myOS450.scale_power(data) ``` Elements of this list can be accessed with normal list operations: ```python first_element = pwr_db[0] ``` To stop pinging on the Omniscan: ```python 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: ```python 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: ```python myOS450.stop_logging() ``` ### Example Code The full example is provided below and can be run like this: ```bash $ python simpleOSExample.py ``` {% file src="" %} ### More Examples The [GitHub repository](https://github.com/bluerobotics/ping-python/blob/master/examples/omniscan450Example.py) contains a more detailed example which demonstrates more features like command-line arguments, signal handlers, and replaying from `.svlog` files.