3.6 KiB
openUF
Daemon that makes an OpenWrt router appear as a UniFi AP to UniFi Network controllers.
Implemented Features
| Feature | Description | Implementation |
|---|---|---|
| L2 Discovery | UDP broadcast + multicast every 10s | announce.c → port 10001 |
| Adoption | AES-128-CBC handshake with the controller | inform.c → handle_response() |
| WiFi Config | Creates WiFi networks from the controller via UCI | wlan.c → wlan_apply_config() |
| Band Steering | 802.11k/v Neighbor Reports + BSS Transition | wlan.c → apply_vap() |
| Fast Roaming | 802.11r FT with mobility_domain derived from MAC | wlan.c → apply_vap() |
| WPA3 / PMF | SAE, SAE-mixed, 802.11w 0/1/2 | wlan.c → sec_to_uci() |
| WiFi Clients | MAC, signal, bitrate, bytes per VAP | clients.c → iw station dump |
| Wired Clients | MACs from bridge FDB | clients.c → bridge fdb |
| CPU / RAM | Real-time usage | sysinfo.c → /proc/stat + /proc/meminfo |
| Interfaces | Speed, duplex, rx/tx counters | sysinfo.c → /proc/net/dev |
| Channel / RF | Channel utilization, noise, tx_power | sysinfo.c → iw survey dump |
| LLDP Send | Custom frames via AF_PACKET raw socket | lldp.c → lldp_send_frame() |
| LLDP Read | Neighbors for UniFi topology | lldp.c → lldpctl -f json |
Building in the dev container
# From the OpenWrt build root
cd /home/openwrt/openwrt
# Build only this package
make package/OpenUniFi/compile
# For a clean package rebuild
make package/OpenUniFi/clean
make package/OpenUniFi/compile
Makefile.standalone is an alternative for compiling directly on an OpenWrt
device that has the development dependencies installed:
make -f Makefile.standalone
Contributors and AI agents should read AGENTS.md for the concise
architecture map, invariants, and validation checklist.
Changing Compiler Settings
# OpenWRT build directory
cd /home/openwrt/openwrt
# Change settings
make menuconfig
# export settings
./scripts/diffconfig.sh
# Paste settings into .devcontainer/openwrt.config file in the code
# Then rebuild the dev container by pressing F1 in VScode
# and typing rebuild and selecting rebuild dev container
Configuration
On the access point, run the following to install the package:
# Install dependencies
# replace wpad-basic-mbedtls with wpad-mbedtls
apk del wpad-basic-mbedtls && apk add wpad-mbedtls && /etc/init.d/network restart
# Remove old installation
apk -r del openuf
# Install new version
apk add openuf-0.4.0-r1.apk --allow-untrusted
# Configure
vi /etc/openuf/openuf.conf
Example Configuration
controller_ip = 192.168.1.1 # UniFi controller IP
lan_if = br-lan # Default Lan interface Name
ufmodel = u6-inwall # emulated model
inform_interval = 10 # inform interval
enable_announce = 1
enable_inform = 1 # Enable adoption and telemetry requests
enable_logging = 1 # Write diagnostics to /var/log/openuf.log
protocol_debug_level = 0 # 0=off, 1=safe response details,
# 2=full decrypted JSON (contains secrets)
Daemon settings live in /etc/openuf/openuf.conf. Adoption and controller state
are persisted separately in /etc/openuf/state.json; do not copy that file
between devices because it contains the device authentication key.
Glossary
TNBU
TNBU is the magic string/identifier at the start of the binary packet format used in this custom Inform protocol implementation.
CCQ
Client Connection Quality