prplMesh

prplMesh is an open-source, carrier-grade and certifiable implementation of the WiFi Alliance’s Multi-AP specification.

The result will be source-code covering both the agent and the controller part of the Multi-AP specification. However, it is scoped as a reference implementation and will leave ample room for differentiation, for example for proprietary IP algorithms making intelligent decisions for the whole Multi-AP network.

In short, the project’s aim is to create a baseline for OEMs and developers to easily integrate Multi-AP into various products and platforms. Initial targets include prplWrt and RDK-B with support for WiFi chipsets from almost any SoC vendor to be used in residential gateways, WiFi extenders from both retail brands and internet service providers.

This project is part of a wider collaboration between Prpl Foundation and Broadband Forum, and is based on a proven full mesh solution contributed by Intel Corp (Controller and Agent running on actual HW).

Architecture documentation can be found in the documentation folder.

The latest build artifacts are always accessible.

Fetch Sources

If you haven't done so already, set up your git configuration:

git config --global user.email your@email.address
git config --global user.name "Your Name"

If you already have a gitlab account:

git clone ssh://git@gitlab.com/prpl-foundation/prplmesh/prplMesh.git

Otherwise

git clone https://gitlab.com/prpl-foundation/prplmesh/prplMesh.git

Build in Docker

See corresponding README

Native Build

As an alternative to the manual steps outlined below, tools/maptools.py can be used to build and install prplMesh with a single command.

Requirements

An up-to-date list of packages you need to build prplMesh on Ubuntu (18.04) is available in the Dockerfile This is used in our automated builds, so is guaranteed to be up to date. As of the time of writing, it includes the following packages:

• binutils
• cmake
• gcc
• git
• libjson-c-dev
• libncurses-dev
• libnl-3-dev
• libnl-genl-3-dev
• libnl-route-3-dev
• libssl-dev
• ninja-build
• pkg-config
• python
• python-yaml
• python3
• python3-yaml
• bison
• curl
• flex
• libevent-dev
• libyajl-dev
• lua5.1
• liblua5.1-0-dev
• build-essential
• clang-format
• gcovr
• bridge-utils
• ebtables
• iproute2
• net-tools
• psmisc
• uuid-runtime

Run Build

Use standard CMake to build prplMesh, with a configure-build-install cycle.

To build prplMesh natively in debug mode (for being able to debug with gdb), with all features and tests, and installed in a local directory, run

cmake -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=../build/install -H. -B../build -G Ninja
ninja -C ../build install

If you prefer, make can be used instead of ninja by removing the -G Ninja part in 1st command and by replacing ninja with make in 2nd one.

Install

For system-level install, the standard DESTDIR approach can be used for installing prplMesh as a package.

DESTDIR=/tmp/prplMesh-install ninja install

Running Instructions

Once built, prplMesh controller, agent and framework can be started using prplmesh_utils.sh:

cd <path/to/install/dir>/scripts
sudo ./prplmesh_utils.sh start

Debugging Instructions

To debug prplMesh controller, agent or cli it is needed to install 'Native Debug' extension for Visual Studio Code. Also prplMesh solution should be compiled with CMAKE_BUILD_TYPE=Debug flag. Debug instruction:

1. Start prplMesh solution(read Running Instructions)
2. To remote debug it is needed to start gdbserver

gdbserver :9999 --attach <pid of controller/agent/cli>

2. Go to debug tab in the VSCode and choose one the option from the dropdown list.
3. Add breakpoint and click start debugging.

Log files locations

• framework /tmp/mapf
• controller /tmp/beerocks/logs/beerocks_controller.log
• platform manager & backhaul manager /tmp/beerocks/logs/beerocks_backhaul.log
• agent /tmp/beerocks/logs/beerocks_agent.log
• agent fronthaul ap manager wlan0 /tmp/beerocks/logs/beerocks_ap_manager_wlan0.log
• agent fronthaul ap monitor wlan0 /tmp/beerocks/logs/beerocks_monitor_wlan0.log
• agent fronthaul ap manager wlan2 /tmp/beerocks/logs/beerocks_ap_manager_wlan2.log
• agent fronthaul ap monitor wlan2 /tmp/beerocks/logs/beerocks_monitor_wlan2.log

Checking status

System is operational if you see FSM: CONNECTED --> OPERATIONAL in the main agent log. In the future there will be a bml cli command to verify operational state.

Displaying the connection map (GUI)

There is a tool to display the connection map on a GUI in tools/beerocks_analyzer. Its README file explains how to use it.

Troubleshooting

If master branch does not work / does not pass tests on your computer make sure that:

• you loaded ebtables kernel module: sudo modprobe ebtables
• you updated your docker images with tools/docker/image-build.sh