By default, actors have an omniscient plugin, so if you launch sphinx with the --datalog
option, you should be able to get their odometry via telemetry as explained here.
Here is an explanation on how to use actors. This tutorial is yet to be included in Sphinx documentation:
How to use Follow Me with Parrot-Sphinx
This tutorial shows how to set up your world to use the Follow Me mode with Parrot-Sphinx.
Set up your world
Below is a command line example that shows how to insert a drone and a pedestrian actor with a prefined path into the scene:
sphinx /opt/parrot-sphinx/usr/share/sphinx/drones/anafi4k.drone::name=follower \
/opt/parrot-sphinx/usr/share/sphinx/actors/pedestrian.actor::machine=follower::path=/opt/parrot-sphinx/usr/share/sphinx/paths/square_walk.path
Actors come with GPS and barometer plugins. When properly configured, the drone can receive the actor barometer and GPS data from Parrot-Sphinx instead of FreeFlight. To do that, you must set the actor machine
parameter to the name of the drone.
Note: It is possible to send barometer and GPS data to multiple drones:
sphinx /opt/parrot-sphinx/usr/share/sphinx/drones/anafi4k.drone::name=follower1 \
/opt/parrot-sphinx/usr/share/sphinx/actors/pedestrian.actor::machine=follower1::machine=follower2::path=/opt/parrot-sphinx/usr/share/sphinx/paths/square_walk.path
Parameters
Actor parameters can be modified by command line while launching Parrot-Sphinx. Let’s go through each item:
-
name holds the name of the actor. It must be unique, so if you insert two actors of the same type into the scene, you must at least change the name of one of them. The default value is
pedestrian
for pedestrian actors and vehicle
for vehicle actors.
-
pose holds the initial position and orientation of the actor in world coordinates. By default, the actor appears at the origin.
-
path file containing the description of a path as a list of waypoints in XML format. This parameter can be repeated to create multiple paths.
-
selected_path holds the name of the path that the actor will follow at startup. By default, this parameter is set to the first defined path.
-
machine holds the name of the machine the actor’s sensors (GPS, barometer) will send their data to. This parameter can be repeated to send the data to multiple drones.
Path files
Path files contain the description of a path in XML format. As an example, this is the content of the /opt/parrot-sphinx/usr/share/sphinx/paths/square_walk.path
file:
<?xml version="1.0" encoding="UTF-8"?>
<path name="square_walk">
<loop>true</loop>
<auto_start>true</auto_start>
<delay_start>1</delay_start>
<waypoint>
<animation>walk</animation>
<velocity>1</velocity>
<xy>0 0</xy>
</waypoint>
<waypoint>
<animation>run</animation>
<velocity>2</velocity>
<xy>0 10</xy>
</waypoint>
<waypoint>
<animation>run</animation>
<velocity>2</velocity>
<xy>10 10</xy>
</waypoint>
<waypoint>
<animation>walk</animation>
<velocity>1</velocity>
<xy>10 0</xy>
</waypoint>
<waypoint>
<animation>walk</animation>
<velocity>1</velocity>
<xy>0 0</xy>
</waypoint>
</path>
In above example, the path name is square_walk
. The <path>
contains the list of waypoints that the actor will travel to in sequence.
If the element is set to true, the animation will loop once the actor gets to the last waypoint. If the <auto_start>
element is set to true, the animation starts immediately once selected. The <delay_start>
element can be used to set the amount of time to delay start by.
For pedestrian actors, each <waypoint>
element may contain an <animation>
element which identifies the animation to be played while moving the actor towards the waypoint. By default, the walk
animation is used.
The <velocity>
element is used to set the velocity of the actor in m/s. The waypoint position can either be defined with a <xy>
element or a <model>
element. A <xy>
element contains a position(x,y) with respect to the world frame. A <model>
element contains the name of the model whose position will be
used as the destination. The <stop_duration>
element can be used to set the amount of time the actor will remain at this position before moving to the next waypoint.
Another method for defining a path is to include it from another file:
<path name="external_path">
<filename>/path/to/path.xml</filename>
</path>
User interface
You can select a path either by command line or via the Web interface. See
https://developer.parrot.com/docs/sphinx/pluginctrl_ifaces.html.
Once a path is selected, the actor can be started, stopped and paused, by sending the start
, stop
, and pause
actions to the actor plugin. The pause
action has no effect on vehicle actors.
The visibility of the actor can be controlled with the visible
parameter.
Note that if you used <model>
instead of <xy>
elements to define the position of a waypoint, you can redefine your path while it is playing by sending a pause
action and move the models associated with the waypoints. Once you are satisfied with your new path, simply send a pause
action to resume the
animation or send a stop
action followed by a play
action to restart it from the beginning.
Actor files
1. Pedestrian actors
Pedestrian actors are Gazebo animated characters based on captured pedestrian motion. They can be used to replay captured motion, or to use motion sequences for user-defined complex behaviours.
The file /opt/parrot-sphinx/usr/share/sphinx/actors/pedestrian.actor
contains the description of pedestrian actors. It can be modified to change the default actor’s behaviour.
The <skin>
block tells Gazebo where to find the mesh file that contains the actor’s skin. The <actor>
element contains a child for each skeleton animation contained in mesh files.
The <animation_factor
> element in the actor plugin definition describes the time scaling factor that is used to coordinate translational motion with the actor’s walking animation.
2. Vehicle actors
Vehicle actors are simulated vehicles that can follow a predefined path or be controlled by the user. Right now, the only supported vehicle is a small off-road vehicle.
The file /opt/parrot-sphinx/usr/share/sphinx/actors/off_road_vehicle.actor
contains the description of off-road vehicle actors. It can be modified to tune the vehicle configuration. For example, PID gains can be tuned for each front wheel. The <max_speed>
element defines the maximum speed of the vehicle. The <max_steer>
element defines the maximum steering angle of the front wheels. The <min_brake_percent>
element is used to approximate rolling resistance and engine braking.
Below is a command line example that shows how to insert a drone and a vehicle with a predefined path into the scene:
sphinx /opt/parrot-sphinx/usr/share/sphinx/worlds/outdoor_1.world \
/opt/parrot-sphinx/usr/share/sphinx/drones/anafi4k.drone::name=follower::pose=starting_pen \
/opt/parrot-sphinx/usr/share/sphinx/actors/off_road_vehicle.actor::machine=follower::path=/opt/parrot-sphinx/usr/share/sphinx/paths/follow_road.path
In this example, waypoints are positioned along the road defined in the scene of /opt/parrot-sphinx/usr/share/sphinx/worlds/outdoor_1.world
.
Keyboard controls
A GUI plugin can be used to publish Vehicle messages to control the vehicle’s throttle, brake, and steering with your keyboard:
<plugin name="libsphinx_vehicle_gui" filename="libsphinx_vehicle_gui.so">
<model_name>vehicle</model_name>
</plugin>
It must be copied into your world file before the </gui>
tag. Next you can find the available Vehicle control keys:
Left-Key Increase hand wheel (+20 degree)
Right-Key Decrease hand wheel (-20 degree)
Up-Key Increase gas pedal (+30 %)
Down-Key Decrease gas pedal (-30 %)
h Increase hand brake (+30 %)
n Decrease hand brake (-30 %)
g Increase brake pedal (+30 %)
b Decrease brake pedal (-30 %)
Command line controls
It is also possible to control the vehicle by executing commands in the shell, or in your favorite scripting language.
To set the gas pedal:
/opt/parrot-sphinx/usr/bin/parrot-gz topic -r cmd_gas_pedal -m
To set the handbrake level:
/opt/parrot-sphinx/usr/bin/parrot-gz topic -r cmd_hand_brake -m
To set the brake pedal level:
/opt/parrot-sphinx/usr/bin/parrot-gz topic -r cmd_brake_pedal -m
To control the wheel:
/opt/parrot-sphinx/usr/bin/parrot-gz topic -r cmd_hand_wheel -m