Emulator Networking

The emulator provides versatile networking capabilities that you can use to set up complex modeling and testing environments for your application. The sections below introduce the emulator's network architecture and capabilities.

Network Address Space

Each instance of the emulator runs behind a virtual router/firewall service that isolates it from your development machine's network interfaces and settings and from the internet. An emulated device can not see your development machine or other emulator instances on the network. Instead, it sees only that it is connected through Ethernet to a router/firewall.

The virtual router for each instance manages the 10.0.2/24 network address space — all addresses managed by the router are in the form of 10.0.2.<xx>, where <xx> is a number. Addresses within this space are pre-allocated by the emulator/router as follows:

Network Address

Description

10.0.2.1

Router/gateway address

10.0.2.2

Special alias to your host loopback interface (i.e., 127.0.0.1 on your development machine)

10.0.2.3

First DNS server

10.0.2.4 / 10.0.2.5 / 10.0.2.6

Optional second, third and fourth DNS server (if any)

10.0.2.15

The emulated device's own network/ethernet interface

127.0.0.1

The emulated device's own loopback interface

Note that the same address assignments are used by all running emulator instances. That means that if you have two instances running concurrently on your machine, each will have its own router and, behind that, each will have an IP address of 10.0.2.15. The instances are isolated by a router and can not see each other on the same network. For information about how to let emulator instances communicate over TCP/UDP, see Connecting Emulator Instances.

Also note that the address 127.0.0.1 on your development machine corresponds to the emulator's own loopback interface. If you want to access services running on your development machine's loopback interface (a.k.a. 127.0.0.1

on your machine), you should use the special address 10.0.2.2 instead.

Finally, note that each emulated device's pre-allocated addresses are specific to the Android emulator and will probably be very different on real devices (which are also very likely to be NAT-ed, i.e., behind a router/firewall)

Local Networking Limitations

Each emulator instance runs behind a virtual router, but unlike an actual device connected to a physical router, the emulated device doesn't have access to a physical network. Instead it runs as part of a normal application on your development machine. This means that it is subject to the same networking limitations as other applications on your machine:

• Communication with the emulated device may be blocked by a firewall program running on your machine.

• Communication with the emulated device may be blocked by another (physical) firewall/router to which your machine is connected.

The emulator's virtual router should be able to handle all outbound TCP and UDP connections/messages on behalf of the emulated device, provided your development machine's network environment allows it to do so. There are no built-in limitations on port numbers or ranges except the one imposed by your host operating system and network.

Depending on the environment, the emulator may not be able to support other protocols (such as ICMP, used for "ping") might not be supported. Currently, the emulator does not support IGMP or multicast.

Using Network Redirections

To communicate with an emulator instance behind its virtual router, you need to set up network redirections on the virtual router. Clients can then connect to a specified guest port on the router, while the router directs traffic to/from that port to the emulated device's host port.

To set up the network redirections, you create a mapping of host and guest ports/addresses on the the emulator instance. There are two ways to set up network redirections: using emulator console commands and using the ADB tool, as described below.

Setting up Redirections through the Emulator Console

Each emulator instance provides a control console the you can connect to, to issue commands that are specific to that instance. You can use the redir console command to set up redirections as needed for an emulator instance.

First, determine the console port number for the target emulator instance. For example, the console port number for the first emulator instance launched is 5554. Next, connect to the console of the target emulator instance, specifying its console port number, as follows:

telnet localhost 5554

Once connected, use the redir command to work with redirections. To add a redirection, use:.

add <protocol>:<host-port>:<guest-port>

where <protocol> is either tcp or udp, and <host-port> and <guest-port> sets the mapping between your own machine and the emulated system, respectively.

For example, the following command sets up a redirection that will handle all incoming TCP connections to your host (development) machine on 127.0.0.1:5000 and will pass them through to the emulated system's 10.0.2.15:6000.:

redir add tcp:5000:6 000

To delete a redirection, you can use the redir del command. To list all redirections for a specific instance, you can use redir list. For more information about these and other console commands, see Using the Emulator Console.

Note that port numbers are restricted by your local environment. this typically means that you cannot use host port numbers under 1024 without special administrator privileges. Also, you won't be able to set up a redirection for a host port that is already in use by another process on your machine. In that case, redir generates an error message to that effect.

Setting Up Redirections through ADB

The Android Debug Bridge (ADB) tool provides port forwarding, an alternate way for you to set up network redirections. For more information, see Forwarding Ports in the ADB documentation.

