Send Emulator Console Commands

Each running virtual device provides a console that lets you query and control the emulated device environment. For example, you can use the console to manage port redirection, network characteristics, and telephony events while your app is running on the emulator.

Note: The Emulator Console for Android Emulator 25.0.10 and higher isn't currently fully functional. We recommend that you use the emulator UI and command-line options instead, where possible. For more information, see the Android Issue Tracker and Compare Android Emulator Tools.

Starting and stopping a console session

To access the console and enter commands, from a terminal window, use telnet to connect to the console port and provide your authentication token. Each time the console displays OK, it's ready to accept commands. It doesn't have a typical prompt.

To connect to the console of a running virtual device:

Open a terminal window and enter the following command:

telnet localhost console-port

The emulator window title lists the console port number. For example, the window title for an emulator using console port 5554 could be Nexus_5X_API_23:5554.

By default, a virtual device 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 virtual device running on a particular machine uses console port 5554 and adb port 5555. Subsequent virtual device use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on, to 5584/5585. The range is 5554 to 5584 for console ports; the range is the same plus one for adb ports.

To connect to the console, you must specify a valid console port. If multiple virtual devices are running, you need to determine the console port of the virtual device you want to connect to.

The adb devices command prints a list of running virtual devices and their console port numbers. For more information, see Querying for Emulator/Device Instances.

Note: The emulator listens for connections on ports 5554 to 5585 and accepts connections from localhost only.

After the console displays OK, enter the auth auth_token command.

Before you can enter console commands, the emulator console requires authentication. auth_token must match the contents of the .emulator_console_auth_token file in your home directory.

If that file doesn't exist, the telnet localhost console-port command creates the file, which contains a randomly generated authentication token.

To disable authentication, delete the token from the .emulator_console_auth_token file or create an empty file if it doesn't exist.

After you're connected to the console, enter console commands.

Enter help and help command to see a list of console commands and learn about specific commands.

To exit the console session, enter quit or exit.

Here's an example session:

$ telnet localhost 5554
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Android Console: Authentication required
Android Console: type 'auth <auth_token>' to authenticate
Android Console: you can find your <auth_token> in
'/Users/me/.emulator_console_auth_token'
OK
$ auth 123456789ABCdefZ
Android Console: type 'help' for a list of commands
OK
$ help
Android console command help:

    help|h|?         print a list of commands
    crash            crash the emulator instance
    kill             kill the emulator instance
    quit|exit        quit control session
    redir            manage port redirections
    power            power related commands
    event            simulate hardware events
    avd              control virtual device execution
    finger           manage emulator fingerprint
    geo              Geo-location commands
    sms              SMS related commands
    cdma             CDMA related commands
    gsm              GSM related commands
    rotate           rotate the screen by 90 degrees

try 'help <command>' for command-specific help
OK
$ exit
Connection closed by foreign host.

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

Port redirection

You can use the console to add and remove port redirection while the emulator is running. After you connect to the console, manage port redirection by entering the following command:

redir <list|add|del>

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

Subcommand	Description	Comments
`list`	List the current port redirection.
`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.	The meanings of <protocol> and <host-port> are listed in the previous row.

Geo location provider emulation

You can use the console to set the geographic location reported to the apps running inside an emulator. Use the geo command to send a simple GPS fix to the emulator, with or without NMEA 1083 formatting:

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 virtual device.	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 as soon as a virtual device is running. The emulator sets the location you enter by creating a mock location provider. This provider responds to location listeners set by apps, and also supplies the location to the LocationManager. Any app 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.

Hardware events emulation

The event console command sends hardware events to the emulator. The syntax for this command is as follows:

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 characters as a message,	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.

Device power characteristics

The power command controls the power state reported by the emulator to apps. The syntax for this command is as follows:

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

The power 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.
`health <unknown\|good\|overheat\|dead\|overvoltage\|failure>`	Set battery health state.
`capacity <percent>`	Set remaining battery capacity state (0-100).

Network status

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 network status 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 app 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, while the app 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 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 <delay> 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, while the app 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 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 80

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)
`lte`	LTE	(Up: 58,000, down: 173,000)
`evdo`	EVDO	(Up: 75,000, down: 280,000)
`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.

Telephony emulation

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, establish data connections and terminate them. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio.

You can use the gsm command to access the emulator telephony functions after connecting to the console. The syntax for this command is as follows:

gsm <call|accept|busy|cancel|data|hold|list|voice|status>

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

Subcommand	Description	Comments
`call <phonenumber>`	Simulate an inbound phone call from `<phonenumber>`.
`accept <phonenumber>`	Accept an inbound call from `<phonenumber>` and change the call state "active".	You can change a call state to "active" only if its current state is "waiting" or "held".
`busy <phonenumber>`	Close an outbound call to `<phonenumber>` and change the call state to "busy".	You can change a call 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 `home` -- On local network, non-roaming `roaming` -- On roaming network `searching` -- Searching networks `denied` -- Emergency calls only `off` -- Same as 'unregistered' `on` -- same as 'home'
`hold`	Change the state of a call to "held".	You can change a call 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 `home` -- On local network, non-roaming `roaming` -- On roaming network `searching` -- Searching networks `denied` -- Emergency calls only `off` -- Same as 'unregistered' `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 console lets you generate an SMS message and direct it to a virtual device. Once you connect to a virtual device, you can generate an emulated incoming SMS using the following 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 app that handles that message type.

VM state

You can use the vm command to control the VM on a virtual device. The syntax for this command is as follows:

vm <start|stop|status>

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

Subcommand	Description	Comments
`start`	Start the VM on the instance.
`stop`	Stop the VM on the instance.
`start`	Display the current status of the VM (running or stopped).

Emulator window

You can use the window command to manage the emulator window. The syntax for this command is as follows:

window <scale>

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

Subcommand	Description	Comments
`scale <scale>`	Scale the emulator window.	A number between 0.1 and 3 that sets the 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.

Fingerprint simulation

The console provides the finger command, allowing you to simulate, and thus validate, fingerprint authentication for your app. To use the command, you need SDK Tools 24.3 or higher, and Android 6.0 (API level 23) or higher.

After you set up your app to accept fingerprint authentication, your device should display the fingerprint authentication screen, as shown in figure 1.

Figure 1. The fingerprint authentication screen.

If you don't yet have a fingerprint ID, enroll a new fingerprint in the virtual device by selecting Settings > Security > Fingerprint and then following the enrollment instructions.

While your app displays the fingerprint authentication screen, enter the finger command to simulate finger touch and removal:

finger touch <fingerprint-id> to simulate a finger touching the sensor
finger remove to simulate finger removal

Your app should respond as if a user touched and then removed their finger from the fingerprint sensor.

Terminating a virtual device

You can terminate a virtual device through the console, using the kill command.

Most visited

Recently visited

Results for