vcs.maemo.org Git - mardrone/blob - mardrone/ARDrone_SDK_Version_1_8_20110726/ARDroneLib/Soft/Lib/ardrone_tool/ardrone_tool.h

   1 #ifndef _ARDRONE_TOOL_H_
   2 #define _ARDRONE_TOOL_H_
   3
   4 #include <ardrone_api.h>
   5 #include <VP_Os/vp_os_types.h>
   6 #include <config.h>
   7
   8 #define ARDRONE_REFRESH_MS        20
   9
  10 #define MAX_NAME_LENGTH           255
  11 #define MAX_NUM_DEVICES           10
  12 #define MAX_NUM_INPUT_EVENTS      16
  13
  14 #ifdef ND_WRITE_TO_FILE
  15 extern uint32_t num_picture_decoded;
  16 extern uint32_t wiimote_enable;
  17 extern float32_t wiimote_ax, wiimote_ay, wiimote_az;
  18 #endif
  19
  20 extern char wifi_ardrone_ip[];
  21 extern char app_id[];
  22 extern char app_name[];
  23 extern char usr_id[];
  24 extern char usr_name[];
  25 extern char ses_id[];
  26 extern char ses_name[];
  27
  28 typedef struct _ardrone_tool_configure_data_t {
  29   char* var;
  30   char* value;
  31 } ardrone_tool_configure_data_t;
  32
  33 ///
  34 /// Required api each tool can implement
  35 ///
  36 extern ardrone_tool_configure_data_t configure_data[] WEAK;
  37
  38 extern C_RESULT ardrone_tool_init_custom(int argc, char **argv) WEAK;
  39 extern C_RESULT ardrone_tool_update_custom( void ) WEAK;
  40 extern C_RESULT ardrone_tool_display_custom( void ) WEAK;
  41 extern C_RESULT ardrone_tool_shutdown_custom( void ) WEAK;
  42 extern bool_t   ardrone_tool_exit( void ) WEAK;
  43
  44 // cmd line parsing
  45 extern C_RESULT ardrone_tool_check_argc_custom( int32_t argc) WEAK;
  46 extern void ardrone_tool_display_cmd_line_custom( void ) WEAK;
  47 extern bool_t ardrone_tool_parse_cmd_line_custom( const char* cmd ) WEAK;
  48
  49 // Tricky ...
  50 extern int custom_main(int argc, char **argv) WEAK;
  51
  52 // This is implemented by the library
  53 #ifdef NO_ARDRONE_MAINLOOP
  54 C_RESULT ardrone_tool_init( const char* ardrone_ip, size_t n, AT_CODEC_FUNCTIONS_PTRS *ptrs, const char *appname, const char *usrname);
  55 #else
  56 C_RESULT ardrone_tool_init(int argc, char **argv);
  57 #endif
  58 C_RESULT ardrone_tool_set_refresh_time(int refresh_time_in_ms);
  59 C_RESULT ardrone_tool_pause( void );
  60 C_RESULT ardrone_tool_resume( void );
  61 C_RESULT ardrone_tool_setup_com( const char* ssid );
  62 C_RESULT ardrone_tool_update(void);
  63 C_RESULT ardrone_tool_shutdown(void);
  64
  65
  66 void ardrone_tool_send_com_watchdog(void);  // To send it only once
  67 int main();
  68
  69 // There because not defined in embedded
  70 void api_configuration_get_ctrl_mode(void);
  71 void api_configuration_ack_ctrl_mode(void);
  72
  73 /*! \page page2
  74  * @defgroup ARDrone_Tool ARDrone_Tool
  75
  76 <p>
  77 <hr>
  78
  79 <center><h2> General Overview </h2></center>
  80
  81 \par
  82
  83 ARDrone Tool is an attempt to create a common base code for all tools that must connect to ARDrone. In this document we call client any tools that link with ARDrone Tool. ARDrone Tool
  84
  85    <ul>
  86    <li> already implements main and do various initialization including com layer
  87    <li> implements stub for ATcodec. All functions declared in ardrone_api.h are implemented.
  88    <li> receives, parses Navdata and calls user defined handlers
  89    <li> provides vp_sdk's stages to record video, ...
  90    <li> provides a framework to handle user inputs (keyboard, gamepad, wiimote)
  91    </ul>
  92
  93 \par
  94
  95 Usually a client will create a user interface
  96 User inputs are refreshed every 20 ms (see ARDRONE_REFRESH_MS in ardrone_tool.h)
  97
  98 \par WEAK functions
  99
 100 ARDrone Tool uses a gcc specific extension : WEAK. This extension allows ARDrone Tool to give a default implementation to functions that can be overriden by clients. Overriding is not mandatory so a client can choose to keep a default implementation for these functions.
 101
 102 \note
 103 Some version of mingw32 doesn't support WEAK function.
 104
 105 <p>
 106 <hr>
 107
 108 <center><h2> Code implementation </h2></center>
 109
 110 \section Navdata
 111
 112 Navdata works with a DHCP's option like system. This text is inspired by the rfc2132.
 113
 114 \par
 115 Navdata items are carried in tagged data items that are stored in the options field of the navdata packet. The data items are also called "options". Basically an option is a declaration respecting the following format:
 116
 117 \code
 118   typedef struct _navdata_option_t {
 119     // Common part
 120     uint16_t  tag;
 121     uint16_t  size;
 122
 123     // Opaque declaration
 124     uint8_t   data[];
 125   } navdata_option_t;
 126 \endcode
 127
 128 For example :
 129
 130 \code
 131   typedef struct _navdata_demo_t {
 132     // Common part
 133     uint16_t    tag;
 134     uint16_t    size;
 135
 136     // Specialize part
 137     uint32_t    ctrl_state;
 138     uint32_t    vbat_flying_percentage;
 139
 140     float32_t   theta;
 141     float32_t   phi;
 142     float32_t   psi;
 143
 144     int32_t     altitude;
 145
 146     float32_t   vx;
 147     float32_t   vy;
 148   } navdata_demo_t;
 149 \endcode
 150
 151 A navdata packet follow the following prototype:
 152
 153 \code
 154   typedef struct _navdata_t {
 155     uint32_t    header;
 156     uint32_t    ardrone_state;
 157     uint32_t    sequence;
 158     bool_t      vision_defined;
 159
 160     navdata_option_t  options[1];
 161   } navdata_t;
 162 \endcode
 163
 164 \par
 165 At the moment of we write this document, developper can choose to send all navdata or only a prefdefined subset called Navdata Demo by using a ardrone config variable called navdata_demo. Navdata demo defines minimum data ARDrone must sent to a remote host
 166
 167 \subsection navdata_list List of navdata options.
 168
 169 In the following subsection we described all the currently available navdata options and their meanings.
 170
 171 <TABLE>
 172 <TR><TH>Option</TH><TH>Description</TH></TR>
 173 <TR><TH>NAVDATA_DEMO</TH><TH>Minimum data needed</TH></TR>
 174 <TR><TH>NAVDATA_TIME</TH><TH>ARDrone current time</TH></TR>
 175 <TR><TH>NAVDATA_RAW_MEASURES</TH><TH>Raw measures (acceleros & gyros) coming from PIC</TH></TR>
 176 <TR><TH>NAVDATA_PHYS_MEASURES</TH><TH>Filtered values after control processing</TH></TR>
 177 <TR><TH>NAVDATA_GYROS_OFFSETS</TH><TH>Gyros offsets</TH></TR>
 178 <TR><TH>NAVDATA_EULER_ANGLES</TH><TH>Fused euler angles</TH></TR>
 179 <TR><TH>NAVDATA_REFERENCES</TH><TH></TH></TR>
 180 <TR><TH>NAVDATA_TRIMS</TH><TH></TH></TR>
 181 <TR><TH>NAVDATA_RC_REFERENCES</TH><TH></TH></TR>
 182 <TR><TH>NAVDATA_PWM</TH><TH>Data used to control motors</TH></TR>
 183 <TR><TH>NAVDATA_ALTITUDE</TH><TH>Estimated values with a relation to altitude</TH></TR>
 184 <TR><TH>NAVDATA_VISION_RAW</TH><TH>Vision's estimated velocities</TH></TR>
 185 <TR><TH>NAVDATA_VISION</TH><TH>Data used when computing vision</TH></TR>
 186 <TR><TH>NAVDATA_VISION_PERF</TH><TH>Performance data collected when profiling vision code</TH></TR>
 187 <TR><TH>NAVDATA_TRACKERS_SEND</TH><TH>Position of all trackers computed by vision</TH></TR>
 188 <TR><TH>NAVDATA_VISION_DETECT</TH><TH>Position of the chemney detected by vision</TH></TR>
 189 <TR><TH>NAVDATA_WATCHDOG</TH><TH>Tells if there was an anormal delay between two navdata packets</TH></TR>
 190 <TR><TH>NAVDATA_IPHONE_ANGLES</TH><TH>Used to send back to iPhone its attitude (was an attempt to compute latency between ardrone & iPhone)</TH></TR>
 191 <TR><TH>NAVDATA_ADC_DATA_FRAME</TH><TH>Used in remote control. Sends data frame coming from PIC</TH></TR>
 192 <TR><TH>NAVDATA_CKS</TH><TH>Description</TH></TR>
 193
 194 \subsection navdata_new Adding/Customizing navdata options
 195
 196 \par
 197
 198 When updating a navdata option or adding a navdata option one must take care to update the following files too:
 199
 200    <ul>
 201    <li> navdata_server.h and navdata_server.c in \ref Toy
 202    <li> navdata.h and navdata.c in Soft/Lib/Control
 203    <li> any navdata handler (in particular ardrone_navdata_file.c in \ref ARDrone_Tool )
 204    </ul>
 205
 206 \note
 207 There's a way to ease this process by defining an header file like config_keys.h (TODO list ;-))
 208
 209 \subsection navdata_handling Handling navdata options
 210
 211 \par
 212 ARDrone Tools provides facility to handle navdata options. First ARDrone Tool will established a connection, as a client, on port 5554, when application starts (it handles timeout and reconnections). Then it will listen to navdata's udp packets to parse navdata options found inside them. We called this functionnality unpacking and it is implemented in Control library (Soft/Lib/Control/navdata.c).
 213
 214 \par
 215 When all options are parsed, navdata handlers are called to allow user to manipulate navdata options. Some handlers are predefined. The most important one is ardrone_navdata_file that registers all incomming navdata in local storage.
 216
 217 \par
 218 To add a new handler, a developper have to implement three functions:
 219
 220    <ul>
 221    <li> an init function
 222    <li> a process function
 223    <li> a release function
 224    </ul>
 225
 226 The init and release functions are called only once and the process function is called whenever a new navdata packet is received. The init function can receive any data as a parameter (see ardrone_navdataf_file.c or navdata_ihm.c if you want examples).
 227
 228 \subsection navdata_control Relationship between flashing/updating and configuration by wifi and navdata
 229
 230 \par
 231 Navdata are also used to regulate data we send to ARDrone. We find out there was problem to send big amount of data (some packets were lost). We decided to split large amount of data in smaller packets and to use navdata to delay their sending.
 232
 233 \par
 234
 235 This approach was generalized to send all files to ARDrone:
 236
 237    <ul>
 238    <li> Update file for P5P software [ARDRONE_UPDATE_CONTROL_MODE]
 239    <li> Update file for ADC software [PIC_UPDATE_CONTROL_MODE]
 240    </ul>
 241
 242 to ask for files containing:
 243
 244    <ul>
 245    <li> Configuration data (ini file) [CFG_GET_CONTROL_MODE]
 246    <li> Log of previous flies [LOGS_GET_CONTROL_MODE]
 247    </ul>
 248
 249 and to know when some commands sent over UDP (for example AT_MSG_ATCMD_CONFIG_EXE) are received by setting a flag in navdata's ardrone_state (ARDRONE_COMMAND_MASK).
 250
 251 \note
 252 CONTROL is perhaps a badly choosen name.
 253
 254  */
 255
 256 #endif // _ARDRONE_TOOL_H_