Note that ADB does not currently offer any way to remove a redirection, except by killing the ADB server.

Configuring the Emulator's DNS Settings

At startup, the emulator reads the list of DNS servers that your system is currently using. It then stores the IP addresses of up to four servers on this list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, 10.0.2.5 and 10.0.2.6 as needed.

On Linux and OS X, the emulator obtains the DNS server addresses by parsing the file /etc/resolv.conf. On Windows, the emulator obtains the addresses by calling the GetNetworkParams() API. Note that this usually means that the emulator ignores the content of your "hosts" file (/etc/hosts on Linux/OS X, %WINDOWS%/system32/HOSTS on Windows).

When starting the emulator at the command line, you can also use the -dns-server <serverList> option to manually specify the addresses of DNS servers to use, where <serverList> is a comma-separated list of server names or IP addresses. You might find this option useful if you encounter DNS resolution problems in the emulated network (for example, an "Unknown Host error" message that appears when using the web browser).

Using the Emulator with a Proxy

If your emulator must access the Internet through a proxy server, you can use the -http-proxy <proxy> option when starting the emulator, to set up the appropriate redirection. In this case, you specify proxy information in <proxy> in one of these formats:

or http://<username>:<password>@<machineName>:<port>

The -http-proxy option forces the emulator to use the specified HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not currently supported.

Alternatively, you can define the environment variable http_proxy to the value you want to use for <proxy>. In this case, you do not need to specify a value for <proxy> in the -http-proxy command — the emulator checks the value of the http_proxy environment variable at startup and uses its value automatically, if defined.

You can use the -verbose-proxy option to diagnose proxy connection problems.

Interconnecting Emulator Instances

To allow one emulator instance to communicate with another, you must set up the necessary network redirections as illustrated below.

Assume that your environment is

• A is you development machine

• B is your first emulator instance, running on A

• C is your second emulator instance, running on A too and you want to run a server on B, to which C will connect, here is how you could set it up:

1. Set up the server on B, listening to 10.0.2.15:<serverPort>

2. On B's console, set up a redirection from A:localhost:<localPort> to B:10.0.2.15:<serverPort>

3. On C, have the client connect to 10.0.2.2:<localPort>

For example, if you wanted to run an HTTP server, you can select <serverPort> as 80 and <localPort> as 8080:

Sending a Voice Call or SMS to Another Emulator Instance

The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator

To initiate a simulated voice call to another emulator instance:

1. Launch the dialer application on the originating emulator instance.

2. As the number to dial, enter the console port number of the instance you'd like to call. You can determine the console port number of the target instance by checking its window title, where the console port number is reported as "Android Emulator (<port>).

3. Press "Dial". A new inbound call appears in the target emulator instance.

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.

You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see Telephony Emulation and SMS Emulation.

Using the Emulator Console

Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number.

To connect to the console of any running emulator instance at any time, use this command:

telnet localhost <console-port>

An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility.

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:

Android Emulator (5554)

Alternatively, you can use the adb devices command, which prints a list of running emulator instances and their console port numbers. For more information, see Querying for Emulator/Device Instances in the adb documentation.

| Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.

Once you are connected to the console, you can then enter help [command] to see a list of console commands and learn about specific commands.

To exit the console session, use quit or exit.

The sections below describe the major functional areas of the console.

Port Redirection

You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:

redir <list|add|del>

The redir command supports the subcommands listed in the table below.

Subcommand

Description

Comments

list

List the current port redirections.

add <protocol>:<host-port>:<guest-port>

Add a new port redirection.

• <protocol> must be either "tcp" or "udp"

• <host-port> is the port number to open on the host

• <guest-port> is the port number to route data to on the emulator/device

del <protocol>:<host-port>

Delete a port redirection.

See above for meanings of <protocol> and <host-port>.

Geo Location Provider Emulation

The console provides commands to let you set the geo position used by an emulator emulated device. You can use the geo command to send a simple GPS fix to the emulator, without needing to use NMEA 1083 formatting. The usage for the command is:

geo <fix|nmea>

The geo command supports the subcommands listed in the table below.

Subcommand

Description

Comments

fix <longitude>

<latitude>

[<altitude>]

Send a simple GPS fix to the emulator instance.

Specify longitude and latitude in decimal degrees. Specify altitude in meters.

nmea <sentence>

Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem.

