@@ -42,8 +42,7 @@ config edit
 
 usage: firewheel config edit [-e EDITOR]
 
-Edit the FIREWHEEL configuration with a text editor. The user must set either the VISUAL or EDITOR
-environment variable or use the provided flag to override these environment variables.
+Edit the FIREWHEEL configuration with a text editor. The user must set either the VISUAL or EDITOR environment variable or use the provided flag to override these environment variables.
 
 options:
 
 
@@ -17,7 +17,7 @@ To accomplish this, FIREWHEEL's *Control* system interprets user defined experim
    FIREWHEEL Software Architecture
 
 FIREWHEEL's software architecture, as shown in :numref:`Figure %s <fw_sw_arch>`, consists of a Command Line Interface (CLI), Experiment Models, and three other major components (*Control*, minimega, and the *VM Resource Manager*) that convert experiment models into running experiments, and manage FIREWHEEL's VM deployment, virtual network and VM provisioning, and run time execution capabilities.
-These FIREWHEEL software components are executed within a Python Virtual Environment, which we will refer to as ``fwpy``, and interact with the Hardware Virtualization components, QEMU/KVM and Open vSwitch (OVS), to instantiate experiment models as configured VMs communicating via virtual networks.
+These FIREWHEEL software components are executed within a Python Virtual Environment, which we will refer to as ``fwpy``, and interact with hardware virtualization and networking components, including QEMU/KVM, the Android Emulator when Android VMs are used, and Open vSwitch (OVS), to instantiate experiment models as configured VMs communicating via virtual networks.
 We'll next discuss each of FIREWHEEL's major software components.
 
 .. note::
