Tag: gsoc

Hello everyone! As we reach the midpoint of Google Summer of Code 2025, I’m excited to share the progress on my project, Deep Q Network-based Rate Adaptation for IEEE 802.11ac Networks. The goal of this project is to build an intelligent rate control mechanism that can dynamically adapt transmission rates in Wi-Fi networks using Deep Reinforcement Learning. So far, I’ve implemented a basic DQN-based agent with a simplified environment, introduced group-based rate handling inspired by Minstrel_HT, incorporated success probability tracking, and collected real-world data using a shielding box. This post will walk through these key developments, the challenges encountered, and the next steps toward building a more robust and generalizable solution.

Background

Rate adaptation in Wi-Fi is a critical task that selects the most suitable Modulation and Coding Scheme (MCS) index for transmission. The MCS index encapsulates key physical-layer parameters such as modulations type, coding rate, bandwidth(BW), guard interval (GI), and a number of spatial streams (NSS). Traditional rate adaptation algorithms often rely on heuristics or statistical measurements to infer the best MCS under varying channel conditions. 

In this project, we aim to explore a Deep Q-Network (DQN) based approach for intelligent rate adaptation. Rather than relying on predefined rules, the agent learns to select the optimal MCS indices by interacting with the environment and receiving feedback on transmission success and failure. Unlike many prior works focused solely on simulations, our primary aim is to integrate this learning framework with real-world experimentation using ORCA (Open-source Resource Control API). This enables us to evaluate learning-based adaptation in actual 802.11ac Wi-Fi environments. For more detailed background and motivation, please refer to my initial blog post. Please check out my initial blog post for more information.

1. What We’ve Accomplished So Far

1. Initial Setup -DQN with Dummy States

In the early phase of the project, a basic DQN agent was set up with a placeholder environment to validate the training pipeline. The agent was designed to choose among discrete actions (initially up/down rate shifts), but the state representation was simplified to dummy values.

Each state was initially defined as the list of Received Signal Strength Indicator (RSSI), Signal Noise Ratio(SNR), transmission successes, retransmission attempts, and current MCS (among 8 fixed MCS values). This served as a proof-of-concept to validate the learning loop of DQN interacting with a Gym-style environment.

This served as a proof-of-concept to validate the learning loop of a Deep Q-Network (DQN) interacting with a Gym-style environment. This environment follows the OpenAI Gym(reference) interface, where an agent observes a state, takes an action, and receives a reward and next state in return. This setup helps modularize the environment and makes it easier to test and evolve reinforcement learning agents systematically.

2. Design of the DQN-Based Rate Adaptation Algorithm

In this section, we outline the overall system architecture of our Deep Q-Learning-based Rate adaptation framework. The goal is to give a clear block-level understanding of how the components interact, followed by an explanation of key choices around state, action, reward, and the agent.

Below is the high-level block diagram of the DQN-based rate adaptation system.

Fig1. Current Implementation

PyTorch was chosen as the deep learning framework as it offers easier debugging and flexibility compared to static graph libraries like TensorFlow 1.x. The API is clean and beginner-friendly. As PyTorch is widely used in reinforcement learning research, the community support is strong, which makes it easier to find references and extend the work if needed. 

Components of the DQN

1. Q-Network

A simple feed-forward neural network that takes the current state as input and outputs Q-values for each possible action (rate group). This helps to estimate how good each action is from the current state.

2. Target Network

To stabilize training, we maintain a separate target Q-network that is periodically synced with the main Q-network.

3. Custom Gym Environment
A tailored environment was built following the OpenAI Gym interface to simulate the Wi-Fi rate adaptation scenario.

• The state includes variables like RSSI, current rate index, number of attempts, and success history.
• The action space corresponds to selecting among a defined set of MCS rates.
• The step function computes the resulting throughput, success, and termination condition based on real trace data.

4. Agent

The component is responsible for selecting actions using an epsilon-greedy strategy, balancing exploration and exploitation during learning.

5. Experience Replay Buffer

Transitions (state, action, reward, next_state) are stored in a fixed-size buffer. During training, a batch of past experiences is randomly sampled to break temporal correlations of sequential experiences and improve sample efficiency. 

6. Epsilon-Greedy Exploration Strategy

To balance exploration and exploitation:

Initially, the exploration rate is set to 100%. This means the agent will select the random actions(rates) to determine which give better rewards.

The exploration rate is decayed linearly to promote exploitation (select the best known action) in the later stages.

7. Training Loop and Episode Tracking

The agent was trained over a series of interactions with the environment using a well-structured training loop, which mimics how reinforcement learning systems learn from trial and error.

In our setup:

An episode is a complete cycle of interaction between the agent and the environment. It starts with an environment reset and continues until the agent reaches a terminal state (e.g retransmissiion threshold, low success rate), or the maximum allowed steps for the episodes are completed.

A run refers to one complete training session, which in our case consists of 500 episodes. We can repeat runs with different random seeds or hyperparameters for comparison.

Each episode proceeds step-by-step, where the agent:

1. Selects an action (rate) using an epsilon-greedy policy.
2. Takes the action in the environment and receives the next state, reward, and a termination flag.
3. Stores the transition (state, action, reward, next_state, done) in the experience replay buffer.
4. Samples a batch from the buffer to update the Q-network using the Bellman equation.
5. Synchronizes the target network with the policy network at fixed intervals.

This structure enables stable learning over time, leveraging both exploration and exploitation.

Fig2. Sample Training Behavior

2. Core DQN Logic: State Design, Reward & Group-Based Adaptation

As we transitioned toward real-world deployment of our DQN-based rate adaptation agent using ORCA, we faced a key practical constraint: Signal-to-Noise Ratio (SNR) is not directly available from the ORCA interface. This led to a redesign of the agent’s input state and reward function, grounding our system in metrics that are actually observable in real Wi-Fi environments.

a. Removal of SNR

In early versions of the environment, SNR was included as part of the agent’s observation space. However, since ORCA (the testbed we use for data collection and deployment) does not expose SNR, it cannot be used in real training or evaluation. As a result:

• We removed SNR from the environment’s observation space.
  
• Instead, we rely on RSSI (Received Signal Strength Indicator), which can be collected reliably from transmission feedback logs in ORCA.
  

In the simulation, RSSI is initialized at –60 dBm and updated with small noise in each step. In real training, RSSI will be sourced directly from logs collected during hardware tests.

b.State Definition

Each state observed by the DQN agent is a 4-dimensional vector:

[current_rate, rssi, tx_success_rate, tx_retransmissions]

• current_rate: The transmission rate index selected by the agent in the previous step.
  
• rssi: Signal strength (used instead of SNR), simulated in the dummy setup and real in actual experiments.
  
• tx_success_rate: Maintains an exponential moving average of recent transmission outcomes.
  
• tx_retransmissions: Counts retransmissions, capped at 10.
  

This formulation provides a minimal yet sufficient summary of recent channel behavior and agent action history.

c. Reward Calculation

The reward is designed to reflect actual performance, balancing success and throughput:

success_prob is computed as:

Success_prob = successes/attempts

If the success probability for a rate is too low (<0.4), the agent receives a penalty.

Otherwise, the reward scales with the theoretical data rate of the selected rate and its current success probability.

d. Attempt and Success Counts

The environment internally tracks the number of transmission attempts and successes per rate using two dictionaries:

On each action step, the environment:

1. Increments the attempt count for the selected rate.
   