<sentence> must begin with '$GP'. Only '$GPGGA' and '$GPRCM' sentences are currently supported.

You can issue the geo command to fix the GPS location as soon as an emulator instance is running. The emulator creates a mock location provider that sends it to GPS-aware applications as soon as they start and register location listeners. Any application can query the location manager to obtain the current GPS fix for the emulated device by calling:

LocationManager.getLastKnownLocation("gps")

For more information about the Location Manager, see LocationManager and its methods.

Hardware Events Emulation

You can use the event command to send various events to the emulator.The usage for the command is:

event <send|types|codes|text>

The event command supports the subcommands listed in the table below.

Subcommand

Description

Comments

send <type>:<code>:<value> [...]

Send one or more events to the Android kernel.

You can use text names or integers for <type> and <value>.

types

List all <type> string aliases supported by the event subcommands.

codes <type>

List all <codes> string aliases supported by the event subcommands for the specified <type>.

event text <message>

Simulate keypresses to send the specified string of

The message must be a UTF-8 string. Unicode posts will be reverse-

Device Power Characteristics

You can use the power command to control the simulated power state of the emulator instance.The usage for the command is:

power <display|ac|status|present|health|capactiy>

The event command supports the subcommands listed in the table below.

Subcommand

Description

Comments

display

Display battery and charger state.

ac <on|off>

Set AC charging state to on or off.

status <unknown|charging|discharging|not-charging|full>

Change battery status as specified.

present <true|false>

Set battery presence state.

<unknown|good|overheat|dead|overvoltage|failure>

Set battery health state.

power health <percent>

Set remaining battery capacity state (0-100).

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 netstatus command. Here's an example of the command and its output.

network status

Network Delay Emulation

The emulator lets you simulate various network latency levels, so that you can test your applicaton in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator.

To set latency at emulator startup, use the -netdelay emulator option with a supported <delay> value, as listed in the table below. Here are some examples:

emulator -netdelay gprs emulator -netdelay 40 100

To make dynamic changes to network delay while the emulator is running, connect to the console and use the netdelay command with a supported <delay> value from the table below.

network delay gprs

The format of network is one of the following (numbers are milliseconds):

Value

Description

Comments

gprs

GPRS

(min 150, max 550)

edge

EDGE/EGPRS

(min 80, max 400)

umts

UMTS/3G

(min 35, max 200)

none

No latency

(min 0, max 0)

<num>

Emulate an exact latency (milliseconds).

<min>:<max>

Emulate an specified latency range (min, max milliseconds).

Network Speed Emulation

The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, while the application is running in the emulator.

To set the network speed at emulator startup, use the -netspeed emulator option with a supported <speed> value, as listed in the table below. Here are some examples:

emulator -netspeed gsm emulator -netspeed 14.4 80

To make dynamic changes to network speed while the emulator is running, connect to the console and use the netspeed command with a supported <speed> value from the table below.

network speed 14.4 8 0

The format of network <speed> is one of the following (numbers are kilobits/sec):

Value

Description

Comments

gsm

GSM/CSD

(Up: 14.4, down: 14.4)

hscsd

HSCSD

(Up: 14.4, down: 43.2)

gprs

GPRS

(Up: 40.0, down: 80.0)

edge

EDGE/EGPRS

(Up: 118.4, down: 236.8)

umts

UMTS/3G

(Up: 128.0, down: 1920.0)

hsdpa

HSDPA

(Up: 348.0, down: 14400.0)

full

no limit

(Up: 0.0, down: 0.0)

<num>

Set an exact rate used for both upload and download.

<up>:<down>

Set exact rates for upload and download separately.

The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release.

You can use the console to access the emulator's telephony functions. After connecting to the console, you can use gsm <call|accept|busy|cancel|data|hold|list|voice|status>

to invoke telephony functions.

The gsm command supports the subcommands listed in the table below.

Subcommand

Description

Comments

call

Simulate an inbound

<phonenumber>

phone call from <phonenumber>.

<phonenumber>

Accept an inbound call from <phonenumber> and change the call's state "active".

You can change a call's state to "active" only if its current state is "waiting" or "held".

busy

<phonenumber>

Close an outbound call to <phonenumber> and change the call's state to "busy".

You can change a call's state to "busy" only if its current state is "waiting".

cancel

<phonenumber>

Terminate an inbound or outbound phone call to/from <phonenumber>.

data <state>

Change the state of the GPRS data connection to <state>.

Supported <state> values are:

