Anatomy of a ‘.drone’ file

There are many ways to start Sphinx, open worlds and spawn drones. To start an empty world with a single drone, simply run:

$ sphinx <path/to/my.drone>

To start an existing world and spawn a drone into it:

$ sphinx <path/to/my.world> <path/to/my.drone>

The .drone file contains a description of the drone to be simulated in Sphinx. Sample .drone files can be found in the installed version (default install) under:

/opt/parrot-sphinx/usr/share/sphinx/drones

Let’s take a .drone file example and detail it in the next section.

<?xml version="1.0"?>
<drone
  name="bebop2"
  firmware="http://plf.parrot.com/sphinx/firmwares/ardrone3/milos_pc/latest/images/ardrone3-milos_pc.ext2.zip"
  hardware="milosboard">
  <sdf_params
    low_gpu="false"
    with_front_cam="true" />
  <pose>landing_area</pose>
  <interface>eth1</interface>
  <stolen_interface>wlan0:eth0:192.168.42.1/24</stolen_interface>
  <wifi_channel>6</wifi_channel>
  <stolen_bdaddr>00:00:00:00:00:00</stolen_bdaddr>
  <fs_size>1G</fs_size>
</drone>

Note: Most drone options can be changed from command line. To see the list of available drone options, type:

$ sphinx --help

Thus, to add or to override an option from the command line, you can use the following syntax:

$ sphinx <path/to/my.drone>::<name1>=<value1>::<name2>::<value2>...

For example, to set the wifi channel and the disk size of the drone:

$ sphinx <path/to/my.drone>::wifi_channel=2::fs_size=1G

<sdf_params> attributes can also be set via command line in the same manner. For example, to disable the front camera:

$ sphinx <path/to/my.drone>::with_front_cam=false

The code explained

The first part of the code sets the unique name of the drone, the path to its firmware (check section Path to the firmware for more details) and the board on which the firmware will run (check section Hardware strings for more details).

<drone
  name="bebop2"
  firmware="http://plf.parrot.com/sphinx/firmwares/ardrone3/milos_pc/latest/images/ardrone3-milos_pc.ext2.zip"
  hardware="milosboard">

The optional <sdf_params> tag provides options to customize the way the drone will work. The available sdf_params depend on the drone. More details are given in section Drone sdf_params. If sdf_params are not specified, default values are used.

<sdf_params
  low_gpu="false"
  with_front_cam="true" />

The optional <pose> tag sets the initial pose of the drone’s center of gravity. Its value could either be the name of an existing spawn point in the world or a list of coordinates (x y z roll pitch yaw in meters and radians). The list of spawn points for a given world can be found in its fwman plugin configuration. If the <pose> tag is not defined, the spawn point named “default” will be used by default.

When using coordinates, care must be taken to properly set the z coordinate. If it is too high, the drone is going to fall badly at simulation start. If it is too low, the drone will be dug into the floor, and by reaction, the physics engine will make it springs erratically.

<pose>landing_area</pose>

The mandatory <interface> tag sets the name of the virtual ethernet interface’s end, living in the drone’s firmware instance, it must be set to avoid collisions with the name of the wifi interface, if any.

<interface>eth1</interface>

The optional <stolen_interface> tag configures the wifi interface of the simulated drone. It follows the syntax: NAME:NAME_ONCE_ASSIGNED:IP_ADDRESS where

  • NAME is the name of your wifi interface as it appears on the host when entering ifconfig command.

For the currently supported drones,

  • NAME_ONCE_ASSIGNED must be ‘eth0’,
  • IP_ADDRESS must be ‘192.168.42.1/24’.
<stolen_interface>wlan0:eth0:192.168.42.1/24</stolen_interface>

The optional <wifi_channel> tag forces the use of a specific wifi channel. In some particular cases, this option can help you out.

<wifi_channel>6</wifi_channel>

The optional <stolen_bdaddr> tag sets the MAC address of the Bluetooth interface to be used by the simulated drone. This element is a must if your drone needs a Bluetooth connection.

<stolen_bdaddr>00:00:00:00:00:00</stolen_bdaddr>

The optional <fs_size> tag sets the drone disk space available in the root file system. If this tag is omitted the drone will use the host file system disk space. When this tag is present, it must contain a valid memory size: a positive integer optionally followed by a metric prefix ‘k’, ‘K’, ‘m’, ‘M’, ‘g’ or ‘G’. For example “1048576”, “1m” or “1M” are all equivalent to a 1 MB available disk space. The maximum value for this option is 2 GB.

  <fs_size>1G</fs_size>
</drone>

Hardware strings

Available hardware strings

Drone Hardware name
Bebop mykonos3board
Bebop2 milosboard
Disco evinrudeboard
Airborne delosevosip6board
Mambo delos3board
Swing wingxboard

Path to the firmware

The path to the firmware can be expressed in several ways:

Important note: The firmware images of commercial versions are hosted on a dedicated public server. One can browse all available images by accessing the following URL: http://plf.parrot.com/sphinx/firmwares/index.html

Drone sdf_params

sdf_param expected values description default
with_front_cam true or false if false, remove the frontal camera to lower the ressource needs true
low_gpu true or false if true, reduce camera rendering quality to speed up GPU processing false
with_bumpers true or false if true, add bumpers around drone's body false
with_sequoia_payload true or false if true, add the mass of sequoia boxes in drone's body false
with_hd_battery true or false if true, use an HD battery false
with_flir true or false if true, attach and simulate a FLIR One Thermal camera on the drone. Mass and inertia of the drone are affected by this property even if there is no visual for the FLIR camera false
flir_pos vertical, horizontal or tilted define the orientation of the FLIR One Camera (if with_flir=true) tilted
swing_color black or white set the drone's color black
evo_type hydrofoil, light or brick set the drone's type brick
evo_style travis, mars, swat, maclane, orak, blaze or newz set the drone's style mars

Valid sdf_params by drone models:

drone sdf_param
Bebop with_bumpers
with_front_cam
low_gpu
Bebop2 with_front_cam
with_hd_battery
with_flir
flir_pos
low_gpu
Disco with_front_cam
low_gpu
with_sequoia_payload
Airborne with_bumpers
evo_style
evo_type
Mambo  
Swing swing_color