Parrot AR.Drone Drone Developer Guide
Annonce
Annonce
Developer Guide
SDK 1.7
2
Prepared
Stephane Piskorski
Nicolas Brulez
Pierre Eline
Approved
Title
AR.Drone Developer Guide
Date Revision
May 17, 2011 SDK 1.7
File
Notations used in this document :
$ This is a Linux shell command line (the dollar sign represents the shell prompt and should not be typed)
This is a console output (do not type this)
Here is a file_name.
Here is a
macro
.
iPhone®and iPod Touch®are registered trademarks of Apple Inc.
Wi-Fi®is a trademark of the Wi-Fi Alliance.
Visuals and technical specifications subject to change without notice. All Rights reserved.
The Parrot Trademarks appearing on this document are the sole and exclusive property of Parrot S.A. All the others
Trademarks are the property of their respective owners.
Contents
A.R.Drone Developer Guide
Contents
I SDK documentation
1 Introduction
2 AR.Drone Overview
2.1
Introduction to quadrotor UAV . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2
Indoor and outdoor design configurations . . . . . . . . . . . . . . . . . . . . . . .
2.3
Engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4
LiPo batteries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5
Motion sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6
Assisted control of basic manoeuvres . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7
Advanced manoeuvres using host tilt sensors . . . . . . . . . . . . . . . . . . . . .
2.8
Video streaming and tags detection . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9
Wifi network and connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.10 Communication services between the AR.Drone and a client device . . . . . . . .
3 AR.Drone SDK Overview
3.1
Layered architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2
The AR.Drone Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3
The AR.Drone Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4
The AR.Drone Control Engine - only for Apple iPhone . . . . . . . . . . . . . . . . .
4
ARDroneLIB and ARDroneTool functions
4.1
Drone control functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ardrone_tool_set_ui_pad_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ardrone_tool_set_ui_pad_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ardrone_at_set_progress_cmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2
Drone configuration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ardrone_at_navdata_demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ardrone_at_set_navdata_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 Creating an application with ARDroneTool
5.1
Quick steps to create a custom AR.Drone application . . . . . . . . . . . . . . . .
5.2
Customizing the client initialization . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3
Using navigation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
i
ii
5.4
Command line parsing for a particular application . . . . . . . . . . . . . . . . . .
5.5
Thread management in the application . . . . . . . . . . . . . . . . . . . . . . . . .
5.6
Managing the video stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7
Adding control devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6 AT Commands
6.1
AT Commands syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2
Commands sequencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3
Floating-point parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4
Deprecated commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5
AT Commands summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6
Commands description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*REF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*PCMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*FTRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*CONFIG_IDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*COMWDG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*LED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AT*ANIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7 Incoming data streams
7.1
Navigation data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1.1
Navigation data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1.2
Initiating the reception of Navigation data . . . . . . . . . . . . . . . . . .
7.1.3
Augmented reality data stream . . . . . . . . . . . . . . . . . . . . . . . . .
7.2
The video stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.1
Image structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.2
UVLC codec overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.3
P264 codec overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.4
Specific block entropy-encoding . . . . . . . . . . . . . . . . . . . . . . . .
7.2.5
Transport layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.6
End of sequence (EOS) (22 bits) . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.7
Intiating the video stream . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8 Drone Configuration
8.1
Reading the drone configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1
With ARDroneTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.2
Without ARDroneTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2
Setting the drone configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.1
With ARDroneTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2
From the Control Engine for iPhone . . . . . . . . . . . . . . . . . . . . . .
8.2.3
Without ARDroneTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3
Multiconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.1
With ARDroneTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.2
Multiconfiguration with Control Engine (iPhone only) . . . . . . . . . . .
8.3.3
Without ARDroneTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.4
Common category (CAT_COMMON) . . . . . . . . . . . . . . . . . . . . .
8.3.5
Application category (CAT_APPLI) . . . . . . . . . . . . . . . . . . . . . .
8.3.6
User category (CAT_USER) – also called "Profile" category . . . . . . . . .
8.3.7
Session category (CAT_SESSION) . . . . . . . . . . . . . . . . . . . . . . .
8.3.8
Technical details on id generation and descriptions . . . . . . . . . . . . .
iii
8.4
General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:num_version_config . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:num_version_mb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:num_version_soft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:soft_build_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:motor1_soft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:motor1_hard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:motor1_supplier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:ardrone_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:flying_time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:navdata_demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:navdata_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:com_watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:video_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:vision_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GENERAL:vbat_min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.5
Control configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:accs_offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:accs_gains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:gyros_offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:gyros_gains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:gyros110_offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:gyros110_gains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:gyro_offset_thr_x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:pwm_ref_gyros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:control_level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:shield_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:euler_angle_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:altitude_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:altitude_min . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:control_trim_z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:control_iphone_tilt . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:control_vz_max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:control_yaw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:outdoor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:flight_without_shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:brushless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:autonomous_flight . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:manual_trim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:indoor_euler_angle_max . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:indoor_control_vz_max . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:indoor_control_yaw . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:outdoor_euler_angle_max . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:outdoor_control_vz_max . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:outdoor_control_yaw . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:flying_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTROL:flight_anim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.6
Network configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:ssid_single_player . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:ssid_multi_player . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
NETWORK:secure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:passkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:navdata_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:video_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:at_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:cmd_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:owner_mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:owner_ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:local_ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NETWORK:broadcast_ip_address . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.7
Nav-board configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PIC:ultrasound_freq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PIC:ultrasound_watchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PIC:pic_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.8
Video configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:camif_fps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:camif_buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:num_trackers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:bitrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:bitrate_control_mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:video_codec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VIDEO:videol_channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.9
Leds configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LEDS:leds_anim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.10 Detection configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:enemy_colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:groundstripe_colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:enemy_without_shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:detect_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:detections_select_h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:detections_select_v_hsync . . . . . . . . . . . . . . . . . . . . . . . . . .
DETECT:detections_select_v . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.11 SYSLOG section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.12 CUSTOM section - Multiconfig support . . . . . . . . . . . . . . . . . . . . . . . .
CUSTOM:application_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CUSTOM:application_desc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CUSTOM:profile_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CUSTOM:profile_desc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CUSTOM:session_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CUSTOM:session_desc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9 F.A.Q.
II Tutorials
10 Building the iOS Example
11 Building the Linux Examples
11.1 Set up your development environment . . . . . . . . . . . . . . . . . . . . . . . . .
11.2 Prepare the source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.3 Compile the SDK Demo example . . . . . . . . . . . . . . . . . . . . . . . . . . . .
v
11.4 Run the SDK Demo program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.5 Compile the Navigation example . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.6 Run the Navigation program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12 Building the Windows Example
12.1 Set up your development environment . . . . . . . . . . . . . . . . . . . . . . . . .
12.2 Required settings in the source code before compiling . . . . . . . . . . . . . . . .
12.3 Compiling the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.4 What to expect when running the example . . . . . . . . . . . . . . . . . . . . . .
12.5 Quick summary of problems solving . . . . . . . . . . . . . . . . . . . . . . . . . .
13 Other platforms
13.1 Android example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Part I
SDK documentation
1
1
Introduction
Welcome to the AR.Drone Software Development Kit !
The AR.Drone product and the provided host interface example have innovative and exciting features such as:
• intuitive touch and tilt flight controls
• live video streaming and photo shooting
• updated Euler angles of the AR Drone
• embedded tag detection for augmented reality games
The AR.Drone SDK allows third party developers to develop and distribute new games based on AR.Drone product for Wifi, motion sensing mobile devices like game consoles, the Apple iPhone, iPod touch, the Sony PSP, personal computers or Android phones.
To download the AR.Drone SDK, third party developers will have to register and accept the
AR.Drone SDK License Agreement terms and conditions. Upon final approval from Parrot, they will have access to the AR.Drone SDK download web page.
This SDK includes :
• this document explaining how to use the SDK, and describes the drone communications protocols;
• the AR.Drone Library (ARDroneLIB ), which provides the APIs needed to easily communicate and configure an AR.Drone product;
• the AR.Drone Tool (ARDroneTool ) library, which provides a fully functionnal drone client where developers only have to insert their custom application specific code;
• the AR.Drone Control Engine library which provides an intuitive control interface developed by Parrot for remotely controlling the AR.Drone product from an iPhone;
3
4
• an open-source iPhone game example, several code examples that show how to control the drone from a Linux or Windows personal computer, and a simple example for Android phones.
Where should I start ?
Please first read chapter
to get an overview of the drone abilities and a bit of vocabulary.
You then have the choice between :
• using the provided library
and modifying the provided examples ( 10 ,
your needs
• trying to write your own software from scratch by following the specifications given in
and
2
AR.Drone Overview
2.1
Introduction to quadrotor UAV
AR.Drone is a quadrotor. The mechanical structure comprises four rotors attached to the four ends of a crossing to which the battery and the RF hardware are attached.
Each pair of opposite rotors is turning the same way. One pair is turning clockwise and the other anti-clockwise.
5
6
(a) Throttle (b) Roll
(c) Pitch
Figure 2.1: Drone movements
(d) Yaw
Manoeuvres are obtained by changing pitch, roll and yaw angles of the AR.Drone .
Varying left and right rotors speeds the opposite way yields roll movement. This allows to go forth and back.
Varying front and rear rotors speeds the opposite way yields pitch movement.
Varying each rotor pair speed the opposite way yields yaw movement. This allows turning left and right.
7
(a) Indoor (b) Outdoor
Figure 2.2: Drone hulls
2.2
Indoor and outdoor design configurations
When flying outdoor the AR.Drone can be set in a light and low wind drag configuration ( 2.2b
Flying indoor requires the drone to be protected by external bumpers ( 2.2a
When flying indoor, tags can be added on the external hull to allow several drones to easily detect each others via their cameras.
2.3
Engines
The AR.Drone is powered with brushless engines with three phases current controlled by a micro-controller
The AR.Drone automatically detects the type of engines that are plugged and automatically adjusts engine controls. The AR.Drone detects if all the engines are turning or are stopped. In case a rotating propeller encounters any obstacle, the AR.Drone detects if any of the propeller is blocked and in such case stops all engines immediately. This protection system prevents repeated shocks.
8
(a) Ultrasound sensor
Figure 2.3: Drone Sensors
(b) Camera
2.4
LiPo batteries
The AR.Drone uses a charged 1000mAh, 11.1V LiPo batteries to fly. While flying the battery voltage decreases from full charge (12.5 Volts) to low charge (9 Volts). The AR.Drone monitors battery voltage and converts this voltage into a battery life percentage (100% if battery is full,
0% if battery is low). When the drone detects a low battery voltage, it first sends a warning message to the user, then automatically lands. If the voltage reaches a critical level, the whole system is shut down to prevent any unexpected behaviour.
2.5
Motion sensors
The AR.Drone has many motions sensors. They are located below the central hull.
The AR.Drone features a 6 DOF, MEMS-based, miniaturized inertial measurement unit. It provides the software with pitch, roll and yaw measurements.
Inertial measurements are used for automatic pitch, roll and yaw stabilization and assisted tilting control. They are needed for generating realistic augmented reality effects.
An ultrasound telemeter provides with altitude measures for automatic altitude stabilization and assisted vertical speed control.
A camera aiming towards the ground provides with ground speed measures for automatic hovering and trimming.
2.6
Assisted control of basic manoeuvres
Usually quadrotor remote controls feature levers and trims for controlling UAV pitch, roll, yaw and throttle. Basic manoeuvres include take-off, trimming, hovering with constant altitude, and landing. It generally takes hours to a beginner and many UAV crashes before executing safely these basic manoeuvres.
Thanks to the AR.Drone onboard sensors take-off, hovering, trimming and landing are now completely automatic and all manoeuvres are completely assisted.
9
User interface for basics controls on host can now be greatly simplified :
• When landed push take-off button to automatically start engines, take-off and hover at a pre-determined altitude.
• When flying push landing button to automatically land and stop engines.
• Press turn left button to turn the AR Drone automatically to the left at a predetermined speed. Otherwise the AR Drone automatically keeps the same orientation.
• Press turn right button to turn the AR Drone automatically to the right. Otherwise the AR
Drone automatically keeps the same orientation.
• Push up button to go upward automatically at a predetermined speed. Otherwise the AR
Drone automatically stays at the same altitude.
• Push down to go downward automatically at a predetermined speed. Otherwise the AR
Drone automatically stays at the same altitude.
A number of flight control parameters can be tuned:
• altitude limit
• yaw speed limit
• vertical speed limit
• AR.Drone tilt angle limit
• host tilt angle limit
2.7
Advanced manoeuvres using host tilt sensors
Many hosts now include tilt motion sensors. Their output values can be sent to the AR.Drone
as the AR.Drone tilting commands.
One tilting button on the host activates the sending of tilt sensor values to the AR.Drone . Otherwise hovering is a default command when the user does not input any manoeuvre command.
This dramatically simplifies the AR.Drone control by the user.
The host tilt angle limit and trim parameters can be tuned.
10
2.8
Video streaming and tags detection
The frontal camera is a CMOS sensor with a 90 degrees angle lens.
The AR.Drone automatically encodes and streams the incoming images to the host device.
QCIF and QVGA image resolutions are supported. The video stream frame rate is set to 15 Hz.
Tags painted on drones can be detected by the drone front camera. These tags can be used to detect other drones during multiplayer games, or to help a drone find its way in the environment. Both tags on the external and internal hull can be detected.
(a) 2D tags on outdoor shell (b) 2D tags on indoor shell
Figure 2.4: Drone shell tags
2.9
Wifi network and connection
The AR.Drone can be controlled from any client device supporting the Wifi ad-hoc mode. The following process is followed :
1. the AR.Drone creates a WIFI network with an ESSID usually called adrone_xxx and self allocates a free, odd IP address.
2. the user connects the client device to this ESSID network.
3. the client device requests an IP address from the drone DHCP server.
4. the AR.Drone DHCP server grants the client with an IP address which is :
• the drone own IP address plus 1 (for drones prior to version 1.1.3)
• the drone own IP address plus a number between 1 and 4 (starting from version
1.1.3)
5. the client device can start sending requests the AR.Drone IP address and its services ports.
The client can also initiate the Wifi ad-hoc network. If the drone detects an already-existing network with the SSID it intented to use, it joins the already-existing Wifi channel.
11
2.10
Communication services between the AR.Drone and a client device
Controlling the AR.Drone is done through 3 main communication services.
Controlling and configuring the drone is done by sending AT commands on UDP port 5556.
The transmission latency of the control commands is critical to the user experience. Those commands are to be sent on a regular basis (usually 30 times per second). The list of available commands and their syntax is discussed in chapter
Information about the drone (like its status, its position, speed, engine rotation speed, etc.), called navdata, are sent by the drone to its client on UDP port 5554. These navdata also include tags detection information that can be used to create augmented reality games. They are sent approximatively 30 times per second.
A video stream is sent by the AR.Drone to the client device on port 5555. Images from this video stream can be decoded using the codec included in this SDK. Its encoding format is discussed in section
A fourth communication channel, called control port, can be established on TCP port 5559 to transfer critical data, by opposition to the other data that can be lost with no dangerous effect.
It is used to retrieve configuration data, and to acknowledge important information such as the sending of configuration information.
3
AR.Drone SDK
Overview
This SDK allows you to easily write your own applications to remotely control the drone :
• from any personal computer with Wifi connectivity (Linux or Windows);
• from an Apple iPhone;
• (soon) from an Android mobile phone.
It also allows you, with a bit more effort, to remotely control the drone from any programmable device with a Wifi network card and a TCP/UDP/IP stack - for devices which are not supported by Parrot, a complete description of the communication protocol used by the drone is given in this document;
However, this SDK does NOT support :
• rewriting your own embedded software - no direct access to the drone hardware (sensors, engines) is allowed.
3.1
Layered architecture
Here is an overview of the layered architecture of a host application built upon the AR.Drone
SDK.
13
14
Application level
Host application
Application threads
ARDrone Control
Engine (only for iPhone)
Threads level host sw
Host hw
ARDrone
Library
Data streams AT cmds
Host hw/sw API openGL Wifi Touchpad Accelerometer
3.2
The AR.Drone Library
The AR.Drone Library is currently provided as an open-source library with high level APIs to access the drone.
Let’s review its content :
• S
OFT
: the drone-specific code, including :
– C
OMMON
: header (.h) files describing the communication structures used by the drone (make sure you pack the C structures when compiling them)
– Lib/ardrone_tool
: a set of tools to easily manage the drone, like an AT command sending loop and thread, a navdata receiving thread, a ready to use video pipeline, and a ready to use main function
• VLIB : the video processing library. It contains the functions to receive and decode the video stream
• VPSDK : a set of general purpose libraries, including
– VPSTAGES
: video processing pieces, which you can assemble to build a video processing pipeline
– VPOS
: multiplatform (Linux/Windows/Parrot proprietary platforms) wrappers for system-level functions (memory allocation, thread management, etc.)
– VPCOM
: multiplatform wrappers for communication functions (over Wifi, Bluetooth, etc.)
– VPAPI
: helpers to manage video pipelines and threads
15
Let’s now detail the ARDroneTool part :
• ardrone_tool.c : contains a ready-to-use main C function which initialises the Wifi network and initiates all the communications with the drone
• UI : contains a ready-to-use gamepad management code
• AT : contains all the functions you can call to actually control the drone. Most of them directly refer to an AT command which is then automatically built with the right syntax and sequencing number, and forwarded to the AT management thread.
• N
AVDATA
: contains a ready-to-use Navdata receiving and decoding system
3.3
The AR.Drone Tool
Part of the AR.Drone Library is the ARDroneTool .
The ARDroneTool is a library which implements in an efficient way the four services described in section
In particular, it provides :
• an AT command management thread, which collects commands sent by all the other threads, and send them in an ordered manner with correct
• a navdata management thread which automatically receives the navdata stream, decodes it, and provides the client application with ready-to-use navigation data through a callback function
• a video management thread, which automatically receives the video stream and provides the client application with ready-to-use video data through a callback function
• a control thread which handles requests from other threads for sending reliable commands from the drone, and automatically checks for the drone acknowledgements.
All those threads take care of connecting to the drone at their creation, and do so by using the vp_com library which takes charge of reconnecting to the drone when necessary.
These threads, and the required initialization, are created and managed by a main function, also provided by the ARDroneTool in the ardrone_tool.c file.
All a programmer has to do is then fill the desired callback functions with some application specific code. Navdata can be processed as described in section
retrived as mentionned in
16
3.4
The AR.Drone Control Engine - only for Apple iPhone
The AR.Drone control engine (aka. ARDrone engine) provides all the AR.Drone applications for iPhonewith common methods for managing the drone, displaying its video stream and managing touch/tilt controls and special events on the iPhone.
It is meant to be a common base for all iPhone applications, in order to provide a common drone API and user interface (common controls, setting menus, etc.). The Control Engine API is the only interface to the drone from the iPhone application. It is the Control Engine task to acces the ARDroneLIB .
The AR.Drone Control Engine automatically opens, receives, decodes and displays video stream coming from toy using OpenGL routines. Only one AR Drone Control Engine function need be called inside application for displaying automatically the incoming video stream. Another function allows getting a status of this process.
The following flight parameters are superimposed on video:
• AR Drone battery life will be displayed on top right
The following controls are superimposed on video:
• At the bottom, a take-off button when landed or a landing button when flying
• On the left, a settings button and a zap (change video channel) button
• On the top, an emergency button, which will stop the AR.Drone motors
Special events can occur when in game, and trigger warning messages :
• battery too low
• wifi connection loss
• video connection loss
• engine problem
User can be requested to acknowledge special event message on touch pad.
4
ARDroneLIB and
ARDroneTool functions
Here are discussed the functions provided by the ARDroneLIB to manage and control the drone.
Important
Those functions are meant to be used along with the whole ARDroneLIB and ARDroneTool framework.
You can use them when building your own application as described in chapter
or when modifying the examples.
They cannot be used when writing an application from scratch; you will then have to reimplement your own framework by following the specifications of the AT commands (chapter
navigation data (section
Most of them are declared in file ardrone_api.h of the SDK.
4.1
Drone control functions
ardrone_tool_set_ui_pad_start
Summary :
Take off - Land
Corresponding AT command :
Args : ( int value
: take off flag
Description :
Makes the drone take-off (if value=1) or land (if value=0).
When entering an emergency mode, the client program should call this function with a zero argument to prevent the drone from taking-off once the emergency has finished.
17
)
18
ardrone_tool_set_ui_pad_select
Summary :
Send emergency signal / recover from emergency
Corresponding AT command :
Args : ( int value
: emergency flag
Description :
When the drone is in a normal flying or ready-to-fly state, use this command with value=1 to start sending an emergency signal to the drone, i.e. make it stop its engines and fall.
When the drone is in an emergency state, use this command with value=1 to make the drone try to resume to a normal state.
Once you sent the emergency signal, you must check the drone state in the navdata and wait until its state is actually changed. You can then call this command with value=0 to stop sending the emergency signal.
ardrone_at_set_progress_cmd
Summary :
Moves the drone
Corresponding AT command :
Args : ( int flags
: Flag enabling the use of progressive commands and the new Com-
float phi
: bined Yaw control mode
Left/right angle ∈ [−1.0; +1.0]
float theta
: Front/back angle ∈ [−1.0; +1.0]
float gaz
: Vertical speed ∈ [−1.0; +1.0]
float yaw
: Angular speed ∈ [−1.0; +1.0]
)
Description :
This function makes the drone move in the air. It has no effect when the drone lies on the ground.
The drone is controlled by giving as a command a set of four parameters :
• a left/right bending angle, with 0 being the horizontal plane, and negative values bending leftward
• a front/back bending angle, with 0 being the horizontal plane, and negative values bending frontward
• a vertical speed
• an angular speed around the yaw-axis
In order to allow the user to choose between smooth or dynamic moves, the arguments of this function are not directly the control parameters values, but a percentage of the maximum corresponding values as set in the drone parameters. All parameters must thus be floatingpoint values between −1.0 and 1.0.
)
19
The flags argument is a bitfiels containing the following informations :
• Bit 0 : when Bit0=0 the drone will enter the hovering mode, i.e. try to stay on top of a fixed point on the ground, else it will follow the commands set as parameters.
• Bit 1 : when Bit1=1 AND CONTROL:control_level configuration Bit1=1, the new Combined Yaw mode is activated. This mode includes a complex hybridation of the phi parameter to generate complete turns (phi+yaw).
4.2
Drone configuration functions
Before recieving the navdata, your application must set the GENERAL:navdata_demo configuration on the AR.Drone . This can be done using the following functions, or directly by calling the
ARDRONE_TOOL_CONFIGURATION_ADDEVENT
macro.
ardrone_at_navdata_demo
Summary :
Makes the drone send a limited amount of navigation data
Corresponding AT command :
[This function does not take any parameter.
Description :
Some navigation data are used for debugging purpose and are not useful for every day flights.
You can choose to receive only the most useful ones by calling this function. This saves some network bandwidth. Most demonstration programs in the SDK (including the iPhone FreeFlight application) use this restricted set of data. Ardrone Navigation uses the whole set of data.
Note :
You must call this function or ardrone_at_set_navdata_all to make the drone start sending any navdata.
ardrone_at_set_navdata_all
Summary :
Makes the drone send all the navigation data
Corresponding AT command :
[This function does not take any parameter.
Description :
Some navigation data are used for debugging purpose and are not useful for every day flights.
You can choose to receive all the available navdata by calling this function. This used some more network bandwidth.
Note :
You must call this function or ardrone_at_navdata_demo to make the drone start sending any navdata.
5
Creating an application with ARDroneTool
The ARDroneTool library includes all the code needed to start your application. All you have to do is writing your application specific code, and compile it along with the ARDroneLIB library to get a fully functional drone client application which will connect to the drone and start interacting with it.
This chapter shows you how to quickly get a customized application that suits your needs.
You can try to immediately start customizing your own application by reading section
it is recommended you read the whole chapter to understand what is going on inside.
5.1
Quick steps to create a custom AR.Drone application
The fastest way to get an up and running application is to copy the SDK Demo application folder and bring the following modifications to suit your needs :
• customize the demo_navdata_client_process function to react to navigation information reception (more details in
• customize the output_gtk_stage_transform function to react to video frames reception
(more details in
• customize the update_gamepad function to react to inputs on a game pad (more details in
• create a new thread and add it to the THREAD_TABLE structure to send commands independently from the above-mentioned events (more details in
Customizing mainly means sending the appropriate commands from the ARDroneTool API.
Those commands are listed in chapter
To compile your customized demo, please refer to the tutorials.
21
22
5.2
Customizing the client initialization
As is true for every C-based application, the initial entry point for every AR.Drone application is a function called main. The good news is that, when you create a new application using the
ARDroneTool
library, you do not have to write this function yourself.
The ARDroneTool library includes a version of this function with all the code needed to start your application. All you have to do is writing your application specific code, and compile it along with the ARDroneLIB library to get a fully functional drone client application.
Listing
shows the main function for the ARDrone application. It is located in the file
ardrone_tool.c and should not require any modification. Every application you create will have a main function that is almost identical to this one.
This function performs the following tasks :
• Configures WIFI network.
• Initializes the communication ports (AT commands, Navdata, Video and Control).
• Calls the ardrone_tool_init_custom function. Its prototype is defined in ardrone_tool.h file, and must be defined and customized by the developer (see example
function we can find:
–
the local initialization for your own application.
–
the initialization of input devices, with the ardrone_tool_input_add function
–
the starting off all threads except the navdata_update and ardrone_control that are started by the main function.
• Starts the thread navdata_update that is located in ardrone_navdata_client.c file. To run properly this routine, the user must declare a table ardrone_navdata_handler_table. Listing 3 shows how to declare an ardrone_navdata_handler table. The MACRO is located in ardrone_navdata_client.h file.
• Starts the thread ardrone_control that is located in ardrone_control.c file. To send an event you must use ardrone_control_send_event function declared in ardrone_control.h.
• Acknowledge the Drone to indicate that we are ready to receive the Navdata.
• At last call ardrone_tool_update function in loop. The application does not return from this function until it quits. This function retrieves the device information to send to the
Drone. The user can declare ardrone_tool_update_custom function, that will be called by the ardrone_tool_update function.
5.3
Using navigation data
During the application lifetime, the ARDroneTool library automatically calls a set of userdefined callback functions every time some navdata arrive from the drone.
Declaring such a callback function is done by adding it to the NAVDATA_HANDLER_TABLE table. In code example
, a navdata_ihm_process function, written by the user, is declared.
Note : the callback function prototype must be the one used in code example
Listing 5.1: Application initialization with ARDroneLIB
int main( int argc, char
{
...
*argv[]) ardrone_tool__setup__com( NULL ); ardrone_tool_init(argc, argv); while ( SUCCEED(res) && ardrone_tool_exit() == FALSE )
{ res = ardrone_tool_update();
} res = ardrone_tool_shutdown();
}
Listing 5.2: Custom application initialization example
C_RESULT ardrone_tool_init_custom( int argc, char
**argv)
{ gtk_init(&argc, &argv);
/// Init specific code for application ardrone_navdata_handler_table[NAVDATA_IHM_PROCESS_INDEX].data = &cfg;
// Add inputs ardrone_tool_input_add( &gamepad );
// Sample run thread with ARDrone API.
START_THREAD(ihm, &cfg); return C_OK;
}
Listing 5.3: Declare a navdata management function
BEGIN_NAVDATA_HANDLER_TABLE //Mandatory
NAVDATA_HANDLER_TABLE_ENTRY(navdata_ihm_init, navdata_ihm_process, navdata_ihm_release,
NULL)
END_NAVDATA_HANDLER_TABLE //Mandatory
//Definition for init, process and release functions.
C_RESULT navdata_ihm_init( mobile_config_t* cfg )
{.
..
}
C_RESULT navdata_ihm_process( const navdata_unpacked_t* const pnd )
{.
..
}
C_RESULT navdata_ihm_release( void )
{
}
23
24
Listing 5.4: Example of navdata management function
/* Receving navdata during the event loop */ inline C_RESULT demo_navdata_client_process( const navdata_unpacked_t* const navdata )
{ const navdata_demo_t* const nd = &navdata->navdata_demo; printf( "Navdata for flight demonstrations\n" ); printf( "Control state : %s\n" ,ctrl_state_str(nd->ctrl_state)); printf( "Battery level : %i/100\n" ,nd->vbat_flying_percentage); printf( "Orientation : [Theta] %f [Phi] %f [Psi] %f\n" ,nd->theta,nd->phi,nd
->psi); printf( "Altitude printf( "Speed
: %i\n" ,nd->altitude);
: [vX] %f [vY] %f\n" ,nd->vx,nd->vy); printf( "\033[6A" ); // Ansi escape code to go up 6 lines
} return C_OK;
5.4
Command line parsing for a particular application
The user can implement functions to add arguments to the default command line. Functions are defined in <ardrone_tool/ardrone_tool.h> file :
• ardrone_tool_display_cmd_line_custom (Not mandatory): Displays help for particular commands.
• ardrone_tool_check_argc_custom (Not mandatory) : Checks the number of arguments.
• ardrone_tool_parse_cmd_line_custom (Not mandatory): Checks a particular line command.
5.5
Thread management in the application
In the preceding section, we showed how the ARDrone application was initialized and how it manages the Navdata and control events. In addition to those aspects of the application creation, there are also smaller details that need to be considered before building a final application.
It’s the responsibility of the user to manage the threads. To do so, we must declare a thread table with MACRO defined in vp_api_thread_helper.h file. Listing
shows how to declare a threads table.
The threads navdata_update and ardrone_control do not need to be launched and released; this is done by the ARDroneMain for all other threads, you must use the MACRO named
START_THREAD
and
JOIN_THREAD
.
25
In the preceding sections, we have seen that the user must declare functions and tables
(ardrone_tool_init_custom, ardrone_tool_update_custom, ardrone_navdata_handler_table and
threads table), other objects can be defined by the user but it is not mandatory :
• adrone_tool_exit function, which should return true to exit the main loop
• ardrone_tool_shutdown function where you can release the resources. These functions are defined in
• ardrone_tool.h.
Listing 5.5: Declaration of a threads table
BEGIN_THREAD_TABLE //Mandatory
THREAD_TABLE_ENTRY( ihm, 20 ) // For your own application
THREAD_TABLE_ENTRY( navdata_update, 20 ) //Mandatory
THREAD_TABLE_ENTRY( ardrone_control, 20 ) //Mandatory
END_THREAD_TABLE //Mandatory
5.6
Managing the video stream
This SDK includes methods to manage the video stream. The whole process is managed by a video pipeline, built as a sequence of stages which perform basic steps, such as receiving the video data from a socket, decoding the frames, and displaying them.
It is strongly recommended to have a look at the video_stage.c file in the code examples to see how this works, and to modify it to suit your needs. In the examples a fully functionnal pipeline is already created, and you will probably just want to modify the displaying part.
A stage is embedded in a structure named vp_api_io_stage_t that is defined in the file
<VP_Api/vp_api.h>.
Definition of the structure of a stage:
Listing
shows how to build a pipeline with stages. In this sample a socket is opened and the video stream is retrieved.
Listing
shows how to run the pipeline. This code must be implemented by the user; a sample is provided in the SDK Demo program. For example, you can use a thread dedicated to this.
Functions are defined in <VP_Api/vp_api.h> file : vp_api_open : Initialization of all the stages embedded in the pipeline. vp_api_run : Running of all the stages, in loop. vp_api_close : Close of all the stages.
26
Listing 5.6: The video pipeline
typedef struct _vp_api_io_stage_
{
//Enum corresponding to the type of stage available, include in file <VP_Api/ vp_api.h>.
//Only used for Debug.
VP_API_IO_TYPE type;
//Specific data to the current stage. Definitions are given in include files < void
VP_Stages/*> .
*cfg;
//Structure {vp_api_stage_funcs} is included in <VP_Api/vp_api_stage.h> with the definition of stages.
Stages are included also in the directory Soft/Lib/ardrone_tool/Video.
vp_api_stage_funcs_t funcs;
/ /This structure is included in the file <VP_Api/vp_api.h> and is shared between all stages. It contains video buffers and information on decoding the video.
vp_api_io_data_t data;
} vp_api_io_stage_t;
Definition of the structure of a pipeline:
The structure is included in file <VP_Api/vp_api.h> : typedef struct _vp_api_io_pipeline_
{
//Number of stage to added in the pipeline.
uint32_t nb_stages;
//Address to the first stage.
vp_api_io_stage_t *stages;
//Must equal to NULL vp_api_handle_msg_t handle_msg;
//Must equal to 0.
uint32_t nb_still_running;
//Must equal to NULL.
vp_api_fifo_t fifo;
} vp_api_io_pipeline_t;
5.7
Adding control devices
The ARDroneTool and demonstration programs come with an example of how to use a gamepad to pilot the drone.
The gamepad.c[pp] files in the example contain the code necessary to detect the presence of a gamepad, poll its status and send corresponding commands.
To add a control device and make ARDroneTool consider it, you must write :
• an initialization function, that ARDroneTool will call once when initializing the application. The provided example scans the system and searches a known gamepad by looking for its USB Vendor ID and Product ID.
• an update function, that ARDroneTool will systatically call every 20ms during the application lifetime, unless the initialization fails
• a clean up function, that ARDroneTool calls once at the end of the application
27
Listing 5.7: Building a video pipeline
#include <VP_Api/vp_api.h>
#include <VP_Api/vp_api_error.h>
#include <VP_Api/vp_api_stage.h>
#include <ardrone_tool/Video/video_com_stage.h>
#include <ardrone_tool/Com/config_com.h> vp_api_io_pipeline_t pipeline; vp_api_io_data_t out; vp_api_io_stage_t stages[NB_STAGES]; video_com_config_t icc; icc.com = COM_VIDEO(); icc.buffer_size = 100000; icc.protocol = VP_COM_UDP;
COM_CONFIG_SOCKET_VIDEO(&icc.socket, VP_COM_CLIENT, VIDEO_PORT, wifi_ardrone_ip); pipeline.nb_stages = 0; stages[pipeline.nb_stages].type = VP_API_INPUT_SOCKET; stages[pipeline.nb_stages].cfg = ( void
*)&icc; stages[pipeline.nb_stages].funcs = video_com_funcs; pipeline.nb_stages++;
Listing 5.8: Running a video pipeline
res = vp_api_open(&pipeline, &pipeline_handle); if ( SUCCEED(res) )
{ int loop = SUCCESS; out.status = VP_API_STATUS_PROCESSING; while (loop == SUCCESS)
{ if ( SUCCEED(vp_api_run(&pipeline, &out)) )
{ if ( (out.status == VP_API_STATUS_PROCESSING || out.status ==
VP_API_STATUS_STILL_RUNNING) )
{ loop = SUCCESS;
}
} else loop = -1; // Finish this thread
} vp_api_close(&pipeline, &pipeline_handle);
}
28
Once these functions are written, you must register your to ARDroneTool by using ardrone_tool_input_add function which takes a structure parameter input_device_t defined in <ardrone_tool/UI/ardrone_input.h>.
This structure holds the pointers to the three above-mentioned functions.
Structure input_device_t with fields :
Listing 5.9: Declaring an input device to ARDroneTool
struct _input_device_t { char name[MAX_NAME_LENGTH];
C_RESULT (*init)( void );
C_RESULT (*update)( void );
C_RESULT (*shutdown)( void );
} input_device_t;
The update function will typically call the following functions depending on the buttons pressed by the user :
•
: Takeoff / Landing button
•
ardrone_tool_set_ui_pad_select
: emergency reset all button
•
: directional buttons or sticks
Note : In SDKs newer than 1.0.4, the following functions are deprecated, and are all replaced by the
command :
• ardrone_tool_set_ui_pad_ad : turn right button
• ardrone_tool_set_ui_pad_ag : turn left button
• ardrone_tool_set_ui_pad_ab : go down button
• ardrone_tool_set_ui_pad_ah : go up button
• ardrone_tool_set_ui_pad_l1 : go left button
• ardrone_tool_set_ui_pad_r1 : go right button
• ardrone_tool_set_ui_pad_xy : go forward/backward buttons (2 arguments)
6
AT Commands
AT commands are text strings sent to the drone to control its actions.
Those strings are generated by the ARDroneLib and ARDroneTool libraries, provided in the
SDK. Most developers should not have to deal with them. Advanced developers who would like to rewrite their own A.R.Drone middle ware can nevertheless send directly those commands to the drone inside UDP packets on port UDP-5556, from their local UDP-port 5556
(using the same port numbers on both sides of the UDP/IP link is a requirement in the current
SDK).
Note : According to tests, a satisfying control of the AR.Drone is reached by sending the ATcommands every 30 ms for smooth drone movements. To prevent the drone from considering the WIFI connection as lost, two consecutive commands must be sent within less than 2 seconds.
29
30
6.1
AT Commands syntax
Strings are encoded as 8-bit ASCII characters, with a Line Feed character (byte value 10
(10)
), noted
<LF>
hereafter, as a newline delimiter.
One command consists in the three characters AT* (i.e. three 8-bit words with values 41
(16)
,54
(16)
,2a
(16)
) followed by a command name, and equal sign, a sequence number, and optionally a list of comma-separated arguments whose meaning depends on the command.
A single UDP packet can contain one or more commands, separated by newlines (byte value
0A
(16)
). An AT command must reside in a single UDP packet. Splitting an AT command in two or more UDP packets is not possible.
Example :
AT*
PCMD = 21625 ,1,0,0,0,0
<LF>
AT*
REF = 21626 ,290717696
<LF>
The maximum length of the total command cannot exceed 1024 characters; otherwise the entire command line is rejected. This limit is hard coded in the drone software.
Note : Incorrect AT commands should be ignored by the drone. Nevertheless, the client should always make sure it sends correctly formed UDP packets.
Most commands will accept arguments, which can be of three different type :
• A signed integer, stored in the command string with a decimal representation (ex: the sequence number)
• A string value stored between double quotes (ex: the arguments of AT*CONFIG)
• A single-precision IEEE-754 floating-point value (aka. float). Those are never directly stored in the command string. Instead, the 32-bit word containing the float will be considered as a 32-bit signed integer and printed in the AT command (an example is given below).
6.2
Commands sequencing
In order to avoid the drone from processing old commands, a sequence number is associated to each sent AT command, and is stored as the first number after the "equal" sign. The drone will not execute any command whose sequence number is less than the last valid received AT-
Command sequence number. This sequence number is reset to 1 inside the drone every time a client disconnects from the AT-Command UDP port (currently this disconnection is done by not sending any command during more than 2 seconds), and when a command is received with a sequence number set to 1.
A client MUST thus respect the following rule in order to successfully execute commands on the drone :
31
• Always send 1 as the sequence number of the first sent command.
• Always send commands with an increasing sequence number. If several software threads send commands to the drone, generating the sequence number and sending UDP packets should be done by a single dedicated function protected by a mutual exclusion mechanism.
Note : Drones with SDK version 0.3.1 (prior to May 2010) had a different and incompatible sequencing system which used the AT*SEQ command. These must be considered deprecated.
6.3
Floating-point parameters
Let’s see an example of using a float argument and consider that a progressive command is to be sent with an argument of −0.8 for the pitch. The number −0.8 is stored in memory as a 32bit word whose value is BF 4CCCCD
(16)
, according to the IEEE-754 format. This 32-bit word can be considered as holding the 32-bit integer value −1085485875
(10)
. So the command to send will be AT* PCMD = xx ,xx,−1085485875,xx,xx.
Listing 6.1: Example of AT command with floating-point arguments
assert( sizeof ( int )== sizeof ( float )); sprintf(my_buffer, "AT*PCMD,%d,%d,%d,%d,%d\r" , sequence_number,
*( int
*)(&my_floating_point_variable_1),
*( int
*)(&my_floating_point_variable_2),
*( int
*)(&my_floating_point_variable_3),
*( int
*)(&my_floating_point_variable_4)
);
The ARDroneLIB provides a C union to ease this conversion. You can use the _float_or_int_t to store a float or an int in the same memory space, and use it as any of the two types.
6.4
Deprecated commands
The following commands might have existed in old version of SDKs, and are not supported any more. They should thus NOT be used.
Deprecated commands: AT*SEQ, AT*RADGP, AT*MTRIM
32
6.5
AT Commands summary
AT command Arguments
1
AT*REF
AT*PCMD
AT*ANIM
input
flag, roll, pitch, gaz, yaw
AT*FTRIM
AT*CONFIG
key, value
AT*CONFIG_IDS
session, user, application ids
AT*LED
animation, frequency, duration animation, dura-
AT*COMWDG
tion
Description
Takeoff/Landing/Emergency stop command
Move the drone
Sets the reference for the horizontal plane
Configuration of the AR.Drone
Identifiers for AT*CONFIG commands
Set a led animation on the AR.Drone
Set a flight animation on the AR.Drone
Reset the communication watchdog
1 apart from the sequence number
33
6.6
Commands description
AT*REF
Summary :
Controls the basic behaviour of the drone (take-off/landing, emergency stop/reset)
Corresponding API function :
Corresponding API function :
ardrone_tool_set_ui_pad_select
Syntax : AT*
REF = %d ,%d
<LF>
Argument 1 : the sequence number
Argument 2 : an integer value in [0..2
32 controlling the drone.
− 1], representing a 32 bit-wide bit-field
Description :
Send this command to control the basic behaviour of the drone. With SDK version 1.5, only bits 8 and 9 are used in the control bit-field. Bits 18, 20, 22, 24 and 28 should be set to 1. Other bits should be set to 0.
Bits
31 .. 10 9 8
Usage Do not use Takeoff/Land Emergency
(aka. "start bit") (aka. "select bit")
7 .. 0
Do not use
Bit 9 usages :
Send a command with this bit set to 1 to make the drone take-off. This command should be repeated until the drone state in the navdata shows that drone actually took off. If no other command is supplied, the drone enters a hovering mode and stays still at approximately 1 meter above ground.
Send a command with this bit set to 0 to make the drone land. This command should be repeated until the drone state in the navdata shows that drone actually landed, and should be sent as a safety whenever an abnormal situation is detected.
After the first start AT-Command, the drone is in the taking-Off state, but still accepts other commands. It means that while the drone is rising in the air to the "1-meterhigh-hovering state", the user can send orders to move or rotate it.
Bit 8 usages :
When the drone is a "normal" state (flying or waiting on the ground), sending a command with this bit set to 1 (ie. sending an "emergency order") makes the drone enter an emergency mode. Engines are cut-off no matter the drone state. (ie. the drone crashes, potentially violently).
When the drone is in an emergency mode (following a previous emergency order or a crash), sending a command with this bit set to 1 (ie. sending an "emergency order") makes the drone resume to a normal state (allowing it to take-off again), at the condition the cause of the emergency was solved.
Send an AT*REF command with this bit set to 0 to make the drone consider following
"emergency orders" commands (this prevents consecutive "emergency orders" from flip-flopping the drone state between emergency and normal states).
34
Note :
The names "start" and "select" come from previous versions of the SDK when take-off and landing were directly managed by pressing the select and start buttons of a game pad.
Example :
The following commands sent in a standalone UDP packet will send an emergency signal :
AT*
REF = 1 ,290717696
<LF>
AT*
REF = 2 ,290717952
<LF>
AT*
REF = 3 ,290717696
<LF>
35
AT*PCMD
Summary :
Send progressive commands - makes the drone move (translate/rotate).
Corresponding API function : ardrone_at_set_progress_cmd
Syntax : AT*
PCMD = %d ,%d,%d,%d,%d,%d
<LF>
Argument 1 : the sequence number
Argument 2 : flag enabling the use of progressive commands and/or the Combined Yaw mode (bitfield)
Argument 3 : drone left-right tilt - floating-point value in range [−1..1]
Argument 4 : drone front-back tilt - floating-point value in range [−1..1]
Argument 5 : drone vertical speed - floating-point value in range [−1..1]
Argument 6 : drone angular speed - floating-point value in range [−1..1]
Description :
This command controls the drone flight motions.
Always set the flag (argument 2) bit zero to one to make the drone consider the other arguments. Setting it to zero makes the drone enter hovering mode (staying on top of the same point on the ground).
Bits
31 .. 2 1 0
Usage Do not use Combined yaw Progressive commands enable enable
The left-right tilt (aka. "drone roll" or phi angle) argument is a percentage of the maximum inclination as configured here. A negative value makes the drone tilt to its left, thus flying leftward. A positive value makes the drone tilt to its right, thus flying rightward.
The front-back tilt (aka. "drone pitch" or theta angle) argument is a percentage of the maximum inclination as configured here. A negative value makes the drone lower its nose, thus flying frontward. A positive value makes the drone raise its nose, thus flying backward.
The drone translation speed in the horizontal plane depends on the environment and cannot be determined. With roll or pitch values set to 0, the drone will stay horizontal but continue sliding in the air because of its inertia. Only the air resistance will then make it stop.
The vertical speed (aka. "gaz") argument is a percentage of the maximum vertical speed as defined here. A positive value makes the drone rise in the air. A negative value makes it go down.
The angular speed argument is a percentage of the maximum angular speed as defined here.
A positive value makes the drone spin right; a negative value makes it spin left.
36
AT*FTRIM
Summary :
Flat trims - Tells the drone it is lying horizontally
Corresponding API function : ardrone_at_set_flat_trim
Syntax : AT*
FTRIM = %d ,
<LF>
Argument 1 : the sequence number
Description :
This command sets a reference of the horizontal plane for the drone internal control system.
It must be called after each drone start up, while making sure the drone actually sits on a horizontal ground. Not doing so before taking-off will result in the drone not being able to stabilize itself when flying, as it would not be able to know its actual tilt.
When receiving this command, the drone will automatically adjust the trim on pitch and roll controls.
37
AT*CONFIG
Summary :
Sets an configurable option on the drone
Corresponding API function : ardrone_at_set_toy_configuration
Syntax : AT*
CONFIG = %d ,%s,%s
<LF>
Argument 1 : the sequence number
Argument 2 : the name of the option to set, between double quotes (byte with hex.value 22h)
Argument 3 : the option value, between double quotes
Description :
Most options that can be configured are set using this command. The list of configuration options can be found in chapter
AT*CONFIG_IDS
Summary :
Identifiers for the next AT*CONFIG command
Corresponding API function : ardrone_at_set_toy_configuration
Syntax : AT*
CONFIG_IDS = %d ,%s,%s,%s
<LF>
Argument 1 : the sequence number
Argument 2 : Current session id
Argument 3 : Current user id
Argument 4 : Current application id
Description :
While in multiconfiguration, you must send this command before every AT*CONFIG. The config will only be applied if the ids must match the current ids on the AR.Drone.
ARDroneTool
does this automatically.
AT*COMWDG
Summary :
reset communication watchdog
38
AT*LED
Summary :
Sets the drone control loop PID coefficients
Corresponding API function : ardrone_at_set_led_animation
Syntax : AT*
LED = %d ,%d,%d,%d
<LF>
Argument 1 : the sequence number
Argument 2 : integer - animation to play
Argument 3 : float - frequence in Hz of the animation
Argument 4 : integer - total duration in seconds of the animation (animation is played (duration×frequence times)
Description :
This command makes the four motors leds blink with a predetermined sequence. The leds cannot be freely controlled by the user.
See the API function description to get the list of the available animations.
Note : The frequency parameter is a floating point number, as previously explained.
AT*ANIM
Summary :
Makes the drone execute a predefined movement (called animation).
Corresponding API function : ardrone_at_set_anim
Syntax : AT*
ANIM = %d ,%d,%d
<LF>
Argument 1 : the sequence number
Argument 2 : integer - animation to play
Argument 3 : integer - total duration in seconds of the animation
Description :
Plays an animation, ie. a predetermined sequence of movements. Most of these movements are small movements (shaking for example) superposed to the user commands.
See the API function description to get the list of the available animations.
7
Incoming data streams
The drone provides its clients with two main data streams : the navigation data (aka. navdata) stream, and the video stream.
This chapter explains their format. This is useful for developers writing their own middleware.
Developers using ARDroneTool can skip this part and directly access these data from the callback function triggered by ARDroneTool when receiving incoming data from the drone
(see
and ??).
7.1
Navigation data
The navigation data (or navdata) is are a mean given to a client application to receive periodically (< 5ms) information on the drone status (angles, altitude, camera, velocity, tag detection results ...).
This section shows how to retrieve them and decode them. Do not hesitate to use network traffic analysers like Wireshark to see how they look like.
7.1.1
Navigation data stream
The navdata are sent by the drone from and to the UDP port 5554. Information are stored is a binary format and consist in several sections blocks of data called options.
Each option consists in a header (2 bytes) identifying the kind of information contained in it, a 16-bit integer storing the size of the block, and several information stored as 32-bit integers,
32-bit single precision floating-point numbers, or arrays. All those data are stored with littleendianess.
Header Drone Sequence Vision Option 1
0x55667788 state number flag
id size
32-bit int.
32-bit int.
32-bit int.
32-bit int.
16-bit int.
16-bit int.
data
. . .
. . .
. . .
. . .
. . .
. . .
39
Checksum block
cks id size cks data
16-bit 16-bit 32-bit int.
int.
int.
40
All the blocks share this common structure :
Listing 7.1: Navdata option structure
typedef struct _navdata_option_t { uint16_t tag; /* Tag for a specific option */ uint16_t size; /* Length of the struct */ uint8_t data[]; /* Structure complete with the special tag */
} navdata_option_t;
The most important options are navdata_demo_t, navdata_cks_t, navdata_host_angles_t and
navdata_vision_detect_t. Their content can be found in the C structure, mainly in the navdata_common.h.
7.1.2
Initiating the reception of Navigation data
To receive Navdata, you must send a packet of some bytes on the port
NAVDATA_PORT
of host.
Two cases :
• the drone starts in bootstrap mode, only the status and the sequence counter are sent.
• the Drone is always started, Navdata demo are send.
To exit BOOTSTRAP mode, the client must send an AT command in order to modify configuration on the Drone. Send AT command: "AT*CONFIG=\"general:navdata_demo\",\"TRUE\"\\r".
Ack control command, send AT command: "AT*CTRL=0. The drone is now initialized and sends Navdata demo. This mechanism is summarized by figure
How do the client and the drone synchronize ?
The client application can verify that the sequence counter contained in the header structure of
NavData is growing.
There are two cases when the local (client side) sequence counter should be reset :
• the drone does not receive any traffic for more that 50ms; it will then set its
ARDRONE_COM_WATCHDOG_MASK
bit in the ardrone_state field (2nd field) of the navdata packet. To exit this mode, the client must send the AT Command
• The drone does not receive any traffic for more than 2000ms; it will then stop all communication with the client, and internally set the
ARDRONE_COM_LOST_MASK
bit in its state variable. The client must then reinitialize the network communication with the drone.
24 (54)
Stéphane Piskorski A.R. Drone Developer Guide
Approved
M. Lefébure
Date
26/07/2010 n
Revisio File
4.0 AR_Drone_Developer_Guide_Release_4.0_proposal.doc
Mechanism to receive NavData demo:
HOST CLIENT
41
Send one packet to NAVDATA_PORT
Send at least the status to NAVDATA_PORT
Send AT command
("AT*CONFIG=\"general:navdata_demo\",\"TRUE\"\r")
Send AT command (ACK_CONTROL_MODE)
Sending continuous navdata demo
How to check the integrity of NavData ?
Compute a checksum of data and compare them with the value contained in the structure
[navdata_cks_t]. The checksum is always the last option (data block) in the navdata packet.
Note : this checksum is already computed by ARDroneLIB .
42
7.1.3
Augmented reality data stream
In the previously described NavData, there are informations about vision-detected tags. The goal is to permit to the host to add some functionalities, like augmented reality features. The principle is that the AR.Drone sends informations on recognized
and position.
Listing 7.2: Navdata option for vision detection
typedef struct _navdata_vision_detect_t { uint16_t tag; uint16_t size; uint32_t nb_detected; uint32_t type[4]; uint32_t xc[4]; uint32_t yc[4]; uint32_t width[4]; uint32_t height[4]; uint32_t dist[4];
} __attribute__ ((packed)) navdata_vision_detect_t;
The drone can detect up to four 2D-tags. The kind of detected tag, and which camera to use, can be set by using the configuration parameter
Let’s detail the values in this block :
• nb_detected: number of detected 2D-tags.
• type[i]: Type of the detected tag #i ; see the
CAD_TYPE
enumeration.
• xc[i], yc[i]: X and Y coordinates of detected 2D-tag #i inside the picture, with (0, 0) being the top-left corner, and (1000, 1000) the right-bottom corner regardless the picture resolution or the source camera.
• width[i], height[i]: Width and height of the detection bounding-box (2D-tag #i), when applicable.
• dist[i]: Distance from camera to detected 2D-tag #i in centimeters, when applicable.
43
7.2
The video stream
Two codecs are available UVLC (MJPEG-like) and P264 (H.264-like).
UVLC features :
colorspace YUV 4:2:0 transform 8x8 dct entropy coding RLE+UVLC
P264 vs H264 :
Feature transform frame type intra 4x4 prediction intra 16x16 prediction intra 8x8 chroma prediction macroblock partition for motion compensation motion compensation precision entropy
P264 pseudo dct 4x4
4x4 luma DC transform
2x2 Chroma DC transform
I/P mode 0-8 mode 0-3 mode 0-3
16x16 only
1 pixel
RLE+UVLC
H264 baseline profile pseudo dct 4x4
4x4 luma DC transform
2x2 Chroma DC transform
I/P mode 0-8 mode 0-3 mode 0-3
16x16,16x8,8x16,8x8,8x4,4x8,4x4
1/4 pixel
CAVLC
7.2.1
Image structure
An image is split in groups of blocks (GOB), which correspond to 16-lines-height parts of the image, split as shown below :
GOB #0
GOB #1
GOB #2
GOB #3
GOB #4
GOB #5
GOB #6
GOB #7
Figure 7.2: Example image (source : http://en.wikipedia.org/wiki/YCbCr
)
Each GOB is split in Macroblocks, which represents a 16x16 image.
44
MBlock #0 #1 #2 #3 #4 #5 #6 #7 #8 #9
Each macroblock contains informations of a 16x16 image, in Y C
B
C
R format, type 4:2:0.
(see http://en.wikipedia.org/wiki/YCbCr
, http://en.wikipedia.org/wiki/Chroma_subsampling
, http://www.ripp-it.com/glossaire/mot-420-146-lettre-tous-Categorie-toutes.
html
)
RGB image Y image C
B
image C
R
image
The 16x16 image is finally stored in the memory as 6 blocks of 8x8 values:
• 4 blocks (Y0, Y1, Y2 and Y3) to form the 16x16 pixels Y image of the luma component
(corresponding to a greyscale version of the original 16x16 RGB image).
• 2 blocks of down-sampled chroma components (computed from the original 16x16 RGB image):
–
Cb: blue-difference component (8x8 values)
–
Cr: red-difference component (8x8 values)
16
16
Y
0
Y
1
Y
2
Y
3
8
C
B
C
R
8
45
7.2.2
UVLC codec overview
UVLC codec is very closed to JPEG please refer to http://en.wikipedia.org/wiki/JPEG for more details.
Step 1
: each 8x8 block of the current macroblock is transformed by DCT.
Step 2
: each element of the transformed 8x8 block is divided by a quantization coefficient. The quantization matrix used in UVLC codec is defined by:
QU AN T
_IJ(i, j, q) = (1 + (1 + (i) + (j)) ∗ (q)) where i,j are the index of current element in the 8x8 block, and q is a number between 1 and 30.
A low q, produces a better image but more bytes are used to encode it
Step 3
: the block 8x8 is then zig zag reordered.
Step 4
: the block 8x8 is then encoded using UVLC method (see entropy coding section)
8x8 image block to compute
Forward DCT 8x8 DCT image block
QUANTIZATION
Proprietary format
Final stream
(compressed data)
Entropy encoding
DC value
ZZ-list of 16 bits data, without the last “0” values.
-26; -3: 0; -3; -2;
-6; 2; -4; 1; -4; 1;
1; 5; 1; 2; -1; 1;
-1; 2; 0; 0; 0; 0;
0; -1; -1; EOB
8x8 quantified block
Zig-zag ordering
46
7.2.3
P264 codec overview
Since the encoding concepts involved comes from the H264 specification, this part is only a brief description of P264. Please refer to the Recommendation ITU-T H.264 for further details.
7.2.3.1
I Frame
An I frame is a complete frame. No reference to any previous frame is needed to decode it. Like
H264, P264 makes a spatial prediction for each macroblock based on the neighbouring pixels.
Several mode are available for I macroblock:
• intra 16x16 - a prediction is made over the all 16x16 macroblock.
• intra 4x4 - the macroblock is divided into 16 4x4 blocks. Each 4x4 block has its own intra prediction
Once the intra prediction is done, it is subtracted from the current macroblock. The residual data is then processed with classical steps : transform, quantization, entropy coding. (see residual data section)
7.2.3.1.1
Luma intra 16x16 prediction
4 modes are available:
• VERTICAL - extends the 16 upper neighbour pixels over the all 16x16 macroblock
• HORIZONTAL - extends the 16 left neighbour pixels over the all 16x16 macroblock
• DC - fills the 16x16 block with the mean of the 16 upper and the 16 left neighbour pixels
• PLANE - makes interpolation of the 16 upper and the 16 left neighbour pixels
47
7.2.3.1.2
Luma intra 4x4 prediction
9 modes are available :
• VERTICAL_4x4_MODE
• HORIZONTAL_4x4_MODE
• DC_4x4_MODE
• DIAGONAL_DL_4x4_MODE
• DIAGONAL_DR_4x4_MODE
• VERTICAL_RIGHT_4x4_MODE
• HORIZONTAL_DOWN_4x4_MODE
• VERTICAL_LEFT_4x4_MODE
• HORIZONTAL_UP_4x4_MODE
7.2.3.1.3
Chroma 8x8 prediction
For chroma prediction, 4 modes are available :
• DC
• HORIZONTAL
• VERTICAL
• PLANE
Those modes are equivalent to luma intra 16x16 except for DC which is slightly different. Please refer to H.264 specification for more details.
7.2.3.2
P Frame
While I frame performs a spatial prediction, P frames make predictions based on the previous encoded frames.
For each macroblock, a reference is found in the previous frame by looking around the current position. The motion vector is the distance between the reference in the previous picture and the current macroblock to be encoded. The best reference is subtracted from the current macroblock to form the residual data. The motion vector will be transmitted in the data stream so that decoder could rebuild the frame.
48
The motion vector has a pixelic precision for luma component and half pixel precision for chroma component due to chroma subsampling. Therefore Chroma needs to be interpolated to access sub pixels (refer to h.264 specification).
Today, P264 doesn’t allow macroblock fragmentation for motion estimation. Only one motion vector is computed for the entire 16x16 macroblock. The reference frame is always the previous encoded/decoded frame.
7.2.3.3
Residual data
Once intra/inter prediction is done, it is subtracted from the current macroblock. The residual data is then processed with the next scheme :
step 1:
split the residual macroblock into 16 4x4 luma blocks and 4 4x4 chroma block for each chroma component
step 2:
apply pseudo dct 4x4 on each 4x4 block
step 3:
quantize all 4x4 blocks
step 4:
if current macroblock is encoded using a luma 16x16 prediction, collect all DC coefficients of each 4x4 luma block and apply an hadamard transformation (see h.264 spec)
step 5:
for each chroma component collect the 4 chroma DC values and performs an 2x2 hadamard transform (see h.264 spec)
step 6:
zigzag all AC blocks
step 7:
entropy encoding
Note:
step 1-6 are exactly the same for P264 and H264.
In fact in intra 4x4 coding, for each 4x4 block, the intra prediction is determined first then the residual 4x4 block is processed from step 1 to step 3. Then the 4x4 block is reconstructed in order to have the correct neigbouring pixels for the next 4x4 block intra prediction.
The order for luma (Y) and chroma (C) 4x4 block encoding is resume here :
Y0 Y1 Y4 Y5
Y2 Y3 Y6 Y7
Y8 Y9 Y12 Y13
Y10 Y11 Y14 Y15
C0
C2
C1
C3
49
7.2.4
Specific block entropy-encoding
The proprietary format used to encode blocks is based on a mix of RLE and Huffman coding (cf.
http://en.wikipedia.org/wiki/Run-length_encoding and http://en.wikipedia.
org/wiki/Huffman_coding
).
To resume, the RLE encoding is used to optimize the many zero values of the list, and the
Huffman encoding is used to optimize the non-zero values.
Below will be shown the pre-defined sets of codewords ("dictionaries"), for RLE and Huffman coding. Then, the process description and an example.
Note: For UVLC codec, the first value of the list (the "DC value") is not compressed, but 16 to
10 bits encoded. That’s not the case in P264.
Coarse Additionnal Size Value of run Range Length of run
1 1 0 0 1
2 1 0 1
0 0 1 x
0 0 0 1 x x
4
6
1 1
(x) + 2
2 : 3
(x x) +4
4 : 7
2
3
0 0 0 0 1 x x x
0 0 0 0 0 1 x x x x
0 0 0 0 0 0 1 x x x x x
8
10
(x x x) +8 8 : 15
(x x x x) +16 16 : 31
12
(x x x x x) +32
32 : 63
4
5
6
Coarse Additionnal Size
1
0 1
s
2
0 0 1
0 0 0 1
0 0 0 0 1
0 0 0 0 0 1
0 0 0 0 0 0 1
0 0 0 0 0 0 1 x s x x s x x x s x x x x s x x x x x s x x x x x s
Value of run
1
Range
2
5
7
0 or EOB
(x) + 2
±2 : 3
(x x) +4 ±4 : 7
9
11
(x x x) +8
±8 : 15
(x x x x) +16
±16 : 31
13
(x x x x x) +32 ±32 : 63
15 (x x x x x x) +64
±64 : 127
Length of run
1
2
3
4
5
6
7
Note: s is the sign value (0 if datum is positive, 0 otherwise.)
7.2.4.1
Entropy-encoding process
Encoding principle :
The main principle to compress the values is to form a list of pairs of encoded-data. The first datum indicates the number of successive zero values (from 0 to 63 times). The second one corresponds to a non-zero Huffman-encoded value (from 1 to 127), with its sign.
Compression process :
The process to compress the "ZZ-list" (cf. Figure 13) in the output stream could be resumed in few steps:
• Direct copy of the 10-significant bits of the first 16-bits datum ("DC value") (only for
UVLC codec
)
50
• Initialize the counter of successive zero-values at zero.
• For each of the remaining 16-bits values of the list:
–
If the current value is zero:
* Increment the zero-counter
–
Else:
* Encode the zero-counter value as explained below :
· Use the RLE dictionary (cf. Figure 14) to find the corresponding range of the value (ex: 6 is in the 4 : 7 range).
· Subtract the low value of the range (ex: 6 − 4 = 2)
· Set this temporary value in binary format (ex: 2
(10)
= 10
(2)
)
· Get the corresponding "coarse" binary value (ex: 6
(10)
→ 0001
(2)
)
· Merge it with the temporary previously computed value (ex: 0001
(2)
+10
(2)
→
000110
(2)
)
* Add this value to the output stream
* Set the zero-counter to zero
* Encode the non-zero value as explain below :
· Separate the value in temporary absolute part a, and sign part s. (s = 0 if datum is positive, 1 otherwise). Ex: for d = −13 → a = 13 and s = 1.
· Use the Huffman dictionary (cf.Figure 15) to find the corresponding range of a (ex: 13 is in the 8 : 15 range).
· Subtract the lower bound (ex : 13 − 8 = 5)
· Set this temporary value in binary format (ex : 5
(10)
= 101
(2)
)
· Get the corresponding coarse binary value (ex : 5 → 00001
(2)
)
· Merge it with the temporary previously computed value, and the sign (ex :
00001
(2)
+ 101
(2)
+ 1
(2)
→ 000011011
(2)
)
* Add this value to the output stream
–
Get to the next value of the list
• (End of "For")
7.2.4.2
Entropy-decoding process
The process to retrieve the "ZZ-list" from the compressed binary data is detailed here :
• Direct copy of the first 10 bits in a 16-bits datum ("DC value"), and add it to the output list. (only for UVLC codec)
• While there remains compressed data (till the "EOB" code):
–
Reading of the zero-counter value as explain below:
* Read the coarseS pattern part (bit-per-bit, till there is 1 value).
* On the corresponding line (cf.Figure 14), get the number of complementary bits to read. (Ex: 000001
(2)
→ xxxx → 4 more bits to read.)
* If there is no 0 before the 1 (first case in the RLE table): ⇒ Resulting value (zerocounter) is equal to 0.
51
* Else: ⇒ Resulting value (zero-counter) is equal to the direct decimal conversion of the merged read binary values. Ex: if xxxx = 1101
(2)
→ 000001
(2)
+ 1101
(2)
=
0000011101
(2)
= 29
(10)
–
Add "0" to the output list, as many times indicated by the zero-counter.
–
Reading of the non-zero value as explain below:
* Read the coarse pattern part (bit-per-bit, till there is 1 value).
* On the corresponding line (cf.Figure 15), get the number of complementary bits to read. Ex: 0001
(2)
→ xxs → 2 more bits to read (then the sign bit.)
* If there is no 0 before the 1 (coarse pattern part = 1, in the first case of the Huffman table): ⇒ Temporary value is equal to 1.
* Else if the coarse pattern part = 01
(2)
(second case of the Huffman table) : ⇒
Temporary value is equal to End Of Bloc code (EOB).
* Else ⇒ Temporary value is equal to the direct decimal conversion of the merged read binary values. Ex: if xx = 11 → 00001
(2)
+ 11
(2)
= 0000111
(2)
= 7
(10)
Read the next bit, to get the sign (s).
* If s = 0: ⇒ Resulting non-zero value = temporary value
* Else (s = 1): ⇒
* Resulting non-zero value = temporary value x (-1)
–
Add the resulting non-zero value to the output list.
• (End of "while")
7.2.4.3
Example
Encoding :
• Initial data list :
-26; -3; 0; 0; 0; 0; 7; -5; EOB
• Step 1 :
-26; 0x"0"; -3; 4x"0"; 7; 0x"0"; -5; 0x"0"; EOB
• Step 2 (binary form):
1111111111100110; 1; 001 11; 0001 00; 0001 110; 1; 0001 011; 1; 01
• Final stream :
1111100110100111000100000111010001011101
Decoding :
• Initial bit-data stream :
{11110001110111000110001010010100001010001101}
• Step 1 (first 10 bits split) :
{1111000111}; {0111000110001010010100001010001101}
• Step 2 (16-bits conversion of DC value) :
{1111111111000111}; {0111000110001010010100001010001101}
52
• Step 3, remaining data (DC value is done) :
{"-57"}; {011100011000101001010001100110101}
• Step 4, first couple of values:
{"-57"}; [{01.}; {1.1}]; {00011000101001010001100110101}
{"-57"}; ["0"; "-1"]; {00011000101001010001100110101}
• Step 5, second couple of values :
{"-57"; "0"; "-1"; [{0001.10}; {001.01}]; {001010001100110101}
{"-57"; "0"; "-1"; ["000000"; "-2"]; {001010001100110101}
• Step 6, third couple of values :
{"-57"; "0"; "-1"; "000000"; "-2"; [{001.0}; {1.0}]; {001100110101}
{"-57"; "0"; "-1"; "000000"; "-2"; [""; "+1"]; {001100110101}
• Step 7, fourth couple of values :
{"-57"; "0"; "-1"; "000000"; "-2"; "+1"; [{001.1}; {001.10}]; {101}
{"-57"; "0"; "-1"; "000000"; "-2"; "+1"; ["000"; "+3"]; {101}
• Step 8, last couple of values (no "0" and "EOB" value):
{"-57"; "0"; "-1"; "000000"; "-2"; "+1"; "000"; "+3"; [{1.}; {01}]
{"-57"; "0"; "-1"; "000000"; "-2"; "+1"; "000"; "+3"; [""; "EOB"]
• Final data list :
{"-57"; "0"; "-1"; "0"; "0"; "0"; "0"; "0"; "0"; "-2"; "+1"; "0"; "0"; "0"; "+3"; "EOB"}
7.2.5
Transport layer
This section describes how the final data stream is generated.
For each picture, data correspond to an image header followed by data blocks groups and an ending code (EOS, end of sequence).
The composition of each block-layer is resumed here:
Picture Header blockline = 0
PSC
(22 bits)
FORMAT
(2 bits)
RESOLUTION
(3 bits)
PICTURE TYPES
(3 bits)
QUANT uvlc (5 bits) p264 (6 bits)
FRAME NUMBER
(32 bits)
GOB
(XXX bits)
GOB Header blockline = n
…
GOB Header last blockline
GOBSC
(22 bits)
GOBSC
(22 bits)
QUANT uvlc (5 bits) p264 (6 bits)
QUANT uvlc (5 bits) p264 (6 bits)
GOB
(XXX bits)
GOB
(XXX bits)
EOS
(22 bits)
GOB
(XXX bits)
MB0
(XXX bits)
…
picture layer
MBN
(XXX bits)
gob layer
53
MBx
(XXX bits)
MBC
(1 bit)
MBDES
(8 bits)
MBDIFF
(2 bits)
(reserved)
Y0
(XXX bits)
Y1
(XXX bits)
Y2
(XXX bits)
Y3
(XXX bits)
U0
(XXX bits)
V0
(XXX bits)
uvlc macroblock layer
Intra MBx
(XXX bits)
INTRA
LUMA
TYPE
(1 bit)
INTRA CHROMA
TYPE
(2 bits)
INTRA
4x4
INTRA
16x16
INTRA LUMA 4x4
MODE
(16*XXX bits)
INTRA LUMA 16x16
MODE
(2 bits)
Y0
(XXX bits)
DC Y
(XXX bits)
...
AC Y0
(XXX bits)
Y15
(XXX bits)
...
AC Y15
(XXX bits)
CHROMA DATA
Inter MBx
(XXX bits)
PARTITION LIST
(3 bits)
MOTION VECTOR LIST
(XXX bits)
Y0
(XXX bits)
...
Y15
(XXX bits)
CHROMA DATA
CHROMA DATA DC U
(XXX bits)
AC U0
(XXX bits)
… AC U3
(XXX bits)
DC V
(XXX bits)
AC V0
(XXX bits)
p264 macroblock layer
..
AC V3
(XXX bits)
7.2.5.1
Picture start code (PSC) (22 bits)
UVLC start with a PSC (Picture start code) which is 22 bits long:
0000 0000 0000 0000 1 00000
P264 PSC is:
0000 0000 0000 0001 0 00000
A PSC is always byte aligned.
7.2.5.2
Picture format (PFORMAT) (2 bits)
The second information is the picture format which can be one of the following : CIF or VGA
• 00 : forbidden
• 01 : CIF
• 10 : VGA
7.2.5.3
Picture resolution (PRESOLUTION) (3 bits)
Picture resolution which is used in combination with the picture format (3 bits)
• 000 : forbidden
• 001 : for CIF it means sub-QCIF
• 010 : for CIF it means QCIF
• 011 : for CIF it means CIF
54
• 100 : for CIF it means 4-CIF
• 101 : for CIF it means 16-CIF
7.2.5.4
Picture type (PTYPE) (3 bits)
Picture type:
• 000 : INTRA picture
• 001 : INTER picture
7.2.5.5
Picture quantizer (PQUANT) (5/6 bits)
UVLC codec:
The PQUANT code is a 5-bits-long word. The quantizer’s reference for the picture that range from 1 to 30.
P264 codec:
The PQUANT code is a 6-bits-long word and range from 0 to 63;
7.2.5.6
Picture frame (PFRAME) (32 bits)
The frame number (32 bits).
7.2.5.7
Group of block start code (GOBSC) (22 bits)
Each GOB starts with a GOBSC (Group of block start code) which is 22 bits long:
uvlc codec :
0000 0000 0000 0000 1xxx xx
p264 codec :
0000 0000 0000 0001 0xxx xx
A GOBSC is always a byte aligned. The least significant bytes represent the blockline’s number.
We can see that PSC means first GOB too. So for the first GOB, GOB’s header is always omitted.
7.2.5.8
Group of block quantizer (GOBQUANT) (5/6 bits)
Equivalent to PQUANT for the current GOB.
55
7.2.5.9
UVLC Macroblocks Layer
Data for each macroblock corresponding to an header of macroblock followed by data of macroblock.
MBx
(XXX bits)
MBC
(1 bit)
MBDES
(8 bits)
MBDIFF
(2 bits)
(reserved)
Y0
(XXX bits)
Y1
(XXX bits)
Y2
(XXX bits)
Y3
(XXX bits)
U0
(XXX bits)
V0
(XXX bits)
uvlc macroblock layer
MBC - Coded macroblock bit:
• Bit 0 : ‘1’ means there’s a macroblock / ‘0’ means macroblock is all zero.
• If MBC is 0, the following fields are omitted.
MBDES - Macroblock description code:
• Bit 0 : ‘1’ means there’s non dc coefficients for block y0.
• Bit 1 : ‘1’ means there’s non dc coefficients for block y1.
• Bit 2 : ‘1’ means there’s non dc coefficients for block y2.
• Bit 3 : ‘1’ means there’s non dc coefficients for block y3.
• Bit 4 : ‘1’ means there’s non dc coefficients for block cb.
• Bit 5 : ‘1’ means there’s non dc coefficients for block cr.
• Bit 6 : ‘1’ means there’s a differential quantization (MBDIFF) value following this code.
Not implemented, always 0
• Bit 7 : Always ‘1’ to avoid a zero byte.
MBDIFF – differential quantization: Not implemented
Y0-Y3 U0 V0: Each block Yi, U and V are encoded using the method described in section 4.x.x
Block Entropy-encoding process.
7.2.5.10
P264 Macroblock Layer
Intra MBx
(XXX bits)
INTRA
LUMA
TYPE
(1 bit)
INTRA CHROMA
TYPE
(2 bits)
INTRA
4x4
INTRA
16x16
INTRA LUMA 4x4
MODE
(16*XXX bits)
INTRA LUMA 16x16
MODE
(2 bits)
Y0
(XXX bits)
DC Y
(XXX bits)
...
AC Y0
(XXX bits)
Y15
(XXX bits)
...
AC Y15
(XXX bits)
CHROMA DATA
Inter MBx
(XXX bits)
PARTITION LIST
(3 bits)
MOTION VECTOR LIST
(XXX bits)
Y0
(XXX bits)
...
Y15
(XXX bits)
CHROMA DATA
CHROMA DATA DC U
(XXX bits)
AC U0
(XXX bits)
… AC U3
(XXX bits)
DC V
(XXX bits)
AC V0
(XXX bits)
p264 macroblock layer
..
AC V3
(XXX bits)
56
There are 3 types of Macroblock in the transport layer :
• I frame with intra 16x16 prediction for the current macroblock
• I frame with intra 4x4 prediction for the current macrobock
• P frame
Macroblock intra 16x16:
INTRA LUMA TYPE – fragmentation used for intra prediction:
Bit 0 : ’0’ means intra 4x4, ’1’ means intra 16x16. Thus INTRA LUMA TYPE is set to 1 for an intra 16x16 Macroblock
INTRA CHROMA TYPE – intra mode for chroma component:
One of the four available intra chroma predictions coded over 2 (bits).
INTRA LUMA 16x16 MODE – 16x16 intra mode for luma component:
One of the four available intra chroma predictions coded over 2 (bits).
Y0 – Y15 – luma 4x4 blocks:
Each block (16 elements) is encoded using the method described in section Block Entropyencoding process.
CHROMA DATA – U and V blocks:
This segment is common to all types of macroblock. See description below.
Macroblock intra 4x4:
INTRA LUMA TYPE – fragmentation used for intra prediction:
Bit 0 : ’0’ means intra 4x4, ’1’ means intra 16x16. Thus INTRA LUMA TYPE is set to 0 for a intra
4x4 Macroblock
INTRA CHROMA TYPE – intra mode for chroma component:
One of the four available intra chroma prediction coded over 2 (bits).
INTRA LUMA 4x4 MODE - list of 16 intra 4x4 prediction:
Each intra 4x4 is one of the nine available intra 4x4 luma prediction (horizontal, vertical, vertical up, . . . )
Each element of the list is coded using a prediction based on the neighbouring predictions. If the prediction is correct, the element is coded using only 1 bit. If the prediction is false 4 bits are used. Please refer to h264 specification for details about how the prediction is done on intra
4x4 mode.
DC Y – list of 16 DC value:
DC Y is a list of 16 elements which gather DC values from the 16 4x4 blocks of the current macroblock. This list is written in the data stream using the block-encoding method.
AC Yx – block of AC coeff:
Each AC block (15 elements) is encoded with the block-encoding method.
CHROMA DATA – U and V blocks:
This segment is common to all type of macroblocks. See description below.
57
Inter Macroblock :
PARTITION LIST – list of mb subdivision for motion estimation:
Always read as ’000’ because P264 doesn’t support macroblock partition.
MOTION VECTOR LIST – list of motion vector associated to each partition:
There is only one motion vector per macroblock. The vector is not put in the stream directly. A predicted motion vector for the current macroblock is determined with the already transmitted neighboring motion vector. The difference between the prediction and the real motion vector is written in the data stream.
The x component is transmitted before the y. Each component is written with the level-encoding method (see block-encoding). For further details about the way prediction is determined please refer to h.264 specification.
Y0 – Y15 – luma 4x4 blocks:
Each block (16 elements) is encoded using the method described in section Block Entropyencoding process.
CHROMA DATA – U and V blocks:
This segment is common to all type of macroblocks. See description below.
Chroma Data:
DC U – list of 4 DC value:
DC U is a list which contains the DC values from each chroma 4x4 block. This list is encoded with the block-encoding method.
AC Ux - block of AC coeff:
Each AC block (15 elements) is encoded with the block-encoding method.
DC V:
Same as DC U
AC Vx:
Same as AC Ux
7.2.6
End of sequence (EOS) (22 bits)
The end of sequence (EOS) which is 22 bits long :
0000 0000 0000 0001 0111 11
58
7.2.7
Intiating the video stream
To start receiving the video stream, a client just needs to send a UDP packet on the drone video port.
The drone will stop sending data if it cannot detect any network activity from its client.
HOST
Send one packet to VideoPort
(to wake-up the Host)
CLIENT
Socket initialization
Send picture by blockline
(UDP packets)
Image blocks decoding
8
Drone Configuration
The drone behaviour depends on many parameters which can be modified by using the
AT command, or by using the appropriate ARDroneLIB function (see chapter
This chapter shows how to read/write a configuration parameter, and gives the list of parameters you can use in your application.
8.1
Reading the drone configuration
8.1.1
With ARDroneTool
ARDroneTool
implements a ’control’ thread which automatically retrieves the drone configuration at startup.
Include the <ardrone_tool/ardrone_tool_configuration.h> file in your C code to access the
ardrone_control_config structure which contains the current drone configuration. Its most interesting fields are described in the next section.
If your application is structured as recommended in chapter
or you are modifying one of the examples, the configuration should be retrieved by ARDroneTool before the threads containing your code get started by ARDroneTool .
8.1.2
Without ARDroneTool
The drone configuration parameters can be retrieved by sending the AT*CTRL command with a mode parameter equaling 4 (
CFG_GET_CONTROL_MODE
).
The drone then sends the content of its configuration file, containing all the available configuration parameters, on the control communication port (TCP port 5559). Parameters are sent as
ASCII strings, with the format Parameter_name = Parameter_value.
Here is an example of the sent configuration :
59
60
Listing 8.1: Example of configuration file as sent on the control TCP port
GENERAL:num_version_config = 1
GENERAL:num_version_mb = 17
GENERAL:num_version_soft = 1.1.3
GENERAL:soft_build_date = 2010-08-06 09:48
GENERAL:motor1_soft = 1.8
GENERAL:motor1_hard = 3.0
GENERAL:motor1_supplier = 1.1
GENERAL:motor2_soft = 1.8
GENERAL:motor2_hard = 3.0
GENERAL:motor2_supplier = 1.1
GENERAL:motor3_soft = 1.8
GENERAL:motor3_hard = 3.0
GENERAL:motor3_supplier = 1.1
GENERAL:motor4_soft = 1.8
GENERAL:motor4_hard = 3.0
GENERAL:motor4_supplier = 1.1
GENERAL:ardrone_name = My ARDrone
GENERAL:flying_time = 1810
GENERAL:navdata_demo = TRUE
GENERAL:com_watchdog = 2
GENERAL:video_enable = TRUE
GENERAL:vision_enable = TRUE
GENERAL:vbat_min = 9000
CONTROL:accs_offset = { -2.2696499e+03 1.9345000e+03 1.9331300e+03 }
CONTROL:accs_gains = { 9.6773100e-01 2.3794901e-02 7.7836603e-02 -1.2318300e-02
-9.8853302e-01 3.2103900e-02 7.2116204e-02 -5.6212399e-02 -9.8713100e-01 }
CONTROL:gyros_offset = { 1.6633199e+03 1.6686300e+03 1.7021300e+03 }
CONTROL:gyros_gains = { 6.9026551e-03 -6.9553638e-03 -3.8592720e-03 }
CONTROL:gyros110_offset = { 1.6560601e+03 1.6829399e+03 }
CONTROL:gyros110_gains = { 1.5283586e-03 -1.5365391e-03 }
CONTROL:gyro_offset_thr_x = 4.0000000e+00
CONTROL:gyro_offset_thr_y = 4.0000000e+00
CONTROL:gyro_offset_thr_z = 5.0000000e-01
CONTROL:pwm_ref_gyros = 471
CONTROL:control_level = 1
CONTROL:shield_enable = 1
CONTROL:euler_angle_max = 3.8424200e-01
CONTROL:altitude_max = 3000
CONTROL:altitude_min = 50
CONTROL:control_trim_z = 0.0000000e+00
CONTROL:control_iphone_tilt = 3.4906584e-01
CONTROL:control_vz_max = 1.2744493e+03
CONTROL:control_yaw = 3.1412079e+00
CONTROL:outdoor = TRUE
CONTROL:flight_without_shell = TRUE
CONTROL:brushless = TRUE
CONTROL:autonomous_flight = FALSE
CONTROL:manual_trim = FALSE
NETWORK:ssid_single_player = AR_hw11_sw113_steph
NETWORK:ssid_multi_player = AR_hw11_sw113_steph
NETWORK:infrastructure = TRUE
NETWORK:secure = FALSE
NETWORK:passkey =
NETWORK:navdata_port = 5554
NETWORK:video_port = 5555
NETWORK:at_port = 5556
NETWORK:cmd_port = 0
NETWORK:owner_mac = 04:1E:64:66:21:3F
NETWORK:owner_ip_address = 0
NETWORK:local_ip_address = 0
NETWORK:broadcast_address = 0
61
PIC:ultrasound_freq = 8
PIC:ultrasound_watchdog = 3
PIC:pic_version = 100925495
VIDEO:camif_fps = 15
VIDEO:camif_buffers = 2
VIDEO:num_trackers = 12
DETECT:enemy_colors = 1
SYSLOG:output = 7
SYSLOG:max_size = 102400
SYSLOG:nb_files = 5
.
8.2
Setting the drone configuration
8.2.1
With ARDroneTool
Use the
ARDRONE_TOOL_CONFIGURATION_ADDEVENT
macro to set any of the configuration parameters.
This macro makes ARDroneTool queue the new value in an internal buffer, send it to the drone, and wait for an acknowledgment from the drone.
It takes as a first parameter the name of the parameter (see next sections to get a list or look at the config_keys.h file in the SDK). The second parameter is a pointer to the new value to send to the drone. The third parameter is a callback function that will be called upon completion.
The callback function type is void (*callBack)(unsigned int success). The configuration tool will call the callback function after any attempt to set the configuration, with zero as the parameter in case of failure, and one in case of success. In case of failure, the tool will automatically retry after an amount of time.
Your program must not launch a new
ARDRONE_TOOL_CONFIGURATION_ADDEVENT
call at each time the callback function is called with zero as its parameter.
The callback function pointer can be a NULL pointer if your application don’t need any acknowledgment.
Listing 8.2: Example of setting a config. paramter
int enemy\_color; enemy\_color = ORANGE_GREEN;
ARDRONE\_TOOL\_CONFIGURATION\_ADDEVENT(enemy__colors, \&enemy\_color, NULL);
62
8.2.2
From the Control Engine for iPhone
Using the Control Engine for iPhone, the ARDrone instance of your application can accept messages to control some parts of the configuration.
The message is -(void) executeCommandIn:(ARDRONE_COMMAND_IN_WITH_PARAM)commandIn fromSender:(id)sender refreshSettings:(BOOL)refresh.
The ARDRONE_COMMAND_IN_WITH_PARAM structure (declared in ARDroneTypes.h) is composed of the following members :
• ARDRONE_COMMAND_IN command : This is the same parameter as the legacy "executeCommandIn" message (see below for details).
• command_in_configuration_callback callback : This is a callback that will be called upon configuration completion. If your application does not need the callback, you may put this field to NULL.
• void *parameter : Parameter to the command (descrbed below).
As 1.7 SDK, ARDRONE_COMMAND_IN enum contains the following members (In parenthesis, the pointer type of the parameter associated) :
• ARDRONE_COMMAND_ISCLIENT : For multiplayer games, set different ultrasound frequencies for server and client (integer casted to (void *)).
• ARDRONE_COMMAND_DRONE_ANIM : Play a flight anim (ARDRONE_ANIMATION_-
PARAM pointer, see ARDroneTypes.h and config.h).
• ARDRONE_COMMAND_DRONE_LED_ANIM : Play a LED animation (ARDRONE_-
LED_ANIMATION_PARAM pointer, see ARDroneTypes.h and led_animations.h).
• ARDRONE_COMMAND_SET_CONFIG : Set any config key value (ARDRONE_CON-
FIG_PARAM pointer, see ARDroneTypes.h).
• ARDRONE_COMMAND_ENABLE_COMBINED_YAW : Enable (Disable) the combined yaw mode. (boolean casted to (void *)).
The second parameter is currently unused (passing nil is ok).
The third parameter is a boolean tha tells the control engine to refresh the settings menu upon configuration completion. This can take nearly a second (request of configuration file of the
AR.Drone), so you should not activate this when not needed.
Listing 8.3: Example of setting outdoor flight with Control Engine
ARDRONE\_COMMAND\_IN\_WITH\_PARAM command;
ARDRONE\_CONFIG\_PARAM param; int value; value = 1; // Will be treated as a boolean
63 param.config\_key = ARDRONE\_CONFIG\_KEY\_OUTDOOR; param.value = ( void
*)&value; command.command = ARDRONE\_COMMAND\_SET\_CONFIG; command.callback = NULL; command.parameter = ( void
*)¶m;
[ardrone executeCommandIn:command fromSender:nil refreshSettings:NO];
Note : Using multiconfiguration, the AR.Drone will ignore any configuration request when not setted to the correct appli/user/session profiles. To reflect that, we’ve added an isInit field to the ARDroneNavigationData structure. Your application must ensure that the isInit flag is set
(value will be 1) before sending any configuration. (Note that this flag CAN go back to zero during flight when a WiFi disconnection is detected).
Note : The legacy (1.6 SDK) executeCommandIn message is still supported in 1.7 SDK, but is flagged as deprecated and may be removed in future versions.
8.2.3
Without ARDroneTool
Use the
command to send a configuration value to the drone. The command must be sent with a correct sequence number, the parameter note between double-quotes, and the parameter value between double-quotes.
64
8.3
Multiconfiguration
Starting with firmware 1.6.4, the AR.Drone supports different configurations depending on the application, user and session connected.
This allow different applications and users to share the same AR.Drone with different settings without any user action nor any "send all configurations" at application startup.
Configuration keys are split into 4 categories :
• CAT_COMMON : This is the default category, common to all applications.
• CAT_APPLI : This setting will be saved for the current application (regardless of the device it is running on).
• CAT_USER : This setting will be saved for the current user (regardless of the application).
For more information about users, see the
section of this documentation. (User category is also called "profile" category).
• CAT_SESSION : This setting will be saved for the current flight session (regardless of application/user).
The legacy /data/config.ini file contains the cofiguration for unidentified applications, and all
CAT_COMMON settings. All identified applications settings are stored into /data/custom.config/ folder, under subfolders applis, profiles and sessions, with the name config.<id>.ini.
Note : When the drone detects a disconnection, it will automatically switch back to the default configuration, and get back in bootstrap mode (no navdata are sent).
Note : As the session holds the application and user identifiers (CAT_SESSION settings), switching back to the session id will automatically put the drone back into the correct application/user. (See the
documentation for further informations).
8.3.1
With ARDroneTool
The ardrone_tool_init function now takes two string pointers to the application name and the user name that will be used as the application defaults.
The session name is a random generated number, and can not be specified from the application.
This function set an ardrone_config_t structure called ardrone_application_default_config which will hold the default configuration needed by your application. These configuration will be sent to the AR.Drone when the associate configuration are created. (Note : CAT_COMMON configs are never sent).
This allow users to overwrite your default settings, because your application will only send them once, and not at each startup.
Note : All description above refers to the NO_ARDRONE_MAINLOOP version of the ardrone_tool_init function. This is the reference mode, and the legacy ARDroneTool main loop should
65 not be used anymore. The legacy function only sets the application name according to argv[0] and init the ardrone_application_default_config structure.
8.3.2
Multiconfiguration with Control Engine (iPhone only)
The Control Engine init function (ARDrone object init) calls the ardrone_tool_init_custom passing the bundle name as the application name (e.g. "com.parrot.freeflight" for AR.FreeFlight), and the device type/UDID as the user.
(e.g. ".iPhone:0123456789ABCDEF", or ".iPod Touch:ABCDEF0123456789")
Note : The dot (’.’) at the beginning of the username is explained in the
documentation.
To set the default configuration, the ARDrone class supports a new message called -(void) set-
DefaultConfigurationForKey:(ARDRONE_CONFIG_KEYS)key withValue:(void *)value.
The first parameter is the name of the configuration key (found in ARDroneGeneratedTypes.h file). The second parameter is a valid pointer to the value that you want to set as default.
Pointer types for each keys can be found in the config_keys.h file.
Note : The default configuration must be set AFTER creating the ARDrone instance (after connecting to the AR.Drone), but BEFORE changing its state to "inGame".
8.3.3
Without ARDroneTool
When running on the default configuration, the drone use the standard behaviour, and does not require any aditionnal informations.
When running inside of any new configuration (application, user, session or any combinaison of theses), the AR.Drone expect to receive a new
command before each
AT*CONFIG . The AR.Drone will only set the configuration if the AT*CONFIG_IDS
identifiers match the currently loaded configuration. In any case, the configuration will be acknowledged to the application.
8.3.4
Common category (CAT_COMMON)
This category holds the config keys that are common to all applications and users. These keys should not be initialized by your application, as they are shared between all.
This category holds, for exmple, all the version numbers, network configuration, and indoor/outdoor settings.
66
8.3.5
Application category (CAT_APPLI)
This category hold all the application specific configuration. Currently, this is limited to the video encoding options and the navdata_options required by your application.
8.3.6
User category (CAT_USER) – also called "Profile" category
This is the most complex category as different applications may want to access the same user profiles, so application must be able to swith their active user at runtime.
The ARDroneTool provides a few functions to do that. These functions are described in the
ardrone_api.h file.
By convention, we use the dot (’.’) as an "hidden user" identifier (like hidden files in UNIX systems). These user are default users that should not be shown to the consumer (e.g. default user for each iDevice, default user for a predefined flying mode ...), in regard to the "real" users that people will create on their drone to share their settings between many applications
(including games). This convention is used inside the ardrone_get_user_list function to build a
"visible user list" rather than a complete list.
Note : Known issues : As 1.8 version of AR.FreeFlight, user switch is not implemented, and thus partially untested. Changing the user (using ardrone_api.h functions) will cause an immediate change of the application identifier, but the queuing of the associated
In result, any queued config at this time may be refused by the AR.Drone before the effective config switch (see
for details).
8.3.7
Session category (CAT_SESSION)
The session category holds the "current flight session" settings. These settings includes the active video camera, the active video detection ...
This allow your application to get back to the exact same state after a drone reboot (battery change), or WiFi disconnection. In either cases, the drone is put back to the default configuration, and in bootstrap mode (no navdatas). To reconnect, your application just need to send back its session id (this will automatically put back the AR.Drone into the good application/user profiles), then ask again for navdata_demo and navdata_options keys.
See ardrone_general_navdata.c for an example.
Note : All application are expected to clean all sessions file at startup (see ardrone_general_navdata.c), so you may not rely on sessions when your application was shut down for any reason.
8.3.8
Technical details on id generation and descriptions
67
The ARDroneTool generates the different ids the following way :
The application id is generated as a CRC32 of a string composed of the application name and the SDK current version (e.g. for AR.FreeFlight 1.8, the complete string is "com.parrot.freeflight:1.7").
The application description is set as the application name only (e.g. "com.parrot.freeflight" for
AR.FreeFlight 1.8)
The user id is generated as a CRC32 of the username provided to the ARDroneTool . The description is set as the username.
The session id is randomly generated. The session description is set as "Session <number>" with <number> the generated id.
Note : The CRC32 function used to generate the ids is NOT collision free. It’s impossible for the AR.Drone to make the difference between two applications if their ids are the same.
68
8.4
General configuration
All the configurations are given accordingly to the config_keys.h file order.
In the API examples, the myCallback argument can be a valid pointer to a callback function, or a NULL pointer if no callback is needed by the application.
GENERAL:num_version_config
Description :
Version of the configuration subsystem (Currently 1).
CAT_COMMON | Read only
GENERAL:num_version_mb
Description :
Hardware version of the drone motherboard.
GENERAL:num_version_soft
Description :
Firmware version of the drone.
GENERAL:soft_build_date
Description :
Date of drone firmware compilation.
CAT_COMMON | Read only
CAT_COMMON | Read only
CAT_COMMON | Read only
GENERAL:motor1_soft
CAT_COMMON | Read only
Description :
Software version of the motor 1 board. Also exists for motor2, motor3 and motor4.
GENERAL:motor1_hard
CAT_COMMON | Read only
Description :
Harware version of the motor 1 board. Also exists for motor2, motor3 and motor4.
GENERAL:motor1_supplier
CAT_COMMON | Read only
Description :
Supplier version of the motor 1 board. Also exists for motor2, motor3 and motor4.
GENERAL:ardrone_name
CAT_COMMON | Read/Write
Description :
Name of the AR.Drone. This name may be used by video games developper to assign a default name to a player, and is not related to the Wi-Fi SSID name.
69
AT command example :
API use example :
AT* CONFIG = 605 ,"general:ardrone_name","My ARDrone Name"
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (ardrone_name, "My ARDrone Name", myCallback);
GENERAL:flying_time
CAT_COMMON | Read only
Description :
Numbers of seconds spent by the drone in a flying state in its whole lifetime.
GENERAL:navdata_demo
CAT_COMMON | Read/Write
Description :
The drone can either send a reduced set of navigation data (navdata) to its clients, or send all the available information which contain many debugging information that are useless for everyday flights.
If this parameter is set to TRUE, the reduced set is sent by the drone (this is the case in the
AR.FreeFlight iPhone application).
If this parameter is set to FALSE, all the available data are sent (this is the cae in the Linux example ardrone_navigation).
AT command example : AT* CONFIG = 605 ,"general:navdata_demo","TRUE"
API use example :
bool_t value = TRUE;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (navdata_demo, &value, myCallback);
GENERAL:navdata_options
CAT_APPLI | Read/Write
Description :
When using navdata_demo, this configuration allow the application to ask for others navdata packets. Most common example is the default_navdata_options macro defined in the config_key.h file. The full list of the possible navdata packets can be found in the navdata_common.h file.
AT command example : AT* CONFIG = 605 ,"general:navdata_options","65537"
API use example :
uint32_t ndOptions = (NAVDATA_OPTION_MASK (NAVDATA_DEMO_TAG) | NAVDATA_-
OPTION_MASK (NAVDATA_VISION_DETECT_TAG));
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (navdata_options, &ndOptions, myCallback);
GENERAL:com_watchdog
CAT_COMMON | Read/Write
Description :
Time the drone can wait without receiving any command from a client program. Beyond this delay, the drone will enter in a ’Com Watchdog triggered’ state and hover on top a fixed point.
70
Note : This setting is currently disabled. The drone uses a fixed delay of 250 ms.
GENERAL:video_enable
CAT_COMMON | Read/Write
Description :
Reserved for future use. The default value is TRUE, setting it to FALSE can lead to unexpected behaviour.
GENERAL:vision_enable
CAT_COMMON | Read/Write
Description :
Reserved for future use. The default value is TRUE, setting it to FALSE can lead to unexpected behaviour.
Note : This setting is not related to the tag detection algoritms
GENERAL:vbat_min
CAT_COMMON | Read only
Description :
Reserved for future use. Minimum battery level before shutting down automatically the AR.Drone.
71
8.5
Control configuration
CONTROL:accs_offset
Description :
Parrot internal debug informations. AR.Drone accelerometers offsets.
CAT_COMMON | Read only
CONTROL:accs_gains
Description :
Parrot internal debug informations. AR.Drone accelerometers gains.
CAT_COMMON | Read only
CONTROL:gyros_offset
Description :
Parrot internal debug informations. AR.Drone gyrometers offsets.
CAT_COMMON | Read only
CONTROL:gyros_gains
Description :
Parrot internal debug informations. AR.Drone gyrometers gains.
CAT_COMMON | Read only
CONTROL:gyros110_offset
Description :
Parrot internal debug informations.
CONTROL:gyros110_gains
Description :
Parrot internal debug informations.
CONTROL:gyro_offset_thr_x
Description :
Parrot internal debug informations.
Note : Also exists for the y and z axis.
CONTROL:pwm_ref_gyros
Description :
Parrot internal debug informations.
CAT_COMMON | Read only
CAT_COMMON | Read only
CAT_COMMON | Read only
CAT_COMMON | Read only
72
CONTROL:control_level
CAT_APPLI | Read/Write
Description :
This configuration describes how the drone will interprete the progressive commands from the user.
Bit 0 is a global enable bit, and should be left active.
Bit refers to a combined yaw mode, where the roll commands are used to generates roll+yaw based turns. This is intended to be an easier control mode for racing games.
Note : This configuration and the flags parameter of the ardrone_at_set_progress_commands function will be compared on the drone. To activate the combined yaw mode, you must set both the bit 1 of the control_level configuration, and the bit 1 of the function parameters.
The ardrone_at_set_progress_commands function parameter reflects the current user commands, and must be set only when the combined_yaw controls are activated (e.g. both buttons pressed)
This configuration should be left active on the AR.Drone if your application makes use of the combined_yaw functionnality.
AT command example : AT* CONFIG = 605 ,"control:control_level","3"
API use example :
ardrone_control_config.control_level |= (1 « CONTROL_LEVEL_COMBINED_-
YAW);
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (control_level, &(ardrone_control_config.control_level), myCallback);
CONTROL:shield_enable
Description :
Reserved for future use.
CAT_COMMON | Read/Write
CONTROL:euler_angle_max
CAT_USER | Read/Write
Description :
Maximum bending angle for the drone in radians, for both
and
angles.
The
and
refer to a percentage of this value.
This parameter is a positive floating-point value between 0 and 0.52 (ie. 30 deg). Higher values might be available on a specific drone but are not reliable and might not allow the drone to stay at the same altitude.
This value will be saved to indoor/outdoor_euler_angle_max, according to the CONFIG:outdoor setting.
AT command example : AT* CONFIG = 605 ,"control:euler_angle_max","0.25"
API use example :
float eulerMax = 0.25;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (euler_angle_max, &eulerMax, myCallback);
73
CONTROL:altitude_max
Description :
Maximum drone altitude in millimeters.
CAT_COMMON | Read/Write
Give an integer value between 500 and 5000 to prevent the drone from flying above this limit, or set it to 10000 to let the drone fly as high as desired.
AT command example : AT* CONFIG = 605 ,"control:altitude_max","3000"
API use example :
uint32_t altMax = 3000;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (altitude_max, &altMax, myCallback);
CONTROL:altitude_min
Description :
Minimum drone altitude in millimeters.
CAT_COMMON | Read/Write
Should be left to default value, for control stabilities issues.
AT command example : AT* CONFIG = 605 ,"control:altitude_min","50"
API use example :
uint32_t altMin = 50;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (altitude_min, &altMin, myCallback);
CONTROL:control_trim_z
Description :
Manual trim function : should not be used.
CAT_USER | Read/Write
CONTROL:control_iphone_tilt
CAT_USER | Read/Write
Description :
The angle in radians for a full iPhone accelerometer command. This setting is stored and computed on the AR.Drone so an iPhone application can send progressive commands without taking this in account.
On AR.FreeFlight, the progressive command sent is between 0 and 1 for angles going from 0 to
90
. With a control_iphone_tilt of 0.5 (approx 30), the drone will saturate the command at 0.33
Note : This settings corresponds to the iPhone tilt max setting of AR.FreeFlight
AT command example : AT* CONFIG = 605 ,"control:control_iphone_tilt","0.25"
API use example :
float iTiltMax = 0.25;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (control_iphone_tilt, &iTiltMax, myCallback);
74
CONTROL:control_vz_max
Description :
Maximum vertical speed of the AR.Drone, in milimeters per second.
CAT_USER | Read/Write
Recommanded values goes from 200 to 2000. Others values may cause instability.
This value will be saved to indoor/outdoor_control_vz_max, according to the CONFIG:outdoor setting.
AT command example : AT* CONFIG = 605 ,"control:control_vz_max","1000"
API use example :
uint32_t vzMax = 1000;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (control_vz_max, &vzMax, myCallback);
CONTROL:control_yaw
Description :
Maximum yaw speed of the AR.Drone, in radians per second.
CAT_USER | Read/Write
Recommanded values goes from 40/s to 350/s (approx 0.7rad/s to 6.11rad/s). Others values may cause instability.
This value will be saved to indoor/outdoor_control_yaw, according to the CONFIG:outdoor setting.
AT command example : AT* CONFIG = 605 ,"control:control_yaw","3.0"
API use example :
float yawSpeed = 3.0;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (control_yaw, &yawSpeed, myCallback);
CONTROL:outdoor
CAT_COMMON | Read/Write
Description :
This settings tells the control loop that the AR.Drone is flying outside.
Setting the indoor/outdoor flight will load the corresponding indoor/outdoor_control_yaw, indoor/outdoor_euler_angle_max and indoor/outdoor_control_vz_max.
Note : This settings corresponds to the Outdoor flight setting of AR.FreeFlight
AT command example : AT* CONFIG = 605 ,"control:outdoor","TRUE"
API use example :
bool_t isOutdoor = TRUE;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (outdoor, &isOutdoor, myCallback);
CONTROL:flight_without_shell
Description :
CAT_COMMON | Read/Write
75
This settings tells the control loop that the AR.Drone is currently using the outdoor hull. Deactivate it when flying with the indoor hull
Note : This settings corresponds to the outdoor hull setting of AR.FreeFlight.
Note : This setting is not linked with the CONTROL:outdoor setting. They have different effects on the control loop.
AT command example : AT* CONFIG = 605 ,"control:flight_without_shell","TRUE"
API use example :
bool_t withoutShell = TRUE;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (flight_without_shell, &withoutShell, myCallback);
CONTROL:brushless
Description :
Deprecated.
CAT_COMMON | Read/Write
CONTROL:autonomous_flight
CAT_COMMON | Read/Write
Description :
Deprecated : This setting enables the autonomous flight mode on the AR.Drone. This mode was developped for 2010 CES and is no longer maintained.
Enabling this can cause unexpected behaviour on commercial AR.Drones.
CONTROL:manual_trim
CAT_USER | Read only
Description :
This setting will be active if the drone is using manual trims. Manual trims should not be used on commercial AR.Drones, and this field should always be FALSE.
CONTROL:indoor_euler_angle_max
CAT_USER | Read/Write
Description :
This setting is used when CONTROL:outdoor is false. See the CONTROL:euler_angle_max description for further informations.
CONTROL:indoor_control_vz_max
CAT_USER | Read/Write
Description :
This setting is used when CONTROL:outdoor is false. See the CONTROL:control_vz_max description for further informations.
CONTROL:indoor_control_yaw
Description :
CAT_USER | Read/Write
76
This setting is used when CONTROL:outdoor is false. See the CONTROL:control_yaw description for further informations.
CONTROL:outdoor_euler_angle_max
CAT_USER | Read/Write
Description :
This setting is used when CONTROL:outdoor is true. See the CONTROL:euler_angle_max description for further informations.
CONTROL:outdoor_control_vz_max
CAT_USER | Read/Write
Description :
This setting is used when CONTROL:outdoor is true. See the CONTROL:control_vz_max description for further informations.
CONTROL:outdoor_control_yaw
CAT_USER | Read/Write
Description :
This setting is used when CONTROL:outdoor is true. See the CONTROL:control_yaw description for further informations.
CONTROL:flying_mode
CAT_SESSION | Read/Write
Description :
Since 1.5.1 firmware, the AR.Drone has two different flight modes. The first is the legacy
FreeFlight mode, where the user controls the drone, an a new semi-autonomous mode, called
"HOVER_ON_TOP_OF_ROUNDEL", where the drones will hover on top of a ground tag, and won’t respond to the progressive commands. This new flying mode was developped for 2011
CES autonomous demonstration.
Note : This mode is experimental, and should be used with care. The roundel (cocarde) detection and this flying mode are subject to changes without notice in further firmwares.
Note : Roundel detection must be activated with the DETECT:detect_type setting if you want to use the "HOVER_ON_TOP_OF_ROUNDEL" mode.
Note : Enum with modes can be found in the ardrone_api.h file.
AT command example : AT* CONFIG = 605 ,"control:flying_mode","0"
API use example :
FLYING_MODE fMode = FLYING_MODE_FREE_FLIGHT;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (flying_mode, &fMode, myCallback);
CONTROL:flight_anim
Description :
Use this setting to launch drone animations.
CAT_COMMON | Read/Write
The parameter is a string containing the animation number and its duration, separated with a
77 comma. Animation numbers can be found in the config.h file.
Note : The MAYDAY_TIMEOUT array contains defaults durations for each flight animations.
AT command example : AT* CONFIG = 605 ,"control:flight_anim","3,2"
API use example :
char param[20]; snprintf (param, sizeof (param), "%d,%d", ARDRONE_ANIMATION_YAW_SHAKE,
MAYDAY_TIMEOUT[ARDRONE_ANIMATION_YAW_SHAKE]);
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (flight_anim, param, myCallback);
78
8.6
Network configuration
NETWORK:ssid_single_player
Description :
The AR.Drone SSID. Changes are applied on reboot
AT command example :
CAT_COMMON | Read/Write
AT* CONFIG = 605 ,"network:ssid_single_player","myArdroneNetwork"
API use example :
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (ssid_single_player, "myArdroneNetwork", myCallback);
NETWORK:ssid_multi_player
Description :
Currently unused.
CAT_COMMON | Read/Write
NETWORK:infrastructure
Description :
Reserved for future use.
NETWORK:secure
Description :
Reserved for future use.
CAT_COMMON | Read/Write
CAT_COMMON | Read/Write
NETWORK:passkey
Description :
Reserved for future use.
CAT_COMMON | Read/Write
NETWORK:navdata_port
Description :
The UDP socket port where the navdata are sent. Defaults to 5554.
CAT_COMMON | Read only
NETWORK:video_port
Description :
The UDP socket port where the vido is sent. Defaults to 5555.
CAT_COMMON | Read only
NETWORK:at_port
Description :
CAT_COMMON | Read only
79
The UDP socket port where the AT*commands are sent. Defaults to 5556
NETWORK:cmd_port
Description :
Unused.
CAT_COMMON | Read only
NETWORK:owner_mac
CAT_COMMON | Read/Write
Description :
Mac addres paired with the AR.Drone. Set to "00:00:00:00:00:00" to unpair the AR.Drone.
AT command example : AT* CONFIG = 605 ,"network:owner_mac","01:23:45:67:89:ab"
API use example :
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (owner_mac, "cd:ef:01:23:45:67", myCallback);
NETWORK:owner_ip_address
Description :
Unused.
NETWORK:local_ip_address
Description :
Unused.
NETWORK:broadcast_ip_address
Description :
Unused.
CAT_COMMON | Read/Write
CAT_COMMON | Read/Write
CAT_COMMON | Read/Write
80
8.7
Nav-board configuration
PIC:ultrasound_freq
CAT_COMMON | Read/Write
Description :
Frequency of the ultrasound measures for altitude. Using two different frequencies can reduce significantly the ultrasound perturbations between two AR.Drones.
Only two frequencies ar availaible : 22.22 and 25 Hz.
The enum containing the values are found in the ardrone_common_config.h file.
AT command example : AT* CONFIG = 605 ,"pic:ultrasound_freq","7"
API use example :
ADC_COMMANDS uFreq = ADC_CMD_SELECT_ULTRASOUND_22Hz;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (ultrasound_freq, &uFreq, myCallback);
PIC:ultrasound_watchdog
Description :
Debug configuration that should not be modified.
PIC:pic_version
Description :
The software version of the Nav-board.
CAT_COMMON | Read/Write
CAT_COMMON | Read only
81
8.8
Video configuration
VIDEO:camif_fps
CAT_COMMON | Read only
Description :
Current FPS of the video interface. This may be different than the actual framerate.
VIDEO:camif_buffers
Description :
Buffer depth for the video interface.
CAT_COMMON | Read only
VIDEO:num_trackers
Description :
Number of tracking point for the speed estimation.
CAT_COMMON | Read only
VIDEO:bitrate
CAT_APPLI | Default : Read only | Multiconfig : Read/Write
Description :
When using the bitrate control mode in "VBC_MODE_MANUAL", sets the bitrate of the video transmission (size, in octets, of each frame).
Recommanded values are 20000 for VLIB codec, and 15000 for P264 codec.
Note : This value is dynamically changed when bitrate_control_mode is set to VBC_MODE_-
DYNAMIC. Note : This configuration can’t be changed on default configuration.
AT command example : AT* CONFIG = 605 ,"video:bitrate","15000"
API use example :
uint32_t frameSize = 20000;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (bitrate, &frameSize, myCallback);
VIDEO:bitrate_control_mode
CAT_APPLI | Default : Read only | Multiconfig : Read/Write
Description :
Enables the automatic bitrate control of the video stream. Enabling this configuration will reduce the bandwith used by the video stream under bad Wi-Fi conditions, reducing the commands latency.
Note : Setting the VBC_MODE_DISABLED when codec is P264 can cause unexpected behaviours Note : This configuration can’t be changed on default configuration.
AT command example : AT* CONFIG = 605 ,"video:bitrate_control_mode","1"
API use example :
VIDEO_BITRATE_CONTROL_MODE vbcMode = VBC_MODE_DYNAMIC;
82
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (bitrate_control_mode, &vbcMode, myCallback);
VIDEO:video_codec
CAT_APPLI | Default : Read only | Multiconfig : Read/Write
Description :
Starting from 1.6.4 firmware, the AR.Drone supports two different video codecs:
• VLIB (also called UVLC) : A MJPG-like codec, which was the default one until 1.6.4.
• P264 : A h264-like codec, which should be the default one after 1.6.4.
Codec enums are defined in the file VLIB/video_codec.h. Only UVLC_CODEC and P264_-
CODEC are supported.
Note : As the P264 codec does not support VBC_MODE_DISABLED, setting this codec while in this bitrate control mode will cause the AR.Drone to switch to VBM_MANUAL with a constant bitrate of 15000. Note : This configuration can’t be changed on default configuration.
AT command example : AT* CONFIG = 605 ,"video:video_codec","64"
API use example :
codec_type_t mCodec = P264_CODEC;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (video_codec, &mCodec, myCallback);
VIDEO:videol_channel
Description :
The video channel that will be sent to the controller.
Current implementation supports 4 different channels :
- ZAP_CHANNEL_HORI
- ZAP_CHANNEL_VERT
- ZAP_CHANNEL_LARGE_HORI_SMALL_VERT
- ZAP_CHANNEL_LARGE_VERT_SMALL_HORI
CAT_SESSION | Read/Write
AT command example : AT* CONFIG = 605 ,"video:video_channel","2"
API use example :
ZAP_VIDEO_CHANNEL nextChannel = ZAP_CHANNEL_HORI;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (video_channel, &nextChannel, myCallback);
8.9
Leds configuration
83
LEDS:leds_anim
Description :
Use this setting to launch leds animations.
CAT_COMMON | Read/Write
The parameter is a string containing the animation number, its frequency (Hz) and its duration
(s), separated with commas. Animation names can be found in the led_animation.h file.
Note : The frequency parameter is a floating point parameter, but in configuration string it will be print as the binary equivalent integer.
AT command example : AT* CONFIG = 605 ,"leds:leds_anim","3,1073741824,2"
API use example :
char param[20]; float frequency = 2.0; snprintf (param, sizeof (param), "%d,%d,%d", ARDRONE_LED_ANIMATION_BLINK_-
ORANGE, *(unsigned int *)&frequency, 5);
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (leds_anim, param, myCallback);
84
8.10
Detection configuration
DETECT:enemy_colors
CAT_COMMON | Read/Write
Description :
The color of the hulls you want to detect. Possible values are green, yellow and blue (respective integer values as of 1.5.1 firmware : 1, 2, 3).
Note : This config will only be used for standard tags/hulls detection. New detection algorithms (Cocarde, Stripe) have predefined colors.
AT command example : AT* CONFIG = 605 ,"detect:enemy_colors","2"
API use example :
ENEMY_COLORS_TYPE enemyColors = ARDRONE_DETECTION_COLOR_BLUE;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (enemy_colors, &enemyColors, myCallback);
DETECT:groundstripe_colors
CAT_SESSION | Read/Write
Description :
The color of the ground stripe you want to detect. Possible values are orange/green and, yellow/blue (respective integer values as of 1.6.4 firmware : 0x10, 0x11).
Note : This config will only be used for groundstripe detection.
AT command example : AT* CONFIG = 605 ,"detect:groundstripe_colors","0x10"
API use example :
COLORS_DETECTION_TYPE color = ARDRONE_ENEMY_COLOR_ARRACE_FINISH_-
LINE;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (groundstripe_colors, &color, myCallback);
DETECT:enemy_without_shell
CAT_COMMON | Read/Write
Description :
Activate this in order to detect outdoor hulls. Deactivate to detect indoor hulls.
AT command example : AT* CONFIG = 605 ,"detect:enemy_without_shell","1"
API use example :
uint32_t activated = 0;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (enemy_without_shell, &activated, myCallback);
DETECT:detect_type
Description :
Select the active tag detection.
CAT_SESSION | Read/Write
Some details about detections can be found in the ardrone_api.h file.
85
Note : It is advised to enable the multiple detection mode, and then configure the detection needed using the following keys.
Note : Roundel (Cocarde) detection is experimental and may be changed in further firmwares.
Note : The multiple detection mode allow the selection of different detections on each camera.
Note that you should NEVER enable two similar detection on both cameras, as this will cause failures in the algorithms.
AT command example : AT* CONFIG = 605 ,"detect:detect_type","10"
API use example :
CAD_TYPE detectType = CAD_TYPE_MULTIPLE_DETECTION_MODE;
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (detect_type, &detectType, myCallback);
DETECT:detections_select_h
CAT_SESSION | Read/Write
Description :
Bitfields to select detections that should be enabled on horizontal camera.
Detections offsets are defined in the ardrone_api.h file.
Note : Roundel (Cocarde) detection is experimental and may be changed in further firmwares.
Note : You should NEVER enable one detection on two different cameras.
AT command example : AT* CONFIG = 605 ,"detect:detections_select_h","1"
API use example :
uint32_t detectH = TAG_TYPE_MASK (TAG_TYPE_SHELL_TAG);
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (detections_select_h, &detectH, myCallback);
DETECT:detections_select_v_hsync
CAT_SESSION | Read/Write
Description :
Bitfileds to select the detections that should be enabled on vertical camera.
Detection enables in the hsync mode will run synchronously with the horizontal camera pipeline, a 20fps instead of 60. This can be useful to reduce the CPU load when you don’t need a 60Hz detection.
Note : You should use either v_hsync or v detections, but not both at the same time. This can cause unexpected behaviours.
Note : Notes from DETECT:detections_select_h also applies.
AT command example : AT* CONFIG = 605 ,"detect:detections_select_v_hsync","2"
API use example :
uint32_t detectVhsync = TAG_TYPE_MASK (TAG_TYPE_ROUNDEL);
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (detections_select_v_hsync, &detectVhsync,
86 myCallback);
DETECT:detections_select_v
CAT_SESSION | Read/Write
Description :
Bitfileds to select the detections that should be active on vertical camera.
These detections will be run at 60Hz. If you don’t need that speed, using detections_select_v_hsync instead will reduce the CPU load.
Note : See the DETECT:detections_select_h and DETECT:detections_select_v_hsync for further details.
AT command example : AT* CONFIG = 605 ,"detect:detections_select_v","2"
API use example :
uint32_t detectV = TAG_TYPE_MASK (TAG_TYPE_ROUNDEL);
ARDRONE_TOOL_CONFIGURATION_ADDEVENT (detections_select_v, &detectV, myCallback);
87
8.11
SYSLOG section
This section is a Parrot internal debug section, and should therefore not be used.
8.12
CUSTOM section - Multiconfig support
CUSTOM:application_id
CAT_SESSION | Read/Write
Description :
Sets the current application identifier (creates application settings if they don’t exist, switch to application afterwise) Note : To remove an application, put a "-" before its id (e.g. "-01234567").
Note : To remove all applications, use "-all" as id. Note : When removing a multiconfig setting, ensure that you won’t remove any "other application" setting !
AT command example : AT* CONFIG = 605 ,"custom:application_id","0a1b2c3d"
CUSTOM:application_desc
Description :
Sets the current application description string
AT command example :
Name"
CAT_APPLI | Read/Write
AT* CONFIG = 605 ,"custom:application_desc","My Application
CUSTOM:profile_id
CAT_SESSION | Read/Write
Description :
Sets the current user identifier (creates user settings if they don’t exist, switch to user afterwise)
Note : To remove a profile, put a "-" before its id (e.g. "-01234567"). Note : To remove all profiles, use "-all" as id. Note : When removing a multiconfig setting, ensure that you won’t remove any "other application" setting !
AT command example : AT* CONFIG = 605 ,"custom:profile_id","0a1b2c3d"
CUSTOM:profile_desc
CAT_USER | Read/Write
Description :
Sets the current user description string (typically user name). Note : "Hidden" users description starts with a dot (’.’)
AT command example : command example :
AT* CONFIG = 605 ,"custom:profile_desc","My Visible User" AT
AT* CONFIG = 605 ,"custom:profile_desc",".My Hidden User"
CUSTOM:session_id
Description :
CAT_SESSION | Read/Write
88
Sets the current session identifier (creates session settings if they don’t exist, switch to session afterwise) Note : To remove a session, put a "-" before its id (e.g. "-01234567"). Note : To remove all session, use "-all" as id. Note : When removing a multiconfig setting, ensure that you won’t remove any "other application" setting !
AT command example : AT* CONFIG = 605 ,"custom:session_id","0a1b2c3d"
CUSTOM:session_desc
Description :
Sets the current session description string.
AT command example :
CAT_SESSION | Read/Write
AT* CONFIG = 605 ,"custom:session_desc","Session 0a1b2c3d"
9
F.A.Q.
Here you will find questions frequently asked on the different forums.
Why is the Android example incomplete ?
The AR.Drone product was designed to work with an ad-hoc Wifi connection, in order to be controllable anywhere in the wild from a mobile device like the iPhone. Unfortunately Google does not currently officially allow the use of ad-hoc connections with the Android OS. Though such connection is technically possible, the Android example application is not a priority until
Google changes its mind. It was successfully run on a Nexus One phone though, and the code is provided for people who are not afraid of jail breaking their phone and getting their hands dirty.
Can I add some additional hardware to the drone ?
This is currently not supported. The drone has a USB master port that could be used later to customize the drone hardware, but it is disbaled on current drones.
Can I replace the embedded drone software with my own ? Can I get the sensors and engines specifications ?
No. This SDK is meant to allow remote controlling of the drone only.
89
Part II
Tutorials
91
10
Building the iOS
Example
The AR.Drone SDK provides the full source code of AR.FreeFligt iPhone application.
To compile both the Control Engine and the AR.FreeFlight project, you need to use Apple
XCode IDE on an Apple computer.
You also need to have an Apple developper account with associated Developper profiles.
Further informations can be found on Apple website
93
11
Building the Linux
Examples
The AR.Drone SDK provides two client application examples for Linux.
The first one, called Linux SDK Demo, shows the minimum software required to control an
AR.Drone with a gamepad. It should be used as a skeleton for all your Linux projects.
The second one, called ARDrone Navigation, is the tool used internally at Parrot to test drones in flight. It shows all the information sent by the drone during a flight session.
In this section, we are going to show you how to build those example on an Ubuntu 10.04
workstation. We will suppose you are familiar with C programming and you already have a C compiler installed on your machine.
11.1
Set up your development environment
If you have not done so yet, please download the latest version of the SDK here (you must first register on the site).
Then unpack the archive ARDrone_API-x.x.x.tar.bz2 in the directory of your choice. In this document we will note hSDKithe extracted directory name.
$ tar xjf ARDrone_API-«<ARDversion»>.tar.bz2
95
96
To build the examples, you will need libraries like IW (for wireless management), gtk (to display an graphic interface), and SDL (to easily display the video stream) :
$ sudo apt-get update
$ sudo apt-get install libsdl-dev libgtk2.0-dev libiw-dev
11.2
Prepare the source code
The demonstration programs allow you to pilot the drone with a gamepad. To keep the code simple enough, it only works with two models of gamepads : a Logitech Precision gamepad and a Sony Playstation 3 gamepad. If you own one of these, you can plug it now and skip this section. Otherwise you must first change a few settings in the code, or the demonstration programs won’t do much.
Identify your gamepad
Plug the gamepad you want to use, and retrieve its USB identifier with the lsusb command.
Here is an example for the logitech gamepad :
We are interested in the ID 046d:c21a information. It must be copied at the beginning of the
sdk_demo/Sources/UI/gamepad.h file.
Listing 11.1: Changing gamepad.h
...
// replace this value with the ID of your own gamepad
#define GAMEPAD_LOGITECH_ID 0x046dc21a
...
This value will be used by the SDK demo program to find which gamepad to query when flying.
Next step is identifying the buttons on your gamepad, with the jstest utility :
$ sudo apt-get install joystick
$ jstest /dev/input/js0
97
You will see a list of axes and buttons; play with your gamepads buttons and make a list of which buttons you want to use to go up/down,left/right,etc.
Once you have done so, edit the sdk_demo/Sources/UI/gamepad.c file, and search the gamepad_update function. This function is called 20 times per second and reads the gamepad state to send according commands to the drone. The code should be self-explanatory; have a look at the
update_ps3pad for an example with a analogic pad.
Please do the same to the and Navigation/Sources/UI/gamepad.c file, for the two examples programs are independant and do not share their gamepad management code, though they are the same. You can even copy/paste the gamepad files between the two examples.
11.3
Compile the SDK Demo example
First we must build the ARDroneLIB library, by using the makefile provided :
$ cd
hSDKi/ARDroneLib/Soft/Build
$ make
Compilation is successful if the last executed action is "ar rcs libpc_ardrone.a ..." and succeeds.
The second step is to compile the example itself :
$ cd
hSDKi/Examples/Linux/sdk_demo/Build
$ make
An executable program called linux_sdk_demo is created in the current working directory.
11.4
Run the SDK Demo program
First unpair your drone if you flew with an iPhone before !
Although the demonstration program can configure the WIFI network itself, it is safer for a first test to manually connect your workstation to the drone WIFI network, and potentially manually configure its IP address to 192.168.1.xxx and subnet mask to 255.255.255.0, where xxx>1.
Once this is done, you can test the connection with a ping command :
$ ping 192.168.1.1
If connection is successful, the ping command will return you the time needed for data to go back and forth to the drone.
You can then launch the demo program :
What to expect ?
98
Check the printed messages; it should say a gamepad was found and then initialize a bunch of things :
Now press the button you chose as the select button. Press it several times to make the motors leds switch between red (emergency mode) and green(ready to fly mode).
Clear the drone surroundings and press the button you chose as the start button. The drone should start flying.
11.5
Compile the Navigation example
First we must build the ARDroneLIB library (unless you already have for the SDK Demo example), by using the makefile provided :
$ cd
hSDKi/ARDroneLib/Soft/Build
$ make
Compilation is successful if the last executed action is "ar rcs libpc_ardrone.a ..." and succeeds.
The second step is to compile the example itself :
$ cd
hSDKi/Examples/Linux/Navigation/Build
$ make
An executable program called ardrone_navigation is created in the hSDKi/ARDroneLib/Version/Release directory.
99
11.6
Run the Navigation program
First unpair your drone if you flew with an iPhone before !
Although the demonstration program can configure the WIFI network itself, it is safer for a first test to manually connect your workstation to the drone WIFI network, and potentially manually configure its IP address to 192.168.1.xxx and subnet mask to 255.255.255.0, where xxx>1.
Once this is done, you can test the connection with a ping command :
$ ping 192.168.1.1
If connection is successful, the ping command will return you the time needed for data to go back and forth to the drone.
You can then launch the navigation program :
What to expect ?
You should see a GUI showing the current drone state. If connection with the drone is successful, the central graphs entitled theta,phi and psi should change according to the drone angular position. In the following screenshot the drone is bending backwards.
Now press the button you chose as the select button. Press it several times to make the motors leds switch between red (emergency mode) and green(ready to fly mode).
Clear the drone surroundings and press the button you chose as the start button. The drone should start flying.
100
Check the VISION image checkbox to make a second window appear, which will display the video stream :
Feel free to click on all the buttons you want to discover all the commands and all the information sent by the drone (just be careful with the PID gains) !
12
Building the Windows
Example
The AR.Drone SDK provides a client application example for Windows.
This example called SDK Demo, shows the minimum software required to control an AR.Drone
with a gamepad or a keyboard. It should be used as a skeleton for all your Windows projects.
In this section, we are going to show you how to build this example on a Windows Seven workstation. We will suppose you are familiar with C programming and you already have
Visual Studio installed on your machine.
12.1
Set up your development environment
Get some development tools
This demo was tested with Microsoft Visual C++ 2008 Express edition, on a Windows 7 64Bits
Platform. It should work with any version of Windows XP, Vista, and Seven with minor changes if any.
The required libraries are :
• The Microsoft Windows SDK ( available here ), Windows Headers and Library.
• The Microsoft DirectX SDK ( available here ), to use a Gamepad for drone control.
• The SDL Library ( available here ) which is used in the example to display the video, but which can be easily replaced;
• Only for Windows XP and earlier - The Pthread for Win32 library ( available here )
101
102
Get the development files
You should have downloaded and unpacked the following elements :
• the ARDroneLib directory (with the Soft, VLIB and VP_SDK subdirectories)
• the Examples directory and specifically its Win32 subdirectory, which contains :
–
the demonstration source code in sdk_demo
–
the Visual C++ 2008 Express solution in VCProjects
Make the project aware of the code location on your computer
• Open the Visual Studio solution ( file \Examples \Win 32\VCProjects \ARDrone \ARDrone .sln).
• Open the Property Manager tab (next to the Solution Explorer and the Class View tabs).
• Double click on any of the ArDrone_properties entry to edit it.
• Go to
Common Properties -> User Macros
• Edit the
ARDroneLibDir
macro so its contains the path to the ARDroneLib directory on your computer.
• Edit the
Win32ClientDir
macro so its contains the path to the demonstration source code directory on your computer.
Note : you can also directly modify those paths by editing the ArDrone_properties.vsprops file with any text editor.
Make the project aware of the libraries location on your computer
• In Visual Studio up to version 2008, the menu
Tools->Options->Environment->Projects and Solutions->VC++ Directories
must contains the paths to the Include and Libraries files for the above mentioned prerequisite libraries.
• In Visual Studio 2010, these directories must be set in the Project settings.
103
12.2
Required settings in the source code before compiling
Operating System related settings
In the Solution Explorer, search for the vp_os_signal_dep.h in the ARDroneLib project.
In this header file, one of the two following macros must be defined :
• Use #
define USE_WINDOWS_CONDITION_VARIABLES
to use Microsoft Windows SDK for thread synchronisation (you must have Windows Vista or later)
• Use #
define USE_PTHREAD_FOR_WIN32
to use pthreads for synchronisation (mandatory if you have Windows XP or earlier, possible with later Windows versions)
Drone related settings
The win32_custom.h file contains the IP address to connect to. It’s 192.168.1.1 by default, but the drone actual IP address might be different if several drones use the same Wifi network
(drones then pick random addresses to avoid IP address conflicts). Check your drone IP address with pings or telnet commands before running the example.
Gamepad related settings
The gamepad.cpp file contains code to pick the first gamepad that can be found on the computer and which is supported by the DirectX subsystem. In the example, buttons are statically linked to drone actions for three specific gamepads. Other gamepads have no effect. Please modify this code to enable the drone to move with your own input device (code should be selfexplanatory).
To identify the buttons available on your gamepad, go to the Windows configuration pannel and go to your gamepad properties pages (there you can calibrate your pad and test the buttons and sticks). You can also use the Microsoft DirectX SDK \Samples \C ++\DirectInput \Joystick tool.
12.3
Compiling the example
Simply generate the solution once the above mentioned settings were done.
104
12.4
What to expect when running the example
Before running the example, one of the computer network connections must be connected with the drone. Pinging the drone or connecting to its telnet port MUST work properly. The drone
MUST NOT be paired with an iPhone (using the drone with an iPhone prevents the drone from accepting connections from any other device, including a PC, unless the unpair button (below the drone) is pressed (which is acknowledged by the drone by making the motor leds blink).
If the network is correctly set, running the example will display a console window showing which commands are being sent to the drone, and a graphic window showing the drone broadcasted video.
You can then control the drone by using your gamepad, or use the keyboard with the following jeys :
Key
8
or I
2
or K
4
or J
6
or L
A
or +
Q
or -
7
or U
9
or O
Action
Fly forward
Fly backward
Fly leftward
Fly rightward
Fly up
Fly down
Rotate anticlockwise
Rotate clockwise
Space
Takeoff/Land
Escape
or Tab Send emergency
1
/recover from emergency signal
F
G
Send flat trim command
Hover
105
The example is basic one which simply hangs by saying "Connection timeout" if no connection is possible. Check the network connectivity and restart the application if such thing happens.
The video window does not respond if no video is received from the drone. Close the console window to close the application, or deport the SDL window management code from the video processing thread to an independent thread.
12.5
Quick summary of problems solving
P.
The application starts, but no video is displayed, or "Connection timeout" appears.
S.
The client was to slow connecting to the drone, or could not connect. Restart the application, or check your network configuration if the problem remains.
P.
I can’t open any source file from the solution explorer
S.
Make sure the
ARDroneLibDir
and
Win32ClientDir
macros are set in the Properties Manager
P.
I get the "Windows.h : no such file or directory" message when compiling.
S.
Make sure the Windows SDK was correctly installed. A light version should be installed along with VC Express.
P.
I get the "Cannot open input file ’dxguid.lib’ message when compiling.
S.
Make sure the DirectX SDK was correctly installed
P.
I get the "Error spawning mt.exe" message when compiling.
S.
There is a problem with the Windows SDK installation. Please reinstall.
13
Other platforms
13.1
Android example
Please refer to the <SDK>/Examples/Android/ardrone directory, and its two files INSTALL and
README to compile the Android example. It was successfully tested (controls and video display) on a rooted Google/HTC Nexus One phone, using NDK r3.
107
Download
Offentligt link opdateret
Det offentlige link til din chat er blevet opdateret. You may view and manage your chat links after registration here.
Dokument offentligt link
Annonce