• unregistered -- No network available

• searching -- Searching networks

• denied -- Emergency calls only

• on -- same as 'home'

hold

Change the state of a call to "held".

You can change a call's state to "held" only if its current state is "active" or "waiting".

list

List all inbound and outbound calls and their states.

voice <state>

Change the state of the GPRS voice connection to <state>.

Supported <state> values are:

• unregistered -- No network available

• searching -- Searching networks

• denied -- Emergency calls only

• on -- Same as 'home'

status

Report the current GSM voice/data state.

Values are those described for the voice and data commands.

SMS Emulation

The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:

sms send <senderPhoneNumber> <textmessage>

where <senderPhoneNumber> contains an arbitrary numeric string.

The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type.

VM State

You can use the vm command to control the VM on an emulator instance.The usage for the command is: vm <start|stop|status>

The vm command supports the subcommands listed in the table below.

Subcommand start stop start

Description

Start the VM on the instance.

Stop the VM on the instance.

Display the current status of the VM (running or stopped).

Comments

Emulator Window

You can use the window command to manage the emulator window. The usage for the command is: window <scale>

The vm command supports the subcommands listed in the table below.

Subcommand scale <scale>

Description

Scale the emulator window.

Comments

<scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" tells the emulator to select the best window size.

Terminating an Emulator Instance

You can terminate an emulator instance through the console, using the kill command.

Using Emulator Skins

You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use -skin <skinID> when starting the emulator.

For example:

emulator -skin HVGA-L Note that you must enter the <skinID> in uppercase letters (if your development computer is case-sensitive).

skinID Description Skin

HVGA-L 480x320, landscape

HVGA-P 320x480, portrait (default)

qvga-l 320x240, landscape

•—•

r

i

qvga-p 240x320, portrait

Running Multiple Emulator Instances

Through the AVDs configurations used by the emulator, 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. You no longer need to use the -d option when launching the emulator, to point to an instance-specific storage area.

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 package it in a .apk file using the Android Asset Packaging Tool. Once the application is installed, you can start the emulator from the command line, as described in this document, 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-data option. For more information about the user-data partition and other emulator storage, see Working with Emulator Disk Images.

SD Card Emulation

You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. To do this, you can use the android tool to create a new SD card image with a new AVD, or you can use the mksdcard utility included in the SDK.

The sections below describe how to create an SD card disk image, how to copy files to it, and how to load it in the emulator at startup.

Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator.

The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.

Creating an SD card image using the android tool

The easiest way to create a new SD card is to use the android tool. When creating an AVD, you simply specify the -c option, like this:

android create avd -n <avd_name> -t <targetID> -c <size>[K|M]

You can also use the -c option to specify a path to an SD card image to use in the new AVD. For more information, see Android Virtual Devices.

Creating an SD card image using mksdcard

You can use the mksdcard tool, included in the SDK, to create a FAT32 disk image that you can load in the emulator at startup. You can access mksdcard in the tools/ directory of the SDK and create a disk image like this:

mksdcard <size> <file>

For example:

mksdcard 1024M sdcard1.iso

For more information, see Other Tools.

Copying Files to a Disk Image

Once you have created the disk image, you can copy files to it prior to loading it in the emulator. To copy files, you can mount the image as a loop device and then copy the files to it, or you can use a utility such as mtools to copy the files directly to the image. The mtools package is available for Linux, Mac, and Windows.

Loading the Disk Image at Emulator Startup

By default, the emulator loads the SD card image that is stored with the active AVD (see the -avd startup option).

Alternatively, you ca start the emulator with the -sdcard flag and specify the name and path of your image (relative to the current working directory):

emulator -sdcard <filepath>

Troubleshooting Emulator Problems

The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as install. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see Android Debug Bridge.

For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an /etc/resolv.conf file. If not, please run the following line in a command window:

ln -s /private/var/run/resolv.conf /etc/resolv.conf See Frequently Asked Questions for more troubleshooting information.

Emulator Limitations

In this release, the limitations of the emulator include:

• No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however.

• No support for USB connections

• No support for camera/video capture (input).

• No support for device-attached headphones

• No support for determining connected state

• No support for determining battery charge level and AC charging state

• No support for determining SD card insert/eject

• No support for Bluetooth

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License. Android 1.5 r1 - 27 Apr 2009 0:19

Site Terms of Service - Privacy Policy - Brand Guidelines

oro^oo

deve

0 0

Post a comment