Interact with the simulation#

An important feature of Parrot Sphinx is the control of the behaviour of simulated drone’s hardware/physical components. Components are typically the drone sensors, the propulsion group(s), or the aerodynamic model. For example, if you need to test your application with a drone that has no GPS signal, you can simply deactivate the GPS component for the desired duration.

Three interfaces are available to interact with components:

  • Web dashboard: the most convenient in case of manual tests

  • Command line: more appropriate to automatize sequences

  • Python API: for advanced usage

Web dashboard#

See the section about the Web dashboard.

Command line#

Within a shell, once Parrot Sphinx is started, you can issue commands with the sphinx-cli tool to perform various actions, such as display information about the simulation, print or modify a component parameter value, or trigger actions on a component.

For the most current list of commands and options, execute sphinx-cli --help.

Below are some examples that show how you can control the drone components with command lines thanks to sphinx-cli.

Example 1: The following example displays information about the running simulation:

$ sphinx-cli info

The returned object is built as follows:

{
    <machine>:
    {
      "components":
      [
        {
        "name": <objectid>,
        "type": <type>,
        "param1": ...,
        "param2": ...,
        ...
        },
        ...
      ]
   }
}

Example 2: The following example prints the list of available parameters:

$ sphinx-cli param -l

The returned object is built as follows:

{
    <machine> : { objectid/type : [param1, param2, ...] }
}

Example 3: The following example sets the variable update_rate of the GPS component to 5.0 for the drone named “anafi_ai”:

$ sphinx-cli param -m anafi_ai gps/gps update_rate 5.0

Example 4: The following example triggers the action start on the component handling/calibration for the drone named “anafi”:

$ sphinx-cli action -m anafi calibration start

Note

Some parameters can take sophisticated expressions in order to describe the behavior of the components as realistically as possible. They can be recognized by the “_expr” at the end of their name.

For example, if you want to have the wind follow sinusoidal variations with some gaussian noise, do the following:

$ sphinx-cli param -m world wind magnitude_expr "2 * sin(rtime) + 3 * noise()"

A dedicated section that explains how to write these expressions is available here : How to write expression to change HW component behavior

Python API#

Parrot Sphinx comes with a Python library called pysphinx. It provides access to components, telemetry, and cameras at runtime.

Before being able to use it, you have to set the LD_LIBRARY_PATH and PYTHONPATH environment variables such that programs can have access to pysphinx and its dependencies. To do that, within the shell where pysphinx will be used, enter the following command:

$ . /opt/parrot-sphinx/usr/bin/parrot-sphinx-setenv.sh

Here is a code snippet that shows how to use pysphinx to deactivate the GPS component of a drone named “anafi_ai”:

import pysphinx

# instantiate a Sphinx class to communicate with Parrot Sphinx
sphinx = pysphinx.Sphinx(ip="127.0.0.1", port=8383)

# get the GPS component
gps = sphinx.get_component(machine_name="anafi_ai", name="gps", type_="gps")

# deactivate the GPS component
gps.set_param(param="out_of_order", value="true")

Internals#

In Gazebo, drones and other actors in the simulation are represented by models in a world, and their components are implemented inside plugins. In Parrot Sphinx, three types of plugins are being used to simulate components:

  • Sensor plugins: For image type sensors like cameras, ultrasound, time-of-flight sensors, …

  • Model plugins: For other types of model components like IMU, magnetometer, GPS, …

  • World plugins: To control world properties like wind properties.

Parrot Sphinx lets you communicate with components of a running simulation by starting automatically a RPC server. The communication relies on JSON-RPC (version 2.0), which runs on top of an HTTP protocol.

By default, Parrot Sphinx’s JSON-RPC server is going to listen on port 8383 (decimal) through an HTTP server. If required, you can use the --json-rpc-port option with Parrot Sphinx command to specify a different port number. Note that, if you change the port number, you must also launch your UE4 applications with the -sphinx-port option set to the appropriate number.

sphinx-cli and pysphinx both rely on this protocol to communicate with Parrot Sphinx.

The Web dashboard communicates with Parrot Sphinx via another HTTP server that listens on port 9002 (decimal). If required, you can use the --http-port option with Parrot Sphinx command to specify a different port number.