1page.title=Using the Emulator 2@jd:body 3 4<div id="qv-wrapper"> 5<div id="qv"> 6 7 <h2>In this document</h2> 8 <ol> 9 <li><a href="#overview">Overview</a></li> 10 <li><a href="#avds">Android Virtual Devices and the Emulator</a></li> 11 <li><a href="#starting">Starting and Stopping the Emulator</a></li> 12 <li><a href="#apps">Installing Applications on the Emulator</a></li> 13 <li><a href="#acceleration">Using Hardware Acceleration</a> 14 <ol> 15 <li><a href="#accel-graphics">Configuring Graphics Acceleration</a></li> 16 <li><a href="#accel-vm">Configuring Virtual Machine Acceleration</a></li> 17 </ol> 18 </li> 19 <li><a href="#sdcard">SD Card Emulation</a> 20 <ol> 21 <li><a href="#sdcard-creating">Creating an SD card image</a></li> 22 <li><a href="#sdcard-files">Copying files to an SD card image</a></li> 23 <li><a href="#sdcard-loading">Loading an SD card image</a></li> 24 </ol> 25 </li> 26 <li><a href="#diskimages">Working with Emulator Disk Images</a> 27 <ol> 28 <li><a href="#defaultimages">Default image files</a></li> 29 <li><a href="#runtimeimages">Runtime images: user data and SD card</a></li> 30 <li><a href="#temporaryimages">Temporary images</a></li> 31 </ol> 32 </li> 33 <li><a href="#emulatornetworking">Emulator Networking</a> 34 <ol> 35 <li><a href="#networkaddresses">Network Address Space</a></li> 36 <li><a href="#networkinglimitations">Local Networking Limitations</a></li> 37 <li><a href="#redirection">Using Network Redirection</a></li> 38 <li><a href="#dns">Configuring the Emulator's DNS Settings</a></li> 39 <li><a href="#proxy">Using the Emulator with a Proxy</a></li> 40 <li><a href="#connecting">Interconnecting Emulator Instances</a></li> 41 <li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li> 42 </ol> 43 </li> 44 <li><a href="#console">Using the Emulator Console</a> 45 <ol> 46 <li><a href="#portredirection">Port Redirection</a></li> 47 <li><a href="#geo">Geo Location Provider Emulation</a></li> 48 <li><a href="#events">Hardware Events Emulation</a></li> 49 <li><a href="#power">Device Power Characteristics</a></li> 50 <li><a href="#netstatus">Network Status</a></li> 51 <li><a href="#netdelay">Network Delay Emulation</a></li> 52 <li><a href="#netspeed">Network Speed Emulation</a></li> 53 <li><a href="#telephony">Telephony Emulation</a></li> 54 <li><a href="#sms">SMS Emulation</a></li> 55 <li><a href="#vm">VM State</a></li> 56 <li><a href="#window">Emulator Window</a></li> 57 <li><a href="#terminating">Terminating an Emulator Instance</a></li> 58 </ol> 59 </li> 60 <li><a href="#limitations">Emulator Limitations</a></li> 61 <li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li> 62 </ol> 63 64 <h2>See also</h2> 65 <ol> 66 <li><a href="{@docRoot}tools/help/emulator.html">Android Emulator</a></li> 67 <li><a href="{@docRoot}tools/devices/managing-avds.html">Managing AVDs with AVD Manager</a></li> 68 </ol> 69</div> 70</div> 71 72<p>The Android SDK includes a virtual mobile device emulator 73that runs on your computer. The emulator lets you prototype, develop and test 74Android applications without using a physical device. </p> 75 76<p>The Android emulator mimics all of the hardware and software features 77of a typical mobile device, except that it cannot place actual phone 78calls. It provides a variety of navigation and control keys, which you can "press" 79using your mouse or keyboard to generate events for your application. It also 80provides a screen in which your application is displayed, together with any other 81active Android applications. </p> 82 83<img src="{@docRoot}images/emulator-wvga800l.png" width="367" height="349" /> 84 85<p>To let you model and test your application more easily, the emulator utilizes 86Android Virtual Device (AVD) configurations. AVDs let you define certain hardware 87aspects of your emulated phone and allow you to create many configurations to test 88many Android platforms and hardware permutations. Once your application is running on 89the emulator, it can use the services of the Android platform to invoke other 90applications, access the network, play audio and video, store and retrieve data, 91notify the user, and render graphical transitions and themes. </p> 92 93<p>The emulator also includes a variety of debug capabilities, such as a console 94from which you can log kernel output, simulate application interrupts (such as 95arriving SMS messages or phone calls), and simulate latency effects and dropouts 96on the data network.</p> 97 98 99 100<h2 id="overview">Overview</h2> 101 102<p>The Android emulator is an application that provides a virtual 103mobile device on which you can run your Android applications. It runs a full 104Android system stack, down to the kernel level, that includes a set of 105preinstalled applications (such as the dialer) that you can access from your 106applications. You can choose what version of the Android system you want to 107run in the emulator by configuring AVDs, and you can also customize the 108mobile device skin and key mappings. When launching the emulator and at runtime, 109you can use a variety of commands and options to control its behavior. 110</p> 111 112<p>The Android system images available through the Android SDK Manager contain 113code for the Android Linux kernel, the native libraries, the Dalvik VM, and the 114various Android packages (such as the Android framework and preinstalled 115applications). The emulator provides dynamic binary translation of device 116machine code to the OS and processor architecture of your development 117machine.</p> 118 119<p>The Android emulator supports many hardware features likely to be found on 120mobile devices, including: </p> 121 122<ul> 123 <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li> 124 <li>A 16-bit LCD display</li> 125 <li>One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone 126buttons)</li> 127 <li>A sound chip with output and input capabilities</li> 128 <li>Flash memory partitions (emulated through disk image files on the 129development machine)</li> 130 <li>A GSM modem, including a simulated SIM Card</li> 131 <li>A camera, using a webcam connected to your development computer.</li> 132 <li>Sensors like an accelerometer, using data from a USB-connected Android device.</li> 133</ul> 134 135<p>The following sections describe the emulator and its use for development of Android 136applications in more detail.</p> 137 138 139<h2 id="avds">Android Virtual Devices and the Emulator</h2> 140 141<p>To use the emulator, you first must create one or more AVD configurations. In each 142configuration, you specify an Android platform to run in the emulator and the set of hardware 143options and emulator skin you want to use. Then, when you launch the emulator, you specify 144the AVD configuration that you want to load. </p> 145 146<p>Each AVD functions as an independent device, with its own private storage for 147user data, SD card, and so on. When you launch the emulator with an AVD configuration, 148it automatically loads the user data and SD card data from the AVD directory. By default, 149the emulator stores the user data, SD card data, and cache in the AVD directory.</p> 150 151<p>To create and manage AVDs you use the AVD Manager UI or the <code>android</code> tool 152that is included in the SDK. 153For complete information about how to set up AVDs, see <a 154href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a>.</p> 155 156 157<h2 id="starting">Starting and Stopping the Emulator</h2> 158 159<p>During development and testing of your application, you install and run your 160application in the Android emulator. You can launch the emulator as a standalone 161application from a command line, or you can run it from within your Eclipse 162development environment. In either case, you specify the AVD configuration to 163load and any startup options you want to use, as described in this document. 164</p> 165 166<p>You can run your application on a single instance of the emulator or, 167depending on your needs, you can start multiple emulator instances and run your 168application in more than one emulated device. You can use the emulator's 169built-in commands to simulate GSM phone calling or SMS between emulator 170instances, and you can set up network redirection that allows emulators to send 171data to one another. For more information, see <a href="#telephony">Telephony 172Emulation</a>, <a href="#sms">SMS Emulation</a>, and 173<a href="#emulatornetworking">Emulator Networking</a></p> 174 175<p>To start an instance of the emulator from the command line, navigate to the 176<code>tools/</code> folder of the SDK. Enter <code>emulator</code> command 177like this: </p> 178 179<pre>emulator -avd <avd_name> [<options>]</pre> 180 181<p>This initializes the emulator, loads an AVD configuration and displays the emulator 182window. For more information about command line options for the emulator, see the 183<a href="{@docRoot}tools/help/emulator.html">Android Emulator</a> tool reference.</p> 184 185<p class="note"><strong>Note:</strong> You can run multiple 186instances of the emulator concurrently, each with its own AVD configuration and 187storage area for user data, SD card, and so on.</p> 188 189<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your 190application and starts the emulator automatically, when you run or debug 191the application. You can specify emulator startup options in the Run/Debug 192dialog, in the Target tab. When the emulator is running, you can issue 193console commands as described later in this document.</p> 194 195<p>If you are not working in Eclipse, see <a href="#apps">Installing Applications 196on the Emulator</a> for information about how to install your application.</p> 197 198<p>To stop an emulator instance, just close the emulator's window.</p> 199 200<p>For a reference of the emulator's startup commands and keyboard mapping, see 201the <a href="{@docRoot}tools/help/emulator.html">Android Emulator</a> tool 202reference.</p> 203 204 205<h2 id="apps">Installing Applications on the Emulator</h2> 206 207<p>If you don't have access to Eclipse or the ADT Plugin, you can install your application on the 208emulator using the <a href="{@docRoot}tools/help/adb.html#move">adb</a> utility. Before 209installing the application, you need to build and package it into an <code>.apk</code> as described 210in <a href="{@docRoot}tools/building/index.html">Building and 211Running Apps</a>. Once the application is installed, you can start the emulator from the command 212line as described previously, using any startup options necessary. 213When the emulator is running, you can also connect to the emulator instance's 214<a href="#console">console</a> to issue commands as needed.</p> 215 216<p>As you update your code, you periodically package and install it on the emulator. 217The emulator preserves the application and its state data across restarts, 218in a user-data disk partition. To ensure that the application runs properly 219as you update it, you may need to delete the emulator's user-data partition. 220To do so, start the emulator with the <code>-wipe-data</code> option. 221For more information about the user-data partition and other emulator storage, 222see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> 223 224 225<h2 id="acceleration">Using Hardware Acceleration</h2> 226 227<p>In order to make the Android emulator run faster and be more responsive, you can configure it to 228take advantage of hardware acceleration, using a combination of configuration options, specific 229Android system images and hardware drivers.</p> 230 231 232<h3 id="accel-graphics">Configuring Graphics Acceleration</h3> 233 234<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the graphics 235acceleration feature for the emulator is experimental; be alert for incompatibilities and 236errors when using this feature. </p> 237 238<p>Graphics acceleration for the emulator takes advantage of your development computer's graphics 239hardware, specifically its graphics processing unit (GPU), to make screen drawing faster. To use 240the graphics acceleration feature, you must have the following versions of the Android development 241tools installed:</p> 242 243<ul> 244 <li>Android SDK Tools, Revision 17 or higher</li> 245 <li>Android SDK Platform API 15, Revision 3 or higher</li> 246</ul> 247 248<p>Use the <a href="{@docRoot}sdk/installing/index.html#AddingComponents">Android SDK 249Manager</a> to install these components:</p> 250 251<p class="note"><strong>Note:</strong> Not all applications are compatible with graphics hardware 252acceleration. In particular, the Browser application and applications using the {@link 253android.webkit.WebView} component are not compatible with graphics acceleration.</p> 254 255<p>To configure an AVD to use graphics acceleration:</p> 256 257<ol> 258 <li>Make sure you have the required SDK components installed (listed above).</li> 259 <li>Start the AVD Manager and create a new AVD with the <strong>Target</strong> value of 260<strong>Android 4.0.3 (API Level 15)</strong>, revision 3 or higher.</li> 261 <li>If you want to have graphics acceleration enabled by default for this AVD, in the 262<strong>Hardware</strong> section, click <strong>New</strong>, select <strong>GPU emulation</strong> 263and set the value to <strong>Yes</strong>. 264 <p class="note"><strong>Note:</strong> You can also enable graphics acceleration when you 265start an emulator using command line options as describe in the next section.</p> 266 </li> 267 <li>Name the AVD instance and select any other configuration options. 268 <p class="caution"><strong>Caution:</strong> Do not select the <strong>Snapshot: Enabled</strong> 269option. Snapshots are not supported for emulators with graphics acceleration enabled.</p> 270 </li> 271 <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li> 272</ol> 273 274<p>If you set <strong>GPU emulation</strong> to <strong>Yes</strong> for your AVD, then graphics 275acceleration is automatically enabled when you run it. If you did not enable <strong>GPU 276emulation</strong> when you created the AVD, you can still enable it at runtime.</p> 277 278<p>To enable graphics acceleration at runtime for an AVD:</p> 279 280<ul> 281 <li>If you are running the emulator from the command line, just include the {@code -gpu on} 282option: 283<pre>emulator -avd <avd_name> -gpu on</pre> 284 <p class="note"><strong>Note:</strong> You must specify an AVD configuration that uses 285Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not 286available for earlier system images.</p> 287 </li> 288 <li>If you are running the emulator from Eclipse, run your Android application using an AVD with 289the {@code -gpu on} option enabled: 290 <ol> 291 <li>In Eclipse, click your Android project folder and then select <strong>Run > Run 292Configurations...</strong></li> 293 <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android 294project run configuration or create a new configuration.</li> 295 <li>Click the <strong>Target</strong> tab.</li> 296 <li>Select the AVD you created in the previous procedure.</li> 297 <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:<br> 298 {@code -gpu on}</li> 299 <li>Run your Android project using this run configuration.</li> 300 </ol> 301 </li> 302</ul> 303 304 305<h3 id="accel-vm">Configuring Virtual Machine Acceleration</h2> 306 307<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the virtual machine 308acceleration feature for the emulator is experimental; be alert for incompatibilities and errors 309when using this feature.</p> 310 311<p>Many modern CPUs provide extensions for running virtual machines (VMs) more efficiently. Taking 312advantage of these extensions with the Android emulator requires some additional configuration of 313your development system, but can significantly improve the execution speed. Before attempting to use 314this type of acceleration, you should first determine if your development system’s CPU supports one 315of the following virtualization extensions technologies:</p> 316 317<ul> 318 <li>Intel Virtualization Technology (VT, VT-x, vmx) extensions</li> 319 <li>AMD Virtualization (AMD-V, SVM) extensions (only supported for Linux)</li> 320</ul> 321 322<p>The specifications from the manufacturer of your CPU should indicate if it supports 323virtualization extensions. If your CPU does not support one of these virtualization technologies, 324then you cannot use virtual machine acceleration.</p> 325 326<p class="note"><strong>Note:</strong> Virtualization extensions are typically enabled through 327your computer's BIOS and are frequently turned off by default. Check the documentation for your 328system's motherboard to find out how to enable virtualization extensions.</p> 329 330<p>Once you have determined that your CPU supports virtualization extensions, make sure you can work 331within these additional requirements of running an emulator inside an accelerated virtual 332machine:</p> 333 334<ul> 335 <li><strong>x86 AVD Only</strong> - You must use an AVD that is uses an x86 system image target. 336AVDs that use ARM-based system images cannot be accelerated using the emulator configurations 337described here.</li> 338 <li><strong>Not Inside a VM</strong> - You cannot run a VM-accelerated emulator inside another 339virtual machine, such as a VirtualBox or VMWare-hosted virtual machine. You must run the emulator 340directly on your system hardware.</li> 341 <li><strong>Other VM Drivers</strong> - If you are running another virtualization technology on 342your system such as VirtualBox or VMWare, you may need to unload the driver for that virtual machine 343hosting software before running an accelerated emulator.</li> 344 <li><strong>OpenGL® Graphics</strong> - Emulation of OpenGL ES graphics may not perform at the 345same level as an actual device.</li> 346</ul> 347 348<p>To use virtual machine acceleration with the emulator, you need the following version of Android 349development tools. Use the <a href="{@docRoot}sdk/installing/index.html#AddingComponents">Android SDK 350Manager</a> to install these components:</p> 351 352<ul> 353 <li>Android SDK Tools, Revision 17 or higher</li> 354 <li>Android x86-based system image</li> 355</ul> 356 357<p>If your development environment meets all of the requirements for running a VM-accelerated 358emulator, you can use the AVD Manager to create an x86-based AVD configuration:</p> 359 360<ol> 361 <li>In the Android SDK Manager, make sure you have an x86-based <strong>System Image</strong> 362 installed for your target Android version. If you do not have an x86 <strong>System 363 Image</strong> installed, select one in the Android SDK Manager and install it. 364 <p class="note"><strong>Tip:</strong> System images are listed under each API Level in the SDK 365 Manager. An x86 system image may not be available for all API levels.</p> 366 </li> 367 <li>Start the AVD Manager and create a new AVD with an x86 value for the 368<strong>CPU/ABI</strong> field. You may need to select a specific <strong>Target</strong> value, or 369select a <strong>Target</strong> value and then select a specific <strong>CPU/ABI</strong> 370option.</li> 371 <li>Name the emulator instance and select any other configuration options.</li> 372 <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li> 373</ol> 374 375<h4 id="vm-windows">Configuring VM Acceleration on Windows</h4> 376 377<p>Virtual machine acceleration for Windows requires the installation of the Intel Hardware 378Accelerated Execution Manager (Intel HAXM). The software requires an Intel CPU with 379Virtualization Technology (VT) support and one of the following operating systems:</p> 380 381<ul> 382 <li>Windows 7 (32/64-bit)</li> 383 <li>Windows Vista (32/64-bit)</li> 384 <li>Windows XP (32-bit only)</li> 385</ul> 386 387<p>To install the virtualization driver:</p> 388 389<ol> 390 <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel 391Hardware Accelerated Execution Manager</strong>.</li> 392 <li>After the download completes, execute {@code 393<sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.exe}.</li> 394 <li>Follow the on-screen instructions to complete installation.</li> 395 <li>After installation completes, confirm that the virtualization driver is operating correctly by 396opening a command prompt window and running the following command: 397 <pre>sc query intelhaxm</pre> 398 <p>You should see a status message including the following information:</p> 399<pre> 400SERVICE_NAME: intelhaxm 401 ... 402 STATE : 4 RUNNING 403 ... 404</pre> 405 </li> 406</ol> 407 408<p>To run an x86-based emulator with VM acceleration:</p> 409<ul> 410 <li>If you are running the emulator from the command line, just specify an x86-based AVD: 411<pre>emulator -avd <avd_name></pre> 412 <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration 413name, otherwise VM acceleration will not be enabled.</p> 414 </li> 415 <li>If you are running the emulator from Eclipse, run your Android application with an x86-based 416AVD: 417 <ol> 418 <li>In Eclipse, click your Android project folder and then select <strong>Run > Run 419Configurations...</strong></li> 420 <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android 421project run configuration or create a new configuration.</li> 422 <li>Click the <strong>Target</strong> tab.</li> 423 <li>Select the x86-based AVD you created previously.</li> 424 <li>Run your Android project using this run configuration.</li> 425 </ol> 426 </li> 427</ul> 428 429<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running 430its installer.</p> 431 432<p>You can stop using the virtualization driver by uninstalling it. Re-run the installer or use 433the Control Panel to remove the software.</p> 434 435 436<h4 id="vm-mac">Configuring VM Acceleration on Mac</h4> 437 438<p>Virtual machine acceleration on a Mac requires the installation of the Intel Hardware Accelerated 439Execution Manager (Intel HAXM) kernel extension to allow the Android emulator to make use of CPU 440virtualization extensions. The kernel extension is compatible with Mac OS X Snow Leopard (version 44110.6.0) and higher.</p> 442 443<p>To install the Intel HAXM kernel extension:</p> 444 445<ol> 446 <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel 447Hardware Accelerated Execution Manager</strong>. 448 <li>After the download completes, execute 449 {@code <sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.dmg}.</li> 450 <li>Double click the <strong>IntelHAXM.mpkg</strong> icon to begin installation.</li> 451 <li>Follow the on-screen instructions to complete installation.</li> 452 <li>After installation completes, confirm that the new kernel extension is operating correctly by 453opening a terminal window and running the following command: 454 <pre>kextstat | grep intel</pre> 455 <p>You should see a status message containing the following extension name, indicating that the 456 kernel extension is loaded:</p> 457 <pre>com.intel.kext.intelhaxm</pre> 458 </li> 459</ol> 460 461<p>To run an x86-based emulator with VM acceleration:</p> 462<ul> 463 <li>If you are running the emulator from the command line, just specify an x86-based AVD: 464<pre>emulator -avd <avd_name></pre> 465 <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration 466name, otherwise VM acceleration will not be enabled.</p> 467 </li> 468 <li>If you are running the emulator from Eclipse, run your Android application with an x86-based 469AVD: 470 <ol> 471 <li>In Eclipse, click your Android project folder and then select <strong>Run > Run 472Configurations...</strong></li> 473 <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android 474project run configuration or create a new configuration.</li> 475 <li>Click the <strong>Target</strong> tab.</li> 476 <li>Select the x86-based AVD you created previously.</li> 477 <li>Run your Android project using this run configuration.</li> 478 </ol> 479 </li> 480</ul> 481 482<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running 483the installer.</p> 484 485<p>You can stop using the virtualization kernel driver by uninstalling it. Before removing it, shut 486down any running x86 emulators. To unload the virtualization kernel driver, run the following 487command in a terminal window:</p> 488 489<pre>sudo /System/Library/Extensions/intelhaxm.kext/Contents/Resources/uninstall.sh</pre> 490 491<h4 id="vm-linux">Configuring VM Acceleration on Linux</h4> 492 493<p>Linux-based systems support virtual machine acceleration through the KVM software package. Follow 494<a href="https://www.google.com/?q=kvm+installation">instructions for installing KVM</a> on your 495Linux system, and verify that KVM is enabled. In addition to following the installation 496instructions, be aware of these configuration requirements:</p> 497 498<ul> 499 <li>Running KVM requires specific user permissions, make sure you have sufficient permissions 500according to the KVM installation instructions.</li> 501 <li>If you use another virtualization technology in your Linux platform, unload its kernel driver 502before running the x86 emulator. For example, the VirtualBox driver program is {@code vboxdrv}.</li> 503</ul> 504 505<p>To run an x86-based emulator with VM acceleration:</p> 506 507<ul> 508 <li>If you are running the emulator from the command line, start the emulator with an x86-based 509AVD and include the KVM options: 510<pre>emulator -avd <avd_name> -qemu -m 512 -enable-kvm</pre> 511 <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration 512name, otherwise VM acceleration will not be enabled.</p> 513 </li> 514 <li>If you are running the emulator from Eclipse, run your Android application with an x86-based 515AVD and include the KVM options: 516 <ol> 517 <li>In Eclipse, click your Android project folder and then select <strong>Run > Run 518Configurations...</strong></li> 519 <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android 520project run configuration or create a new configuration.</li> 521 <li>Click the <strong>Target</strong> tab.</li> 522 <li>Select the x86-based AVD you created previously.</li> 523 <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter: 524 <pre>-qemu -m 512 -enable-kvm</pre> 525 </li> 526 <li>Run your Android project using this run configuration.</li> 527 </ol> 528 </li> 529</ul> 530 531<p class="note"><strong>Important:</strong> When using the {@code -qemu} command line option, make sure 532it is the last parameter in your command. All subsequent options are interpreted as qemu-specific 533parameters.</p> 534 535 536<h2 id="sdcard">SD Card Emulation</h2> 537 538<p>You can create a disk image and then load it to the emulator at startup, to 539simulate the presence of a user's SD card in the device. To do this, you can specify 540an SD card image when you create an AVD, or you can use the mksdcard utility included 541in the SDK.</p> 542 543<p>The following sections describe how to create an SD card disk image, how to copy 544files to it, and how to load it in the emulator at startup. </p> 545 546<p>Note that you can only load a disk image at emulator startup. Similarly, you 547can not remove a simulated SD card from a running emulator. However, you can 548browse, send files to, and copy/remove files from a simulated SD card either 549with adb or the emulator. </p> 550 551<p>The emulator supports emulated SDHC cards, so you can create an SD card image 552of any size up to 128 gigabytes.</p> 553 554 555<h3 id="sdcard-creating">Creating an SD card image</h3> 556 557<p>There are several ways of creating an SD card image. The easiest way is to use the 558<strong>AVD Manager</strong> to create a new SD card by specifying a size when you create an AVD. 559You can also use the {@code android} command line tool when creating an AVD. Just add the 560<code>-c</code> option to your command: </p> 561 562<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> 563 564<p>The <code>-c</code> option can also be used to to specify a path to an SD card 565image for the new AVD. For more information, see <a 566href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing Virtual Devices 567from the Command Line</a>. 568</p> 569 570<p>You can also use the mksdcard tool, included in the SDK, to create a FAT32 disk 571image that you can load in the emulator at startup. You can access mksdcard in 572the tools/ directory of the SDK and create a disk image like this: </p> 573 574<pre>mksdcard <size> <file></pre> 575 576<p>For example:</p> 577 578<pre>mksdcard 1024M sdcard1.iso</pre> 579 580<p>For more information, see <a 581href="{@docRoot}tools/help/mksdcard.html"><code>mksdcard</code></a>.</p> 582 583 584<h3 id="sdcard-files">Copying files to an SD card image</h3> 585 586<p>Once you have created the disk image, you can copy files to it prior to 587loading it in the emulator. To copy files, you can mount the image as a loop 588device and then copy the files to it, or you can use a utility such as {@code mtools} to 589copy the files directly to the image. The {@code mtools} package is available for Linux, 590Mac, and Windows.</p> 591 592<p>Alternatively, you can use the {@code adb push} command to move files onto an SD card image 593while it is loaded in an emulator. For more information see the <a 594href="{@docRoot}tools/help/adb.html#copyfiles">{@code adb push}</a> documentation.</p> 595 596<h3 id="sdcard-loading">Loading an SD card image</h3> 597 598<p>By default, the emulator loads the SD card image that is stored with the active 599AVD (see the <code>-avd</code> startup option).</p> 600 601<p>Alternatively, you can start the emulator with the 602<code>-sdcard</code> flag and specify the name and path of your image (relative 603to the current working directory): </p> 604 605<pre>emulator -sdcard <filepath></pre> 606 607 608<h2 id="diskimages">Working with Emulator Disk Images</h2> 609 610<p>The emulator uses mountable disk images stored on your development machine to 611simulate flash (or similar) partitions on an actual device. For example, it uses a 612disk image containing an emulator-specific kernel, the Android system, a 613ramdisk image, and writeable images for user data and simulated SD card.</p> 614 615<p>To run properly, the emulator requires access to a specific set of disk image 616files. By default, the Emulator always looks for the disk images in the 617private storage area of the AVD in use. If no images exist there when 618the Emulator is launched, it creates the images in the AVD directory based on 619default versions stored in the SDK. </p> 620 621<p class="note"><strong>Note:</strong> The default storage location for 622AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and 623Settings\<user>\.android\</code> on Windows XP, and 624<code>C:\Users\<user>\.android\</code> 625on Windows Vista.</p> 626 627<p>To let you use alternate or custom versions of the image files, the emulator 628provides startup options that override the default locations and filenames of 629the image files. When you use one of these options, the emulator searches for the image 630file under the image name or location that you specify; if it can not locate the 631image, it reverts to using the default names and location.</p> 632 633<p>The emulator uses three types of image files: default image files, runtime 634image files, and temporary image files. The sections below describe how to 635override the location/name of each type of file. </p> 636 637<h3 id="defaultimages">Default image files</h3> 638 639<p>When the emulator launches, but does not find an existing user data image in 640the active AVD's storage area, it creates a new one from a default version 641included in the SDK. The default user data image is read-only. The image 642files are read-only.</p> 643 644<p>The emulator provides the <code>-system <dir></code> startup option to 645let you override the location where the emulator looks for the default 646user data image. </p> 647 648<p>The emulator also provides a startup option that lets you override the name 649of the default user data image, as described in the following table. When you use the 650option, the emulator looks in the default directory, or in a custom location 651(if you specified <code>-system <dir></code>). </p> 652 653 654<table> 655<tr> 656 <th width="10%" >Name</th> 657 <th width="30%" >Description</th> 658 <th width="40%" >Comments</th> 659</tr> 660 661<!-- 662<tr> 663 <td><code>kernel-qemu.img</code></td> 664 <td>The emulator-specific Linux kernel image</td> 665 <td>Override using <code>-kernel <file></code></td> 666</tr> 667 668<tr> 669 <td><code>ramdisk.img</code></td> 670 <td>The ramdisk image used to boot the system.</td> 671 <td>Override using <code>-ramdisk <file></code></td> 672</tr> 673 674<tr> 675 <td><code>system.img</code></td> 676 <td>The <em>initial</em> Android system image.</td> 677 <td>Override using <code>-image <file></code></td> 678</tr> 679--> 680<tr> 681 <td><code>userdata.img</code></td> 682 <td>The <em>initial</em> user-data disk image</td> 683 <td>Override using <code>-initdata <file></code>. Also see 684<code>-data <file></code>, below.</td> 685</tr> 686 687</table> 688 689<h3 id="runtimeimages">Runtime images: user data and SD card</h3> 690 691<p>At runtime, the emulator reads and writes data to two disk images: a 692user-data image and (optionally) an SD card image. These images emulate the user-data 693partition and removable storage media on actual device. </p> 694 695<p>The emulator provides a default user-data disk image. At startup, the emulator 696creates the default image as a copy of the system user-data image (user-data.img), 697described above. The emulator stores the new image with the files of the active AVD.</p> 698 699<!-- 700<p>The emulator provides a startup option, <code>-datadir <dir></code>, 701that you can use to override the location under which the emulator looks for the runtime 702image files. </p> 703--> 704 705<p>The emulator provides startup options to let you override the actual names and storage 706locations of the runtime images to load, as described in the following table. When you use one 707of these options, the emulator looks for the specified file(s) in the current working directory, 708in the AVD directory, or in a custom location (if you specified a path with the filename). </p> 709 710<table> 711<tr> 712 <th width="10%" >Name</th> 713 <th width="30%" >Description</th> 714 <th width="40%" >Comments</th> 715</tr> 716<tr> 717 <td><code>userdata-qemu.img</code></td> 718 <td>An image to which the emulator writes runtime user-data for a unique user.</td> 719 <td>Override using <code>-data <filepath></code>, where <code><filepath></code> is the 720path the image, relative to the current working directory. If you supply a filename only, 721the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does 722not exist, the emulator creates an image from the default userdata.img, stores it under the name you 723specified, and persists user data to it at shutdown. </td> 724</tr> 725 726<tr> 727 <td><code>sdcard.img</code></td> 728 <td>An image representing an SD card inserted into the emulated device.</td> 729 <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the 730path the image, relative to the current working directory. If you supply a filename only, 731the emulator looks for the file in the current working directory. </td> 732</tr> 733 734</table> 735 736<h4>User-Data Image</h4> 737 738<p>Each emulator instance uses a writeable user-data image to store user- and 739session-specific data. For example, it uses the image to store a unique user's 740installed application data, settings, databases, and files. </p> 741 742<p>At startup, the emulator attempts to load a user-data image stored during 743a previous session. It looks for the file in the current working directory, 744in the AVD directory described in a previous section and at the custom location/name 745that you specified at startup. </p> 746 747<ul> 748<li>If it finds a user-data image, it mounts the image and makes it available 749to the system for reading and writing of user data. </li> 750<li>If it does not find one, it creates an image by copying the system user-data 751image (userdata.img), described above. At device power-off, the system persists 752the user data to the image, so that it will be available in the next session. 753Note that the emulator stores the new disk image at the location/name that you 754specify in <code>-data</code> startup option.</li> 755</ul> 756 757<p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator, 758each emulator instance gets its own dedicated storage. There is no longer a need 759to use the <code>-d</code> option to specify an instance-specific storage area.</p> 760 761<h4>SD Card</h4> 762 763<P>Optionally, you can create a writeable disk image that the emulator can use 764to simulate removeable storage in an actual device. For information about how to create an 765emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> 766 767<p>You can also use the android tool to automatically create an SD Card image 768for you, when creating an AVD. For more information, see <a 769href="{@docRoot}tools/devices/managing-avds.html">Managing Virtual Devices with AVD 770Manager</a>. 771 772 773<h3 id="temporaryimages">Temporary Images</h3> 774 775<p>The emulator creates two writeable images at startup that it deletes at 776device power-off. The images are: </p> 777 778<ul> 779 <li>A writable copy of the Android system image</li> 780 <li>The <code>/cache</code> partition image</li> 781</ul> 782 783<p>The emulator does not permit renaming the temporary system image or 784persisting it at device power-off. </p> 785 786<p>The <code>/cache</code> partition image is initially empty, and is used by 787the browser to cache downloaded web pages and images. The emulator provides an 788<code>-cache <file></code>, which specifies the name of the file in which 789to persist the <code>/cache</code> image at device power-off. If <code><file> 790</code> does not exist, the emulator creates it as an empty file. </p> 791 792<p>You can also disable the use of the cache partition by specifying the 793<code>-nocache</code> option at startup. </p> 794 795 796<h2 id="emulatornetworking">Emulator Networking</h2> 797 798<p>The emulator provides versatile networking capabilities that you can use to 799set up complex modeling and testing environments for your application. The 800sections below introduce the emulator's network architecture and capabilities. 801</p> 802 803<h3 id="networkaddresses">Network Address Space</h3> 804 805<p>Each instance of the emulator runs behind a virtual router/firewall service 806that isolates it from your development machine's network interfaces and settings 807and from the internet. An emulated device can not see your development machine 808or other emulator instances on the network. Instead, it sees only that it is 809connected through Ethernet to a router/firewall.</p> 810 811<p>The virtual router for each instance manages the 10.0.2/24 network address 812space — all addresses managed by the router are in the form of 81310.0.2.<xx>, where <xx> is a number. Addresses within this space are 814pre-allocated by the emulator/router as follows:</p> 815 816<table> 817 <tr> 818 <th>Network Address</th> 819 <th>Description</th> 820 </tr> 821 <tr> 822 <td>10.0.2.1</td> 823 <td>Router/gateway address </td> 824 </tr> 825 <tr> 826 <td>10.0.2.2</td> 827 <td>Special alias to your host loopback interface (i.e., 127.0.0.1 on your 828development machine)</td> 829 </tr> 830 <tr> 831 <td>10.0.2.3</td> 832 <td>First DNS server</td> 833 </tr> 834 <tr> 835 <td>10.0.2.4 / 10.0.2.5 / 10.0.2.6</td> 836 <td>Optional second, third and fourth DNS server (if any) </td> 837 </tr> 838 <tr> 839 <td>10.0.2.15</td> 840 <td>The emulated device's own network/ethernet interface</td> 841 </tr> 842 <tr> 843 <td>127.0.0.1</td> 844 <td>The emulated device's own loopback interface </td> 845 </tr> 846</table> 847 848<p>Note that the same address assignments are used by all running emulator 849instances. That means that if you have two instances running concurrently on 850your machine, each will have its own router and, behind that, each will have an 851IP address of 10.0.2.15. The instances are isolated by a router and can 852<em>not</em> see each other on the same network. For information about how to 853let emulator instances communicate over TCP/UDP, see <a 854href="#connecting">Connecting Emulator Instances</a>.</p> 855 856<p>Also note that the address 127.0.0.1 on your development machine corresponds 857to the emulator's own loopback interface. If you want to access services running 858on your development machine's loopback interface (a.k.a. 127.0.0.1 on your 859machine), you should use the special address 10.0.2.2 instead.</p> 860 861<p>Finally, note that each emulated device's pre-allocated addresses are 862specific to the Android emulator and will probably be very different on real 863devices (which are also very likely to be NAT-ed, i.e., behind a 864router/firewall)</p> 865 866 867<h3 id="networkinglimitations">Local Networking Limitations</h3> 868 869<p>Android applications running in an emulator can connect to the network available on your 870workstation. However, they connect through the emulator, not directly to hardware, and the emulator 871acts like a normal application on your workstation. This means that the emulator, and thus your 872Android applications, are subject to some limitations:</p> 873 874<ul> 875 <li>Communication with the emulated device may be blocked by a firewall 876program running on your machine.</li> 877 <li>Communication with the emulated device may be blocked by another 878(physical) firewall/router to which your machine is connected.</li> 879</ul> 880 881<p>The emulator's virtual router should be able to handle all outbound TCP and 882UDP connections/messages on behalf of the emulated device, provided your 883development machine's network environment allows it to do so. There are no 884built-in limitations on port numbers or ranges except the one imposed by your 885host operating system and network.</p> 886 887<p>Depending on the environment, the emulator may not be able to support other 888protocols (such as ICMP, used for "ping") might not be supported. Currently, the 889emulator does not support IGMP or multicast. </p> 890 891<h3 id="redirection">Using Network Redirection</h3> 892 893<p>To communicate with an emulator instance behind its virtual router, you need 894to set up network redirection on the virtual router. Clients can then connect 895to a specified guest port on the router, while the router directs traffic 896to/from that port to the emulated device's host port. </p> 897 898<p>To set up the network redirection, you create a mapping of host and guest 899ports/addresses on the emulator instance. There are two ways to set up 900network redirection: using emulator console commands and using the ADB tool, as 901described below. </p> 902 903 904<h4 id="consoleredir">Setting up Redirection through the Emulator Console</h4> 905 906<p>Each emulator instance provides a control console the you can connect to, to 907issue commands that are specific to that instance. You can use the 908<code>redir</code> console command to set up redirection as needed for an 909emulator instance. </p> 910 911<p>First, determine the console port number for the target emulator instance. 912For example, the console port number for the first emulator instance launched is 9135554. Next, connect to the console of the target emulator instance, specifying 914its console port number, as follows: </p> 915 916<pre><code>telnet localhost 5554</code></pre> 917 918<p>Once connected, use the <code>redir</code> command to work with redirection. 919To add a redirection, use:</p> 920 921<pre><code>add <protocol>:<host-port>:<guest-port></code> 922</pre> 923 924<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, 925and <code><host-port></code> and <code><guest-port></code> sets the 926mapping between your own machine and the emulated system, respectively. </p> 927 928<p>For example, the following command sets up a redirection that handles all 929incoming TCP connections to your host (development) machine on 127.0.0.1:5000 930and will pass them through to the emulated system's 10.0.2.15:6000.:</p> 931 932<pre>redir add tcp:5000:6000</pre> 933 934<p>To delete a redirection, you can use the <code>redir del</code> command. To 935list all redirection for a specific instance, you can use <code>redir 936list</code>. For more information about these and other console commands, see 937<a href="#console">Using the Emulator Console</a>. </p> 938 939<p>Note that port numbers are restricted by your local environment. this typically 940means that you cannot use host port numbers under 1024 without special 941administrator privileges. Also, you won't be able to set up a redirection for a 942host port that is already in use by another process on your machine. In that 943case, <code>redir</code> generates an error message to that effect. </p> 944 945<h4 id="adbredir">Setting Up Redirection through ADB</h4> 946 947<p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate 948way for you to set up network redirection. For more information, see <a 949href="{@docRoot}tools/help/adb.html#forwardports">Forwarding Ports</a> in the ADB 950documentation.</p> 951 952<p>Note that ADB does not currently offer any way to remove a redirection, 953except by killing the ADB server.</p> 954 955 956<h3 id="dns">Configuring the Emulator's DNS Settings</h3> 957 958<p>At startup, the emulator reads the list of DNS servers that your system is 959currently using. It then stores the IP addresses of up to four servers on this 960list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, 96110.0.2.5 and 10.0.2.6 as needed. </p> 962 963<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing 964the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the 965addresses by calling the <code>GetNetworkParams()</code> API. Note that this 966usually means that the emulator ignores the content of your "hosts" file 967(<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code> 968 on Windows).</P> 969 970<p>When starting the emulator at the command line, you can also use the 971<code>-dns-server <serverList></code> option to manually specify the 972addresses of DNS servers to use, where <serverList> is a comma-separated 973list of server names or IP addresses. You might find this option useful if you 974encounter DNS resolution problems in the emulated network (for example, an 975"Unknown Host error" message that appears when using the web browser).</p> 976 977 978<h3 id="proxy">Using the Emulator with a Proxy</h3> 979 980<p>If your emulator must access the Internet through a proxy server, you can use 981the <code>-http-proxy <proxy></code> option when starting the emulator, to 982set up the appropriate redirection. In this case, you specify proxy information 983in <code><proxy></code> in one of these formats:</p> 984 985<pre>http://<machineName>:<port></pre> 986 987<p>or</p> 988 989<pre>http://<username>:<password>@<machineName>:<port></pre> 990 991<p>The <code>-http-proxy</code> option forces the emulator to use the specified 992HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not 993currently supported.</p> 994 995<p>Alternatively, you can define the environment variable 996<code>http_proxy</code> to the value you want to use for 997<code><proxy></code>. In this case, you do not need to specify a value for 998<code><proxy></code> in the <code>-http-proxy</code> command — the 999emulator checks the value of the <code>http_proxy</code> environment variable at 1000startup and uses its value automatically, if defined. </p> 1001 1002<p>You can use the <code>-verbose-proxy</code> option to diagnose proxy 1003connection problems.</p> 1004 1005 1006<h3 id="connecting">Interconnecting Emulator Instances</h3> 1007 1008<p>To allow one emulator instance to communicate with another, you must set up 1009the necessary network redirection as illustrated below. </p> 1010 1011<p>Assume that your environment is</p> 1012 1013<ul> 1014 <li>A is you development machine</li> 1015 <li>B is your first emulator instance, running on A</li> 1016 <li>C is your second emulator instance, also running on A</li> 1017</ul> 1018 1019<p>and you want to run a server on B, to which C will connect, here is how you 1020could set it up: </p> 1021 1022<ol> 1023 <li>Set up the server on B, listening to 1024<code>10.0.2.15:<serverPort></code></li> 1025 <li>On B's console, set up a redirection from 1026<code>A:localhost:<localPort></code> to <code> 1027B:10.0.2.15:<serverPort></code></li> 1028 <li>On C, have the client connect to <code>10.0.2.2:<localPort></code></li> 1029</ol> 1030 1031<p>For example, if you wanted to run an HTTP server, you can select 1032<code><serverPort></code> as 80 and <code><localPort></code> as 10338080:</p> 1034 1035<ul> 1036 <li>B listens on 10.0.2.15:80</li> 1037 <li>On B's console, issue <code>redir add tcp:8080:80</code></li> 1038 <li>C connects to 10.0.2.2:8080</li> 1039</ul> 1040 1041<h3 id="calling">Sending a Voice Call or SMS to Another Emulator Instance</h3> 1042 1043<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to 1044another. To send a voice call or SMS, use the dialer application or SMS application, respectively, 1045from one of the emulators.</p> 1046 1047<p>To initiate a simulated voice call to another emulator instance:</p> 1048<ol> 1049<li>Launch the dialer application on the originating emulator instance.</li> 1050<li>As the number to dial, enter the console port number of the instance you'd like to call. You can determine 1051 the console port number of the target instance by checking its window title, where the 1052 console port number is reported as "Android Emulator (<port>). </li> 1053<li>Press "Dial". A new inbound call appears in the target emulator instance. </li> 1054</ol> 1055 1056<p>To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance. </p> 1057 1058<p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>. 1059 1060 1061<h2 id="console">Using the Emulator Console</h2> 1062 1063<p>Each running emulator instance provides a console that lets you query and control the emulated 1064device environment. For example, you can use the console to manage port redirection, network 1065characteristics, and telephony events while your application is running on the emulator. To 1066access the console and enter commands, use telnet to connect to the console's port number.</p> 1067 1068<p>To connect to the console of any running emulator instance at any time, use this command: </p> 1069 1070<pre>telnet localhost <console-port></pre> 1071 1072<p>An emulator instance occupies a pair of adjacent ports: a console port and an {@code adb} port. 1073The port numbers differ by 1, with the {@code adb} port having the higher port number. The console 1074of the first emulator instance running on a given machine uses console port 5554 and {@code adb} 1075port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 10765558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> 1077 1078<p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p> 1079 1080<p><code>Android Emulator (5554)</code></p> 1081 1082<p>Alternatively, you can use the <code>adb devices</code> command, which prints a list of running emulator instances and their console port numbers. For more information, see <a href="{@docRoot}tools/help/adb.html#devicestatus">Querying for Emulator/Device Instances</a> in the adb documentation.</p> 1083 1084<p class="note">Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.</p> 1085 1086<p>Once you are connected to the console, you can then enter <code>help [command]</code> to see a list of console commands and learn about specific commands. </p> 1087 1088<p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p> 1089 1090<p>The following sections below describe the major functional areas of the console.</p> 1091 1092 1093<h3 id="portredirection">Port Redirection</h3> 1094 1095<p>You can use the console to add and remove port redirection while the emulator is running. After 1096you connect to the console, manage port redirection by entering the following command:</p> 1097 1098<pre>redir <list|add|del> </pre> 1099 1100<p>The <code>redir</code> command supports the subcommands listed in the table below. </p> 1101 1102<table> 1103<tr> 1104 <th width="25%" >Subcommand 1105 <th width="30%" >Description</th> 1106 <th width="35%">Comments</th> 1107</tr> 1108 1109 <tr> 1110 <td><code>list</code></td> 1111 <td>List the current port redirection.</td> 1112 <td> </td> 1113 </tr> 1114 1115 1116<tr> 1117 <td><code>add <protocol>:<host-port>:<guest-port></code></td> 1118 <td>Add a new port redirection.</td> 1119<td><ul><li><protocol> must be either "tcp" or "udp"</li> 1120<li><host-port> is the port number to open on the host</li> 1121<li><guest-port> is the port number to route data to on the emulator/device</li> 1122</ul></td> 1123</tr> 1124<tr> 1125 <td><code>del <protocol>:<host-port></code></td> 1126 <td>Delete a port redirection.</td> 1127<td>The meanings of <protocol> and <host-port> are listed in the previous row.</td> 1128</tr> 1129</table> 1130 1131 1132<h3 id="geo">Geo Location Provider Emulation</h3> 1133 1134<p>You can use the console to set the geographic location reported to the applications running 1135inside an emulator. Use the <code>geo</code> command to send a simple GPS fix to the 1136emulator, with or without NMEA 1083 formatting:</p> 1137 1138<pre>geo <fix|nmea></pre> 1139 1140<p>The <code>geo</code> command supports the subcommands listed in the table below.</p> 1141 1142<table> 1143<tr> 1144 <th width="25%">Subcommand</th> 1145 <th width="30%">Description</th> 1146 <th width="35%">Comments</th> 1147</tr> 1148 1149 <tr> 1150 <td><code>fix <longitude> <latitude> [<altitude>]</code></td> 1151 <td>Send a simple GPS fix to the emulator instance.</td> 1152 <td>Specify longitude and latitude in decimal degrees. Specify altitude in meters.</td> 1153 </tr> 1154<tr> 1155 <td><code>nmea <sentence></code></td> 1156 <td>Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem.</td> 1157<td><code><sentence></code> must begin with '$GP'. Only '$GPGGA' and '$GPRCM' sentences are currently supported.</td> 1158</tr> 1159</table> 1160 1161<p>You can issue the <code>geo</code> command as soon as an emulator instance is running. The 1162emulator sets the location you enter by creating a mock location provider. This provider responds to 1163location listeners set by applications, and also supplies the location to the {@link 1164android.location.LocationManager}. Any application can query the location manager to obtain the 1165current GPS fix for the emulated device by calling: 1166 1167<pre>LocationManager.getLastKnownLocation("gps")</pre> 1168 1169<p>For more information about the Location Manager, see {@link android.location.LocationManager}. 1170</p> 1171 1172<h3 id="events">Hardware Events Emulation</h3> 1173 1174<p>The {@code event} console commands sends hardware events to the emulator. The syntax for this 1175command is as follows:</p> 1176 1177<pre>event <send|types|codes|text></pre> 1178 1179<p>The <code>event</code> command supports the subcommands listed in the table below. </p> 1180 1181<table> 1182<tr> 1183 <th width="25%" >Subcommand 1184 <th width="30%" >Description</th> 1185 <th width="35%">Comments</th> 1186</tr> 1187 1188 <tr> 1189 <td><code>send <type>:<code>:<value> [...]</code></td> 1190 <td>Send one or more events to the Android kernel. </td> 1191 <td>You can use text names or integers for <code><type></code> and <code><value></code>.</td> 1192 </tr> 1193<tr> 1194 <td><code>types</code></td> 1195 <td>List all <code><type></code> string aliases supported by the <code>event</code> subcommands.</td> 1196<td> </td> 1197</tr> 1198<tr> 1199 <td><code>codes <type></code></td> 1200 <td>List all <code><codes></code> string aliases supported by the <code>event</code> 1201 subcommands for the specified <code><type></code>.</td> 1202<td> </td> 1203</tr> 1204<tr> 1205 <td><code>event text <message></code></td> 1206 <td>Simulate keypresses to send the specified string of characters as a message,</td> 1207<td>The message must be a UTF-8 string. Unicode posts will be reverse-mapped according to the current device keyboard. Unsupported characters will be discarded silently.</td> 1208</tr> 1209</table> 1210 1211 1212<h3 id="power">Device Power Characteristics</h3> 1213 1214<p>The {@code power} command controls the power state reported by the emulator to applications. The 1215syntax for this command is as follows: </p> 1216 1217<pre>power <display|ac|status|present|health|capacity></pre> 1218 1219<p>The <code>event</code> command supports the subcommands listed in the table below. </p> 1220 1221<table> 1222<tr> 1223 <th width="25%" >Subcommand </th> 1224 <th width="30%" >Description</th> 1225 <th width="35%">Comments</th> 1226</tr> 1227 1228 <tr> 1229 <td><code>display</code></td> 1230 <td>Display battery and charger state.</td> 1231 <td> </td> 1232 </tr> 1233<tr> 1234 <td><code>ac <on|off></code></td> 1235 <td>Set AC charging state to on or off. </td> 1236<td> </td> 1237</tr> 1238<tr> 1239 <td><code>status <unknown|charging|discharging|not-charging|full></code></td> 1240 <td>Change battery status as specified.</td> 1241<td> </td> 1242</tr> 1243 1244<tr> 1245 <td><code>present <true|false></code></td> 1246 <td>Set battery presence state.</td> 1247<td> </td> 1248</tr> 1249<tr> 1250 <td><code>health <unknown|good|overheat|dead|overvoltage|failure></code></td> 1251 <td>Set battery health state.</td> 1252<td> </td> 1253</tr> 1254<tr> 1255 <td><code>capacity <percent></code></td> 1256 <td>Set remaining battery capacity state (0-100).</td> 1257<td> </td> 1258</tr> 1259</table> 1260 1261 1262<h3 id="netstatus">Network Status</h3> 1263 1264<p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p> 1265 1266<pre>network status 1267</pre> 1268 1269 1270<h3 id="netdelay">Network Delay Emulation</h3> 1271 1272<p>The emulator lets you simulate various network latency levels, so that you can test your 1273application in an environment more typical of the actual conditions in which it will run. You can 1274set a latency level or range at emulator startup or you can use the console to change the latency, 1275while the application is running in the emulator. </p> 1276 1277<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a 1278supported <code><delay></code> value, as listed in the table below. Here are some 1279examples:</p> 1280 1281<pre>emulator -netdelay gprs 1282emulator -netdelay 40 100</pre> 1283 1284<p>To make changes to network delay while the emulator is running, connect to the console and use 1285the <code>netdelay</code> command with a supported <code><delay></code> value from the table 1286below.</p> 1287 1288<pre>network delay gprs</pre> 1289 1290<p>The format of network <delay> is one of the following (numbers are milliseconds):</p> 1291 1292<table style="clear:right;width:100%;"> 1293<tr> 1294 <th width="30%" >Value</th> 1295 <th width="35%" >Description</th><th width="35%">Comments</th></tr> 1296 1297 <tr><td><code>gprs</code></td><td>GPRS</td> 1298 <td>(min 150, max 550)</td> 1299 </tr> 1300 1301<tr><td><code>edge</code></td><td>EDGE/EGPRS</td> 1302<td>(min 80, max 400)</td> 1303</tr> 1304<tr><td><code>umts</code></td><td>UMTS/3G</td> 1305<td>(min 35, max 200)</td> 1306</tr> 1307<tr><td><code>none</code></td><td>No latency</td><td>(min 0, max 0)</td></tr> 1308<tr><td><code><num></code></td> 1309<td>Emulate an exact latency (milliseconds).</td> 1310<td> </td></tr> 1311<tr><td><code><min>:<max></code></td> 1312<td>Emulate an specified latency range (min, max milliseconds).</td> 1313<td> </td></tr> 1314</table> 1315 1316 1317<h3 id="netspeed">Network Speed Emulation</h3> 1318 1319<p>The emulator also lets you simulate various network transfer rates. 1320You can set a transfer rate or range at emulator startup or you can use the console to change the 1321rate, while the application is running in the emulator.</p> 1322 1323<p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported 1324<code><speed></code> value, as listed in the table below. Here are some examples:</p> 1325 1326<pre>emulator -netspeed gsm 1327emulator -netspeed 14.4 80</pre> 1328 1329<p>To make changes to network speed while the emulator is running, connect to the console and use 1330the <code>netspeed</code> command with a supported <code><speed></code> value from the table 1331below.</p> 1332 1333<pre>network speed 14.4 80</pre> 1334 1335<p>The format of network <code><speed></code> is one of the following (numbers are 1336kilobits/sec):</p> 1337<table style="clear:right;width:100%;"> 1338<tbody> 1339<tr> 1340 <th width="30%">Value</th> 1341 <th width="35%">Description</th><th width="35%">Comments</th></tr> 1342 1343 <tr> 1344 <td><code>gsm</code></td> 1345 <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr> 1346<tr> 1347 <td><code>hscsd</code></td> 1348 <td>HSCSD</td><td>(Up: 14.4, down: 43.2)</td></tr> 1349<tr> 1350 <td><code>gprs</code></td> 1351 <td>GPRS</td><td>(Up: 40.0, down: 80.0)</td></tr> 1352<tr> 1353 <td><code>edge</code></td> 1354 <td>EDGE/EGPRS</td> 1355 <td>(Up: 118.4, down: 236.8)</td> 1356</tr> 1357<tr> 1358 <td><code>umts</code></td> 1359 <td>UMTS/3G</td><td>(Up: 128.0, down: 1920.0)</td></tr> 1360<tr> 1361 <td><code>hsdpa</code></td> 1362 <td>HSDPA</td><td>(Up: 348.0, down: 14400.0)</td></tr> 1363<tr> 1364 <td><code>full</code></td> 1365 <td>no limit</td><td>(Up: 0.0, down: 0.0)</td></tr> 1366<tr> 1367 <td><code><num></code></td> 1368 <td>Set an exact rate used for both upload and download.</td><td></td></tr> 1369<tr> 1370 <td><code><up>:<down></code></td> 1371 <td>Set exact rates for upload and download separately.</td><td></td></tr> 1372</table> 1373 1374 1375<h3 id="telephony">Telephony Emulation</h3> 1376 1377<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony 1378functions in the emulator. For example, you can simulate inbound phone calls, establish data 1379connections and terminate them. The Android system handles simulated calls exactly as it would 1380actual calls. The emulator does not support call audio.</p> 1381 1382<p>You can use the {@code gsm} command to access the emulator's telephony functions after connecting 1383to the console. The syntax for this command is as follows:</p> 1384 1385<pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre> 1386 1387<p>The <code>gsm</code> command supports the subcommands listed in the table below. </p> 1388<table> 1389 <tr> 1390 <th>Subcommand </th> 1391 <th width="25%">Description</th> 1392 <th>Comments</th> 1393 </tr> 1394 <tr> 1395 <td><code>call <phonenumber></code></td> 1396 <td>Simulate an inbound phone call from <phonenumber>.</td> 1397 <td> </td> 1398 </tr> 1399 <tr> 1400 <td><code>accept <phonenumber></code></td> 1401 <td>Accept an inbound call from <phonenumber> and change the call's state "active".</td> 1402 <td>You can change a call's state to "active" only if its current state is "waiting" or "held".</td> 1403 </tr> 1404 <tr> 1405 <td><code>busy <phonenumber></code></td> 1406 <td>Close an outbound call to <phonenumber> and change the call's state to "busy".</td> 1407 <td>You can change a call's state to "busy" only if its current state is "waiting".</td> 1408 </tr> 1409 <tr> 1410 <td><code>cancel <phonenumber></code></td> 1411 <td>Terminate an inbound or outbound phone call to/from <phonenumber>.</td> 1412 <td> </td> 1413 </tr> 1414 <tr> 1415 <td><code>data <state></code></td> 1416 <td>Change the state of the GPRS data connection to <state>.</td> 1417 <td>Supported <state> values are:<br /> 1418 <ul> 1419 <li><code>unregistered</code> -- No network available</li> 1420 <li><code>home</code> -- On local network, non-roaming</li> 1421 <li><code>roaming</code> -- On roaming network</li> 1422 <li><code>searching</code> -- Searching networks</li> 1423 <li><code>denied</code> -- Emergency calls only</li> 1424 <li><code>off</code> -- Same as 'unregistered'</li> 1425 <li><code>on</code> -- same as 'home'</li> 1426 </ul> 1427 </td> 1428 </tr> 1429 <tr> 1430 <td><code>hold</code></td> 1431 <td>Change the state of a call to "held". </td> 1432 <td>You can change a call's state to "held" only if its current state is "active" or "waiting". </td> 1433 </tr> 1434 <tr> 1435 <td><code>list</code></td> 1436 <td>List all inbound and outbound calls and their states.</td> 1437 <td> </td> 1438 </tr> 1439 <tr> 1440 <td><code>voice <state></code></td> 1441 <td>Change the state of the GPRS voice connection to <state>.</td> 1442 <td>Supported <state> values are:<br /> 1443 <ul> 1444 <li><code>unregistered</code> -- No network available</li> 1445 <li><code>home</code> -- On local network, non-roaming</li> 1446 <li><code>roaming</code> -- On roaming network</li> 1447 <li><code>searching</code> -- Searching networks</li> 1448 <li><code>denied</code> -- Emergency calls only</li> 1449 <li><code>off</code> -- Same as 'unregistered'</li> 1450 <li><code>on</code> -- Same as 'home'</li> 1451 </ul> 1452 </td> 1453 </tr> 1454 1455 <tr> 1456 <td><code>status</code></td> 1457 <td>Report the current GSM voice/data state.</td> 1458 <td>Values are those described for the <code>voice</code> and <code>data</code> commands.</td> 1459 </tr> 1460</table> 1461 1462 1463<h3 id="sms">SMS Emulation</h3> 1464 1465<p>The Android emulator console lets you generate an SMS message and direct it to an emulator 1466instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using 1467the following command:</p> 1468 1469<pre>sms send <senderPhoneNumber> <textmessage></pre> 1470 1471<p>where <code><senderPhoneNumber></code> contains an arbitrary numeric string. </p> 1472 1473<p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p> 1474 1475 1476<h3 id="vm">VM State</h3> 1477 1478<p>You can use the <code>vm</code> command to control the VM on an emulator instance. The syntax for 1479this command is as follows: </p> 1480 1481<pre>vm <start|stop|status></pre> 1482 1483<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> 1484 1485<table> 1486<tr> 1487 <th width="25%">Subcommand</th> 1488 <th width="30%">Description</th> 1489 <th width="35%">Comments</th> 1490</tr> 1491<tr> 1492 <td><code>start</code></td> 1493 <td>Start the VM on the instance. </td> 1494 <td> </td> 1495</tr> 1496<tr> 1497 <td><code>stop</code></td> 1498 <td>Stop the VM on the instance. </td> 1499 <td> </td> 1500</tr> 1501<tr> 1502 <td><code>start</code></td> 1503 <td>Display the current status of the VM (running or stopped). </td> 1504 <td> </td> 1505</tr> 1506</table> 1507 1508 1509<h3 id="window">Emulator Window</h3> 1510 1511<p>You can use the <code>window</code> command to manage the emulator window. The syntax for this 1512command is as follows: </p> 1513 1514<pre>window <scale></pre> 1515 1516<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> 1517 1518<table> 1519<tr> 1520 <th width="25%">Subcommand</th> 1521 <th width="30%">Description</th> 1522 <th width="35%">Comments</th> 1523</tr> 1524<tr> 1525 <td><code>scale <scale></code></td> 1526 <td>Scale the emulator window.</td> 1527 <td>A number between 0.1 and 3 that sets the scaling factor. You can 1528 also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" 1529 tells the emulator to select the best window size.</td> 1530</tr> 1531</table> 1532 1533 1534<h3 id="terminating">Terminating an Emulator Instance</h3> 1535 1536<p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p> 1537 1538 1539<h2 id="limitations">Emulator Limitations</h2> 1540 1541<p>The functional limitations of the emulator include: </p> 1542<ul> 1543 <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed 1544 and received) through the emulator console, however. </li> 1545 <li>No support for USB connections</li> 1546 <li>No support for device-attached headphones</li> 1547 <li>No support for determining network connected state</li> 1548 <li>No support for determining battery charge level and AC charging state</li> 1549 <li>No support for determining SD card insert/eject</li> 1550 <li>No support for Bluetooth</li> 1551</ul> 1552 1553 1554<h2 id="troubleshooting">Troubleshooting Emulator Problems</h2> 1555 1556<p>The {@code adb} utility sees the emulator as an actual physical device. For this reason, you 1557might have to use the {@code -d} flag with some common {@code adb} commands, such as 1558<code>install</code>. The {@code -d} flag lets you specify which of several connected devices to use 1559as the target of a command. If you don't specify {@code -d}, the emulator targets the first 1560device in its list. For more information about {@code adb}, see <a 1561href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a>.</p> 1562 1563<p>For emulators running on Mac OS X, if you see an error {@code Warning: No DNS servers found} 1564when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If 1565not, please run the following line in a command window:</p> 1566 <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre> 1567 1568<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more 1569troubleshooting information. </p> 1570
