# 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 `S500` and `definitions` modules can be imported like this: ```python 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. ```python myS500 = S500() ``` The `S500` class allows for logging to the [SonarView log file format](/c/sonarview/replaying-saved-sonar-files.md). Logging can be enabled and log directory can be set during initialization. (Note: When no log directory is specified, it defaults to `../logs/s500`) ```python myS500 = S500(logging=True, log_directory="logs/s500") ``` The Sounder S500 can communicate in a few ways which are detailed [here](/c/s-500-sounder/communicating-with-the-sounder-s500.md). 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](https://github.com/bluerobotics/ping-python/tree/master). 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. ```python 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](/c/cerulean-ping-protocol/general-packet-definitions/device_information.md) and set up logging if it's enabled. It returns `True` if a response packet is returned or `False` otherwise. ```python 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](/c/s-500-sounder/technical-details/programming-api.md#commands). The methods titled `control_` 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. ```python 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: ```python 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_()` methods, this is not the recommended way as the Sounder S500 will continually send packets after pinging is enabled. ```python 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](/c/s-500-sounder/technical-details/programming-api.md#ping-response-packets). For example, to access the `ping_number` field in the `profile6_t` packet, the corresponding attribute can be accessed like so: ```python 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. ```python 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: ```python pwr_db = myS500.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 Sounder S500: ```python 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: ```python 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: ```python S500.stop_logging() ``` ### Example Code The full example is provided below and can be run like this: ```bash $ python simpleS500Example.py ``` {% file src="/files/DxzxUOwV3xvgqeoS7CyF" %} ## More Examples The [GitHub repository](https://github.com/bluerobotics/ping-python/blob/master/examples/s500Example.py) contains a more detailed example which demonstrates more features like command-line arguments, signal handlers, and replaying from `.svlog` files. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ceruleansonar.com/c/s-500-sounder/getting-started-with-ping-python.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.