Setting up AVD and mobile connection

Learning Resources
 

Setting up AVD and mobile connection

An Android Virtual Device (AVD) is an emulator configuration that lets you model an actual device by defining hardware and software options to be emulated by the Android Emulator.

The easiest way to create an AVD is to use the graphical AVD Manager, which you launch from Eclipse by clicking Window > AVD Manager. You can also start the AVD Manager from the command line by calling the androidtool with the avdoptions, from the /tools/ directory.

You can also create AVDs on the command line by passing the androidtool options. For more information on how to create AVDs in this manner, see Managing Virtual Devices from the Command Line.

An AVD consists of:

  • A hardware profile: Defines the hardware features of the virtual device. For example, you can define whether the device has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how much memory it has, and so on.
  • A mapping to a system image: You can define what version of the Android platform will run on the virtual device. You can choose a version of the standard Android platform or the system image packaged with an SDK add-on.
  • Other options: You can specify the emulator skin you want to use with the AVD, which lets you control the screen dimensions, appearance, and so on. You can also specify the emulated SD card to use with the AVD.
  • A dedicated storage area on your development machine: the device's user data (installed applications, settings, and so on) and emulated SD card are stored in this area.

You can create as many AVDs as you need, based on the types of device you want to model. To thoroughly test your application, you should create an AVD for each general device configuration (for example, different screen sizes and platform versions) with which your application is compatible and test your application on each one.

Keep these points in mind when you are selecting a system image target for your AVD:

  • The API Level of the target is important, because your application will not be able to run on a system image whose API Level is less than that required by your application, as specified in the minSdkVersion attribute of the application's manifest file. For more information about the relationship between system API Level and application minSdkVersion, see Specifying Minimum System API Version.
  • You should create at least one AVD that uses a target whose API Level is greater than that required by your application, because it allows you to test the forward-compatibility of your application. Forward-compatibility testing ensures that, when users who have downloaded your application receive a system update, your application will continue to function normally.
  • If your application declares a uses-library element in its manifest file, the application can only run on a system image in which that external library is present. If you want to run your application on an emulator, create an AVD that includes the required library. Usually, you must create such an AVD using an Add-on component for the AVD's platform (for example, the Google APIs Add-on contains the Google Maps library).

Managing AVDs with AVD Manager

The AVD Manager is an easy to use user interface to manage your AVD (Android Virtual Device) configurations. An AVD is a device configuration for the Android emulator that allows you to model different configurations of Android-powered devices. When you start the AVD Manager in Eclipse or run the androidtool on the command line, you will see the AVD Manager as shown in figure 1:

Figure 1. Screenshot of the AVD Manager.

From the main screen, you can create, delete, repair and start AVDs as well as see the details of each AVD.

Creating an AVD

You can create as many AVDs as you would like to test on. It is recommended that you test your applications on all API levels higher than the target API level for your application.

To create an AVD:

  1. Start the AVD Manager:
    • In Eclipse: select Window > AVD Manager, or click the AVD Manager icon in the Eclipse toolbar.
    • In other IDEs: Navigate to your SDK's tools/directory and execute the androidtool with no arguments.

  2. In the Virtual Devices panel, you'll see a list of existing AVDs. Click New to create a new AVD. The Create New AVD dialog appears.

    AVD Dialog

    Figure 2. Screenshot of the Create AVD window

  3. Fill in the details for the AVD.

    Give it a name, a platform target, an SD card size, and a skin (HVGA is default). You can also add specific hardware features of the emulated device by clicking the New... button and selecting the feature. For a list of hardware features, see Hardware options.

    Note: Be sure to define a target for your AVD that satisfies your application's Build Target (the AVD platform target must have an API Level equal to or greater than the API Level that your application compiles against).

  4. Click Create AVD.

Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or launch an emulator with the AVD by selecting a device and clicking Start.

Hardware options

If you are creating a new AVD, you can specify the following hardware options for the AVD to emulate:

