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