2. Samples a binary transmission outcome using the current estimated success probability.
   
3. Updates the success count if the transmission succeeded.

e. Why Warm-Start the Attempt and Success Counts

At the start of training, all rates have 0 attempts and 0 successes. This makes success probability undefined or zero, which results in poor early rewards and unstable learning.

To mitigate this, we use a warm-start strategy:

• A few rates are preloaded with 5 attempts and 4 successes.
  

This gives the agent initial traction and prevents early negative feedback loops.

This trick significantly stabilizes training in the first few episodes and is especially useful when rewards are sparse or noisy.

f. Group-Based Rate Adaptation (Inspired by Minstrel_HT)

In our implementation, we adopted a group-based rate adaptation strategy inspired by the structure used in Minstrel_HT and aligned with the rate grouping logic defined within ORCA. Each group corresponds to a specific combination of key physical-layer parameters, including spatial streams(NSS), bandwidth, guard interval, MCS modulation and coding.

Rate grouping is employed to generalize success estimates across similar rates.When a rate has never been used (0 attempts), its success probability falls back to that of higher-used rates in the same group.For example, our project uses Group 20, which corresponds to 3 spatial streams, 40 MHz bandwidth, and a short guard interval (SGI). The associated rate indices and their characteristics are:

Rate Index	MCS	Modulation	Coding	Data Rate (Mbps)	Airtime (ns)
200	BPSK, 1/2	BPSK	1/2	45.0	213,572
201	QPSK, 1/2	QPSK	1/2	90.0	106,924
202	QPSK, 3/4	QPSK	3/4	135.0	71,372
203	16-QAM, 1/2	16-QAM	1/2	180.0	53,600
204	16-QAM, 3/4	16-QAM	3/4	270.0	35,824
205	64-QAM, 2/3	64-QAM	2/3	360.0	26,824
206	64-QAM, 3/4	64-QAM	3/4	405.0	23,900
207	64-QAM, 5/6	64-QAM	5/6	450.0	21,424
208	256-QAM, 3/4	256-QAM	3/4	540.0	18,048
209	256-QAM, 5/6	256-QAM	5/6	600.0	16,248

Fig3. Details of Group 20

g. From Incremental Actions to Direct Rate Selections

Initially, the action space consisted of just 2 actions: increase or decrease the rate(MCS-style adaptation). However, after several trials it was clear that this incremental strategy was too slow, and most supported rates were never reached during the training. 

For a simple start, we chose 10 rates out of all the supported rates.

So, we updated the action space to be direct rate selection:

• Instead of navigating one rate at a time, the agent now chooses directly from a subset of these 10 representative rates.
• This allows faster exploration and better convergence.

This change made a major difference in the agent’s ability to adapt and explore diverse transmission configurations.

3. Real Data Collection with Shielding Box

To enable rate adaptation in real-world Wi-Fi networks, we began by collecting real channel data using controlled hardware setups. This data is essential for grounding our DQN training in reality and ensuring the learned policy performs well in practical deployment.

Rather than relying solely on simulated environments, our aim is to train and evaluate the DQN algorithm on actual wireless conditions. This is crucial for developing a rate adaptation mechanism that is robust and effective in real network scenarios. 

Test Setup

We used a shielding box setup to ensure accurate and isolated measurements. The shielding box allowed us to eliminate external interference, offering a reproducible environment to study channel behavior. ORCA provided fine-grained control over the STA, such as adjusting MCS rates, attenuation and collecting relevant metrics

Measurement Scope:

We systematically tested the full set of supported transmission rates to understand their performance under varying signal conditions:

• Covered all supported rates (hex:120 to 299)
  
• Grouped rates into prefix-based clusters (e.g., 12, 40)
  
• Each group was tested across attenuation levels from 40 dB to 70 dB in 5 dB steps for 20 seconds in each step.
  
• For each group, we collected:
  • RSSI over time
    
  • Selected transmission rates
    
  • Corresponding throughput

    These metrics were then visualized in the form of plots to understand behavior patterns and build insights.

The real-world dataset will be instrumental in training the DQN agent directly on real channel traces. We can validate the reward function logic and evaluate the effectiveness of the learned rate adaptation policy with this data. Finally, it will be helpful in deploying and testing the trained policy in live networks.

For Group 20 => Rates 200-209(Hex) (Fig3.)

Fig4. RSSI vs Time

Fig5. Rates and Corresponding Throughput vs Time

So far, the environment simulated RSSI dynamics using random noise, which lacks the variability and structure of real wireless channels. Moving forward, this collected dataset opens the door to a more realistic simulation and training loop, such as:

Conditional sampling: RSSI values and throughputs can be sampled based on selected rate and attenuation level, simulating how a rate would realistically perform under current channel conditions.

Replay of real RSSI traces: Instead of generating random RSSI values, the environment can replay actual RSSI sequences from the logs.

Rate-Throughput mapping: Instead of assigning theoretical data rates(Mbps), we can use empirical throughput measurements for each (rate, RSSI) pair, making the reward signal much more grounded.

Conditional sampling: RSSI values and throughputs can be sampled based on selected rate and attenuation level, simulating how a rate would realistically perform under current channel conditions.

This integration would make the environment closer to real-world performance, enabling the agent to learn from more structured feedback.This is a critical step for bridging the gap between simulation and real deployment.

4. Next Steps

Environment Refinement Using Real Data

• Use the collected shielding box data to model real rate-to-reward mappings.
• Replace random assignment of noise and RSSI values with the real trace data.
  

Train with Full Action Space

• Expand action space from binary (up/down) to direct rate selection.
  
• Evaluate trade-offs in convergence speed and learning stability.
  –

Integration with ORCA and Real Hardware

• Plug the DQN model into the ORCA framework for live experimentation.
  
• Use real-time stats from RateMan to drive the agent’s decisions.
  

Logging & Visualization

Visualize Q-values, state evolution, and rate changes over time.
Add detailed logging of action-reward-history.

5. Challenges and Open Questions
While progress has been substantial, several challenges and open questions remain, which need thoughtful solutions going forward:

1. Kickstarting Learning Without Warm-Up Rates

To prevent the agent from receiving only negative rewards in early episodes, we manually pre-filled success/attempt stats for certain rates. However, in real deployments, such a warm-up is not always possible.

Challenge: How to design exploration or reward shaping mechanisms that allow agents to learn from scratch without manual initialization?

2.  Large Action Space: Curse of Dimensionality

The supported rates in our setup are ~232. A large action space may:

• Make learning slower and unstable
  
• Lead to sparse exploration and poor generalization
  
• Cause overfitting to rarely used or unreachable rates
  

3. High Attenuation Handling

Under higher attenuation (e.g., 65–70 dB), only lower MCS rates may be feasible.

Challenge: Should the agent learn rate-attenuation mappings and restrict its actions contextually, or penalize high-rate selections under weak channel conditions?

4. Real-Time Constraints

The agent needs to make decisions at frame-level or sub-second intervals. Any delay in inference or policy selection may render the decision obsolete due to fast-varying wireless environments.

Challenge: Can we compress or distill the trained agent for low-latency environments?

Conclusion

The first half of GSoC has been a learning-intensive and productive phase. From environment design to agent training, we now have a complete pipeline to simulate, train, and evaluate DQN-based rate adaptation. The next steps will focus on making the model robust, interpretable, and hardware-ready.