Characteristic Description Property
Device ram size The amount of physical RAM on the device, in megabytes. Default value is "96". hw.ramSize
Touch-screen support Whether there is a touch screen or not on the device. Default value is "yes". hw.touchScreen
Trackball support Whether there is a trackball on the device. Default value is "yes". hw.trackBall
Keyboard support Whether the device has a QWERTY keyboard. Default value is "yes". hw.keyboard
DPad support Whether the device has DPad keys. Default value is "yes". hw.dPad
GSM modem support Whether there is a GSM modem in the device. Default value is "yes". hw.gsmModem
Camera support Whether the device has a camera. Default value is "no". hw.camera
Maximum horizontal camera pixels Default value is "640". hw.camera.maxHorizontalPixels
Maximum vertical camera pixels Default value is "480". hw.camera.maxVerticalPixels
GPS support Whether there is a GPS in the device. Default value is "yes". hw.gps
Battery support Whether the device can run on a battery. Default value is "yes". hw.battery
Accelerometer Whether there is an accelerometer in the device. Default value is "yes". hw.accelerometer
Audio recording support Whether the device can record audio. Default value is "yes". hw.audioInput
Audio playback support Whether the device can play audio. Default value is "yes". hw.audioOutput
SD Card support Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes". hw.sdCard
Cache partition support Whether we use a /cache partition on the device. Default value is "yes". disk.cachePartition
Cache partition size Default value is "66MB". disk.cachePartition.size
Abstracted LCD density Sets the generalized density characteristic used by the AVD's screen. Default value is "160". hw.lcd.density
 

The androidtool lets you manage AVDs on the command line. For a complete reference of the command line options that you can use, see the reference for the android tool.

Listing Targets

To generate a list of system image targets, use this command:

android list targets

The androidtool scans the /platforms/and /add-ons/directories looking for valid system images and then generates the list of targets. Here's an example of the command output:

Available Android targets:
id: 1 or "android-3"
     Name: Android 1.5
     Type: Platform
     API level: 3
     Revision: 4
     Skins: QVGA-L, HVGA-L, HVGA (default), HVGA-P, QVGA-P
id: 2 or "android-4"
     Name: Android 1.6
     Type: Platform
     API level: 4
     Revision: 3
     Skins: QVGA, HVGA (default), WVGA800, WVGA854
id: 3 or "android-7"
     Name: Android 2.1-update1
     Type: Platform
     API level: 7
     Revision: 2
     Skins: QVGA, WQVGA400, HVGA (default), WVGA854, WQVGA432, WVGA800
id: 4 or "android-8"
     Name: Android 2.2
     Type: Platform
     API level: 8
     Revision: 2
     Skins: WQVGA400, QVGA, WVGA854, HVGA (default), WVGA800, WQVGA432
id: 5 or "android-9"
     Name: Android 2.3
     Type: Platform
     API level: 9
     Revision: 1
     Skins: HVGA (default), WVGA800, WQVGA432, QVGA, WVGA854, WQVGA400

Creating AVDs

In addition to creating AVDs with the AVD Manager user interface, you can also create them by passing in command line arguments to the androidtool.

Open a terminal window and change to the /tools/directory, if needed.

To create each AVD, you issue the command android create avd, with options that specify a name for the new AVD and the system image you want to run on the emulator when the AVD is invoked. You can specify other options on the command line also, such as the emulated SD card size, the emulator skin, or a custom location for the user data files.

Here's the command-line usage for creating an AVD:

android create avd -n  -t  [-<option> ] ...

You can use any name you want for the AVD, but since you are likely to be creating multiple AVDs, you should choose a name that lets you recognize the general characteristics offered by the AVD. The target ID is an integer assigned by the androidtool. The target ID is not derived from the system image name, version, or API Level, or other attribute, so you need to run the android list targetscommand to list the target ID of each system image. You should do this before you run the android create avdcommand. See the android tool documentation for more information on the command line options.

When you've selected the target you want to use and made a note of its ID, use the android create avdcommand to create the AVD, supplying the target ID as the -targument. Here's an example that creates an AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5 system image in the list above):

android create avd -n my_android1.5 -t 2

If the target you selected was a standard Android system image ("Type: platform"), the androidtool next asks you whether you want to create a custom hardware profile.

Android 1.5 is a basic Android platform.
Do you wish to create a custom hardware profile [no]

If you want to set custom hardware emulation options for the AVD, enter "yes" and set values as needed. If you want to use the default hardware emulation options for the AVD, just press the return key (the default is "no"). The androidtool creates the AVD with name and system image mapping you requested, with the options you specified. For more information, see Setting Hardware Emulation Options.

Note: If you are creating an AVD whose target is an SDK add-on, the androidtool does not allow you to set hardware emulation options. It assumes that the provider of the add-on has set emulation options appropriately for the device that the add-on is modeling, and so prevents you from resetting the options.

Customize the device resolution or density

When testing your application, we recommend that you test your application in several different AVDs, using different screen configurations (different combinations of size and density). In addition, you should set up the AVDs to run at a physical size that closely matches an actual device.

