Configuration at launch time¶
Important
This sections describes how to set the parameters and run the simulation using the command line.
In addition to the command line, Parrot Sphinx also comes with a launcher. See About Parrot Sphinx launcher
Before launching the simulation, you can play on many parameters to put the simulated drone in the desired context. The present section describes the most frequently used ones.
First of all, the command line help pages can be accessed this way:
$ parrot-ue<x>-<xxxxx> -help
$ sphinx --help
They provides a comprehensive list of all available command line parameters.
Depending on the feature you want to trigger/configure, you will need to act on
the command line either from sphinx command or from parrot-uex-xxxx.
The sphinx command line is composed of:
global options like
-hor--helpa path to a “.drone” file, which can be appended with drone parameters, each parameter being separated with two colons “::”. Here is a dummy example:
/path/to/my.drone::param1=value1::param2=value2. See detailed information below.
Choosing the world level¶
Most of the UE worlds come with several levels - or scenes. First, you can display the list of the available levels.
$ parrot-ue4-forest -list-levels
== Available levels ==========================================
- main
- sparse
==============================================================
Now, you can start the UE application selecting the desired level:
$ parrot-ue4-forest -level=sparse
Setting the spawn point¶
The spawn point is the place in the scene where the drone will be dropped at startup. It is common to have several spawn points available in a given world level. To list up the possible spawn points:
$ parrot-ue4-landscape-mountains -level=main -ams-path=DefaultPath,Pickup,Jasper
-list-spawn-points
== Available world spawn points ===========================================
- Name: Default
Pose: 136.084000 191.384995 130.190002 0.000000 -0.000000 0.000000
- Name: lake
Pose: 168.300003 59.299999 101.519997 0.000000 -0.000000 0.000000
== Available spawn points for vehicles ====================================
- Name: Pickup/roof
Pose: 73.095589 160.851761 136.603943 0.000000 7.916531 -40.431931
- Name: Pickup
Pose: 72.018608 161.769379 135.935638 0.000000 7.916531 -40.431931
== Available spawn points for characters ==================================
- Name: Jasper
Pose: 30.256489 216.198868 149.466949 0.000000 9.234401 -27.866959
===========================================================================
There is always a Default spawn point in every world level.
Now you can run sphinx with the selected spawn point, using the drone
parameter pose:
$ sphinx <my.drone>::pose=Lake
In case the predefined spawn points are not enough, you also can directly set the desired coordinates. Beware of taking a location slightly above the ground.
$ sphinx <my.drone>::pose="14.7 80.2 200.2 0 0 3.14159"
It is also possible to set a pose offset relative to the chosen spawn point,
using the drone parameter pose_offset.
$ sphinx <my.drone>::pose="default"::pose_offset="21.5 100.7 0.2 0 0 3.14159"
More information about poses and coordinates HERE
Setting custom GPS coordinates¶
It is possible to override the default GPS coordinates by some user-defined.
To do so, you need to add the option -gps-json to the
parrot-uex-xxx command line, like in the following example.
$ parrot-ue4-landscape-mountains -gps-json='{"lat_deg":-48.876667, "lng_deg":-123.393333, "elevation":1.5}'
Latitude and longitude are expressed in decimal degrees, while elevation is in meters.
Drone general settings¶
For each supported drone model, there is .drone file in Parrot Sphinx’
installation directory. More precisely, default .drone files
are all located here:
/opt/parrot-sphinx/usr/share/sphinx/drones/
The .drone file contains general settings of the drone to be simulated.
Below is a typical example:
<?xml version="1.0" encoding="UTF-8"?>
<drone name="my_awesome_drone"
firmware="https://url/to/my/anafi2-pc.ext2.zip"
hardware="anafi2">
<pose>default</pose>
<wifi_iface>auto</wifi_iface>
<wan_access>false</wan_access>
<remote_ctrl_ip></remote_ctrl_ip>
<ext_storage_size>8G</ext_storage_size>
<with_front_cam>1</with_front_cam>
<with_gimbal>1</with_gimbal>
<with_front_stcam>1</with_front_stcam>
<invisible_body>0</invisible_body>
</drone>
These settings are mainly related to connectivity and peripherals.
Every single field included in this file can be overridden through the sphinx
command line. If we wish to set the parameter wan_access to true:
$ sphinx <my.drone>::wan_access=true
On top of that change, let’s provide the path to a firmware image stored locally:
$ sphinx <my.drone>::wan_access=true::firmware="/to/my/local/firmware.ext2.zip"
Another way to customize the drone settings is copying the .drone file from the installation directory to a R/W directory of your choice, then editing the copied version.
Now let’s go through the generic parameters, i.e. not depending on the drone model.
name¶
Unique name of the drone.
hardware¶
String identifying the hardware on which the firmware image has to run.
firmware¶
Path or URL to the drone firmware. It can be expressed in several ways:
a path to an ext2.zip file, .e.g.
/home/myself/sphinx/anafi-pc.ext2.zipa HTTP link, e.g.
https://path/to/my/firmware.ext2.zipan FTP address, e.g.
ftp://myftpsite.com/myfirmware.ext2.zip
model¶
Path to the drone model folder to run Parrot Sphinx in Pure Model mode.
Parameters model and firmware cannot be set to a non-empty string
together. It would lead to a fatal error at startup.
pose¶
The pose parameter 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 expressed in Gazebo system.
See HERE for more details about the coordinates.
If the pose parameter is not defined, the spawn point named
“default” will be used by default.
pose_offset¶
The pose_offset parameter sets the pose offset of the drone’s center of
gravity relative to the chosen initial pose. Its value should be a list of
coordinates expressed in Gazebo system.
See HERE for more details about the coordinates.
If the pose_offset parameter is not defined, no offset will be used
by default.
wifi_iface¶
The wifi_iface parameter tells which Wi-Fi interface to take.
There are three possible ways to use this parameter:
empty string - Parrot Sphinx will not deploy any Wi-Fi AP.
auto- it automatically takes the first wireless interface available. If no interface is found, Wi-Fi link is deactivated silently.interface name as it appears on the host when running
iwconfig- this option is recommended when the host includes several wireless interfaces.
wifi_channel¶
When a regular Wi-Fi hardware is used as Wi-Fi interface for the simulated drone,
the only way to change the Wi-Fi channel is by adding the wifi_channel=<num>
drone parameter to the command line.
Note that when a physical drone is used as Wi-Fi interface, the entire Wi-Fi configuration is done at run time from the controller (e.g. Freeflight).
mountbind¶
The mountbind parameter sets the directory on host and the
directory on simulated drone where the first will be mounted. It must follow the
syntax host_dir:remote_mount_dir, where:
host_dir: absolute path of directory on host to mount on remote
remote_mount_dir: absolute path on remote where the directory
will be mounted (NOTE: bash expansion isn’t applied here).
Example:
<mountbind>/home/user/mission:/mnt/mission</mountbind>
fs_size¶
The fs_size parameter sets the drone’s system disk size.
If this parameter is omitted the drone will use the host file system
disk space. When this parameter 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.
[int/ext]_storage_size¶
The drone parameters int_storage_size and ext_storage_size
specify the size of the drone’s internal and external storages.
If the parameter is not set, a default value is used for the size of the
corresponding storage: 500M for int_storage_size, 10G for ext_storage_size.
If set to a value different from zero, a virtual device is created, mimicking
an SD card or an eMMC memory.
The given sizes can be expressed with units, like for the fs_size option.
E.g. 10M, 3G. Without unit, the values are supposed to be given in bytes.
The size can be suffixed by -raw, which leaves the storage in a “raw” state,
meaning that it requires to be partitioned and formatted,
which can be done using the same methods as with a real drone.
If the drone model does not include the storage for which we specify a size, the option has no effect.
Examples:
::int_storage_size=500M
::ext_storage_size=2G-raw
wan_access¶
The wan_access parameter is a boolean value (can take “0”, “1”, “false”,
or “true”). If set to true, it allows the simulated drone to access a Wide
Area Network, i.e. the Internet.
remote_ctrl_ip¶
If remote_ctrl_ip is left blank (default), the port forwarding mode is not
activated. Otherwise, it expects a valid IPv4 address, pointing to the host that
is going to run the controller application.
Model-specific configurations¶
| model-specific param | expected values | description | default |
|---|---|---|---|
| with_front_cam | 1 or 0 | if 0, remove the frontal camera to lower the resource needs | 1 |
| with_gimbal | 1 or 0 | if 1, activate all joints related to the gimbal(s). If 0, camera stabilization is faked. | 1 |
| with_front_stcam | 1 or 0 | if 1, add a stereo camera (i.e. a pair of cams) in the front part of the drone. | 0 |
| invisible_body | 1 or 0 | if 1, hides the drone's body. | 0 |
| with_tracking_hil | 1 or 0 | if 1, use a drone chipset to detect class objects and track targets. | 0 |
| with_depth_hil | 1 or 0 | if 1, add a stereo camera (i.e. a pair of cams) in the front part of the drone and use a drone chipset to generate realistic depth/disparity maps. | 0 |
| hil_ip | string containing an IP address | The IP address of the drone that will generate realistic depth/disparity maps if with_depth_hil=1 and detect class objects and track targets if with_tracking_hil=1. If you declare "auto", you indicate the the IP address will be found automatically. | auto |
| with_xlr | 1 or 0 | if 1, activates the ANAFI UKR XLR battery. | 0 |
drone |
model-specific param |
|---|---|
ANAFI |
with_front_cam |
ANAFI Ai |
with_front_cam |
ANAFI UKR |
with_front_cam |