Please feel free to reach out if you’re interested in reinforcement learning in networks or Wi-Fi resource control. Thank you for reading!

References

1. Pawar, S. P., Thapa, P. D., Jelonek, J., Le, M., Kappen, A., Hainke, N., Huehn, T., Schulz-Zander, J., Wissing, H., & Fietkau, F. 

Open-source Resource Control API for real IEEE 802.11 Networks. 

2. Queirós, R., Almeida, E. N., Fontes, H., Ruela, J., & Campos, R. (2021). 

Wi-Fi Rate Adaptation using a Simple Deep Reinforcement Learning Approach. IEEE Access. 

This is Victor and in this blog post I will update regarding my progress for GSOC2025 : Adding wifi support to QEMU wifi simulations in LibreMesh

A bit of back regarding wifi in the Linux Kernel

Modern Linux kernel wifi stack can be seen like that :

1. userspace tools
2. netlink
3. nl80211 driver
4. cfg80211 subsystem
5. mac80211 subsystem – basic hardware handling

In simple terms, it works like this :

• Userspace programs fires a command that interacts with wifi : programs such as `iw`, `hostapd`, `wpa_supplicant` etc.
• Command is passed to the kernel through _nl80211_ over the netlink protocol, in openwrt it is usually handled by [tiny-libnl](https://git.openwrt.org/?p=project/libnl-tiny.git)
• _cfg80211_ is here to bridge the userpace and the drivers so that with nl80211 they provide a consistent API, it’s also here that parts of the regulatory spectrum use is enforced depending on country specific legislation.
• _mac80211_ then provides a software implementation of wifi behaviors such as queuing, frame reordering, aggregation, mesh support etc.
• The driver (ath9k or *mac80211_hwsim*) then handles hardware specificities

Why is this important for our project

This layered approach is essential to our project, as it will enable us to create virtual tests beds that should be almost transparent to a real world experiment.

By just simulating the last brick – mac80211_hwsim – we’ll be able to recreate the whole wifi stack.
We will still see the same exact path consisting of :
userspace configuration -> nl80211 -> cfg80211 -> mac80211

Which means that without the need for expensive and complicated set up, we achieve the same possible tests for configuring the different interfaces, and in our case with the added reproducibility : setting up the infrastructure will only require a computer able to launch qemu-system, and if we decide to reproduce it with real hardware, we should observe an almost 1:1 reproducibility of the tests.

Virtualizing wifi : many tools, troubling setup

So we now that we have a clearer understanding on how wifi is handled in the Linux Kernel, and the existence of a tool to simulate wifi hardware, let’s see what is possible to do with it !

mac80211_hwsim in LibreMesh ?

Since LibreMesh is built on OpenWRT, our first task will be to bring mac80211_hwsim to OpenWRT.

Thankfully, this tool is known and already used by the OpenWRT community, and it is delightfully provided as a package that you can install in your system through opkg :
opkg install kmod-mac80211-hwsim
Which means, no need for custom kernel setup and compilation – and that’s good news.

Installation methods :

If your machine has an AMD/Intel CPU, simply go get the combined (squashfs) of the Generic x86/64 through the firmware selector.

unzip the image : gunzip openwrt-*-x86-64-generic-squashfs-combined.img.gz

You should then end up with something like that :

openwrt-24.10.2-x86-64-generic-squashfs-combined.img
Simply put, this is a kernel+root file system (that’s what combined means), using a compressed
read only filesytem (squashfs).

Now we need to instantiate our virtual machine, using qemu it can be done like this :

qemu-system-x86_64 -enable-kvm -smp 1 -m 512 -drive file=openwrt-24.10.2-x86-64-generic-squashfs-combined.img,if=virtio,format=raw -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22 -nographic

Just wait a bit for the boot to finish, you should see a Please press Enter to activate this console.

Inside the vm you’ll then have to run :
uci set network.lan.proto='dhcp'

uci commit network

service network restart

Inside the vm you’ll then have to run :
uci set network.lan.proto='dhcp' uci commit network service network restart

This convert the LAN to a DHCP client and allow the VM to grab the 10.0.2.x lease from QEMU,
Which will then enable you to run :
opkg update

and finally :
opkg install kmod-mac80211-hwsim

By default, mac80211_module is loaded with 2 radios, but the behavior can be changed with this command :
insmod mac80211_hwsim radios=X` with X the number of radios you want to have in your VM.

Let’s also not forget to include the right packages since we want to test wifi :
Since we’re not constrained by flash space on our laptop/computer, we’ll use wpad :
opkg install wpad

Congratulation, you now have an OpenWRT based virtual machine with a working virtual wifi ! Actually, not so fast…

One of the classical example when searching for the documentation regarding mac80211_hwsim module is the access point/station association using two different virtual radios (on the same host). 1 2
So let’s be original, and recreate this example (but in this case in OpenWRT !).

Virtual AP/Station association in a OpenWRT virtual machine :

When we install mac80211_hwsim/boot the VM, it should auto load the module with 2 radios.
You can check the presence of the 2 radios with this command :

iw phy | grep phy
Wiphy phy1
wiphy index: 1
Wiphy phy0
wiphy index: 0

As for the wifi devices, so far, nothing :
iw dev won’t return anything at this point.
We now need to configure these two (virtual) physical radios in order to have : an AP and a station.
Let’s check the default configuration of the wireless in our image :

root@OpenWrt:~# cat /etc/config/wireless

config wifi-device ‘radio0’
option type ‘mac80211’
option path ‘virtual/mac80211_hwsim/hwsim0’
option band ‘6g’
option channel ‘auto’
option htmode ‘EHT80’
option disabled ‘1’

config wifi-iface ‘default_radio0’
option device ‘radio0’
option network ‘lan’
option mode ‘ap’
option ssid ‘OpenWrt’
option encryption ‘none’

config wifi-device ‘radio1’
option type ‘mac80211’
option path ‘virtual/mac80211_hwsim/hwsim1’
option band ‘6g’
option channel ‘auto’
option htmode ‘EHT80’
option disabled ‘1’

config wifi-iface ‘default_radio1’
option device ‘radio1’
option network ‘lan’
option mode ‘ap’
option ssid ‘OpenWrt’
option encryption ‘none’

As we can see, both of our wifi-device are disabled, and also both in ap mode.
So the easy way out of this would be to do :
uci set wireless.radio0.disabled=0

uci set wireless.radio1.disabled=1

uci set wireless.radio1.mode=sta

uci commit

wifi reload

With all that we should be set ? No ?
Still nothing.
This was a real mystery for me, but after some digging, it appears that when using the 6g band, wpa3 is mandatory.
This is defined by the IEEE 802.11ax standard, and in our case the wifi 6E extension.
Since encryption testing isn’t on the scope of this project so far, let’s be conservative and try some true and tested wifi bands (2g) and see what happens.

In the end your /etc/config/wireless should look something like that :

config wifi-device ‘radio0’
option type ‘mac80211’
option phy ‘phy0’
option band ‘2g’
option channel ‘1’

config wifi-iface ‘default_radio0’
option device ‘radio0’
option network ‘lan’
option mode ‘ap’
option ssid ‘OpenWrt’
option encryption ‘none’

config wifi-device ‘radio1’
option type ‘mac80211’
option phy ‘phy1’
option band ‘2g’
option channel ‘1’

config wifi-iface ‘default_radio1’
option device ‘radio1’
option network ‘wann’
option mode ‘sta’
option ssid ‘OpenWrt’
option encryption ‘none’

With this configuration you still need to wifi reload or reboot if you don’t see any changes happening.
We finally have our prized AP/station association :

daemon.notice hostapd: phy0-ap0: interface state UNINITIALIZED->ENABLED
daemon.notice hostapd: phy0-ap0: AP-ENABLED
daemon.notice wpa_supplicant[1825]: phy1-sta0: SME: Trying to authenticate with 02:00:00:00:00:00 (SSID=’OpenWrt’ freq=2412 MHz)
daemon.info hostapd: phy0-ap0: STA 02:00:00:00:01:00 IEEE 802.11: authenticated
daemon.notice wpa_supplicant[1825]: phy1-sta0: Trying to associate with 02:00:00:00:00:00 (SSID=’OpenWrt’ freq=2412 MHz)
daemon.info hostapd: phy0-ap0: STA 02:00:00:00:01:00 IEEE 802.11: associated (aid 1)
daemon.notice hostapd: phy0-ap0: AP-STA-CONNECTED 02:00:00:00:01:00 auth_alg=open
daemon.info hostapd: phy0-ap0: STA 02:00:00:00:01:00 RADIUS: starting accounting session 2E622F6D18713536
daemon.notice wpa_supplicant[1825]: phy1-sta0: Associated with 02:00:00:00:00:00
daemon.notice wpa_supplicant[1825]: phy1-sta0: CTRL-EVENT-CONNECTED – Connection to 02:00:00:00:00:00 completed [id=1 id_str=]
daemon.notice wpa_supplicant[1825]: phy1-sta0: CTRL-EVENT-SUBNET-STATUS-UPDATE status=0

Let’s check what iw is reporting :

iw dev
phy#1
Interface phy1-sta0
ifindex 7
wdev 0x100000002
addr 02:00:00:00:01:00
type managed
channel 1 (2412 MHz), width: 20 MHz (no HT), center1: 2412 MHz
txpower 20.00 dBm
multicast TXQ:
qsz-byt qsz-pkt flows drops marks overlmt hashcol tx-bytes tx-packets
0 0 0 0 0 0 0 0 0
phy#0
Interface phy0-ap0
ifindex 8
wdev 0x2
addr 02:00:00:00:00:00
ssid OpenWrt
type AP
channel 1 (2412 MHz), width: 20 MHz (no HT), center1: 2412 MHz
txpower 20.00 dBm
multicast TXQ:
qsz-byt qsz-pkt flows drops marks overlmt hashcol tx-bytes tx-packets
0 0 11 0 0 0 0 1358 11
And finally :
iw dev phy0-ap0 station dump
Station 02:00:00:00:01:00 (on phy0-ap0)
inactive time: 4950 ms
rx bytes: 2077
rx packets: 50
tx bytes: 131
tx packets: 2
tx retries: 0
tx failed: 0
rx drop misc: 0
signal: -30 dBm
signal avg: -30 dBm
tx duration: 0 us
rx bitrate: 54.0 MBit/s
rx duration: 0 us
authorized: yes
authenticated: yes
associated: yes
preamble: short
WMM/WME: yes
MFP: no
TDLS peer: no
DTIM period: 2
beacon interval:100
short preamble: yes
short slot time:yes
connected time: 1232 seconds
associated at [boottime]: 59.854s
associated at: 1752513660712 ms
current time: 1752514892128 ms

All in all, lots of troubleshooting, qemu-system network was a bit novel for me and I spent a lot of time on it figuring it out why some things worked on others didn’t.
Also having mac80211_hwsim fully working in a OpenWRT qemu vm was definitely not easy at first : some documentation for the setting it up in a regular Linux environment, but didn’t find much regarding OpenWRT ?

Enabling mac80211_hwsim in LibreMesh

Now that we have a proof of concept of virtual wifi working in OpenWRT, let’s port it to LibreMesh.

Using the LibreMesh firmware selector :

Using LibreMesh firmware selector it is very easy to get an image with mac80211_hwsim enabled.

Simply add these two packages :

• ‘kmod-mac80211-hwsim wpad` to the firmware selector (getting opkg to work in a Libremesh vm is a bit tricky – doing like so is a lot easier)
• request a build

then you’ll be able to recreate the steps from the last section to have AP and mesh radios (You should be able to see the mesh interfaces connect to each other if put on the same channels)

On a custom build

Now that we mostly have figured out mac80211_hwsim with a generic image, let’s enable it in a custom LibreMesh build.

By following these instructions you should be able to get mostly there.

using make menuconfig, you will need to select these targets :

Target System : x86
Subtarget : x86_64

Then it will simply selecting the specific libremesh packages, and lastly :

Kernel modules -> Wireless Drivers -> kmod-mac80211-hwsim
Network -> WirelessAPD -> wpa

Save your config in .config, compile it make -j$(nproc) and then you’ll find your different images in bin/targets/x86/64.

Setting up mac80211_hwsim will require the same steps as the last two (setting the right band/channels/radio)

Conclusion of mac80211_hwsim in Libremesh

In the end mac80211_hwsim provides an excellent tool to test different wifi configuration, enabling it in a LibreMesh build is pretty straight forward, but as for OpenWRT stock image t requires a bit of manual work to set everything right.

My trials and errors for enabling mac80211_hwsim in Libremesh led me to discover some undefined behavior in LibreMesh when the firmware interacts with a wifi 6E able radios, which I will need to provide a patch for in order to continue my integration of qemu wifi testing to LibreMesh in the next half of my GSOC.

VM to VM communication using wifi

I’m proud to announce that I’ve finally managed to recreate the AP-STA scenario using two differents QEMU virtual machines ! OpenWRT <-> OpenWRT as well as LibreMesh <-> OpenWRT was possible. Once I’m able to fully control it and document it, I will provide a libremesh-profile with and easy setup.

This experiment relies on the vwifi project which comes in two part :

• vwifi-server which will run on the host and is here to provide a medium for our wifi : in its default config, it will broadcast the wifi frames of the client connected to it to the other clients.
• vwifi-client that will run on the guest : it basically relies on mac80211_hwsim to create real wifi frames, then relay them to the vwifi-server it is connected to. It also receives wifi frame from the others clients through the server, and manage to inject them in the VM wifi stack, so they get treated correctly and connection is possible.

Building the project is well documented in the README, and one advantages of this project is that it is OpenWRT compatible if we follow closely the instructions.

I struggled a lot a first, thinking I should cross compile it against my custom LibreMesh build, but it seems that as long as you get the right SDK you shouldn’t encounter any issues, aside from the usual qemu troubleshooting.It is also possible to build vwifi-client in order for it to work with vhost-vsock instead of TCP, but I so far didn’t manage to do that/didn’t test it right.

Caveats

run the vwifi-server like this :
vwifi-server -u this will prevent overlapping in the mac address when relaying to the other clients, and save you some time figuring out what’s really happening.

When copying the vwifi-client file to the guest, use these options :
scp -O -p <forwarded port> root@127.0.0.1 since otherwise it will try to rely on sftp, which might not be installed on the OpenWRT guest VM.

vwifi-client needs to connect to the host : use the IP from hostname -I.
Inside the VM you need to run something like that :
`vwifi-client -n –mac

If you don’t want to set it up as a service, remember that you need to remove the mac80211_hwsim module, then insert it again but with 0 radios :
insmod mac80211_hwsim radios=0

In LibreMesh, the current default wireless config is broken, a patch is coming very soon that will allow a seamless integration with the testing, but so far lime-config will put each radios advertised by mac80211_hwsim in the 6g band channel 48 : this won’t work, you need to manually change it to have (modify the /etc/config/wireless)

I still need to provide a full guide and scripts on how to recreate the experiment, but with this picture you should see what it is expected to have :

You can see on the top the LibreMesh VM acting as the access point, with on the left the serial interface running vwifi-client and on the right an ssh connection to this VM used to manage it.
At the bottom of the image it is the same setup but using a different VM, this time with a regular OpenWRT image, acting as the station. We can clearly see the station being connected to the AP from a the other VM.

Integration with LibreMesh testing ?

My initial tests and discoveries with virtualized wifi in a QEMU environment and the different tools that this kind of setup enables makes me more and more confident in the usefullness of adopting this approach for future development in LibreMesh and OpenWRT.
From this 6 weeks coding period that were mostly troubleshooting and figuring why things don’t work I’ve managed to find an undefined behavior in the way LibreMesh sets itself up on newer hardware without the need to acquire the said hardware, it also seems that it’s not even been discovered yet by an user : fixing bugs before they even show up.

Now for integrating this kind of qemu testing, the LibreMesh community have decided to use the openwrt-tests framework, a framework based on labgrid aimed at providing ways to write and run tests for OpenWRT devices, being real hardware or virtual one (in our case).

I’ve already made some preliminary work for enabling LibreMesh to integrate with this framework.
So far the framework provide satisfaction with my goals, the only real issues I’ve encountered were actually the divergence between OpenWRT and LibreMesh in some areas, meaning all the demos tests need some integration before being part of the testing pipeline.

Conclusion

I’ve mostly met my goal of having a working virtualized LibreMesh wifi mesh using a qemu infrastructure, I’m a bit behind regarding documentation as well as automation, but my plan is still well defined and I hope now mostly trouble free.

I now should be able in the coming weeks to :

• Provide ample documentation for future work in this area
• Leverage the new testing framework to provide reproducible and automated testing scenario, portable to real hardware
• Fully integrate the project with LibreMesh testing pipeline, with documentation for extension
• Port the current Docker based test to the new QEMU environment.

Bonus

I’ve had the pleasure to meet with the Freifunk/OpenWRT/LibreMesh community over the BattlemeshV17 organized in Sundhausen and I must say it was a very nice experience, learned a lot, flashed my first router with LibreMesh and more than everything felt very welcomed ! Thank you very much to the organizators and the participants, hope to see you again very soon.

This blog documents my ongoing progress with LibreMesh during Google Summer of Code (GSoC) 2025. Specifically, I’m focusing on integrating OpenWrt-native solutions and simplifying LibreMesh modules.

Currently, I am working on two main tasks:

1. Replacing deferrable-reboot with watchcat: Migrating LibreMesh’s custom reboot scheduling script to the built-in OpenWrt watchcat package for improved reliability.
2. Migrating DHCP functionality from dnsmasq to odhcpd: Transitioning DHCP and IPv6 handling to OpenWrt’s native odhcpd, currently in development and community testing.

For testing and validation, I’m using three physical routers configured to simulate realistic network conditions.

Task 1: Integrate OpenWrt’s watchcat via Hardware Detection

a. Motivation

The primary motivation for replacing LibreMesh’s deferrable-reboot script with OpenWrt’s watchcat is to leverage upstream-maintained tools, reduce redundancy, and enhance maintainability. watchcat provides robust functionality including scheduled reboots and network monitoring to automatically reboot routers in case of failure.

The design involves creating a hardware-detection (HWD) module within LibreMesh, enabling dynamic generation of watchcat configurations from user-defined UCI entries.

b. Implementation Details

The new package, lime-hwd-watchcat, is implemented in Lua, performing the following:

• Unique Section Identification: Creates unique configuration section names prefixed with hardware identifiers to avoid conflicts.
• Cleaning Up Configurations: Removes previously generated watchcat configurations.
• Dynamic Configuration Generation: Reads entries from LibreMesh’s UCI configuration (hwd_watchcat) and generates corresponding /etc/config/watchcat entries.
• Service Management: Automatically reloads watchcat after applying configuration changes using the /etc/init.d/watchcat reload command.

c. Testing & Validation

Testing involved:

• Configuring custom UCI settings under config hwd_watchcat.
• Validating automatic generation and updates to /etc/config/watchcat.
• Confirming the proper removal of old configurations.
• Checking watchcat service status and reload logs for expected behavior.

Default configuration:

Lets change it with the new package! Using:

uci add lime-node hwd_watchcat
uci set lime-node.@hwd_watchcat[-1].mode='ping_reboot'
uci set lime-node.@hwd_watchcat[-1].pinghosts='4.2.2.2'
uci set lime-node.@hwd_watchcat[-1].pingperiod='30s'
uci set lime-node.@hwd_watchcat[-1].period='6h'
uci set lime-node.@hwd_watchcat[-1].forcedelay='1m'
uci commit lime-node

And after using ‘lime-config’

d. Resources

You can see the code and the PRs for this package here:

Package (Github)

Pull Request approved

Task 2: Replace dnsmasq DHCP with odhcpd

a. Motivation

OpenWrt’s native odhcpd daemon already powers IPv6 RA/DHCPv6 and integrates tightly with ubus. The goal is to phase out dnsmasq’s DHCP functionality in favor of odhcpd, leveraging its superior IPv6 support, integration with OpenWrt, and streamlined lease handling.

The new shared-state-odhcpd_leases package watches local leases, serialises them as CRDT objects via shared-state-async, and injects remote leases back into odhcpd, giving every node the same “view” of the network.

b. Implementation Details

The new package is entirely based in Lua. Its components fall into three small groups:

1. UCI defaults script (90_odhcpd-lease-share) – executed once at install time.
   • registers a community-scoped CRDT called odhcpd-leases, telling shared-state to refresh every two minutes and to expire entries after twenty;
   • sets two critical odhcpd options:
     leasetrigger points to our publisher script, and maindhcp='1' turns odhcpd into the sole DHCP server;
   • creates a legacy-friendly symlink /etc/ethers → /tmp/ethers.mesh;
   • finally reloads odhcpd so the new trigger takes effect.
2. Publisher (shared-state-publish_odhcpd_leases) – called by odhcpd whenever a lease changes.
   It fetches the current lease table with ubus call dhcp ipv4leases, distils it to the minimum JSON mapping IP → {mac,hostname}, and pushes that into the CRDT bus with shared-state-async insert odhcpd-leases.
3. Generator (shared-state-generate_odhcpd_leases) – executed on every CRDT update that the node receives.
   It writes the merged dataset to /tmp/ethers.mesh, moves the file atomically, and reloads odhcpd so the daemon immediately serves and announces the foreign leases as if they were local.

Unit tests live in tests/test_publish_odhcpd_leases.lua; they stub ubus, io.popen and os.execute to validate. The tests run in CI, so regressions in JSON shape or error handling are caught before merging.

c. Testing & Validation

The following testing methods are in progress:

• Unit tests verify robustness of JSON serialization and shared-state publishing logic, covering normal, empty, and malformed market cases.
• Deployment tests across three routers:
  • Confirm odhcpd takes over DHCP (uci show dhcp shows maindhcp=1).
  • Check presence and updates of /tmp/ethers.mesh and /etc/ethers symlink.
  • Simulate lease assignment and verify real-time propagation between nodes.
• Service behavior:
  • Observe leasetrigger invocation on odhcpd-update.
  • Ensure stable operation over lease churn and node restarts.

So, for show how this works, I’ve two routers running LibreMesh, node-1 and node-2.

I connect a device in node-1, then I confirm it with ubus call dhcp ipv4leases '{}'

Then the publisher fires and odhcpd runs the shared-state-publish_odhcpd_leases script, which inserts the JSON blob into the CRDT bus.

Seconds later, on node-2 I dump the CRDT and see the same lease authored by node-1:

This is a minimal example, feel free to test anything you want!

d. Resources

Pull Request of the package,.
Task 2 remains actively in development. Upcoming efforts will involve extensive community testing and careful analysis of how removing dnsmasq‘s DHCP functionality impacts related features and dependencies.

Reflection

The first half of the project required me to dive deeper into LibreMesh’s internals than initially expected, giving me a profound appreciation for this powerful mesh networking tool.

The most valuable lesson was recognizing that removing code (such as the deferrable-reboot script or dnsmasq’s DHCP logic) can be just as rewarding as adding new features. Simplifying the stack enhances its predictability and maintainability, ultimately benefiting the entire LibreMesh community.

Conclussion

After these two initial tasks, LibreMesh now:

• Reboots through watchcat, an OpenWrt-native tool with LuCI support,
• Serves and synchronizes DHCP leases via odhcpd and a lightweight CRDT-based sharing mechanism,
• Incorporates automated tests to ensure reliability and stability through continuous integration (CI).

Looking ahead, I will begin Task 3, removing VLANs from Babel interface, and start prototyping the layer-2-only variant of LibreMesh. I’ll continue employing the methodology proven successful so far: iterative development, backward compatibility, and comprehensive instrumentation.

If future milestones proceed as smoothly, the project will conclude with a cleaner codebase, easier network management, and clearer upgrade paths for community networks.

Current Progress

Since the kickoff of GSoC 2025 in June, the project has made strong progress. Although I began with limited experience in web development and Static Site Generation (SSG), I’ve been able to complete about 50% of our initial milestones while steadily climbing the learning curve. By following Astro’s blog tutorial, I successfully built the foundational site. In addition, I completed the first version of the SQLite3 extraction tool and developed a “TWEETS” page to display the tweet data. While the tweets are currently hidden, they will be visible on the final version of the site. Please view my screenshots instead:

View a preview the current website here:
https://sandraastro.netlify.app/tweets/

GitHub:
https://github.com/freifunk/social-media-archive

Milestone Completion Overview

• Select the Static Site Generator – Finalize the choice of SSG—currently, Astro is the preferred option.
• SSG Setup – Set up the SSG and ensure all related technologies are working. Begin early discussions around prototypes to determine which data fields need to be extracted from the database.
• Develop Data Extraction Tool – Build a script to extract relevant fields from the archived SQLite3 database and normalize them into a unified schema.
• Create Static Site Mockup – Generate an initial static website using the parsed and structured data. 
• Implement Client-Side Search – Define minimal site features. Add client-side search functionality by preprocessing and indexing data during the build process.
• Test, Optimize, and Ensure Scalability – Conduct thorough testing and optimization. Ensure the site remains stable and the search remains accurate, even when additional archives are added.
• Design and Implement Theming Support – Build an engaging, Freifunk-inspired frontend and implement support for customizable themes via configuration files.
• Documentation and Deployment – Write comprehensive documentation and deploy the final static site.

Reflections

Astro, the web framework we’re using to build the website, has excellent documentation. Following their initial blog tutorial was instrumental in helping me grasp the fundamentals and gain momentum early in the project. It energized me and reinforced the importance of good documentation. If a project is hard to understand or use due to poor documentation, its impact decreases. Therefore, I am committed to providing clear documentation for my contributions to the Social Media Archive.

June presented challenges, particularly when trying to balance other commitments. There were times when staying on top of tasks proved difficult. I’m glad to have refocused and gotten back on track. I’ve learned that meaningful progress tends to come from small, consistent steps, and I plan to maintain that approach moving forward. Now that I’ve started using GitHub Issues, I believe I’ll be able to scope tasks more clearly and work more effectively.

Highlights & Wins

I’ve enjoyed learning new tools, such as SQLite3, Astro, and Netlify, in the context of web development. It’s also been fun switching between different languages such as Python, TypeScript, JavaScript, Markdown, CSS, and HTML. While I’m not yet an expert in most of these, this experience has given me considerable confidence in my ability to learn and apply new tools effectively within a formal codebase.

Conclusion

I’m excited for what’s to come in July. Now that some of the core technical components are in place, I’m looking forward to beginning prototype of what the final site could look like. This task will be a key step in personalizing the site for Freifunk and tailoring it to their specific needs. Thanks again to Andi for his continued support. 

Introduction

Hi, it’s been great to meet you all this summer.

I’m Sandra Taskovic, an Honors Computing Science student at the University of Alberta in Canada. This summer, I’m excited to participate in a 90-hour Google Summer of Code project, where I will develop a Social Media Archive Explorer for the Freifunk community.

Project Need

Freifunk has accumulated valuable content across its past social media accounts. This project aims to harness that existing data and re-display it in a new, user-friendly static site. This Social Media Archive Explorer will give the Freifunk community greater independence and long-term control over its outreach history while staying aligned with its commitment to open-source tools.

The archive also aims to engage the community in celebrating its achievements. I’ll design a Freifunk-inspired frontend to ensure the experience is functional and reflective of the community’s spirit, further supporting its ongoing growth and outreach.

Technologies

• Programming Languages: TypeScript / JavaScript
• Static Site Generator (SSG): Astro
• Data Source: Archived SQLite3 database of past X (formerly Twitter) posts
• Data Extraction: Custom script developed to parse and extract relevant content for the site
• Frontend: Additional UI libraries and design packages will be used to create a Freifunk-inspired theme and aesthetic

Plan of Action

1. Select the Static Site Generator – Finalize the choice of SSG—currently, Astro is the preferred option.
2. SSG Setup – Set up the SSG and ensure all related technologies are working. Begin early discussions around prototypes to determine which data fields need to be extracted from the database.
3. Develop Data Extraction Tool – Build a script to extract relevant fields from the archived SQLite3 database and normalize them into a unified schema.
4. Create Static Site Mockup – Generate an initial static website using the parsed and structured data.
5. Implement Client-Side Search – Add client-side search functionality by preprocessing and indexing data during the build process.
6. Test, Optimize, and Ensure Scalability – Conduct thorough testing and optimization. Ensure the site remains stable and the search remains accurate, even when additional archives are added.
7. Design and Implement Theming Support – Build an engaging, Freifunk-inspired frontend and implement support for customizable themes via configuration files.
8. Documentation and Deployment – Write comprehensive documentation and deploy the final static site.

Conclusion

I’m genuinely excited to bring this project to life during GSoC 2025. I look forward to sharing my progress and learnings throughout the summer. A heartfelt thank you to Andreas Bräu, who will be mentoring me on this journey—I’m grateful for the support and guidance ahead.

Introduction

Hi everyone!
I’m Mohit Kumar from Gurgaon, India. I pursued my bachelors in Electronics and Communication Engineering from Indian Institute of Information Technology, Nagpur. I’m very interested in the future of freedom tech which aligns very well with qaul and freifunk projects. Interestingly, I also had a course on Wireless Communication, and that got me hooked on the projects related to freifunk community as well.

In past I’ve contributed to a few open source projects, such as coinswap, eclair-cli, health claims exchange, etc.

About project

qaul is an internet independent wireless mesh communication app. qaul enables you to communicate P2P with people around you without any internet or communication infrastructure, using your local wifi network or via the shared wifi network of your phone. My project focuses on implementing the user authentication layer between libqual and UI, and end to end encryption.

Key features

• Developing the authentication system.
• Introduce session management.
• Implementing End to End Encryption.

In this initial phase, I’m learning more about qaul codebase and discussing design choices for the authentication system with my mentor.

Who would gain from this project?

This would bring several benefits to community networks and various stakeholders.
Users:

• With improved scalability, the network grows organically without compromising the security or the performance.
• Communication between node(libqaul) and UI would be secure and authenticated.
• Users would have the possibility of using several identities on the same node. 
• A node could be a shared communication resource for all users not having the app installed but communicating via a web-interface, being connected to a central node.

Developers and Contributors: The project lays the foundation for a web interface. The authentication system and session management systems create a more extensible architecture, allowing developers to build additional features and functionalities.

Looking Ahead

I’m excited to collaborate with the qaul team and the wideeer freifunk community. Through this project, I hope to grow as a developer, contribute meaningful code, and support decentralized communication efforts.

I’m very grateful to Mathjud for his mentorship, which made my initial hurdles(of exploring new project) a bit smooth. And a huge thanks to the Andibraeu, and the whole community.

Introduction

Hello everyone!
I’m Agustin Trachta, a Computer Engeneering student at National University of Cordoba (Argentina), and I’m thrilled to be participating in Google Summer of Code 2025 with Freifunk, working on LibreMesh!

This summer, I’ll be focusing on simplifying and modernizing LibreMesh by:

• Migrating legacy components to OpenWrt-native solutions, such as replacing custom scripts like deferrable-reboot with watchcat, and moving DHCP handling from dnsmasq to odhcpd.
• Removing unnecessary complexity, like VLANs on Babel interfaces, which have caused compatibility and MTU issues.
• Creating a layer-2-only variant of LibreMesh tailored for lightweight community deployments, based on BATMAN-adv.

My goal is to help make LibreMesh leaner and more accessible to new users, especially communities that rely on low-resource hardware and need plug-and-play reliability. Many of these networks operate in rural or underserved areas where internet access is limited, budgets are tight, and technical expertise is scarce. In such environments, every kilobyte of firmware matters.

By replacing legacy components with OpenWrt-native solutions, we reduce the need for LibreMesh to maintain parallel tools, making the codebase easier to understand and integrate with upstream developments. Additionally, offering a layer-2-only firmware variant allows communities to deploy simpler, lightweight networks that require minimal configuration, consume fewer resources, and are easier to debug.

What I’ll Be Working On

The first task involves replacing LibreMesh’s custom deferrable-reboot script with watchcat, a integrated OpenWrt package. The original script was created to schdeule periodic reboots in order to recover from possible instability after long uptimes, great idea but it’s already implemented in a more robust way, allowing also to trigger network interface restart based on ping failures. Migrating to watchcat ensures better integration with OpenWrt’s LuCI interface.

The second task focuses on improving DHCP handling by transitioning from dnsmasq to odhcpd. While dnsmasq is widely used and remains excelent for DNS forwarding, it’s not ideal for handling modern DHCPv6 configurations and dynamic lease sharing. This migration has been requested for years by the community, and I will work hard on making this a reality!

The third task is about removing VLAN from Babel routing interfaces. LibreMesh always used VLANs to isolate Layer 3 traffic from BATMAN-adv’s Layer 2 mesh, but it introduced issues like lower MTUs, hardware incompatibilities and added configuration burden. My work will include applying and testing relevant patches that have already been worked on, updating configurations and validating that removing VLANs does not introduce routing lops or instability.

Finally, I’ll be developing a Layer-2-only version of LibreMesh, this is other request from the community members who want a simpler and lighter firmware that doesn’t include routing extra daemons. In small mesh networks, users only need a transparent Layer 2 bridge using BATMAN-adv and gateway node doing NAT, my goal is to create a dedicated firmware profile that includes only the essential packages for a Layer-2 mesh and removes unnecessary services. This variant will help networks that value simplicity, speed, and minimal configuration, especially on older routers with tight resource constraints.

Plan of action

To ensure that each change is reliable, compatible, and valuable to the LibreMesh community, I’ll follow a staged and test-driven approach throughout the project.

I’ll begin by setting up a virtualized test environment to quickly prototype and iterate on changes. In parallel, I’ll be using at least three physical routers compatible with LibreMesh to validate the behavior of the firmware under real-world conditions.

Each task will follow a similar cycle:

1. Development and Integration of the change in the LibreMesh build system.
2. Configuration and Testing, both in isolated and multi-node environments.
3. Documentation and Feedback, where I’ll share results with the community, post updates, and adapt based on what users report.

I’ll be actively engaging with the LibreMesh mailing list, GitHub issues, and chat channels to keep the process transparent and collaborative.

Conclusion

I’m very excited to be working on this project as part of the GSoC 2025. I’m looking forward to collaborating, learning, testing, and sharing throughout the summer!

Also I would like to thank my mentor, Javier Jorge, who will be guiding and teaching me a lot about open source projects and local networks.

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_hwsim module 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

Introduction

Hi everyone! I’m Raul Shahi, a Master’s student in Computer Engineering for IoT Systems at Nordhausen University of Applied Sciences, Germany. I’ve been working as a Research Assistant at my university, where I’ve been developing and experimenting with tools for Wi-Fi resource control.

I was also a part of GSoC 2024, where I worked on Throughput-based Dynamic WiFi Power Control for Real Networks. Please feel free to check this blog for the project.

For GSoC 2025, I will work on building a Deep Q-Learning (DQN)-based Wi-Fi Rate Adaptation algorithm for IEEE 802.11ac networks. This project leverages machine learning techniques to address the limitations of traditional rate adaptation algorithms in dynamic wireless environments. In this blog post, I’ll walk you through the motivation, approach, and expected outcomes of the project.

Motivation

Rate Adaptation(RA) in Wi-Fi networks refers to the selection of the optimal Modulation and Coding Scheme (MCS) to maximize data throughput in the presence of varying channel conditions. As wireless links experience fluctuations due to interference, mobility, and environmental factors, a robust RA mechanism is crucial for achieving high performance. RA is a MAC-layer task that must respond rapidly and intelligently to the dynamic nature of wireless channels. The complexity of this task continues to grow with the expansion of the MCS index space, advancements in Wi-Fi standards, and increasingly heterogeneous network topologies.

Several RA algorithms have been developed to address this challenge, with Minstrel-HT being the default RA algorithm in the Linux kernel. While Minstrel-HT performs well in relatively stable conditions, its responsiveness and decision quality tend to degrade in rapidly changing environments, often resulting in sub-optimal throughput and increased latency. Study such as MAC-Layer Rate Control for 802.11 Networks: A Survery [2] provides comprehensive overviews of these limitations.

Recent research has explored the application of Deep Reinforcement Learning (DRL) to Rate Adaptation (RA), showing potential performance improvements over traditional heuristic-based methods by learning RA policies directly from network statistics such as Signal-to-Noise Ratio (SNR), throughput, or ACK failures [3, 4]. However, most of these SOTA approaches are evaluated solely in simulated environments (e.g., ns-3 or MATLAB), lack validation on commercial off-the-shelf (COTS) hardware, and often consider outdated standards like IEEE 802.11n. Additionally, they usually operate on a reduced set of MCS indices or simplified network models, which limits their applicability to modern Wi-Fi deployments with complex topologies and diverse traffic patterns.

Moreover, implementing DRL in practical systems presents inherent challenges: DRL agents typically require substantial computational resources and time for training, making real-time learning and deployment on embedded devices difficult. These issues hinder the direct transfer of DRL-based RA algorithms from simulation to real-world applications.

This project aims to bridge this gap by leveraging the ORCA API and RateMan framework to deploy and evaluate a DRL-based RA solution on real IEEE 802.11ac hardware, with minimal overhead and full observability into transmission statistics.

To overcome the lack of practical platforms for evaluating advanced RA algorithms, this project builds upon ORCA[1], a kernel-user space API that exposes low-level transmission statistics and allows runtime control over Wi-Fi parameters such as MCS, bandwidth, and spatial streams.

On top of ORCA, we utilize RateMan[1], a Python-based interface that simplifies per-STA rate adaptation and integrates cleanly with real-time experimental setups across multiple access points (APs). This setup offers a testbed that is both flexible and extensible, making it well-suited for developing and evaluating DRL-based RA algorithms.

Fig 1. Overview of the architecture of the user-space resource control using RateMan via ORCA[1]

This setup abstracts away kernel-level complexities, allowing developers to focus on high-level algorithm design for rate adaptation. By integrating Deep Reinforcement Learning (DRL) into this user-space framework, we can overcome the limitations of prior work, such as reliance on simulation tools, limited rate sets, or outdated standards and evaluate learning-based approaches directly on commercial off-the-shelf (COTS) Wi-Fi hardware. This bridges the gap between theoretical advancements and practical deployment, enabling reproducible and scalable experimentation in real environments.

Methodology

A Deep Q-Network (DQN) is a reinforcement learning (RL) algorithm that uses deep learning to estimate the Q-function, which represents the cumulative reward of taking an action in a given state.

Fig 2. Illustration of state, action, and reward sequence in the interactions between the agent and environment within the reinforcement learning algorithm [5]

We’ll use the ORCA API and Rateman as our experimental framework. Here’s a high-level overview of our approach:

• DQN Agent Design: The agent observes channel statistics (e.g. throughput, retries, SNR) and learns to select optimal data rates.

• Environment Feedback: The environment will be represented through Rateman, which interfaces with ORCA to provide real-time feedback in the form of Transmit Status (txs) events from OpenWrt-based nodes. These txs events encapsulate per-frame transmission statistics such as retry count, transmission rate (MCS), and success/failure outcomes. This detailed low-level feedback serves as the observable state for our learning agent, enabling fine-grained adaptation and evaluation of RA policies on real hardware.

• Reward Function: We’ll design a reward function based on achieved throughput and transmission efficiency.

Learning: The agent updates its decision policy based on the rewards received, continuously improving its ability to choose optimal actions.

Training Strategy: We’ll apply experience replay, epsion-greedy exploration, and target network updates to stabilize training.

Evaluation: Compare performance against baseline algorithms like MInstrel-HT in both stable and mobile scenarios.

Setup

For the experimentation and evaluation of the DQN-based rate adaptation algorithm, I have access to two primary test environments:

• Local OpenWrt Setup

A pair of OpenWrt-based nodes is configured, one as an Access Point (AP) and the other as a Station(STA). This setup allows for short-range, controlled experiments where the data transmission between the AP and STA can be directly observed and influenced in real-time. The system logs transmission statistics such as throughput, retry rates, and modulation rates, which are essential inputs for the learning algorithm.

The basic setup is ideal for testing initial versions of the DQN agent, debugging learning behavior, and validating the integration with the Rateman interface.

Fig 3. Local Desk Setup

• Remote Shielding Box Environment

Additionally, a remote RF shielding box setup is available, which offers an advanced testing environment. The shielding box can emulate various wireless channel conditions by introducing configurable attenuation, effectively emulating mobility, interference, or range variations. This is particularly valuable for testing how well the DQN agent adapts to dynamic network environments.

Together, these setups provide a well-rounded experimentation environment. The local OpenWrt pair allows for fast prototyping, while the shielding box supports in-depth analysis under variable channel conditions. This ensures the project has ample experimental infrastructure to develop, test, and fine-tune the proposed Learning-based rate adaptation (RA)l algorithm.

Deliverables of The Project

The main outcomes of this GSoC project are : 

1. A modular, well-documented DQN-based Wi-Fi RA agent integrated into Rateman.
2. A training and evaluation pipeline for testing the algorithm on real hardware using ORCA.
3. Performance analysis comparing our method with standard algorithms in dynamic and static environments.
4. A comprehensive technical report and user guide to help others replicate or extend this work.

What has been done until now?

So far, the initial groundwork for the project has been laid out, with the following accomplishments:

• Explored the fundamentals of Deep Q-Learning (DQN) by implementing and experimenting with standard reinforcement learning environments such as FrozenLake and CartPole. These helped build an intuitive understanding of how Q-learning and neural networks interact in dynamic decision-making problems.
• Familiarized with the ORCA API and RateMan interface 
• Successfully set up the experimental testbed with a pair of OpenWrt nodes configured in AP-STA mode. This local setup has been validated for basic connectivity and is ready for integration and testing of learning-based algorithms.
• Studied the performance and limitations of existing ML-based rate adaptation (RA) papers to refine scope.

While the concrete architecture for integrating the DQN agent with real-world transmission feedback is still under development, the foundational components are in place. The next phase will focus on defining a robust training pipeline using txs statistics and determining how to feed real-time feedback into the learning loop.

What’s Next?

• Implement the DQN agent and environment class using PyTorch.
• Integrate the agent with Rateman to observe real-time transmission feedback.
• Begin training and hyperparameter tuning on experimental data.
• Evaluate performance and iterate over model improvements.

Conclusion

I’m incredibly excited to begin this project as part of GSoC 2025! By merging Reinforcement Learning with real-world Wi-Fi experimentation, this project aims to push the boundaries of rate adaptation in wireless networks. I hope this work contributes to more intelligent, efficient, and adaptable wireless systems, and I am looking forward to sharing updates as we move forward. 

Feel free to reach out if you’re interested in the project or have any questions.

References

1. Pawar, S. P., Thapa, P. D., Jelonek, J., Le, M., Kappen, A., Hainke, N., Huehn, T., Schulz-Zander, J., Wissing, H., & Fietkau, F. 

Open-source Resource Control API for real IEEE 802.11 Networks. 

2. Yin, W., Hu, P., Indulska, J., & Portmann, M. (2020). 

MAC-layer rate control for 802.11 networks: A survey. Wireless Networks

3. Queirós, R., Almeida, E. N., Fontes, H., Ruela, J., & Campos, R. (2021). 

Wi-Fi Rate Adaptation using a Simple Deep Reinforcement Learning Approach. IEEE Access. 

4. Karmakar, R., Chattopadhyay, S., & Chakraborty, S. (2022). 

SmartLA: Reinforcement Learning-based Link Adaptation for High Throughput Wireless Access Networks. Computer Networks. 

5. State-Action-Reward Diagram