MEIC/MERC 2014/2015
Mobile Computing
Week 10
Lab Guide 5 – WiFi Direct
Objectives:
- Overview of WiFi Direct.
- Introduction to the Termite network emulator testbed.
Material:
Exercise I: Introduction to the Termite WiFi Direct Emulator
Build a simple application from scratch that allows two nodes to discover each other and to let the user send a file to the receiver. (Based on the Android demo for WiFi Direct)
1. Preliminaries
1. Install Termite: Download the Termite distribution file TermiteCMov-20150419.tgz, decompress it on a local directory, and open the project in Android Studio. In this project, you can see three modules:
- Termite-Cli: a command line tool for managing WiFi Direct emulations.
- Termite-WiFiP2P-API: the Termite WiFi Direct API, which must be imported by WiFi Direct applications targeting the Termite testbed.
- Termite-WiFiP2P-SimpleChat: a simple application that demonstrates the Termite Wifi Direct API; it allows for two devices to form a WiFi Direct group and exchange messages.
2. Configure Termite: Next, you need to set up some configuration attributes of your Termite installation. Under the Termite-Cli directory, open the file etc/backends.conf. By default, this file looks as follows:
{
"backends" : [
{
"id" : "avd",
"connector" : "avd",
"config" : {
"sdk" : "/Users/nsantos/Library/Android/sdk",
"vmi" : "Nexus_5_API_21_x86"
}
}
]
}
You need to update the attributes sdk and vmi. The sdk attribute must be updated with the correct Android SDK path. A simple way to determine this is by opening the TermiteCMov project settings on Android Studio. (Note: on Windows, you must write the sdk path as in, e.g., "c:\\my\\path\\for\\sdk".) The vmi attribute must correspond to a valid Android Virtual Device (AVD) name. Termite will use this name to launch emulator instances using that specific AVD image. To determine which AVDs are available locally, go to the Android SDK directory and under the tools subdirectory execute the command below, and choose the AVD image name you want to be able to launch from termite:
./android list avd
3. Run the termite tool: Build the TermiteCMov project. Then open a terminal window (outside of Android Studio) and change directory to the Termite-Cli folder. Set the environment variable TERMITE_CLI_PATH to point to the location of the Termite CLI module, i.e., this path. An easy way to do this is to update this variable in the file etc/env/env_laptop.sh and then, on the terminal window, execute the command: source etc/env/env_laptop.sh. Naturally, you can also create your own "env" file. Then run the script ./termite.sh. On windows, the procedure is different. To set up the environment variable, use the command "set TERMITE_CLI_PATH=...". To execute termite, run the batch file termite.bat. (But first, you need to download this file and copy it to Termite-Cli.) If everything goes well, the following output is expected:
Termite Testbed Working Directory = /Users/nsantos/Desktop/TestLab05/TermiteCMov/Termite-Cli Type "help" or "h" for the full command list avd:simplechat>
Termite is now ready.
2. Run the SimpleChat Demo
The next step is to test the tool using the SimpleChat demo. The goal will be to emulate two nodes that can communicate with each other over a WiFi Direct network using the SimplaChat app. The virtual nodes we want to simulate will be named A and B. Proceed as follows:
1. Launch two emulators: On termite, create two new emulator instances by executing the command deployemulator. To make sure that the emulators boot properly, a conservative way is to wait until the first emulator finishes bootstrapping. Only then it is ok to launch the second one. If you are experiencing problems (e.g., the emulator hangs), go to Android Studio, open the AVD manager and wipe the data of the respective AVD image. You can list the state of existing emulators by executing the command:
avd:simplechat> deployemulator avd:simplechat> deployemulator avd:simplechat> list emus emulator-5554 => online emulator-5556 => online
2. Configure the network addresses of the emulators: In order for the SimpleChat application to be able to communicate with other virtual devices and for the termite tool to communicate with the emulators, it is necessary to perform some port redirection operations. The termite tool can help in this task. First, you need to assign network addresses to each emulator individually using the assignaddresses as follows:
avd:simplechat> assignaddr emulator-5554
avd:simplechat> assignaddr emulator-5556
avd:simplechat> list emus
emulator-5554 => netok
addr: [ avaddr = 192.168.0.1:10001, araddr = 10.0.2.2:10011, cvaddr = 127.0.0.1:9001, craddr = 127.0.0.1:9011]
emulator-5556 => netok
addr: [ avaddr = 192.168.0.2:10001, araddr = 10.0.2.2:10021, cvaddr = 127.0.0.1:9001, craddr = 127.0.0.1:9021]
From this listing, what is important to understand now is the "avaddr" attribute which means: application virtual address. Essentially these are the virtual addresses that termite will emulate for the application running on that particular emulator. For example, for emulator-5554, the virtual IP address seen by the application is 192.168.0.1, and the port number where the application will be listening is 10001. The SimpleChat application will be listening for connections on this port. These addresses are specified in the termite configuration file etc/netprofiles.conf. More documentation will be published in the future explaining the remaining attributes.
Next, it is necessary to bind the names of the virtual devices A and B to each of the emulators. This is done using the binddevice command as illustrated next:
avd:simplechat> binddevice A emulator-5554 avd:simplechat> binddevice B emulator-5556 avd:simplechat> list devices A 192.168.0.1:10001 10.0.2.2:10011 127.0.0.1:9011 B 192.168.0.2:10001 10.0.2.2:10021 127.0.0.1:9021
The list devices command provides details of your virtual network. In the network emulation, these are the names to be used when referring to the virtual nodes, not emulator names. We are now ready to deploy the application and emulate the network.
3. Deploy the application: From Android Studio, select the SimpleChat module, and deploy the application, first on emulator-5554 and then on emulator-5556. On the termite console, execute ping and verify that the nodes are online:
avd:simplechat> ping A 127.0.0.1 9011 ONLINE B 127.0.0.1 9021 ONLINE
This means that the termite service is waiting on ports 9011 and 9021 of the localhost. These ports are internally redirected to the port 9001 inside the emulator.
4. Emulate node movement: First, you need to hit the "Wifi On" button on each node. Then, on the termite console, emulate the nodes A and B forming a cluster, by moving A close to node B as shown next (make sure that you can see both the emulators when you execute the following commands):
avd:simplechat> move A (B) avd:simplechat> list n A => B B => A avd:simplechat> commit B 127.0.0.1 9021 SUCCESS A 127.0.0.1 9011 SUCCESS
Check that toast messages popped up reading "Peer list changed". Clock on "In range" to see which peers are available. If you click "In network" the list will be empty because the network is not formed yet.
In the sequence of commands performed before, note that the changes to the virtual network topology are performed locally in the termite console. In order to propagate the topology information to the nodes, you must execute commit.
5. Emulate group formation and peer-to-peer communication: Next, form a Wifi direct network (a.k.a group) containing both the nodes A and B. Node A will be the group owner (GO) of the network. Execute these commands:
avd:simplechat> creategroup A (B) avd:simplechat> list groups A => B avd:simplechat> commit
Observe new toasts reading "Network membership changed", and "Group owner changed" for node A. On A, learn B's address (192.168.0.2), type it on A's edit text box, and then hit the "Connect" button. This will open sockets between both nodes enabling them to exchange messages in a conversational fashion. Test this feature. On A, send a message to B. From B send a message to A.
6. Emulate group destruction and communication breaks: Now, delete the group and see what happens. To delete the group, on the command line execute:
avd:simplechat> deletegroup A avd:simplechat> commit B 127.0.0.1 9021 SUCCESS A 127.0.0.1 9011 SUCCESS
It is also possible to emulate nodes moving away and leaving the group without explicitly destroying the group. To test this, recreate the group:
avd:simplechat> creategroup A (B) avd:simplechat> list groups A => B avd:simplechat> commit
Then, on B, open a connection to A. Now, move the nodes apart from each other. This will cause the group to be automatically destroyed. On termite, execute:
avd:simplechat> move A () avd:simplechat> list n A => B => avd:simplechat> list groups A => avd:simplechat> commit B 127.0.0.1 9021 SUCCESS A 127.0.0.1 9011 SUCCESS
7. Adding members to pre-existing groups: From the previous listing, see that the group owned by A still exists. To repeat the scenario in which both nodes can communicate, you can again add B to A's group:
avd:simplechat> move B (A) avd:simplechat> joingroup B (A) avd:simplechat> list groups A => B avd:simplechat> commit A 127.0.0.1 9011 SUCCESS B 127.0.0.1 9021 SUCCESS
Verify that you can again open a channel between A and B and have them communicating.
Tips: To redeploy the application, only need to: deploy it to both emulators from Android Studio and on termite issue the commit command, to propagate the current network state to the devices. It is not necessary to repeat all the network formation steps from scratch if the network topology you need to emulate is already in memory in the termite tool. To know what's the current network state execute: list network.
Exercise II: Building WiFi Direct Apps for Termite
To learn how the Termite WiFi Direct API works, you will now build an application from scratch. This application, called SimpleMessaging, is similar to SimpleChat, but with some differences.
Like SimpleChat it enables communication between two nodes. There is a single activity that shows WiFi connect and disconnect button, buttons for checking the surrounding peers and for querying the list of nodes in the network. It also enables nodes to connect to each other and communicate.
The main difference is that instead of SimpleChat's conversational model, the SimpleMessaging only allows for sending single messages from one node to the other. Each node will be waiting for incoming connections, and when a connection is established, the server will expect a single message to be sent, close the incoming socket, and show to the local user the content of the message.
To implement this application, refer to the source code of SimpleChat and to the Termite WiFi Direct API Guide.
Exercise III: Testing on Real Devices (Optional)
If you have real devices featuring WiFi Direct technology, you cannot directly test the applications implemented in the previous exercise. The reason is that the Termite API and Android API have some differences.
To test WiFi Direct applications on real devices, download the Android sample WifiDirectDemo.tgz and open it on Android Studio.
Modify this application in order that the Group Owner node can determine the IP address of the client. Tip: on the server socket, use the following code:
Socket client = serverSocket.accept();
SocketAddress clientRemoteAddress = client.getRemoteSocketAddress();
clientIP = clientRemoteAddress.toString();