To set up your AVDs for a specific resolution or density, follow these steps:

  1. Use the create avdcommand to create a new AVD, specifying the --skinoption with a value that references either a default skin name (such as "WVGA800") or a custom skin resolution (such as 240x432). Here's an example: 
    android create avd -n  -t  --skin WVGA800
  2. To specify a custom density for the skin, answer "yes" when asked whether you want to create a custom hardware profile for the new AVD.
  3. Continue through the various profile settings until the tool asks you to specify "Abstracted LCD density" (hw.lcd.density). Enter an appropriate value, such as "120" for a low-density screen, "160" for a medium density screen, or "240" for a high-density screen.
  4. Set any other hardware options and complete the AVD creation.

In the example above (WVGA medium density), the new AVD will emulate a 5.8" WVGA screen.

As an alternative to adjusting the emulator skin configuration, you can use the emulator skin's default density and add the -dpi-deviceoption to the emulator command line when starting the AVD. For example:

emulator -avd WVGA800 -scale 96dpi -dpi-device 160

Default location of AVD files

When you create an AVD, the androidtool creates a dedicated directory for it on your development computer. The directory contains the AVD configuration file, the user data image and SD card image (if available), and any other files associated with the device. Note that the directory does not contain a system image — instead, the AVD configuration file contains a mapping to the system image, which it loads when the AVD is launched.

The androidtool also creates an .inifile for the AVD at the root of the .android/avd/directory on your computer. The file specifies the location of the AVD directory and always remains at the root the .android directory.

By default, the androidtool creates the AVD directory inside ~/.android/avd/(on Linux/Mac), C:\Documents and Settings\\.android\on Windows XP, and C:\Users\\.android\on Windows 7 and Vista. If you want to use a custom location for the AVD directory, you can do so by using the -p option when you create the AVD:

android create avd -n my_android1.5 -t 2 -p path/to/my/avd

If the .android directory is hosted on a network drive, we recommend using the -poption to place the AVD directory in another location. The AVD's .ini file remains in the .android directory on the network drive, regardless of the location of the AVD directory.

Moving an AVD

If you want to move or rename an AVD, you can do so using this command:

android move avd -n  [-<option> ] ...

Updating an AVD

If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the android list targetscommand will produce this output:

The following Android Virtual Devices could not be loaded: 
Name: foo 
Path: /.android/avd/foo.avd 
Error: Invalid value in image.sysdir. Run 'android update avd -n foo'

To fix this error, use the android update avdcommand to recompute the path to the system images.

Deleting an AVD

You can use the androidtool to delete an AVD. Here is the command usage:

android delete avd -n

When you issue the command, the androidtool looks for an AVD matching the specified name deletes the AVD's directory and files.

Using the Android Emulator

The Android SDK includes a virtual mobile device emulator that runs on your computer. The emulator lets you prototype, develop and test Android applications without using a physical device.

The Android emulator mimics all of the hardware and software features of a typical mobile device, except that it cannot place actual phone calls. It provides a variety of navigation and control keys, which you can "press" using your mouse or keyboard to generate events for your application. It also provides a screen in which your application is displayed, together with any other active Android applications.

To let you model and test your application more easily, the emulator utilizes Android Virtual Device (AVD) configurations. AVDs let you define certain hardware aspects of your emulated phone and allow you to create many configurations to test many Android platforms and hardware permutations. Once your application is running on the emulator, it can use the services of the Android platform to invoke other applications, access the network, play audio and video, store and retrieve data, notify the user, and render graphical transitions and themes.

The emulator also includes a variety of debug capabilities, such as a console from which you can log kernel output, simulate application interrupts (such as arriving SMS messages or phone calls), and simulate latency effects and dropouts on the data network.

Overview

The Android emulator is an application that provides a virtual mobile device on which you can run your Android applications. It runs a full Android system stack, down to the kernel level, that includes a set of preinstalled applications (such as the dialer) that you can access from your applications. You can choose what version of the Android system you want to run in the emulator by configuring AVDs, and you can also customize the mobile device skin and key mappings. When launching the emulator and at runtime, you can use a variety of commands and options to control its behavior.

The Android system images available through the Android SDK Manager contain code for the Android Linux kernel, the native libraries, the Dalvik VM, and the various Android packages (such as the Android framework and preinstalled applications). The emulator provides dynamic binary translation of device machine code to the OS and processor architecture of your development machine.

