Ravenhammer Research — XiaoVPN

Small project for Seeed XIAO ESP32C3 (XiaoVPN) and a companion Linux helper that creates a VRF + TUN and forwards UDP <-> TUN.

System dependencies (Debian / Ubuntu)

Install common packages needed to build the Linux server and BLE client and to run PlatformIO (firmware build helper):

sudo apt update
sudo apt install -y build-essential cmake pkg-config python3-pip libcap2-bin \
  libnl-3-dev libbluetooth-dev libglib2.0-dev libreadline-dev libdbus-1-dev libudev-dev docker.io
# install PlatformIO (firmware tooling)
pip3 install --user platformio

Note: when installed with --user, the pio binary is placed in ~/.local/bin. Make sure ~/.local/bin is on your PATH (for example, export PATH=$HOME/.local/bin:$PATH) or run the binary at ~/.local/bin/pio.

Build (PlatformIO)

Install PlatformIO and run from project root:

# Build firmware for Seeed XIAO ESP32C6
pio run -e seeed_xiao_esp32c6

# Upload (connect device and ensure correct upload port is auto-detected or pass -p /dev/ttyUSB0)
pio run -e seeed_xiao_esp32c6 -t upload

Build and flash with Docker:

# build image (produces firmware in image filesystem)
docker build -t xiaovpn-builder .

# run the image to flash (expose usb device to container) - example:
# replace /dev/ttyUSB0 with your device path
docker run --rm --device=/dev/ttyUSB0 xiaovpn-builder \
  "pio run -e seeed_xiao_esp32c3 -t upload -p /dev/ttyUSB0"

Linux server

The companion C++ server that creates a VRF + TUN and forwards packets is in the linux/server folder. See linux/server/README.md for build and run instructions.

BLE client

An interactive BLE client for configuring XiaoVPN devices is in linux/ble — see linux/ble/README.md.

Theory of operation

• The Seeed XIAO module can be installed inside a light-socket adapter/holder that contains a small DC power supply, letting the device be powered from an outdoor light socket while the bulb is reinstalled at the end of the adapter (for example:

• enclosure example: https://www.homedepot.com/p/Leviton-660-Watt-15-Amp-2-Outlet-Socket-Adapter-Black-1403-1403/302009539?g_store=4705&source=shoppingads&locale=en-US&fp=ggl).

• 120V to DC power: https://www.amazon.com/AC-DC-Converter-Board-Module-Supply/dp/B09KC5KW59

• In that deployment the device runs continuously while powered by the socket adapter and can be reconfigured over BLE (local) to join open or managed Wi‑Fi access points.

• The device implements the XiaoVPN service: it can operate as a VPN server (accepting incoming VPN connections and attempting to open a port/NAT hole where possible) or be configured to connect out to a remote VPN server (via BLE configuration or an MQTT bootstrap).

• A remote VPN server or client can then proxy traffic through the XiaoVPN device's internet connection, enabling remote access to resources reachable from the Xiao's network interface.

License

This project is licensed under the GNU General Public License v3. See LICENSE.md for details.