Key Concepts

Common language

A successful UI running on multiple devices must share appropriate, accessible and common language. The following list of terms should be used throughout Commotion apps. Some of them include descriptions that can be included in optional tooltips for the user who needs more information. Advanced terminology that requires significant prior knowledge to understand should be reserved for the advanced area of your software.

  • This language should be used when including a short description of the project:
    Commotion is an open-source communication tool that uses wireless devices to create decentralized mesh networks. More at
  • This language should be added when you have more space or on “about” pages:
    The project is collaboratively developed by The Open Technology Initiative, The Work Department, The Guardian Project, The Serval Project, and volunteers within the community.

Common UI Terms

Many terms below reference a definition. A term’s definition should be included in the UI either inline or as a pop-up tooltip in order to help beginning users understand basic concepts.

  1. Mesh Network Name (SSID)
    (Inline definition: Choose a name that is 5-12 characters. The name can include numbers, letters & special characters. Must be the same among multiple nodes.)
    (Pop-up tooltip: The public name of a wireless network. SSID is an acronym for Service Set Identifier.)
    SSID / mesh network name
  2. Node Name
    (Inline definition: Unique name that is 5-12 characters. You can use numbers, letters & special characters.)
    (Pop-up tooltip: Each device connected to the mesh network has a unique name. This name helps you identify your device.)
    node name
  3. Channel
    (Inline definition: Every node on the network must have the same channel.)
    (Pop-up tooltip: The 2.4 GHz Wi-Fi signal range is divided into 11 smaller channels in the U.S. You can choose different channels to avoid wireless interference.)
  4. Node
    (Pop-up tooltip: An individual device on a mesh network.)
  5. Client
    (Pop-up tooltip: A Wi-Fi device that temporarily connects to the mesh network without using Commotion software.)
  6. Join a mesh network
  7. Create a mesh network
  8. Looking for networks...
  9. Joining...
  10. IP Address
  11. Current speed
  12. Average speed
  13. Advanced
  14. Help
  15. Log
  16. Quit

Security, privacy and anonymity

A significant challenge in developing Commotion is balancing ease-of-use and control over functionality. Different users will want Commotion to serve different purposes, and our choices in features and design will make some things easier and some things harder. Unfortunately, we cannot make a perfect package for all situations: we need to be clear about the limitations inherent in Commotion, especially regarding matters of security, privacy and anonymity. These three concepts are related through their importance to communities and people with “real life” concerns of oppression, surveillance, and other attacks.


While Commotion software can’t be solely responsible for providing a definitive education on these topics, the software should make clear any risks or benefits of features that deal with security, privacy, or anonymity.

When a user takes an action that could affect their security, privacy or anonymity, they should see a simple warning message that invites them to learn more by linking to external documentation. Here's an example warning that could pop-up after a user changes the node name. It should include a "Don't warn me again" checkbox to disable this warning for the future. The Commotion website should offer details about potential risks and vulnerabilities related to using the tools in common scenarios.


Within the context of Commotion, you should consider the information security of data on a network as well as the physical security of people using the network. Data security involves trust, fault tolerance, and integrity of connections between mesh nodes. Physical security overlaps with privacy in many ways: can the people who have created the network be identified based on visible hardware or detectable radio signals? We have the responsibility and ability to inform users of information security concerns, but how do we introduce the topic of physical security?

Commotion’s documentation should explain wireless network security concepts and how mesh networks and traditionally-routed networks differ with regards to security. This documentation should be referenced during the initial configuration of a network.

Privacy and Anonymity

Commotion documentation should clearly discuss any issues of privacy and data retention. When Commotion generates and retains logs, it should provide options to anonymize the data, clear logs periodically, and disable logging. If the software collects metadata from the device, it should prompt the user to allow for this information to be spread across the network. If the platform allows it, Commotion software should allow for changing MAC addresses through the advanced settings.

In addition to abilities that Commotion can offer at the network level, the documentation should point to privacy and anonymity resources above the mesh network layer. While software can prevent some attacks against privacy and anonymity, the documentation should outline any vulnerabilities associated with traffic analysis and radio monitoring.

Read more about Commotion Security Architecture.

Common footer

A common footer menu should be available throughout the UI. This ensures that users have consistent access to standard functions of the software at all times. For web-based and desktop applications, create a common green footer in the UI.

In Android, use the native menu. The menu items can also be collapsed to the Android "action overflow" button in the navigation bar if needed.

The menu items are:

  1. Advanced (Goes to a menu of advanced settings)
  2. Help (Goes to a menu of help options)
  3. Log (Goes to an activity log)
  4. Quit (Ends all mesh networking processes and closes the application)