The Android emulator supports many hardware features likely to be found on mobile devices, including:

  • An ARMv5 CPU and the corresponding memory-management unit (MMU)
  • A 16-bit LCD display
  • One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone buttons)
  • A sound chip with output and input capabilities
  • Flash memory partitions (emulated through disk image files on the development machine)
  • A GSM modem, including a simulated SIM Card
  • A camera, using a webcam connected to your development computer.
  • Sensors like an accelerometer, using data from a USB-connected Android device.

The following sections describe the emulator and its use for development of Android applications in more detail.

Android Virtual Devices and the Emulator

To use the emulator, you first must create one or more AVD configurations. In each configuration, you specify an Android platform to run in the emulator and the set of hardware options and emulator skin you want to use. Then, when you launch the emulator, you specify the AVD configuration that you want to load.

Each AVD functions as an independent device, with its own private storage for user data, SD card, and so on. When you launch the emulator with an AVD configuration, it automatically loads the user data and SD card data from the AVD directory. By default, the emulator stores the user data, SD card data, and cache in the AVD directory.

To create and manage AVDs you use the AVD Manager UI or the androidtool that is included in the SDK. For complete information about how to set up AVDs, see Managing Virtual Devices.

Starting and Stopping the Emulator

During development and testing of your application, you install and run your application in the Android emulator. You can launch the emulator as a standalone application from a command line, or you can run it from within your Eclipse development environment. In either case, you specify the AVD configuration to load and any startup options you want to use, as described in this document.

You can run your application on a single instance of the emulator or, depending on your needs, you can start multiple emulator instances and run your application in more than one emulated device. You can use the emulator's built-in commands to simulate GSM phone calling or SMS between emulator instances, and you can set up network redirection that allows emulators to send data to one another. For more information, see Telephony Emulation, SMS Emulation, and Emulator Networking

To start an instance of the emulator from the command line, navigate to the tools/folder of the SDK. Enter emulatorcommand like this:

emulator -avd  [<options>]

This initializes the emulator, loads an AVD configuration and displays the emulator window. For more information about command line options for the emulator, see the Android Emulator tool reference.

Note: You can run multiple instances of the emulator concurrently, each with its own AVD configuration and storage area for user data, SD card, and so on.

If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug the application. You can specify emulator startup options in the Run/Debug dialog, in the Target tab. When the emulator is running, you can issue console commands as described later in this document.

If you are not working in Eclipse, see Installing Applications on the Emulator for information about how to install your application.

To stop an emulator instance, just close the emulator's window.

For a reference of the emulator's startup commands and keyboard mapping, see the Android Emulator tool reference.

Installing Applications on the Emulator

If you don't have access to Eclipse or the ADT Plugin, you can install your application on the emulator using the adb utility. Before installing the application, you need to build and package it into an .apkas described in Building and Running Apps. Once the application is installed, you can start the emulator from the command line as described previously, using any startup options necessary. When the emulator is running, you can also connect to the emulator instance's console to issue commands as needed.

As you update your code, you periodically package and install it on the emulator. The emulator preserves the application and its state data across restarts, in a user-data disk partition. To ensure that the application runs properly as you update it, you may need to delete the emulator's user-data partition. To do so, start the emulator with the -wipe-dataoption. For more information about the user-data partition and other emulator storage, see Working with Emulator Disk Images.

Using Hardware Acceleration

In order to make the Android emulator run faster and be more responsive, you can configure it to take advantage of hardware acceleration, using a combination of configuration options, specific Android system images and hardware drivers.

Configuring Graphics Acceleration

Caution: As of SDK Tools Revision 17, the graphics acceleration feature for the emulator is experimental; be alert for incompatibilities and errors when using this feature.

Graphics acceleration for the emulator takes advantage of your development computer's graphics hardware, specifically its graphics processing unit (GPU), to make screen drawing faster. To use the graphics acceleration feature, you must have the following versions of the Android development tools installed:

  • Android SDK Tools, Revision 17 or higher
  • Android SDK Platform API 15, Revision 3 or higher

Use the Android SDK Manager to install these components:

Note: Not all applications are compatible with graphics hardware acceleration. In particular, the Browser application and applications using the WebViewcomponent are not compatible with graphics acceleration.

To configure an AVD to use graphics acceleration:

  1. Make sure you have the required SDK components installed (listed above).
  2. Start the AVD Manager and create a new AVD with the Target value of Android 4.0.3 (API Level 15), revision 3 or higher.
  3. If you want to have graphics acceleration enabled by default for this AVD, in the Hardware section, click New, select GPU emulation and set the value to Yes.

    Note: You can also enable graphics acceleration when you start an emulator using command line options as describe in the next section.

  4. Name the AVD instance and select any other configuration options.

    Caution: Do not select the Snapshot: Enabled option. Snapshots are not supported for emulators with graphics acceleration enabled.

  5. Click Create AVD to save the emulator configuration.

