Interacting with hardware UEs

This document shows you how to interact with hardware UE nodes in PhantomNet.

Introduction

Working with hardware UE devices in PhantomNet is a bit different from developing locally. Normally when developing with an Android device, you would plug the device into the USB port of your local computer and interact with it using tools such as ADB. Since the UE devices in PhantomNet are in a remote location, the PhantomNet testbed sets up remote access. With a few minor adjustments, you should be able to work with the UE devices in PhantomNet just as you would with local devices attached to your computer.

How UE access is setup

You must specify to PhantomNet that you plan to interface with your hardware UEs. If you don't, the UEs will still be allocated, and will attach to your EPC, but you won't be able to interact with them via ADB, etc. The system-provided PhantomNet profiles that request UE hardware also request out-of-band access to be setup for these devices. See for example the following profile:

Off The Shelf Hardware Radio Access Network profile

These profiles request a dedicated ADB target node, and set an attribute on any UE nodes in the profile script to point them at this node. When an experiment is instantiated from such a profile, the PhantomNet setup machinery forwards a connection from the adbd daemon running on the UE through the infrastructure host it is connected to (via USB). It only allows the ADB target node to connect to this forwarded connection. In other words, the infrastructure host connected to the UE listens on a dynamic TCP port for connections from an ADB target, and forwards this traffic on to the adbd daemon running on the device. The ADB target node is further setup to load and run a disk image that contains tools useful for interacting with Android UE devices. A list of these tools can be found below. Included are unmodified ADB from the Android Open Source Project, and a PhantomNet-specific script called pnadb that understands the nicknames given to the UE devices (from the profile script/RSpec).

How to request UE access via geni-lib

Most of the system-provided profiles available from the PhantomNet Portal are coded in Python, making use of the geni-lib scripting library (including some PhantomNet-specific extensions). If you take a look at the profile linked above and view the source, you should be able to find the declaration of the ADB target node. The associated code looks like this:

# Add a node to act as the ADB target host
adb_t = request.RawPC("adb-tgt")
adb_t.disk_image = GLOBALS.ADB_IMG

Where GLOBALS.ADB_IMG is defined near the top of the profile script like so:

ADB_IMG = URN.Image(PN.PNDEFS.PNET_AM, "PhantomNet:UBUNTU14-64-PNTOOLS")

The PNTOOLS image contains utilities for interacting with hardware UE nodes, and as can be gleaned, is based on a (system-provided) Ubuntu 14 64-bit image. Farther down in the profile script you will find where the UE node is bound to the ADB target node. That bit of code looks something like this:

# Add a real UE
rue1 = request.UE("rue1")
rue1.hardware_type = GLOBALS.UE_HWTYPE
rue1.disk_image = GLOBALS.UE_IMG
rue1.adb_target = "adb-tgt"
rue1_rflink1 = rue1.addInterface("rue1_rflink1")

Where GLOBALS.UE_HWTYPE is set near the top of the script to a type available in the PhantomNet testbed (likely set to "nexus5"). The UE is also set to run a specific OS image (GLOBALS.UE_IMG); this will be set to something like "ANDROID444-STD" (Android 4.4.4). Next, the script has a stanza that sets the adb_target attribute to "adb-tgt", which is the nickname for the ADB target node (see the prior snippet above). The last line in the code snippet above allocates an interface object that is used in another part of the profile script to request an "RF link" connection to another device, typically an eNodeB of some sort (off-the-shelf or SDR). These RF links and the attenuation matrix that they run through are described in the RF Environment (ADD LINK!) document.

Example interactions

We describe here a typical interaction with a UE device in PhantomNet. Assume that we have instantiated an experiment through the PhantomNet Portal based on the geni-lib hardware profile discussed above. The provisioned resources will include the ADB target node. We can log into this node directly with SSH from a local shell, or through the Portal interface by clicking on the node and selecting "Shell" (which brings up a new tab with a shell session connected to this node). Once we have a shell on the ADB target node, we can query for the connection details using the pnadb script:

krw@adb-tgt:~$ pnadb -l
                                 UE Nodes
Name Node ID Console Server Port
------------------------------------------------------------------------------
rue1 ue10 pc599.emulab.net 8001

To connect with ADB, issue: adb connect <console_server>:<port>

This experiment has only a single UE. We can connect to it explicitly by name, like this:

pnadb rue1

Or we can just ask pnadb to connect all UE devices to the ADB target node like so:

pnadb -a

Now if we query ADB, we should see that the device is connected:

krw@adb-tgt:~$ adb devices 
List of devices attached 
pc599.emulab.net:8001 device

The UE hardware can now be accessed as per usual via ADB. For example, we can launch a shell on the UE and try to ping something:

krw@adb-tgt:~$ adb shell
root@hammerhead:/ # ping 8.8.8.8
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=50 time=486 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=50 time=52.6 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=50 time=54.5 ms
64 bytes from 8.8.8.8: icmp_seq=4 ttl=50 time=75.6 ms
^C
--- 8.8.8.8 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3003ms
rtt min/avg/max/mdev = 52.687/167.386/486.688/184.570 ms

(Note the long delay for the first ping packet; the device was idle prior to running ping, so had to re-attach to the network.) We can also use other tools that interact via ADB, such as monkeyrunner (not installed by default) and culebra from the AndroidViewClient project (which is installed in the PNTOOLS image).

If you have more than one UE device in your experiment, you will need to specify which one to operate on when issuing ADB commands. Do this by using the -s flag and the host:port string output from running "adb devices". For example:

adb -s pc599.emulab.net:8001 reboot

Tools of interest in the PNTOOLS image

The UBUNTU14-64-PNTOOLS disk image that is setup to run on the ADB target nodes by the system-provided profiles has a set of tools useful for interacting with Android UE devices. Here is the list:

pnadb

This is a PhantomNet-specific script that can list the mapping from node nickname to remote ADB console:port. It can also connect ADB on the node to one or more (or all) UE devices in your experiment. Run without arguments to get a usage message.

adb

The essential tool for interacting with Android devices, from the Android Open Source Project. This is installed via an Ubuntu (apt) package. Invoke without arguments to get a usage message. The official documentation is here.

Android file system tools

Tools such as ext2simg, make_ext4fs, simg2img, etc., from the Android Open Source Project.

AndroidViewClient

The AndroidViewClient tools and library are installed, which include the culebra and dump scripts. culebra lets you interact with and record macros for the Android GUI. The macros are similar to those you can create using monkeyrunner. Learn more about AndroidViewClient here.

Browser-based remote display facilities

Tightvnc server and noVNC are installed. To set up a remote display session that you can interact with using your web browser, run:

/share/PhantomNet/bin/runvnc.sh

After setting things up, this script will spit out a URL you can paste into your browser. A ctrl-C sent to the shell where you ran this script will kill the running VNC/X server. This X session is handy to have to run things like culebra without needing to setup and forward an X session from your own machine.

Other Notes

You can only connect to UEs from a designated target host

In the example profile above, we show how a geni-lib driven PhantomNet profile can setup ADB access on a designated target node in your experiment. You cannot connect with ADB from any other machine; the infrastructure host is setup to only allow connections from the host set in the adb_target attribute.

To use GUI-based applications, you will need to login to the ADB target node with an ssh client that supports forwarding X sessions

For example, the OpenSSH client can forward your local X session to the ADB target (or other) node in your experiment. The string to use to connect with OpenSSH can be found under the "List View" tab for your experiment from within the PhantomNet Portal. Alternateively, you can setup a browser-accessible X session by running the script mentioned in the "Tools of interest" section above.

PhantomNet UE devices should be rooted

Commands run via the shell interface will run as the root user on the UE.

Rebooting UEs will disconnect them from the ADB target

You must reconnect using the pnadb command as shown above. It may take a minute for the infrastructure host attached to the UE to reestablish the forwarding setup such that you can connect again.