Documentation

Technical Documentation

How Ping Warden works: AWDL events, the privileged helper, XPC, latency measurement, automation, security, diagnostics, and signed updates.

This document is the detailed technical and operational guide for Ping Warden.

Read it on the Ping Warden website. The documentation hub includes setup, pricing, privacy, troubleshooting, and release notes.

For quick setup, see Quick Start. For issue recovery, see Troubleshooting.

1. Overview

Ping Warden is a macOS utility that keeps AWDL from reactivating during latency-sensitive work.

AWDL (Apple Wireless Direct Link) is used by Apple ecosystem features such as AirDrop, AirPlay, and Handoff. On some networks and workflows, AWDL interface transitions can correlate with sudden latency jumps. Ping Warden provides a controlled, user-friendly way to keep AWDL suppressed when desired, while retaining the ability to restore the interface when protection stops.

Primary goals:

• Keep AWDL suppressed during latency-sensitive games, cloud streaming, and calls.
• Avoid repeated password prompts for normal day-to-day usage.
• Provide clear observability (status, ping history, interventions).
• Offer safe operational controls (enable/disable/pause/restore).

2. Why Not Just Run sudo ifconfig awdl0 down?

A one-time shell command might seem like a simple fix, but it doesn't actually solve the problem.

The core issue: macOS can bring AWDL back up automatically. A polling script reacts only after the interface is active, so it cannot prevent the transition itself.

Why Ping Warden is different: Instead of polling, the helper daemon waits for kernel route and interface events through an AF_ROUTE socket. When macOS raises AWDL while protection is active, the helper requests that the interface return down and records an intervention attempt. The count does not establish that the request succeeded or that a particular latency spike was avoided.

Additional benefits:

• No repeated sudo prompts: One-time approval during setup, then background operation.
• Observability: Live dashboard with ping history, intervention counts, and spike timeline.
• Proper lifecycle: Explicit startup, reconnect, health-check, and shutdown behavior.

3. High-Level Architecture

Ping Warden uses a split architecture:

• Main app (Swift/SwiftUI + AppKit bridge):
  • UI, settings, dashboard, diagnostics, automation, Sparkle updates.
• Helper daemon (Objective-C):
  • Privileged AWDL control and low-level monitoring.

Communication boundary:

• XPC service: com.amesvt.pingwarden.xpc
• Protocol: PingWardenHelperProtocol (in PingWarden/Common/HelperProtocol.h)

Registration model:

• Helper is registered using SMAppService.daemon(plistName:).
• Registration requires one-time user approval in System Settings.

4. Key Components

4.1 Main App

Important files:

• PingWarden/PingWarden/PingWardenApp.swift
• PingWarden/PingWarden/PingWardenMonitor.swift
• PingWarden/PingWarden/DashboardView.swift
• PingWarden/PingWarden/ProtectedSessionCoordinator.swift
• PingWarden/PingWarden/PingWardenPreferences.swift
• PingWarden/PingWarden/DiagnosticsExporter.swift

Responsibilities:

• Menu bar app behavior and settings window lifecycle.
• User intent state persistence (isMonitoringEnabled).
• Effective runtime state tracking (effectiveMonitoringEnabled).
• Dashboard data collection and charting.
• Latency Session lifecycle and local recap history.
• Sparkle update checks and update menu entries.

4.2 Helper Daemon

Important files:

• PingWarden/PingWardenHelper/main.m
• PingWarden/PingWardenHelper/PingWardenMonitor.h
• PingWarden/PingWardenHelper/PingWardenMonitor.m
• PingWarden/PingWardenHelper/com.amesvt.pingwarden.helper.plist

Responsibilities:

• Monitor interface change events through AF_ROUTE.
• Enforce desired AWDL state through ioctl on interface flags.
• Count and report interventions.
• Restore AWDL to enabled state when helper exits.

5. Monitoring Model and Timing Behavior

Core behavior:

• AWDL blocking mode means: keep awdl0 down.
• Allow mode means: permit awdl0 to remain up.
• Helper thread blocks on poll() waiting for:
  • Route/interface events (AF_ROUTE socket).
  • Internal control messages (pipe).

When monitoring is active and the system raises AWDL:

1. Kernel route event arrives.
2. Helper identifies awdl0 state change (RTM_IFINFO).
3. The intervention-attempt counter increments.
4. The helper attempts to clear IFF_UP on awdl0 via SIOCSIFFLAGS and reads back the resulting flag state.

This is event-driven, not a delayed periodic shell loop.

6. State Model

Two state concepts are used:

• User intent state:
  • Preference for whether monitoring should be enabled.
  • Stored in user defaults.
• Effective runtime state:
  • Actual active status considering helper availability and XPC connectivity.

This separation allows robust behavior during reconnects, restarts, or temporary failures.

7. Setup and Approval Flow

Initial setup sequence:

1. Launch app.
2. App checks helper registration status via SMAppService.
3. If unregistered or approval required, user is guided to System Settings.
4. App polls registration status and proceeds once enabled.
5. XPC connection is activated.

The design avoids recurring password prompts after the one-time approval step.

The welcome appears automatically once. Dismissing it leaves the free dashboard usable without helper setup; Settings → General → Finish Setup and the menu bar protection action both resume the flow later.

8. Settings and UI Areas

Settings sections:

• Dashboard
• General
• License
• Targets
• Automation
• Advanced

8.1 Dashboard

Provides real-time latency visibility and tuning controls.

Cards include:

• Latency Session:

  • Start and end a measured game or call. Starting a session enables Ping Protection and requires a license or an active transition. Reading past session recaps remains free.
  • Review duration, median, p95, jitter, Probe Failures, and interventions.
  • Share a privacy-scrubbed text recap.

• Network Quality:

  • Current ping, average, best, worst, jitter, Probe Failures, AWDL state.

• Ping History:

  • Timeframe zoom windows: 1 min, 5 min, 15 min, 30 min, 1 hour.
  • Timeframe changes are non-destructive (history is not deleted by zoom changes).

• Latency Timeline:

  • Spike and intervention event list.

• Ping Protection:

  • Intervention counter and explanatory status.

• Ping Target:

  • Shows the current target with a Change… button that opens Settings > Targets.

Data retention behavior:

• Dashboard keeps a rolling history window (approximately one hour plus buffer).
• Chart zoom filters the in-memory history for display only.

8.2 General

Controls:

• Ping Protection setup and status.
• Launch at Login.
• Show Dock Icon.
• Show Live Metrics in Menu (current ping and interventions in the menu dropdown; the same toggle appears in the menu itself).

Status block:

• Displays helper registration and effective blocking status.

8.3 Automation

Controls:

• Game Mode Auto-Detect: engages when a recognized game is the frontmost app, no permission needed; an optional Enable Fullscreen Detection… button requests Screen Recording to also catch fullscreen games behind other windows. Skipped while the Mac is on Ethernet.
• Control Center Only mode, which removes the menu bar and Dock icons for people who use the Control Center toggle (macOS 26+, signed release builds only). It is saved as ControlCenterOnlyEnabled. Version 4.2.1 and earlier offer Hide Menu Bar Icon instead, saved as ControlCenterWidgetEnabled, which hides only the menu bar icon and keeps the Dock icon. Later versions keep that saved choice and its behavior until the person picks Control Center Only or shows the menu bar icon again.

8.4 Advanced

Tools:

• Test the registered helper and signed XPC connection.
• Open Console logs.
• Create a local diagnostics snapshot and review it before sharing.
• Repair the helper connection without changing the protection preference.
• Prepare for removal by turning off protection, unregistering services, clearing local data, revealing the app, and quitting.

8.5 License

• View status (Licensed, transition period with days remaining, or Unlicensed).
• Enter a license key and verify with Gumroad, or open the Gumroad product page.
• The transition applies when protection was enabled with an approved helper at the first launch of version 4. It lasts 90 days from that launch, and updates preserve the deadline. For donations before version 4, the pane explains how to request a license at oliver@ames.consulting.
• Activation and refresh send the license key and product ID to Gumroad over HTTPS. The key stays in the macOS Keychain between checks.
• Eligible users see the transition notice once, then reminders when 30 days and 7 days remain, each showing the days left. The presentation date persists across restarts. Reminders defer during detected games and latency sessions, stop after activation or expiry, never extend the original deadline, and a reminder missed while the app was closed does not stack with the next one.

8.6 Targets

• Ping target selection, including discovered GeForce NOW zones and the network gateway.
• Find Fastest Target.
• Update interval selection.
• Custom servers (add, edit, remove).

9. Menu Bar and App Menu Integration

Menu bar:

• One primary Ping Protection action, plus a contextual 10-minute pause.
• Latency Sessions stay in the dashboard so they are not confused with the persistent protection control.
• Optional live metrics in dropdown.
• Settings, About, Buy a License (while unlicensed), and update actions.
• Help and Documentation opens https://pingwarden.app/docs/. The Help menu includes troubleshooting and the website. About includes both website and documentation links.

App menu (frontmost app state):

• Check for Updates... is injected/ensured when app is active with regular activation policy.
• This complements the status item update command.

10. Sparkle Update System

Update stack:

• Framework: Sparkle 2. The exact version is pinned in the Xcode project's Package.resolved.
• Stable feed: https://oliverames.github.io/ping-warden/appcast.xml.
• Beta feed: https://oliverames.github.io/ping-warden/appcast-beta.xml, selected in Settings → Advanced → Updates. Stable releases also reach this feed.
• Signature model: EdDSA (SUPublicEDKey in app plist).
• Signed feeds and pre-extraction archive verification are required.