If you set GPU emulation to Yes for your AVD, then graphics acceleration is automatically enabled when you run it. If you did not enable GPU emulation when you created the AVD, you can still enable it at runtime.

To enable graphics acceleration at runtime for an AVD:

  • If you are running the emulator from the command line, just include the -gpu onoption: 
    emulator -avd  -gpu on

    Note: You must specify an AVD configuration that uses Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not available for earlier system images.

  • If you are running the emulator from Eclipse, run your Android application using an AVD with the -gpu onoption enabled:
    1. In Eclipse, click your Android project folder and then select Run > Run Configurations...
    2. In the left panel of the Run Configurations dialog, select your Android project run configuration or create a new configuration.
    3. Click the Target tab.
    4. Select the AVD you created in the previous procedure.
    5. In the Additional Emulator Command Line Options field, enter:
      -gpu on
    6. Run your Android project using this run configuration.

Configuring Virtual Machine Acceleration

Caution: As of SDK Tools Revision 17, the virtual machine acceleration feature for the emulator is experimental; be alert for incompatibilities and errors when using this feature.

Many modern CPUs provide extensions for running virtual machines (VMs) more efficiently. Taking advantage of these extensions with the Android emulator requires some additional configuration of your development system, but can significantly improve the execution speed. Before attempting to use this type of acceleration, you should first determine if your development system’s CPU supports one of the following virtualization extensions technologies:

  • Intel Virtualization Technology (VT, VT-x, vmx) extensions
  • AMD Virtualization (AMD-V, SVM) extensions (only supported for Linux)

The specifications from the manufacturer of your CPU should indicate if it supports virtualization extensions. If your CPU does not support one of these virtualization technologies, then you cannot use virtual machine acceleration.

Note: Virtualization extensions are typically enabled through your computer's BIOS and are frequently turned off by default. Check the documentation for your system's motherboard to find out how to enable virtualization extensions.

Once you have determined that your CPU supports virtualization extensions, make sure you can work within these additional requirements of running an emulator inside an accelerated virtual machine:

  • x86 AVD Only - You must use an AVD that is uses an x86 system image target. AVDs that use ARM-based system images cannot be accelerated using the emulator configurations described here.
  • Not Inside a VM - You cannot run a VM-accelerated emulator inside another virtual machine, such as a VirtualBox or VMWare-hosted virtual machine. You must run the emulator directly on your system hardware.
  • Other VM Drivers - If you are running another virtualization technology on your system such as VirtualBox or VMWare, you may need to unload the driver for that virtual machine hosting software before running an accelerated emulator.
  • OpenGL® Graphics - Emulation of OpenGL ES graphics may not perform at the same level as an actual device.

To use virtual machine acceleration with the emulator, you need the following version of Android development tools. Use the Android SDK Manager to install these components:

  • Android SDK Tools, Revision 17 or higher
  • Android x86-based system image

If your development environment meets all of the requirements for running a VM-accelerated emulator, you can use the AVD Manager to create an x86-based AVD configuration:

  1. In the Android SDK Manager, make sure you have an x86-based System Image installed for your target Android version. If you do not have an x86 System Image installed, select one in the Android SDK Manager and install it.

    Tip: System images are listed under each API Level in the SDK Manager. An x86 system image may not be available for all API levels.

  2. Start the AVD Manager and create a new AVD with an x86 value for the CPU/ABI field. You may need to select a specific Target value, or select a Target value and then select a specific CPU/ABI option.
  3. Name the emulator instance and select any other configuration options.
  4. Click Create AVD to save the emulator configuration.

Configuring VM Acceleration on Windows

Virtual machine acceleration for Windows requires the installation of the Intel Hardware Accelerated Execution Manager (Intel HAXM). The software requires an Intel CPU with Virtualization Technology (VT) support and one of the following operating systems:

  • Windows 7 (32/64-bit)
  • Windows Vista (32/64-bit)
  • Windows XP (32-bit only)

To install the virtualization driver:

  1. Start the Android SDK Manager, select Extras and then select Intel Hardware Accelerated Execution Manager.
  2. After the download completes, execute /extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.exe.
  3. Follow the on-screen instructions to complete installation.
  4. After installation completes, confirm that the virtualization driver is operating correctly by opening a command prompt window and running the following command: 
    sc query intelhaxm
    <
 For Support