hermes-ice/homelab/docs/unifi-wifi-calling-optimization.md

project

project
name status category source created updated description carrier affected_ssids affected_vlans tags WiFi Calling Optimization Runbook completed infrastructure homelabagentroot 2026-04-01 2026-04-01 Live configuration and runbook for AT&T WiFi calling optimization on UniFi UCG Ultra AT&T Family of D. Will of D. (Guest) 10 20 40 50 1 unifi wifi wifi-calling att qos 802.11r

WiFi Calling Optimization Runbook

Overview

Optimizations applied to the UniFi Cloud Gateway Ultra (UCG Ultra) to support reliable AT&T WiFi calling across all non-IoT VLANs.

Applied: 2026-04-01
Controller: https://192.168.1.1 (UniFi Network 10.1.85)
Site ID: 88f7af54-98f8-306a-a1c7-c9349722b1f6

AT&T WiFi Calling Requirements

AT&T WiFi calling uses IPSec/IKEv2 tunnels to AT&T infrastructure:

Protocol	Port	Purpose
IKEv2	UDP 500	Key exchange and tunnel establishment
IPSec NAT-T	UDP 4500	Encapsulated ESP through NAT
SIP (fallback)	UDP/TCP 5060, 5061	Session initiation (rarely used by AT&T)
RTP Media	UDP 10000-20000	Voice media (inside IPSec tunnel)

Key insight: RTP media is encrypted inside the IPSec tunnel, so DSCP marking on outer packets has limited effect. The biggest quality improvements come from:

1. Fast roaming (802.11r) to eliminate AP handoff gaps
2. Reducing airtime contention (multicast-to-unicast)
3. Ensuring firewall allows all required ports

Changes Applied

1. Family of D. SSID (b2784680-7b04-4c8a-9098-19aced53fc89)

API: PUT /sites/{siteId}/wifi/broadcasts/b2784680-7b04-4c8a-9098-19aced53fc89

Setting	Before	After	Impact
fastRoamingEnabled	false	true	802.11r - eliminates re-auth gap during AP roaming
wpa3FastRoamingEnabled	false	true	WPA3 Fast Transition for WPA3-only clients
multicastToUnicastConversionEnabled	false	true	Reduces airtime waste from mDNS/SSDP broadcasts

Already enabled (unchanged):

• bandSteeringEnabled: true - prefers 5/6GHz over 2.4GHz
• bssTransitionEnabled: true - 802.11v neighbor reports
• broadcastingFrequenciesGHz: [5, 6, 2.4] - tri-band

2. Will of D. Guest SSID (a2cdccb6-d054-47ad-ab14-62cae625b6af)

API: PUT /sites/{siteId}/wifi/broadcasts/a2cdccb6-d054-47ad-ab14-62cae625b6af

Setting	Before	After	Impact
bssTransitionEnabled	false	true	802.11v - helps guest devices roam efficiently

Not changed on Guest:

• fastRoamingEnabled: remains false (guest devices typically don't need 802.11r)
• multicastToUnicastConversionEnabled: remains false

3. Traffic Matching Rule

API: POST /sites/{siteId}/traffic-matching-lists

Property	Value
Name	WiFi Calling Ports
ID	e7f06077-1a11-4355-88df-185837ba29df
Type	PORTS
Ports	UDP 500, 4500, 5060, 5061

Note: RTP port range (10000-20000) was not added because the UniFi integration API does not support PORT_NUMBER_RANGE in traffic matching list items. The signaling ports (500, 4500) are the most critical for tunnel establishment.

Firewall Verification

All zones already have outbound access to External (internet), so no firewall changes were needed:

Zone	External Access	Status
Internal (1c79c8c2)	Allow All Traffic (system)	OK
Guest (b8d0e4f2)	Guest to External (idx 10000) + fallback	OK
Staging (dc406f85)	Allow All Traffic (system)	OK
Management (ea466cdf)	Allow All Traffic (system)	OK
DMZ (4fb011b4)	Allow All Traffic (system)	OK

Current SSID Configuration (Post-Optimization)

SSID	Bands	Security	Fast Roaming	BSS Transition	Mcast→Ucast
Family of D.	2.4/5/6 GHz	WPA2/WPA3 Personal	Enabled	Enabled	Enabled
Will of D. (Guest)	2.4/5 GHz	WPA2 Personal	Disabled	Enabled	Disabled
Will of D. IoT	2.4 GHz only	WPA2 Personal	Disabled	Disabled	Disabled

Rollback Procedures

Rollback Family of D. Fast Roaming

If legacy devices (older IoT, smart TVs, casting devices) experience connectivity issues:

curl -k -H "X-API-KEY: $UNIFI_API_KEY" -H "Content-Type: application/json" -X PUT \
  -d '{
    "type": "STANDARD",
    "name": "Family of D.",
    "enabled": true,
    "network": {"type": "SPECIFIC", "networkId": "fb44c9bf-1534-4a98-9c7e-6aee4bf4069a"},
    "securityConfiguration": {
      "type": "WPA2_WPA3_PERSONAL",
      "fastRoamingEnabled": false,
      "passphrase": "ILoveNaomi2025",
      "pmfMode": "OPTIONAL",
      "saeConfiguration": {"anticloggingThresholdSeconds": 5, "syncTimeSeconds": 5},
      "wpa3FastRoamingEnabled": false
    },
    "multicastToUnicastConversionEnabled": false,
    "clientIsolationEnabled": false,
    "hideName": false,
    "uapsdEnabled": false,
    "broadcastingFrequenciesGHz": [5, 6, 2.4],
    "bandSteeringEnabled": true,
    "arpProxyEnabled": false,
    "bssTransitionEnabled": true,
    "advertiseDeviceName": false
  }' \
  "https://192.168.1.1/proxy/network/integration/v1/sites/88f7af54-98f8-306a-a1c7-c9349722b1f6/wifi/broadcasts/b2784680-7b04-4c8a-9098-19aced53fc89"

Rollback Guest BSS Transition

curl -k -H "X-API-KEY: $UNIFI_API_KEY" -H "Content-Type: application/json" -X PUT \
  -d '{
    "type": "STANDARD",
    "name": "Will of D.",
    "enabled": true,
    "network": {"type": "SPECIFIC", "networkId": "02364634-a782-4b58-a33b-48b48f492210"},
    "securityConfiguration": {
      "type": "WPA2_PERSONAL",
      "fastRoamingEnabled": false,
      "passphrase": "EmergencyFood2025"
    },
    "multicastToUnicastConversionEnabled": false,
    "clientIsolationEnabled": false,
    "hideName": false,
    "uapsdEnabled": false,
    "broadcastingFrequenciesGHz": [5, 2.4],
    "bandSteeringEnabled": true,
    "arpProxyEnabled": false,
    "bssTransitionEnabled": false,
    "advertiseDeviceName": false
  }' \
  "https://192.168.1.1/proxy/network/integration/v1/sites/88f7af54-98f8-306a-a1c7-c9349722b1f6/wifi/broadcasts/a2cdccb6-d054-47ad-ab14-62cae625b6af"

Delete Traffic Matching Rule

curl -k -H "X-API-KEY: $UNIFI_API_KEY" -X DELETE \
  "https://192.168.1.1/proxy/network/integration/v1/sites/88f7af54-98f8-306a-a1c7-c9349722b1f6/traffic-matching-lists/e7f06077-1a11-4355-88df-185837ba29df"

Troubleshooting

WiFi Call Drops During Roaming

1. Verify fast roaming is enabled: check fastRoamingEnabled on the SSID
2. Check if the phone supports 802.11r (most phones since ~2018 do)
3. Look for excessive AP handoffs in UniFi client history
4. Check RSSI values - phones may be roaming too aggressively

WiFi Call Fails to Establish

1. Verify firewall allows UDP 500, 4500 outbound from the client's zone
2. Check DNS resolution - AT&T WiFi calling needs to resolve carrier domains
3. Verify no DPI/IDS rules are blocking IPSec traffic
4. Check if the phone is on the correct SSID (not IoT SSID)

Poor Call Quality (Jitter/Latency)

1. Check for airtime contention on the AP (too many 2.4GHz clients)
2. Verify band steering is pushing voice clients to 5/6GHz
3. Check if multicast-to-unicast is reducing broadcast noise
4. Review SQM/QoS settings on the WAN interface

Related Documents

• unifi-network-optimization-plan.md
• unifi-execution-plan.md