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