Fab OpenVLC is an experimental research framework for monitoring, controlling, and evaluating handovers between Visible Light Communication (VLC) and Wi-Fi links. It combines OpenVLC, BeagleBone Black devices, traffic generation, channel measurements, and a Fabric-based Intelligent Management System in a reproducible hybrid-network testbed.
Demo · Installation · Run an experiment · Contribute · Roadmap · Cite
Hybrid VLC/Wi-Fi systems combine complementary communication technologies:
- VLC offers high spatial reuse, directional communication, and operation in environments where radio-frequency interference is undesirable.
- Wi-Fi provides wider coverage, mobility support, and a robust fallback when the optical link is blocked or degraded.
The central research challenge is deciding when and how to switch between these links without unnecessarily interrupting application traffic. Fab OpenVLC provides an Intelligent Management System (IMS) that collects link information, controls the transmitter and receiver, and coordinates handover experiments from a central terminal.
The repository is intended for researchers, students, and engineers working on:
- visible-light communication and LiFi;
- hybrid optical/radio networks;
- mobility and handover management;
- experimental networking and testbed automation;
- channel-quality monitoring;
- reproducible wireless-system evaluation.
Evaluating hybrid VLC/Wi-Fi networks normally requires researchers to integrate several independent components: optical hardware, wireless adapters, Linux networking, traffic generators, measurement tools, remote-control scripts, and handover logic. Rebuilding that environment from scratch is time-consuming and can make results difficult to reproduce across laboratories.
Fab OpenVLC reduces that burden by providing:
- a documented hybrid VLC/Wi-Fi topology;
- centralized testbed control through Fabric tasks;
- transmitter and receiver configurations for BeagleBone Black devices;
- procedures for creating VLC and Wi-Fi links;
- traffic generation with
iperf; - manual and controller-driven link switching;
- RSSI and channel-information collection;
- plotting utilities for experimental measurements;
- contribution and citation infrastructure for continued research use.
| Capability | Description |
|---|---|
| Centralized management | Operate the hybrid testbed from the ControlUnit host. |
| Link setup | Configure VLC and Wi-Fi transmitter/receiver roles remotely. |
| Handover control | Run the IMS controller or force traffic onto a selected link. |
| Traffic generation | Generate repeatable UDP traffic using iperf. |
| Channel monitoring | Retrieve Wi-Fi and VLC-related measurements for decision-making. |
| RSSI capture | Export raw measurement samples for subsequent analysis. |
| Experiment visualization | Use the scripts under PlotGraph/ to visualize collected data. |
| Reproducibility support | Record configurations, measurements, code revisions, and experiment conditions. |
The testbed contains three logical control points:
| Component | Role |
|---|---|
| Control Unit | Runs Fabric tasks, collects measurements, and executes the IMS handover logic. |
| BBB-Tx | BeagleBone Black transmitter providing the VLC transmitter and Wi-Fi access-point functions. |
| BBB-Rx | BeagleBone Black receiver providing the VLC receiver and Wi-Fi station functions. |
Traffic can be carried over either the VLC link or the Wi-Fi link. Virtual interfaces are used to simplify routing and allow the two physical links to be treated as independent network paths.
Fab_OpenVLC/
├── ControlUnit/ # Fabric controller, IMS logic, and control configuration
├── BBB_Tx_Full_Repo/ # Transmitter-side software and dependencies
├── BBB_Rx_Full_Repo/ # Receiver-side software and dependencies
├── PlotGraph/ # Measurement visualization scripts
├── prudebug-bbb/ # PRU debugging and sample-capture utilities
├── images/ # Repository images and author assets
├── CONTRIBUTING.md # Contribution workflow and reproducibility guidance
├── ROADMAP.md # Planned engineering and research improvements
├── CITATION.cff # Machine-readable software citation metadata
└── README.md
The transmitter and receiver directories include complete experimental working environments and third-party components. Review the relevant license files before reuse or redistribution.
- two BeagleBone Black devices, used as BBB-Tx and BBB-Rx;
- an OpenVLC-compatible transmitter and receiver setup;
- Wi-Fi adapters for the hybrid radio link;
- a Linux computer used as the Control Unit;
- Ethernet or another management network providing SSH access to both BeagleBone devices.
The original testbed was developed using the TP-Link TL-WN722N v2. Other adapters may work, but driver, monitor-mode, and hostapd compatibility must be verified independently.
The TL-WN722N v3 was reported to present integration difficulties in the original setup. Record the exact adapter model and hardware revision when reporting results or issues.
- Linux on the Control Unit and BeagleBone Black devices;
- OpenVLC, following the upstream OpenVLC repository;
- Python and a Fabric release compatible with
ControlUnit/fabfile.py; - SSH access from the Control Unit to both BeagleBone devices;
iperffor UDP traffic generation;hostapdfor the Wi-Fi access point;- DKMS and build tools when an external Wi-Fi driver is required;
- Python plotting dependencies required by the scripts under
PlotGraph/.
The repository uses the classic
fab <host> <task>command style. Verify the Fabric version and Python environment before running controller tasks.
git clone https://github.com/kotobuki09/Fab_OpenVLC.git
cd Fab_OpenVLCInstall and validate the VLC channel on both BeagleBone devices using the instructions in the upstream OpenVLC repository.
Before integrating the IMS, confirm that:
- the transmitter can send data over the VLC link;
- the receiver can receive that data;
- both devices are reachable from the Control Unit over SSH;
- the OpenVLC paths used by the controller match the paths on each device.
Use a driver supported by your adapter and Linux kernel. The original testbed used an 8188eu-based workflow for the TL-WN722N v2.
Legacy TL-WN722N v2 driver workflow used by the original testbed
sudo apt-get update
sudo apt-get install -y git dkms make build-essential
cd /usr/src
sudo git clone https://github.com/abhijeet2096/TL-WN722N-V2
sudo dkms add ./TL-WN722N-V2
sudo dkms build -m 8188eu -v 1.2
sudo dkms install -m 8188eu -v 1.2
sudo modprobe 8188eu
sudo rebootThis procedure is retained for reproducibility of the original environment. Kernel and driver compatibility may differ on current systems. Validate the upstream driver source before installation.
Open ControlUnit/fabfile.py and adapt the environment to your testbed. At minimum, verify:
- BBB-Tx and BBB-Rx IP addresses;
- SSH usernames, authentication, and ports;
- local and remote working directories;
- interface names;
- VLC and Wi-Fi configuration paths;
- traffic-generation addresses and ports;
- any threshold or timing values used by the IMS.
Avoid committing passwords, private keys, or institution-specific credentials to the repository.
Copy the testbed hostapd.conf configuration from the Control Unit resources to BBB-Tx:
sudo cp hostapd.conf /etc/hostapd/hostapd.confReview the interface name, SSID, channel, country code, and security settings before starting the access point.
Transfer the relevant transmitter-side resources to BBB-Tx and receiver-side resources to BBB-Rx. If the destination directories differ from the original testbed, update the paths in ControlUnit/fabfile.py accordingly.
Run the following commands from the ControlUnit/ directory unless stated otherwise.
cd ControlUnitConfigure the Wi-Fi access point and VLC transmitter:
fab vlc1 setup_wifi_ap
fab vlc1 setup_vlc_txConfigure the Wi-Fi station and VLC receiver:
fab vlc2 setup_wifi_sta
fab vlc2 setup_vlc_rxThe following commands reproduce the virtual-interface configuration used by the original testbed.
sudo ip link add eth10 type dummy
sudo ifconfig eth10 hw ether 00:22:22:ff:ff:ff
sudo ip addr add 192.168.10.1/24 brd + dev eth10 label eth10:0sudo ip link add eth10 type dummy
sudo ifconfig eth10 hw ether 00:22:22:ff:ff:f0
sudo ip addr add 192.168.10.2/24 brd + dev eth10 label eth10:0These addresses are testbed defaults. Change them if they conflict with your network. Some modern distributions do not install ifconfig by default; use an equivalent ip link command or install the required networking tools.
Start the server on BBB-Rx:
iperf -u -l 800 -s -i 3 -B 192.168.10.2 -p 10001Start the client on BBB-Tx:
iperf -c 192.168.10.2 -u -b 1000M -l 800 -p 10001 -t 100000The values above reproduce the original experimental command. Select a realistic offered load for your link capacity and document every traffic parameter used in published results.
fab icontrol_demoThe controller gathers channel information and applies the configured handover logic. Confirm that both nodes are reachable and that the expected measurement commands work before starting a long experiment.
Use the following commands to force traffic onto a specific link during testing.
fab vlc1 wifi_linkfab vlc1 vlc_linkManual selection is useful for validating routing, establishing baseline performance, and comparing forced-link results with controller-driven handovers.
fab vlc2 wchannelStart an iperf server for the configured measurement path:
iperf -u -s -B 10.0.0.16 -p 10002Then collect the corresponding information from the controller:
fab vlc1 iwifiUpdate the bind address and port to match your environment.
On the relevant BeagleBone device:
sudo ./prubgb > filename.rawStore the following metadata with each capture:
- date and time;
- repository commit hash;
- transmitter/receiver geometry;
- optical and radio configuration;
- hardware and driver revisions;
- traffic parameters;
- sampling duration;
- units and preprocessing steps.
Use the utilities under PlotGraph/ to inspect and visualize the recorded samples.
For every experiment, report at least:
- the exact Fab OpenVLC commit or release;
- BeagleBone Black revisions and operating-system images;
- Linux kernel, OpenVLC, driver, Fabric,
hostapd, andiperfversions; - Wi-Fi adapter model and hardware revision;
- room geometry, transmitter-receiver distance, orientation, and lighting conditions;
- IP addresses, interfaces, routes, and traffic parameters;
- handover thresholds and decision intervals;
- number of trials and trial duration;
- definitions of handover latency, interruption time, packet loss, throughput, and jitter;
- raw data, processing scripts, and figure-generation commands.
Do not delete broad system-log directories as part of an experiment. Keep project logs in a dedicated directory and clean only that location, for example:
find ./experiment-logs -type f -mtime +2 -deleteFab OpenVLC is a research prototype, not a production networking product. It is hardware-dependent and may require adaptation for current kernels, drivers, network interfaces, and OpenVLC versions.
Public adoption is represented by the live GitHub badges at the top of this page, together with forks, issues, pull requests, citations, and independently reproduced experiments. Package-registry monthly download statistics are not applicable because this project is not distributed through npm, PyPI, Maven, or a comparable package registry.
Current improvement priorities are documented in ROADMAP.md. Beginner and research contribution opportunities are available in the issue tracker.
- The current setup is closely tied to a specific experimental hardware configuration.
- Paths, addresses, interfaces, and credentials must be reviewed before execution.
- External Wi-Fi drivers may not support every current Linux kernel.
- Hardware-dependent behavior cannot be fully validated through conventional cloud CI.
- The repository contains complete working environments and third-party components, which increases its size and licensing complexity.
- A fully automated clean installation and standardized compatibility matrix remain future work.
This repository supports the following research artifacts:
GitHub can generate a citation from CITATION.cff. When using this repository in academic work:
- cite the software repository;
- cite the relevant publication or dataset above;
- record the exact commit or release used;
- describe any modifications made to the controller, hardware, or experiment configuration.
Contributions are welcome in the following areas:
- installation and compatibility documentation;
- setup automation;
- hardware support;
- measurement and plotting tools;
- handover algorithms;
- experiment reproducibility;
- tests, validation scripts, and safer configuration management.
Read CONTRIBUTING.md before opening a pull request. For planned work, see ROADMAP.md. Use the structured issue forms for bug reports and research or feature proposals.
When reporting a problem, include:
- the failing command and complete error output;
- operating-system and kernel versions;
- hardware and Wi-Fi adapter revisions;
- OpenVLC, Fabric, driver,
hostapd, andiperfversions; - relevant changes made to
fabfile.py; - a minimal sequence that reproduces the issue;
- logs with credentials and private network information removed.
Open an issue through the GitHub issue tracker.
This work acknowledges support and collaboration from:
- University of Palermo
- IMDEA Networks Institute
- Toshiba Research Europe Ltd
- the OpenVLC community and upstream open-source projects included in the experimental environment.
Ngô Trung Kiên
Hanoi School of Business and Management, Vietnam National University, Hanoi
Faculty of Non-Traditional Security
Website: kngo.netlify.app
Email: kiennt@hsb.edu.vn
This repository contains original research code together with third-party software, drivers, and utilities. Those components remain subject to their respective license notices. Review the license files in the relevant directories before modifying, redistributing, or incorporating the software into another project.
If Fab OpenVLC supports your research or teaching, consider starring the repository and sharing a reproducible experiment or improvement.