Raspberry Pi Setup Guide

What you'll need

• Raspberry Pi 3, 4, or Zero 2 W
• MicroSD card (8 GB+)
• A USB wifi dongle (for the second interface) or a Pi with built-in wifi + a dongle
• An internet connection (via ethernet or one wifi interface)

The Pi needs two wifi interfaces: one connects to your upstream internet (STA), the other broadcasts the wifi.tree AP. On a Pi 4, the built-in wifi handles one role and a USB dongle handles the other. A Pi Zero 2 W typically needs a dongle for both.

1. Flash Raspberry Pi OS

Use Raspberry Pi Imager to flash Raspberry Pi OS Lite (64-bit) to your SD card. Enable SSH and set a username/password in the imager's advanced settings.

2. Get the code

git clone https://github.com/AgentMage/wifi.tree
cd wifi.tree/pi

3. Network setup

The Pi implementation uses a virtual AP interface (uap0) on top of the built-in wifi adapter, and NAT via nftables. The AP subnet is 10.42.0.0/24 with the Pi at 10.42.0.1.

# Create the virtual AP interface
sudo bash sbin/wifitree-uap0-setup.sh

# Set up traffic shaping (tc/CAKE)
sudo bash sbin/wifitree-shaping.sh

4. Install services

sudo cp lib/*.py /usr/local/lib/wifitree/
sudo cp sbin/wifitree-*.py /usr/local/sbin/
sudo cp sbin/wifitree-*.sh /usr/local/sbin/

# Install systemd service files (see pi/systemd/)
sudo systemctl enable --now wifitree-portal
sudo systemctl enable --now wifitree-webadmin
sudo systemctl enable --now wifitree-accountd

5. Configure

Edit /etc/wifitree/settings.json for operational settings (leaf TTL, data cap, bandwidth cap) and /etc/wifitree/portal.json for appearance (title, emoji, colors, copy). Both are live-reloaded — no restart needed.

6. Your tree is live

The AP broadcasts wifi.tree. The admin panel runs at http://10.42.0.1:8090 on your local network. 🌳

Services

• wifitree-portal — captive portal HTTP server
• wifitree-webadmin — admin panel on :8090
• wifitree-accountd — bandwidth metering, quota enforcement

sudo systemctl restart wifitree-portal

# Live terminal dashboard
sudo python3 /usr/local/sbin/wifitree-monitor.py

# CLI user management
sudo python3 /usr/local/sbin/wifitree-admin.py list

Pi-only features

• Monthly per-visitor data quotas (resets each calendar month)
• tc/CAKE traffic shaping (20 Mbit shared pool + per-device caps)
• SQLite-backed visitor history (/var/lib/wifitree/wifitree.db)
• dnsmasq DHCP with hostname capture