@@ -103,7 +103,8 @@ FIREWHEEL uses `NetworkX <https://networkx.org/>`_ [#netx]_, a Python library fo
 minimega
 ========
 
-`minimega <https://www.sandia.gov/minimega/>`__, is the name of the virtualization management component that's currently available with FIREWHEEL. minimega will instantiate an experiment using QEMU/KVM for VMs, and OVS networks.
+`minimega <https://www.sandia.gov/minimega/>`__, is the name of the virtualization management component that's currently available with FIREWHEEL.
+minimega will instantiate an experiment using supported VM backends, such as QEMU/KVM for conventional VMs and native Android emulator support for Android VMs, and OVS networks.
 minimega receives an experiment graph from FIREWHEEL's *Control* system, then determines and sends the appropriate set of instructions to the QEMU/KVM hypervisor and OVS virtual networking systems that are needed to instantiate the experiment model as an emulated computer network.
 At this stage the experiment network's topology has been fully instantiated on the virtualization platform, but has yet to have any of its scheduled actions applied to it -- which may further configure the compute systems and network devices as needed before beginning the intended cyber experiment.
 
 
@@ -0,0 +1,124 @@
+.. _adb-driver:
+
+Android Debug Bridge Driver
+===========================
+
+The `Android Debug Bridge (ADB) <https://developer.android.com/tools/adb>`_ driver enables the VM Resource Handler to communicate with Android guests.
+It is selected using the VM Resource Handler engine name ``ADB``.
+
+The ADB driver is intended for Android VMs launched through minimega's native ``android`` VM type.
+It does not use the QEMU Guest Agent or a QGA socket.
+
+Driver Selection
+----------------
+
+Android VM Resource Handler process configurations should use:
+
+.. code-block:: json
+
+   {
+     "engine": "ADB",
+     "adb_serial": "emulator-5554",
+     "android_console_port": 5554,
+     "android_adb_port": 5555,
+     "require_root": true
+   }
+
+The ``adb_serial`` value is the primary identifier used by the driver. If it is
+not provided, the driver can fall back to ``emulator-<android_console_port>``.
+
+ADB, Console Ports, and Serial Names
+------------------------------------
+
+Android emulators normally use two sequential ports:
+
+* an emulator console port, for example ``5554``;
+* an ADB daemon port, typically ``5555``.
+
+The ADB serial uses the console port:
+
+.. code-block:: text
+
+   emulator-5554
+
+minimega is authoritative for the actual assigned port values.
+If the requested port pair is unavailable, minimega may assign a different port pair.
+FIREWHEEL should use the actual values reported by minimega before launching the VM Resource Handler.
+
+Runtime Paths
+-------------
+
+The ADB driver uses Android-native FIREWHEEL runtime paths:
+
+.. code-block:: text
+
+   /data/local/tmp/firewheel/launch
+   /data/local/tmp/firewheel/proc
+
+Generated call scripts use:
+
+.. code-block:: sh
+
+   #!/system/bin/sh
+
+This differs from QGA/Linux VMs, which traditionally use ``/var/launch`` and ``/bin/bash``.
+
+Execution Model
+---------------
+
+The ADB driver executes VM resources by writing a small runner script under:
+
+.. code-block:: text
+
+   /data/local/tmp/firewheel/proc
+
+The runner records:
+
+* stdout
+* stderr
+* exit code
+* a started marker
+
+This avoids long-lived ADB stream parsing and provides reliable exit-code capture for Android VM resources.
+
+Android Shell Limitations
+-------------------------
+
+Android guests should not be assumed to provide:
+
+* ``/bin/bash``
+* ``/bin/sh``
+* Python
+* systemd
+
+VM resources intended for Android should generally use:
+
+.. code-block:: sh
+
+   #!/system/bin/sh
+
+Android model components may provide optional Bash or Python runtimes, but these are not required by the ADB driver.
+
+Root Access
+-----------
+
+The ADB driver can require root by setting ``require_root`` to ``true``.
+This is the default for FIREWHEEL Android experiments that need to configure networking or system-level state.
+
+If ``require_root`` is enabled, the Android image must support ``adb root``.
+
+If ``require_root`` is false, the driver can connect to non-rooted devices, but VM resources that require privileged operations such as network configuration may fail.
+
+File Transfer
+-------------
+
+The ADB driver uses ADB sync operations to push and pull files. File transfers are timestamp-filtered where possible using Android ``stat``/``toybox stat``.
+
+Reboot Behavior
+---------------
+
+The ADB driver can reboot Android guests through ADB.
+Runtime network state such as IP addresses, routes, policy rules, and firewall rules is generally lost on Android reboot.
+Installed APKs typically persist across a normal Android reboot.
+
+Android-specific reboot and runtime-state limitations are documented in the Android model component repository.
@@ -35,3 +35,4 @@ However, there are several benefits to dynamic, automated configuration of VMs o
    vmr_in_experiment
    vm_resource_handler
    qga
+   adb
@@ -4,10 +4,15 @@ QEMU Guest Agent
 ================
 
 The `QEMU Guest Agent (QGA) <https://wiki.qemu.org/Features/GuestAgent>`_ is a binary file located within a VM which receives QEMU Machine Protocol (QMP) messages and can be used to perform actions within the virtual machine.
-The QGA is the primary way in which the :ref:`vm-resource-handler` communicates with VMs and enables the completion of VM resources.
-Therefore, in order for a VM image to be "FIREWHEEL-compatible" the QGA should be installed on the system and set to run as a service on system start.
+The QGA is the primary way in which the :ref:`vm-resource-handler` communicates with QEMU/KVM VMs and enables the completion of VM resources.
+Therefore, in order for a QEMU/KVM VM image to be "FIREWHEEL-compatible" the QGA should be installed on the system and set to run as a service on system start.
 
-When a VM is launched, a virtual serial port that is added which enables the QGA to communicate to FIREWHEEL via the :py:class:`QemuGuestAgentDriver <firewheel.vm_resource_manager.drivers.qemu_guest_agent_driver.QemuGuestAgentDriver>`, which then works with the :ref:`vm-resource-handler` for scheduling and executing VMRs within the VM.
+.. note::
+
+   Android guests use the ADB driver rather than the QEMU Guest Agent. See
+   :ref:`adb-driver`.
+
+When a QEMU/KVM VM is launched with QGA support, a virtual serial port that is added which enables the QGA to communicate to FIREWHEEL via the :py:class:`QemuGuestAgentDriver <firewheel.vm_resource_manager.drivers.qemu_guest_agent_driver.QemuGuestAgentDriver>`, which then works with the :ref:`vm-resource-handler` for scheduling and executing VMRs within the VM.
 
 .. seealso::
 
 
@@ -7,13 +7,19 @@ To facilitate the execution of VMRs, FIREWHEEL uses a :py:class:`VM Resource Han
 In addition to being in charge of loading VMRs on to a VM, it also facilitates executing commands on VMs and extracting information out of the environment (e.g. :ref:`helper_pull_file`).
 
 Practically, the :py:class:`VM Resource Handler <firewheel.vm_resource_manager.vm_resource_handler.VMResourceHandler>` dynamically loads in drivers which perform the actual interactions between the VM and the :py:class:`VM Resource Handler <firewheel.vm_resource_manager.vm_resource_handler.VMResourceHandler>`.
-Currently, there is only one driver (:py:class:`QemuGuestAgentDriver <firewheel.vm_resource_manager.drivers.qemu_guest_agent_driver.QemuGuestAgentDriver>`) which handles VMs of type ``QemuVM`` (see :ref:`qemu-guest-agent`).
-However, this dynamic loading function enables future expansion of drivers that will work without changing the :py:class:`VM Resource Handler <firewheel.vm_resource_manager.vm_resource_handler.VMResourceHandler>` [#f1]_.
+FIREWHEEL currently supports multiple VM Resource Handler communication drivers, including:
+
+* :py:class:`QemuGuestAgentDriver <firewheel.vm_resource_manager.drivers.qemu_guest_agent_driver.QemuGuestAgentDriver>` for QEMU/KVM VMs using the QEMU Guest Agent. This driver is selected with engine ``QemuVM``. See :ref:`qemu-guest-agent`.
+* :py:class:`ADBDriver <firewheel.vm_resource_manager.drivers.adb_driver.ADBDriver>` for Android guests using the Android Debug Bridge. This driver is selected with engine ``ADB``. See :ref:`adb-driver`.
+
+.. note::
+
+   Additional drivers may be added in the future for other guest communication mechanisms, such as `miniccc <https://www.sandia.gov/minimega/module-28-miniccc-and-the-cc-api/>`_.
+
+This dynamic loading mechanism allows FIREWHEEL to support different guest communication mechanisms without changing the VM Resource Handler's scheduling logic.
 
 .. _vm-resource-logs:
 
 VM Resource Logs
 ----------------
 The :py:class:`VM Resource Handler <firewheel.vm_resource_manager.vm_resource_handler.VMResourceHandler>` also facilitates logging VMR data onto the physical host.
-
-.. [#f1] For example, we hope to eventually create a driver for `miniccc <https://www.sandia.gov/minimega/module-28-miniccc-and-the-cc-api/>`_.
 
@@ -101,7 +101,7 @@ These get passed to the program on the command line.
 Finally, the ``vm_resource`` parameter is an optional Boolean that indicates if ``program`` is the name of a script that needs to be loaded on to the VM before execution.
 If ``vm_resource`` is ``True`` then the specified program name is assumed to be the local filename of the file (i.e. not the full path, just the filename) to load on to the VM.
 In this case, like :py:meth:`drop_file <base_objects.VMEndpoint.drop_file>`, the file that corresponds to ``program`` must be part of the ``vm_resources`` list in a model component's ``MANIFEST`` file (see :ref:`vm_resources_field`).
-The user does not need to specify where the file will be dropped on the VM since it will be placed in the appropriate ``/var/launch`` or ``C:\launch`` location (see :ref:`vmr-location`).
+The user does not need to specify where the file will be dropped on the VM since it will be placed in the appropriate launch directory for the VM's communication driver. For QGA Linux guests this is ``/var/launch``; for Windows guests this is ``C:\launch``; for Android guests using the ADB driver this is ``/data/local/tmp/firewheel/launch`` (see :ref:`vmr-location`).
 
 Examples
 """"""""
@@ -183,13 +183,22 @@ Another concrete example of how this can be done is shown in the example below w
 
 Finally, the :ref:`tests.reboot_mc` has various examples of Python VMRs requesting a reboot.
 
+.. note::
+
+   Guest reboot effects are OS-specific. On Android, runtime network configuration
+   such as IP addresses, routes, policy routing rules, and firewall rules is
+   generally lost after reboot. Installed APKs typically persist across a normal
+   Android reboot. Android resources that need networking after reboot should
+   rerun the Android network configuration resources.
+
 .. [#] For more details about why this is the case see https://www.howtogeek.com/182817/htg-explains-why-does-windows-want-to-reboot-so-often/
 
 .. _vmr-env:
 
 VMRs In-Experiment Environment
 ------------------------------
-Because of how the VM Resources are executed within the VMs by the :ref:`QEMU Guest Agent <qga-driver>`, users should not make any assumptions about the `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_ which are available.
+Because VM Resources are executed through a VM Resource Handler driver, users should not make assumptions about the `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_ available inside the VM.
+The exact environment depends on the guest OS and driver. For example, :ref:`QEMU Guest Agent <qga-driver>` Linux execution and Android ADB execution expose different shell environments.
 That is, users should **NOT** assume that standard Environment variables (e.g. ``$HOME``, ``$USER``, ``$SHELL``, etc.) are available.
 Some software may make assumptions that these common environment variables exist, which may result in odd failures when attempting to run the software.
 Below are some examples of environments which *might* be available.
@@ -211,13 +220,19 @@ Example output from :py:meth:`run_executable <base_objects.VMEndpoint.run_execut
    OLDPWD=/
    _=/usr/bin/printenv
 
+Android ADB-based VM resources should generally assume ``/system/bin/sh`` is available, but should **not** assume Bash or Python are installed.
 
 .. _vmr-location:
 
 Location of VMRs within the VM
 ------------------------------
 Prior to the start of :ref:`schedule-negative-time`, VMRs are uploaded onto the VM.
-FIREWHEEL uses the ``/var/launch`` directory on Linux based VMs and the ``C:\launch`` directory on Windows based VMs.
+FIREWHEEL uses driver- and OS-specific launch directories. Common locations include:
+
+* ``/var/launch`` for QGA Linux guests
+* ``C:\launch`` for Windows guests
+* ``/data/local/tmp/firewheel/launch`` for Android guests using the ADB driver
+
 Inside these directories is a series of directories with :ref:`start times <start-time>` that are used by the scheduled VMRs.
 
 For example, if there are VMRs scheduled at -300, -250, -100, and 5 then ``/var/launch`` would look like:
@@ -227,7 +242,7 @@ For example, if there are VMRs scheduled at -300, -250, -100, and 5 then ``/var/
    $ ls /var/launch
    -100 -250 -300 5
 
-Inside these ref:`<start-time>` directories is a directory for each VMR which is scheduled at the given time.
+Inside these :ref:`start time <start-time>` directories is a directory for each VMR which is scheduled at the given time.
 
 For example, if ``set_hostname.sh`` and ``get_stat.py`` both occurred at ``-250`` it would look like:
 
@@ -239,16 +254,17 @@ For example, if ``set_hostname.sh`` and ``get_stat.py`` both occurred at ``-250`
 .. note::
    To access negative time folders you will likely need to use either a full path (e.g. ``/var/launch/-100`` or a specific relative path ``./-100``. This is because the negative sign (i.e. the hyphen) is typically used to express a CLI option for most shell programs.
 
-Each of the folders with the VMR name contains a file called ``call_arguments.sh`` which is a dynamically-generated script which executes the VMR.
+Each VMR directory contains a dynamically-generated call-arguments file which executes the VMR.
+On Linux and Android guests this is typically ``call_arguments.sh``; on Windows guests this is typically ``call_arguments.bat``.
 Additionally, if there is other data, scripts, etc. which need to be executed for the given VMR, they are also located in this directory.
-For example, here is the ``/var/launch/-250/set_hostname.sh`` directory:
+For example, on a QGA Linux guest, here is the ``/var/launch/-250/set_hostname.sh`` directory:
 
  .. code-block:: bash
 
    $ ls /var/launch/-250/set_hostname.sh
    call_arguments.sh set_hostname.sh
 
-Here is an example ``call_arguments.sh`` file for ``set_hostname.sh``:
+Here is an example ``call_arguments.sh`` file on a QGA Linux guest for ``set_hostname.sh``:
 
 .. code-block:: bash
    :caption: Example ``call_arguments.sh``
@@ -258,14 +274,36 @@ Here is an example ``call_arguments.sh`` file for ``set_hostname.sh``:
    cd /var/launch/-250/set_hostname.sh
    /var/launch/-250/set_hostname.sh/set_hostname.sh host.root.net
 
-To re-run the VMR (for debugging purposes) a user can simply re-execute ``call_arguments.sh`` as the root user:
+Here is an example Android ADB ``call_arguments.sh`` file:
+
+.. code-block:: sh
+
+   #!/system/bin/sh
+   CURRENT_DIR="$(dirname "$0")"
+   cd /data/local/tmp/firewheel/launch/-250/set_hostname_android.sh
+   /data/local/tmp/firewheel/launch/-250/set_hostname_android.sh/set_hostname_android.sh android-0
+
+To re-run a VMR (for debugging purposes) a user can simply re-execute ``call_arguments.sh`` as the root user.
+For example, on a Linux VM might it might look like:
 
  .. code-block:: bash
 
    $ sudo /var/launch/-250/set_hostname.sh/call_arguments.sh
 
+On an Android guest using the ADB driver, a user can inspect or re-run the
+generated script with ADB:
+
+.. code-block:: bash
+
+   $ adb -s emulator-5554 shell /system/bin/sh /data/local/tmp/firewheel/launch/-250/set_hostname_android.sh/call_arguments.sh
+
 Becoming familiar with the locations of VMRs with the VMs is useful for developing and debugging new VMRs.
 
+.. note::
+
+   Android VMRs should generally use ``/system/bin/sh`` and should **not** assume
+   ``/bin/bash``, ``/bin/sh``, or Python are installed.
+
 .. _vmr-output:
 
 Extracting VMR data
@@ -300,6 +338,20 @@ This could include running a script that modifies the entire network topology or
 The primary method for scheduling host-based VM resources is through the use of the :py:meth:`run_host_mm_command <base_objects.VMEndpoint.run_host_mm_command>` method, which creates a :py:class:`RunHostExecutableScheduleEntry <base_objects.RunHostExecutableScheduleEntry>` for executing Minimega commands.
 Additional interfaces into host-based scheduling may be added in the future to facilitate common tasks.
 
+Host-side VM resources receive several FIREWHEEL-specific environment variables:
+
+* ``FIREWHEEL_VM_NAME``
+* ``FIREWHEEL_VM_UUID``
+* ``FIREWHEEL_VM_CONFIG_JSON``
+* ``FIREWHEEL_PYTHON``
+
+For Android/ADB-backed VMs, the environment may also include:
+
+* ``FIREWHEEL_ADB_SERIAL``
+* ``FIREWHEEL_ANDROID_CONSOLE_PORT``
+
+These can be useful for host-side resources that need access to information about the scheduling VM.
+
 :py:meth:`run_host_mm_command <base_objects.VMEndpoint.run_host_mm_command>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The :py:meth:`run_host_mm_command <base_objects.VMEndpoint.run_host_mm_command>` method allows a user to schedule Minimega commands directly on the host.