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()`
Remote reboot	Reboots OpenWrt when requested by the controller	`inform.c` → `handle_response()`
Firmware spoofing	Persists and reports the target version requested by an upgrade	`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-r3.apk --allow-untrusted

# Configure
vi /etc/openuf/openuf.conf

Example Configuration

controller_ip   =               # Empty: use IPv4 default gateway
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)

Set controller_ip to a controller IPv4 address or hostname to override autodetection. The automatic mode uses the IPv4 default-route gateway for initial adoption; after adoption, the controller-provided inform URL is kept.

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.

Because UniFi firmware cannot run on the OpenWrt host, an upgrade request does not download or install its image. Instead, openUF saves the requested firmware version in state.json and reports it in subsequent inform packets.

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