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

---
project:
  name: WiFi Calling Optimization Runbook
  status: completed
  category: infrastructure
  source: homelabagentroot
  created: 2026-04-01
  updated: 2026-04-01
  description: Live configuration and runbook for AT&T WiFi calling optimization on UniFi UCG Ultra
  carrier: AT&T
  affected_ssids: [Family of D., Will of D. (Guest)]
  affected_vlans: [10, 20, 40, 50, 1]
  tags: [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:

```bash
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

```bash
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

```bash
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 Network Optimization Plan]]
- [[unifi-execution-plan.md|UniFi Execution Plan]]