Skip to main content

Custom Parameters for Android Automation

You can enter custom parameters when automating Android systems under test (SUTs), both via Android Gateway and via the command line. In both cases, you pass these parameters through SystemNative2 (SN2), an on-device process that enables Android automation.

How to Use Parameters

First, install SN2 on your Android SUT. Open Android Gateway, connect an Android device, and click Start in the Android Gateway interface. Android Gateway installs and launches SN2 on the connected device. After you install SN2 on an Android device, you can automate that device using Android Gateway or the command line.

Automating with Android Gateway

If you're using Android Gateway, enter parameters only in the Custom Parameters field in the Android Gateway GUI.

Automating with the Command Line

If you're automating Android devices using the command line, use this syntax to open SN2 and begin automation:

SystemNative2 --parameters

The available parameters are described below:

Connection Parameters

These parameters apply to Android connections.

--port NNNNSpecifies the port number. The default is 5900.
--reverse <ip_address>Specifies the IP address for a reverse connection.
--rc-port NNNNSpecifies the port number for a reverse connection. The default is 5500.


Specifies whether or not the server can work with multiple clients. The default value is --always-share. When --may-share is specified, client settings determine whether or not to share the server. See also --keep-connected.

Chooses what to do when the server is not being shared between clients, but a second client tries to connect. See also --never-share.
--forward <Address> <Port>Forwards messages to a different server. This is useful when working with LG G5 devices.
--no-forwardingSwitches off forwarding.
--java-port <INT>Uses the specified port for internal communication between SN2 and EggSensor. Note that this option is the same as --es-ports NNN NNN.
--es-ports <Min> <Max>Iterates through the specified range to find an available TCP port on the phone, and uses that port for internal communication between SN2 and EggSensor. The default range is 6000-6050.
--zc <host> <port>Enables Zeroconf. The host can be either a symbolic name or a dot-separated IP address.

Debugging Parameters

These parameters apply to debugging.

--trace-clientPrints debugging information related to receiving and parsing messages.
--trace-client-configPrints debugging information related to client configuration.
--trace-client-managerPrints debugging information related to processing messages.
--trace-connectionDisplays connection messages.
--trace-coreTurns on all VNC/core traces.
--trace-file-transferTraces file transfers from the SUT.
--trace-inboundDisplays inbound messages.
--trace-outboundDisplays outbound messages, except screen update messages.
--trace-performancePrints a table every 10 seconds that shows how much time was spent on different sections of code.
--trace-proceduralDisplays procedural messages.
--trace-screenDisplays outbound screen update messages.
--trace-es-connectionSwitches on traces for the connection between SN2 and EggSensor.
--trace-es-otherSwitches on less verbose traces related to EggSensor.
--trace-keyboardTraces keyboard events.
--trace-eggboardTraces the Unicode keyboard (Eggboard).
--trace-mouse-configTraces mouse detection and configuration.
--trace-screen-configTraces the configuration of the screen capture method.
--trace-androidTraces functionality specific to Android. Using this trace with --trace-core enables all available traces.

General Parameters

These are general parameters for Android testing.

--helpDisplays this help file.
--versionDisplays the version information, then exits immediately.
--empty-passwordSets the password to be an empty string.
--interactiveMakes SN2 read commands from stdin.
--password passwordSpecifies the password. "WordToPass" is the default.
--no-eggsensorDoes not start EggSensor. Set device orientation will not work, and change device orientation notifications will not be sent. This option can help when EggSensor is not compatible with the SUT system.
--enable-unicodeEstablishes a socket connection to Eggboard, which can enter Unicode strings. Disabled by default.
--disable-unicodeDoes not establish a socket connection to Eggboard. Unicode characters will not be available. Use this option if Eggboard is not working or is causing issues.

Mouse Parameters

These parameters apply to touch gestures.

--mouse-device <PATH>Selects a path for the mouse device. This value is only used with --power-mouse. This option should be used only when the program detects the device incorrectly. In all other cases, use --mouse-device-auto.


Chooses the algorithm for controlling the mouse. Portable supports only taps and swipes, not long holds or multitouch gestures. Power mouse supports long holds and pinches. Scaled mouse is similar to power mouse, except it expects different IDs for mouse coordinates. SN2 defaults to power mouse mode; if that fails, SN2 switches to portable mouse mode.
--mouse-device-autoEnabled by default. Runs in power mouse mode, and tries to automatically detect the path for the mouse , and whether it is a button mouse.
--button-mouseTweaks the --power-mouse algorithm to make it work with a few devices that need this option.
--no-button-mouseTweaks the --power-mouse algorithm to make it work with certain devices. Most devices work with this option.
--detect-button-mouseAttempts to detect the type of mouse (button or non-button) using the --power-mouse setting. This option is enabled by default.
--timeless-mouseDoesn't send timestamps to the mouse. This option can be useful when testing older devices.
--backward-mouseFlips the coordinates for the mouse. This command is deprecated; use --mouse-rot instead.
--mouse-rot 0

--mouse-rot 1

--mouse-rot 2

--mouse-rot 3
Turns the mouse coordinates by 0, 90, 180, or 270 degrees, respectively. This can help if the screen displays incorrectly in the Eggplant Functional Viewer window.
--message-spacing <#Nanoseconds>This command affects how Android Gateway processes mouse events. It should only be used while working with Eggplant support.

Screen Parameters

These parameters apply to screen specifications including size, colors, and rotation.

--scale-screen <INT>Scales down the screen size by a given factor to enable faster screen updates. For example, --scale-screen 2 reports a screen resolution of half the actual width and height, and transmits only a quarter of the original number of pixels. This option is useful when working with high resolution screens.
--blendBlends the pixels on a scaled screen instead of dropping them. Blending provides a better image, but can be slower to load.
--max-fps <number>Limits how many screenshots the VNC server takes per second. The default is 5. This value can be a float number. A high frame rate can drain the device battery even if the device is connected to a power source. A lower frame rate also allows more processor time to be spent executing the test.
--screen-slicing NX NYDefine screen slicing. By default, NX and NY are 8.

Enables or disables TightVNC encoding, which compresses screenshots using JPEG formatting.

Enables or disables compression using the zlib standard.
--jpeg-compress-level LSets the compression level for JPEG encoding. For good quality source images, the default (75) is the best choice. The valid range is 0 to 100. For more information see the JPEG image compression FAQ.
--zlib-compress-level LSets the compression level for zlib encoding.


In --rgb-auto mode, the default, the server decides whether to reverse the byte order in the pixel according to the pixel format requested by the client.
--force-rotForces SN2 to rotate the image. Prior to Android 6.0, the image that came from Android OS to SN2 was not rotated, and SN2 had to rotate it, so it would appeared readable in Eggplant Functional. In Android 6.0 and later, SN2 receives an already rotated image. This option forces SN2 to rotate images even on Android 6.0 and later. This option is implemented in case some devices do not have this updated behavior.
--screen-rot 0

--screen-rot 1

--screen-rot 2

--screen-rot 3
Turns the screen by 0, 90, 180, or 270 degrees, respectively.



Selects a method for screen capture. The default is --screencap-use-pipe. This method works on most devices, but not on LG H831. Methods using ...-pipe are the best to use, because they can handle hangs in screen capture.
--screencap-use-pipe-testEnable other algorithms for screen capture.
--screencap-dummyUsed for testing and VNC forwarding.
--hack-orientationEnables an alternative algorithm for changing screen orientation. This option can have unexpected side effects, so do not use unless you have to.
--force-ts-range <X> <Y>Defines the touch screen range. For use with devices (i.e., MC9200), where the dimensions of the touch screen can't be figured out automatically.