Hello everyone! I’m Victor Spehar, a Master’s student from Paris studying operating systems and distributed systems, and this is my first blog post for Freifunk!
This summer, I will be participating in Google Summer of Code 2025 for the Freifunk sister organization, LibreMesh, under the mentorship of Javier Jorge, where I’ll be working on adding Wi-Fi support to QEMU simulations in LibreMesh.
In simple terms, the goal of this project is to have:
- A fully virtualized Wi-Fi router running LibreMesh firmware
- The ability to “bridge” these virtual machines through their Wi-Fi interface in order to create a mesh network
- A more realistic testing pipeline – as far as virtualization goes – to catch regressions earlier and improve overall reliability of LibreMesh
What Is LibreMesh?
LibreMesh is a modular framework for creating OpenWrt-based firmware for wireless mesh nodes. It aims to enable non-expert users to set up mesh networks and manage them through a simple web interface.
Setting up LibreMesh goes like this :
First, find your router, then follow the installation procedure, and voilà – you have a node that is set up and ready to mesh!
Wi-Fi mesh networks provide an easy, cost-effective way to distribute Internet access in large buildings or public places, but they can also effectively be used to bridge 60+ families together. In LibreMesh, it’s simple to host services on each node because every router has its own hostname, making it easily reachable from anywhere in the mesh.
Testing in LibreMesh
Testing is an essential part of any software project: it ensures that new changes don’t introduce regressions and that features work as intended across different environments.
Currently, LibreMesh firmware testing is done in multiple ways:
Unit Tests of the lime-packages
Individual lime-packages are covered by unit tests. A Docker container emulates the OpenWrt userland, but all system-level configuration – which normally runs through UCI – are mocked or stubbed out.
- Pros:
- Easy to run, providing quick insight into which package might be broken
- Generates coverage metrics
- Cons:
- Not so easily expandable : mocks up need to be set up
- Does not emulate a real-world environment, and the distributed nature of LibreMesh
- Abstracts the entire kernel, system configuration cannot be tested that way
Testing on Real Hardware
LibreMesh is tested on real physical routers, but this process is:
- Hardware intensive: Multiple routers required and possibly different clients (laptops, smartphones, etc.) to connect to the mesh
- Time intensive: Each router needs to be flashed with the correct firmware version, all hardware must be set up, configured, and every steps should be documented manually
Additionally, there are currently no automated tests or a documented, repeatable procedure for hardware testing. This kind of testing is not easily reproducible, lacks observability (the bane of a distributed system – and it’s even worse when you are transmitting data over thin air!) and requires manual effort and lots of steps, but it remains essential to catch hardware-specific regressions.
QEMU-Based Testing
At the moment, LibreMesh provides scripts to spin up multiple virtual machine instances and connect them via an Ethernet bridge. Unfortunately, this setup does not cover LibreMesh’s core feature set: Wi-Fi meshes. Moreover, although these virtual machines provide helpful information to developers, no automated tests exist for this environment in LibreMesh, meaning no repeatability.
Since some communities rely on LibreMesh firmware for Internet access, an undetected regression in a new release could cut off users from essential services. Ensuring robust and reproducible testing during development is therefore essential.
Further integrating QEMU-based testing into LibreMesh will enable more realistic scenarios: no more mocking or stubbing for general system configuration testing, and the ability to perform Wi-Fi tests in a virtualized environment by leveraging the Linux mac80211_hwsim kernel module – already widely used by kernel developers for testing Wi-Fi.
A beneficial side effect: Once a test is set up for a QEMU virtual machine, it now can also run on real hardware ! The tests meant for a QEMU virtual machine should run the same on real hardware, meaning from two birds, one stone!
Plan of Action
The Linux mac80211_hwsim kernel module provides support for virtual WLAN devices – allowing us to access, configure, and observe a virtual Wi-Fi interface. It allows the users to set up, monitor and test all kind of configuration for Wi-Fi – no limitation in software compared to hardware, and it’s also not bound to legislation since all of this is virtual, and no radiowave being emitted. A detailed article describing its use can be found here
The idea would be to create a LibreMesh virtual machine with full Wi-Fi support that could speak to similar virtual machines through the Wi-Fi stack, effectively creating a Wi-Fi mesh network, while also being truly observable, tunable, and testable. This will give us complete control over the testing environment: different topologies, latency scenarios, even roaming tests that would be difficult or impossible to recreate in real life without a large real life setup.
To achieve this, I will have to :
- Include the
mac80211_hwsimmodule in a LibreMesh QEMU image and verify that the VM boots with virtual radios - Bridge VMs through their virtual Wi-Fi interfaces so guest radios can communicate directly via Wi-Fi frames
- Develop a set of scripts using RPCd interfaces for network diagnostics (e.g., checking link quality, peer discovery)
- Implement automated tests for different mesh scenarios (e.g., single-link failures, packet loss, variable TX power, multi-hop reachability, routing effectiveness)
- Integrate these new tests into LibreMesh’s existing testing framework
My project will enhance LibreMesh’s QEMU testing environment, improving development efficiency and deployment reliability. It won’t replace hardware testing but will catch bugs earlier in development with a faster, more robust testing pipeline and a controlled and repeatable environment.
Throughout my project, I will communicate with the LibreMesh community, sharing technical details about Wi-Fi integration in a virtualized context and providing documentation for setting up and testing LibreMesh with these new features.
Google Summer of Code: A Fantastic Opportunity!
I would like to thank everyone who made this possible. I’m truly grateful to GSoC, Freifunk, LibreMesh, and my mentor, Javier Jorge. This is my first step as an active open-source contributor and the beginning of a long, exciting journey where I’ll learn a lot!
For any suggestions or comments on my project, you can find me on the LibreMesh mailing list or the Matrix chatroom: libremesh-dev:matrix.guifi.net