Operational details:

• App clears stale user-default feed overrides at startup.
• Updater delegate provides canonical feed URL.
• Manual update checks available from both menu entry points.
• The paid-upgrade boundary at build 40000 requires users of free versions to review the upgrade before installation.

Release wiring:

• PingWarden/PingWarden/release.sh builds a fresh archive, signs and notarizes the app and DMG, and publishes signed update feeds.
• Stable releases replace the Gumroad app download while preserving the license-key block and other buyer content.
• GitHub release artifacts and appcast metadata must remain synchronized.

11. Security Model

Security controls include:

• Privileged helper exposed only through XPC interface.
• Mandatory code-signing requirements for the app and widget XPC clients.
• Exact Team ID and bundle identifier validation in the helper bootstrap path.
• Unsigned or ad-hoc helper builds fail closed instead of falling back to UID-only access.
• Shared defaults and distributed notifications never authorize privileged changes.
• Bounded error handling and controlled shutdown paths.
• Developer ID signing, Hardened Runtime, notarization, and stapling are release gates.

12. Diagnostics and Health Checks

Built-in diagnostics surface:

• Helper registration state.
• XPC reachability.
• Helper version and status calls.
• Current awdl0 flags snapshot.
• Health check pass/fail messaging.
• Intervention counter and reset support.

Export diagnostics:

• Generates a local support snapshot with owner-only permissions.
• Redacts custom ping targets to a category before writing.
• Shows the contents for review and never uploads the file automatically.

13. Performance Characteristics

Design choices for low overhead:

• Event-driven helper thread using poll() rather than busy loops.
• One reference-counted telemetry stream shared by dashboard, menu, and sessions.
• Rolling bounded history with statistics calculated off the main thread.
• Five-minute hostname and address caching with cancellable probe deadlines.
• Game Mode uses event-triggered checks plus a safety timer: 2 seconds while a game is detected, 10 seconds otherwise, dropping to 30 seconds after about 90 seconds without a game. App activation and display changes trigger an immediate re-check.
• Narrow command surface over XPC.
• Dashboard sampling rate configurable by user.

14. Build and Development

Prerequisites:

• macOS 13+
• Xcode supporting project targets and current SDK requirements

Open in Xcode:

cd PingWarden
open PingWarden.xcodeproj

Build from CLI (example):

xcodebuild -project PingWarden.xcodeproj -scheme PingWarden -configuration Debug build

Key project areas:

• App target: UI and orchestration.
• Helper target: privileged monitoring and control.
• Widget target: optional control-center/menu integration path.

15. Release and Distribution

Run the release command from a clean commit that is already pushed:

cd PingWarden/PingWarden
bash release.sh X.Y.Z ../../RELEASE_NOTES.md

Before it builds anything, the command rebuilds the website's generated pages under Site/public from RELEASE_NOTES.md, the READMEs, and the guides, and stops if the committed copies are out of step. The website deploys only when those pages match their sources, so a release that edits the notes must commit the rebuilt Site/public/docs/releases.html alongside the version bump. The release then creates a fresh unsigned archive and dSYMs, validates and signs the app, helper, and widget, notarizes and staples the app and DMG, mount-tests the DMG, signs the Sparkle archive and appcast, publishes the GitHub release and Sentry dSYMs, updates gh-pages, and attaches the DMG to the Gumroad product.

Release files: PingWarden/PingWarden/release.sh, PingWarden/PingWarden/notarize.sh, and appcast.xml.

Important:

• Appcast latest entry must match the intended newest version.
• Feed URL in shipped app must resolve to current appcast location.

16. Limitations and Tradeoffs

Behavioral tradeoff while blocking AWDL:

• Apple features that depend on AWDL (for example AirDrop/AirPlay/Handoff) may be unavailable until blocking is disabled.

Other practical limits:

• Automation features depend on system permissions, game metadata, and signed-release packaging.
• Game mode detection depends on permissions and app/game behavior.
• Network conditions and endpoint choice still influence baseline latency.

17. Operational Best Practices

Recommended usage:

• Start a Latency Session before a latency-sensitive game or call.
• Use dashboard target auto-select periodically if your network path changes.
• Keep update interval moderate unless actively investigating jitter.
• Use diagnostics export before opening support issues.

18. Related Documentation

• Quick Start
• Troubleshooting
• Repository Root README
• Release Notes

19. Credits

• jamestut/awdlkiller
• james-howard/AWDLControl, SMAppService and XPC architecture inspiration

20. License and Pricing

Source code: MIT, Copyright (c) 2025-2026 Oliver Ames. Building from source under MIT does not require a license. See the repository LICENSE.

Prebuilt app: free to download, with Ping Protection gated behind a one-time purchased key. Section 8.5 describes the License pane and the verification behavior the app implements. The root README is the canonical statement of the price, the existing-user transition, and the donor path.

View this guide on GitHub