New America Foundation - Contractor Agreement #19-OTIDOS2013 “NAF3”

In July 2012, The Serval Project commenced a third round of work for the New America Foundation's Open Technology Institute to integrate the Commotion Wireless Project's Ad Hoc Wi-Fi control into the Serval Mesh (app for Android). This was an essential step to allowing Commotion Wireless and Serval Mesh apps to co-exist on the same Android device, by preventing contention for control of the Wi-Fi radio.

Section 1: Work to be Performed (Scope of Work)

  • <BOOKMARK:r1>R1. Prepare several handsets with both Commotion and Serval Android applications, and confirm that each works independently on the prepared handsets.
  • <BOOKMARK:r2>R2. Detect installation of Commotion Android application, and indicate this in the Serval Mesh application's list of available networks.
  • <BOOKMARK:r3>R3. When the Commotion Wireless mesh network is selected from the Serval Mesh Android application, signal the Commotion Android application to start the Commotion Wireless mesh, as well as starting Serval Mesh services.
  • <BOOKMARK:r4>R4. When changing networks from the Serval Mesh application, if the Commotion Wireless mesh network is operating, signal the Commotion Android application to stop the Commotion Wireless mesh network.
  • <BOOKMARK:r5>R5. When the Commotion Android application starts the mesh network, the Serval Mesh application detects this, starts Serval Mesh services if not already running, and updates its state accordingly.
  • <BOOKMARK:r6>R6. When the Commotion Android application stops the mesh network, the Serval Mesh application detects this, and updates its state accordingly.
  • <BOOKMARK:r7>R7. Prepare test plans capable of verifying the correct implementation of the above.
  • <BOOKMARK:r8>R8. Execute test plans to verify the correct implementation of the above.
  • <BOOKMARK:r9>R9. Document the desired behaviour, any outstanding tasks of apparent improvements that could be made in the wikis of both Commotion Wireless and the Serval Project.


This report was produced in fulfilment of R9.

Development commenced prior to the date of contract, and progressed until mid September 2013 until blocking technical issues were encountered (see below). The contract was deemed complete in October 2013.

Although the move towards CyanogenMod by the Commotion Wireless project may eventually render the Mesh Tether app irrelevant, the integration work realised in this contract will still remain useful for integration with other mesh network control components.

Modifications to Serval Mesh app

The commit 18dfb90 encapsulates all the changes made to the Serval Mesh (“Batphone”) source code:

  • whenever displaying a list of networks in its “Connect” activity, Batphone checks for the presence of the net.commotionwireless.meshtether app and that it possesses the permission net.commotionwireless.meshtether.CHANGE_STATE (R2)
  • if the Commotion MeshTether app is installed, Batphone adds its name to the list of available networks on the “Connect” activity, of type “Mesh” (R2)
  • when the user selects the Commotion MeshTether network in Batphone, this causes Batphone to toggle the Commotion mesh state by broadcasting a net.commotionwireless.meshtether.TOGGLE_STATE intent (R3 and R4)
  • Batphone responds to the net.commotionwireless.meshtether.STATE_CHANGED intent from the Commotion app to indicate its state (R5 and R6)
  • between the user toggling the Commotion MeshTether state and the matching STATE_CHANGED intent arriving, Batphone suppresses its own Wi-Fi network scanning (R3 and R4)

MeshTether makes its enabled Ad Hoc mesh mode appear to Android as an active Wi-Fi network connection. Whilst enabled by the user, Batphone automatically starts Serval services (ie, starts the Serval DNA daemon) whenever any Wi-Fi connection is active. It was almost trivial to fulfil R5 and R6 by building on the recent re-design of the Batphone “Connect” menu and Wi-Fi control logic, funded by a grant from OpenITP earlier in 2013 which had the objective of removing Batphone's dependence on root (super-user) privilege. The decision to engage in extensive re-design work during that grant has borne fruit in this grant.

MeshTether issues

The Serval development team could not achieve correct operation of the Commotion MeshTether app (R1) on any of the available handsets:

All these handsets have super-user capability and are known to work with Serval Mesh in Wi-Fi Ad Hoc mode.

Two versions of MeshTether were tested, as described in the MeshTether integration roadmap page:


In fulfilment of R7, two manual test cases were added to the Serval Mesh release test plan, to be performed for all future releases:

The setback described above (MeshTether issues) prevented full testing from being carried out (R8) because the Commotion Mesh could not be activated on any devices.

content/activity/naf3.txt · Last modified: 28/11/2013 21:08 by Andrew Bettison