Host Protocol Stack and Network Service API
Contents
0. Requirements
- Software prototype with reference implementations of MobilityFirst's network protocol stack
- Network service abstractions for MobilityFirst's FIA
1. Mobility First API
In this section it will be described Mobility First's API. At the moment not all interfaces are implemented or works as listed; the API is at the moment under development so it will need some time before reaching a good level of stability. The description provided reflects what is the goal we are trying to achieve. For an implementation reference look the documentation found at THIS location for C/C++ or at THIS location for JAVA.
MFAPI is divided into three major groups that differentiate the patterns of possible communications between network entities. This groups are: primitives, content centric operations and service centric operations.
1.1 Primitives
The set of primitives has been intended to provide basic services to the applications that use them such as initiating a network session by stating the communication intent, ...
1.1.1 Open
Synopsis
open(profile, [profile-opts], [GUID-set]);
Description
The open function shall define the initialization of a communication session between the application layer and the underneath layers. On doing so the system is informed of the intent of the application and can choose the appropriate transportation service and initialize the needed resources.
Profile is a descriptive element that inform the system about the intent of the application.
Profile-opts is optional are additional parameters that can be provided to request additional services expressed as flags. If no value is provided, the system will make the initialization based on the sole Profile
GUID-set is optional and represents the set of GUIDs that the application is willing of listening at. If no value is provided, the system should select the system default GUID identifier for the application.
Return Value
The function returns a value representing the created network endpoint. If the function has failed, this value should represent the incurred error.
1.1.2 Attach
Synopsis
attach(GUID-set);
Description
The attach function provides the functionalities to add additional GUIDs at the the one originally identified during the open call.
GUID-set represents the set of GUIDs that the application wants to add at the set that it is listening at.
Return Value
The returned value shall inform the application of weather the API layer has successfully added the set of GUIDs or not.
1.1.3 Detach
Synopsis
detach(GUID-set);
Description
The detach function shall provide a way of removing GUIDs form the one originally identified during the open call or the ones added through the use of "attach".
GUID-set represents the set of GUIDs that the application wants to remove from the set that it is listening at.
Return Value
The returned value shall inform the application of weather the API layer has successfully removed the set of GUIDs or not.
1.1.4 Send
Synopsis
send(dst-GUID, data, [svc-opts]);
Description
The send operation shall send data to a destination GUID as messages with no size limits except for the ones defined by system resources. The way the message is delivered to the entity defined by the GUID is determined by the session characteristics defined during the open call and eventually by additional service options.
dst-GUID represents the destination GUID.
data is the data message to be sent.
svc-opts are additional service options used to determine how the message is delivered expressed as flags.
Return Value
The function shall return the number of bytes sent.
1.1.5 Recv
Synopsis
recv(src-GUID, buffer, [GUID-set]);
Description
The recv operation shall write into the buffer passed the oldest not read message received.
src-GUID is a variable that will be filled with the GUID of the entity that sent the message.
buffer is filled with the message that has been transmitted.
GUID-set is optional and can be used to limit the set of GUIDs to receive from. These GUIDs need to have been previously included in the set provided during the open call or after additional attach operations.
Return Value
The function shall return the number of bytes written in buffer.
1.1.6 Close
Synopsis
close();
Description
The close function shall close the session initiated with an open call and clear the resources that were allocated.
Return Value
The returned value shall inform the application of weather the API layer has successfully closed the session or not.
1.2 Content Centric Operations
1.2.1 Get
1.2.2 Get_handle
1.2.3 Get_response
1.2.4 Post
1.2.5 Post_handle
1.2.6 Post_response
1.3 Service Centric Operations
1.3.1 Exec
1.3.2 Exec_handle
1.3.3 Exec_response
2. Installation
In this section is explained how to install the system in two different environments: Linux and Android.
2.1 Linux
Manual installation
- Compile:
- If you do not want to include jni interfaces, go to folder: mobilityfirst/trunk/code/prototype/client/api/
- If you do want to include jni interfaces, go to folder: mobilityfirst/trunk/code/prototype/client/api/jmfapi/jni/
- If compiling including the jni export JAVA_HOME to your environment PATH. You can use a command like "export JAVA_HOME=$(find /usr/lib/jvm/ -name 'java-1.7.0-openjdk-*')" if you are using openjdk version 7 (The compilation will fail if you do not do this and want to include jni code).
- Type "make"
- (Optional if the Java API is needed) Maven is required for the compiling the library.
- (Optional if the Java API is needed) Go to folder: mobilityfirst/trunk/code/prototype/client/api/jmfapi/
- (Optional if the Java API is needed) Type "mvn clean package"
- Go to folder: mobilityfirst/trunk/code/prototype/client/stack/src/
- If you do not want to include OML code type "make NO-OML=1"
- If you do want to include OML code type "make"
- Install:
- If you do not want to include jni interfaces, go to folder: mobilityfirst/trunk/code/prototype/client/api/
- If you do want to include jni interfaces, go to folder: mobilityfirst/trunk/code/prototype/client/api/jmfapi/jni/
- Type "make install" (needs su permissions). This will place the generated libraries under /usr/local/libs/
- Go to folder: mobilityfirst/trunk/code/prototype/client/stack/src/
- If you do not want to include OML code type "make install NO-OML=1" (needs su permissions). This will place the generated libraries under /usr/local/bin/
- If you do want to include OML code type "make install" (needs su permissions). This will place the generated libraries under /usr/local/bin/
- Create the folder /data/mfdemo/
- Create the settings file (with the proper values, more to follow)
- Check that all permissions are correctly set to let the files to be read and executed
2.2 Android
There are two options to install all the necessary libraries and binaries in android: manual compilation and installation or use the provided application.
2.2.1 Manual installation
- Dependencies:
- Having command ndk-build (part of Android NDK) in your environment PATH
- Root permissions for your Android device
- Access to Mobility First repository
- Compile:
- Go to folder: mobilityfirst/trunk/code/prototype/client/c_android/
- Type "./c_android"
- All generated files are going to be placed under the mobilityfirst/trunk/code/prototype/client/c_android/bin/ folder
- Install:
- Copy all libraries from the bin folder into /system/lib/ folder in your Android device (.so files)
- Create the folder /data/mfdemo/
- Copy the executable mfandroidstack into the folder /data/mfdemo/
- Place the settings file (named "settings" and with the chosen values) into /data/mfdemo/
- Check that all permissions are correctly set to let the files to be read and executed
- Import the jmfapi.jar library in your Android application by placing it in the libs folder
2.2.2 Automatic installation (not available yet)
- Dependencies:
- Root permissions for your Android device
- Install:
- Install this application
- Open it and click the install button
- Download the jmfapi.jar library or compile it following the "manual installation" instructions
- Import the jmfapi.jar library in your Android application by placing it in the libs folder
3. Running Mobility First protocol stack
To run the stack a settings file needs to be correctly created. An example with the tunable parameters is provided here:
settings.conf INTERFACE = wifi,wlan0,auto INTERFACE = wimax,wmx1,manual, 192.168.1.1, 11:22:33:44:55:66 #manual is used for client to client communications POLICY = bestperformance BUFFER_SIZE = 10 DEFAULT_GUID = 1
Additional examples can be found in the repository in the folder eval/conf/client/.
3.1 Linux
- Execute the stack by typing the following command: mfstack /location/to/settings/settings.conf" (or follow the help instructions obtained running "mfstack -h")
3.2 Android
3.2.1 Manual
- Open a shell in the device (adb shell) and follow the instructions specified in the Linux section
3.2.2 Automatic
- Install THIS apk in your Android device or alternatively compile the same application that can be found in the folder mobilityfirst/trunk/code/prototype/client/stack/launcher (the application provided at this link is not guaranteed to be updated regularly)
- Click the start button specifiend the default GUID and the log level
- To stop press the stop button
3.3 Additional information for Android
In this section it will be described how to connect an Android phone with the running stack to an Orbit node running either an Access router or another client. This section contains ONLY the additional informations relative to connecting the Android device to the node; for all the other instructions please refer either to the previous sections or to the Click Router implementation page.
There are two components that need to be available on the node to let the device to connect to it: a DHCP server and, if running Android 3.x or up, a software Access Point.
3.3.1 Dnsmasq
Dnsmasq can be used to run a DHCP server on the node. Dnsmasq is easily installable through apt.
After the software has been installed the configuration file located at /etc/dnsmasq.conf will need to be properly configured. This is a simple configuration file used to give access to a single phone guaranteeing that it will always be assigned the same IP address:
interface=wlan0 dhcp-range=wlan0,192.168.1.2,192.168.1.20,12h dhcp-host=64:A7:69:93:5F:2F,192.168.11.1,12h
At this point it will be enough to set up the node's wifi interface into Ad-Hoc mode and the phone will see the newly created network and after connecting it it will get the assigned IP.
3.3.2 Hostapd
If running Android 3.x or more or if running a stock Android ROM, Ad-Hoc networks are not identified by the phone; in this case it will be necessary to run a software AP on the node. Hostapd can be used for this purpose (installable through apt).
Also in this case a configuration file needs to be provided to the client. This can be used as an example:
interface=wlan0 driver=nl80211 ssid=mf_test_ap hw_mode=g channel=11 macaddr_acl=0 auth_algs=1 ignore_broadcast_ssid=0 wpa=3 wpa_passphrase=testmfap wpa_key_mgmt=WPA-PSK wpa_pairwise=TKIP rsn_pairwise=CCMP
For any additional information on this two tools please refer to their web pages.
3.4 Usage Example
The following code snippet shows a very simple C program used to send a message to another destination and receive the following reply.
#include <stdio.h> #include <stdlib.h> #include <mfapi.h> int main(int argc, char *argv[]) { struct Handle handle; //Choosing GUIDs 1 and 2 as reference int mine = 1, other = 2, sent = 0, received = 0, size = 65*1024; //Buffer to send and receive messages; I don't care about the content u_char buf[size]; //Requesting basic transport. Listening for GUID mine ret = mfopen(&handle, "basic\0", NULL, mine); if(ret) { fprintf(stderr, "receiver: mfopen error\n"); return (EXIT_FAILURE); } //Send message to other. No additional services requested sent = mfsend(&handle, buf, size, other, NULL); if (sent < 0) { fprintf (stderr,"mfsendmsg error\n"); return EXIT_FAILURE; } //Wait to receive new message received = mfrecv_blk(&handle, buf, size, NULL, 0); if (received < 0) { fprintf (stderr,"mfrecv_blk error\n"); return EXIT_FAILURE; } printf("Intended to send %d bytes, sent %d bytes, received %d bytes\n", size, sent, received); mfclose(&handle); return EXIT_SUCCESS; }
4. Performance
5. Known Issues
- Link layer block id issue on host stack restarts: The Hop link layer data transport uses a monotonously increasing and unique id to identify data blocks. If upstream node (R) has seen a block id before from a host (H, identified by MAC), it simple acknowledges that it has received (and forwarded) the block before and will not forward again. This enables robustness to any misunderstandings whether block was reliably delivered when acks are lost. However, if the protocol stack on host H were to be restarted for some reason it resets block ids to begin from 1 and results in data blocks sent subsequently to node R to be ignored if those ids were used before.
- Potential fix(es): 1. Use content hash as block id, rather than sequence number. 2.) Modify router to consider repeated sequence number as new if time from prior receive has exceeded a threshold.
- Workaround: For experiments, restart router nodes when host stack is restarted. Note that all routers need restart and not only first upstream node R since the same Hop protocol is implemented across routers and host stacks.
- Status: No fix implemented yet.
- Send from application blocks on stack resources exhaustion:
- respond with an error (try again later).
- Status: No fix implemented yet.
- Content/Service operations get different flows (transport IDs) from send/recv operations :
- this could be used to send control messages over the basic interfaces;
- the different flow IDs are used to distinguish between types.
- Status: No fix implemented yet.
- Give option in the API to bind to specific dst NAs. :
- after the first exchange is established NAs are used to keep communicating with the same end node;
- the transport needs to keep track of eventual errors.
- Status: No fix implemented yet.
- API should be able to request buffers of data smaller than the last message :
- Messages delimitates API transactions.
- Status: No fix implemented yet.
- Add asynchronous calls to API:
- Recv/Get.
- Status: No fix implemented yet.
