AutoDroid Documentation

The DroidTask dataset is organized by application folders (e.g., applauncher, calendar). Each application folder contains:

• states/: A folder containing captured application states:
  • Screenshot [n].png: Sequential images of the UI.
  • View hierarchy [n].json: JSON files detailing the UI structure.
• task[i].yaml: YAML files containing ground truth data for specific tasks.
• utg.yaml: A file recording data from random user exploration.

Mapping Tasks to States: To associate a task with a specific visual state:

1. Open a task[i].yaml file and find the state_str identifier.
2. Match that state_str with the state_str inside a View hierarchy [k].json file.
3. Use the index k from the view hierarchy filename to find the corresponding Screenshot [k].png.

To start an automation task, use the droidbot command. You must have an Android device or emulator connected to your host machine via adb and have configured your GPT API key in tools.py by replacing os.environ['GPT_URL'] with your key.

Command Arguments:

• -a <path/to/.apk>: Path to the application APK file.
• -o <output/of/app>: Directory where the output will be saved.
• -task <your task>: The specific task description to execute.
• -keep_env: Flag to keep the environment.
• -keep_app: Flag to keep the application.

droidbot -a <path/to/.apk> -o <output/of/app> -task <your task> -keep_env -keep_app

AutoDroid is built on the DroidBot framework. To install it, ensure you have Python, Java, and the Android SDK installed. You must also add the platform_tools directory from your Android SDK to your system PATH.

Follow these steps to install via pip:

1. Clone the repository.
2. Install the package in editable mode.

git clone git@github.com:MobileLLM/AutoDroid.git
cd AutoDroid/
nip install -e .

DroidBot supports a distributed architecture consisting of a master and worker nodes. Use the -distributed flag to select the mode:

• -distributed master: Starts a DroidMaster instance. This requires providing the RPC address for workers if applicable, though the CLI primarily initializes the master role.
• -distributed worker: Starts a DroidBot instance acting as a worker, connecting to a DroidMaster via the -master argument.

When running as a master, you can also provide QEMU specific configurations like -qemu_hda (the QEMU hda image) and -qemu_no_graphic (to run without a GUI).

# Example: Start a worker node connecting to a master at a specific address
python droidbot/start.py -a app.apk -distributed worker -master 127.0.0.1:5000

The App class provides methods to access core Android identity information:

• get_package_name(): Returns the application's package name.
• get_main_activity(): Returns the main activity name. If it cannot be found in the manifest, it attempts to return a value from dumpsys_main_activity (if available).

package = app.get_package_name()
main_activity = app.get_main_activity()

The App class is used to represent an Android application by parsing its APK file. Upon initialization, it extracts metadata such as the package name, app name, main activity, permissions, and activities using androguard. It also calculates file hashes (MD5, SHA-1, SHA-256) and identifies possible broadcast intents.

Parameters:

• app_path (str): The local file path to the APK file.
• output_dir (str, optional): A directory where output files will be stored. If the directory does not exist, it will be created.

from droidbot.app import App

# Initialize with an APK path
app = App(app_path="/path/to/your/app.apk", output_dir="./output")

print(f"App Name: {app.app_name}")
print(f"Package: {app.package_name}")

The -policy argument determines how DroidBot generates test inputs. The available policies are:

• POLICY_NONE: No events are sent; requires manual interaction.
• POLICY_MONKEY: Uses adb shell monkey to send events.
• POLICY_NAIVE_DFS: Explores the UI using a naive depth-first strategy.
• POLICY_GREEDY_DFS: Explores the UI using a greedy depth-first strategy.
• POLICY_NAIVE_BFS: Explores the UI using a naive breadth-first strategy.
• POLICY_GREEDY_BFS: Explores the UI using a greedy breadth-first strategy.

# Example: Use greedy depth-first search for UI exploration
python droidbot/start.py -a app.apk -policy greedy_dfs

The get_possible_broadcasts() method scans the APK's manifest for registered receivers and their intent filters. It returns a set of Intent objects representing the actions and categories that the application is capable of receiving via broadcasts.

broadcasts = app.get_possible_broadcasts()
for intent in broadcasts:
    print(f"Possible broadcast: {intent}")

Use get_stop_intent() to retrieve an Intent object configured to perform a force-stop on the application's package name.

stop_intent = app.get_stop_intent()