Swift
Add the build script and README.
Andy Gaoc6c31b44f319
diff --git a/README.md b/README.mdnew file mode 100644index 0000000..e50e1a5--- /dev/null+++ b/README.md@@ -0,0 +1,223 @@+# AirPointer++AirPointer turns AirPods Pro in their closed case into a pointer for your Mac.+Move the case to move the cursor. Tap the front of the case to click.++All processing happens on your Mac. The app has no network code.++## Before you use it++AirPointer is an early build. Apple did not make it and does not support it. It+uses private Apple protocols, so a macOS or AirPods update can stop it working.++- **Case analytics:** Ending a session uses up the diagnostic analytics stored on+ the case.+- **AirPods settings:** Some AirPods connection settings stay as the session set+ them. We do not know yet if this effect, or the analytics effect, continues+ after the link resets.+- **Audio:** Each connection drops the AirPods' Bluetooth link for a moment.+ Audio through the AirPods stops. Do not connect during a call.+- **Microphone:** During a session, the app keeps Mac sound and the microphone off+ all AirPods. The app restores them when the session ends.+- **Cursor size:** A cursor smaller than 2× grows to 2× while you point. It returns+ to its size when you pause or disconnect. After a force quit, it returns when+ you next open the app. This uses a private macOS call.++## Requirements++| Item | Status |+|---|---|+| AirPods Pro 3, macOS 26, Apple Silicon | Tested on one Mac with one pair |+| AirPods Pro 2 | Recognized, not tested |+| macOS 14 and 15 | Allowed, not tested |+| Xcode | Required to build |++## Build and run++```sh+zsh ./build.sh+open AirPointer.app+```++The build also runs the offline checks. Do not build during a pointer session.++If AirPointer does not appear in the Accessibility list after a rebuild, run:++```sh+tccutil reset Accessibility local.airpointer+```++## How to use it++The first time you open the app, setup has four steps:++1. **Allow:** Drag AirPointer into the Accessibility list. This lets it move the+ cursor and click.+2. **Connect:** Open the lid, close the lid, set the case down for a moment, and+ turn it upright.+3. **Calibrate:** Point at three dots to show the app where your screen is.+4. **Tap:** Tap the front of the case three times.++After that, press **fn ⌃** in any app to connect. Press it again to pause or+resume. To use a different shortcut, go to Settings.++```mermaid+flowchart TD+ Start(["Press Connect or fn ⌃"]) --> Open["Open the lid"]+ Open --> Close["Close the lid"]+ Close --> Saved{"Sensor offset<br/>saved?"}+ Saved -->|"No"| Hold["Set the case down"]+ Saved -->|"Yes"| Turn["Turn the case upright"]+ Hold --> Turn+ Turn --> Edges{"Screen edges<br/>saved?"}+ Edges -->|"No"| Dots["Point at three dots"]+ Edges -->|"Yes"| Pointing(["Pointing"])+ Dots --> Pointing+ Pointing -->|"fn ⌃"| Paused(["Paused"])+ Paused -->|"fn ⌃"| Pointing+```++## How it works++```mermaid+flowchart LR+ subgraph AirPods["AirPods Pro in the closed case"]+ Sensors["Motion sensors"]+ end++ subgraph Helpers["Helper programs"]+ Restore["ClosedCaseRestore<br/>brings the Bluetooth link up"]+ Motion["ClosedCaseMotion<br/>starts the sensors and<br/>keeps the case awake"]+ end++ subgraph App["AirPointer app"]+ Session["ClosedCaseSession<br/>runs the session"]+ Math["Orientation.js<br/>motion to screen position"]+ Tap["ClosedCaseTap<br/>finds taps"]+ Guard["AudioOutputGuard<br/>keeps sound off the AirPods"]+ UI["Window, menu bar,<br/>notch and setup"]+ end++ Mac["macOS<br/>moves the cursor and clicks"]++ Restore -->|"checks the link"| Sensors+ Sensors -->|"Bluetooth"| Motion+ Motion -->|"motion data, through a pipe"| Session+ Session -->|"heartbeat, every second"| Motion+ Session --> Math+ Session --> Tap+ Math -->|"cursor position"| Mac+ Tap -->|"click"| Mac+ Session --> Guard+ UI <-->|"state and commands"| Session+```++1. **Connect:** `ClosedCaseRestore` makes sure the AirPods' ordinary Bluetooth link+ is up. `ClosedCaseMotion` then reconnects them once, because the motion channel+ only answers just after a connection.+2. **Stream:** `ClosedCaseMotion` starts the sensors and sends paced requests to+ keep the closed case awake. It sends the motion data to the app.+3. **Keep alive:** The app sends a heartbeat every second. If the app stops, the+ helper stops the sensors and releases what it holds.+4. **Point:** `Orientation.js` calculates the case's orientation and converts it to+ a screen position.+5. **Click:** `ClosedCaseTap` looks for a sudden movement in the direction of a tap.+ If it finds one, the app clicks and plays a short sound on the Mac.++If motion stops for less than two seconds, the pointer stops and then continues.+If motion stops for longer, the pointer pauses and continues when motion returns.+A session ends 30 minutes after the lid closes. To continue, open and close the lid.++## Code map++| File | Purpose |+|---|---|+| `ClosedCase/CaseSustainedRenewal.m` | Builds `ClosedCaseMotion.bin`, the helper that talks to the AirPods. Lists its exit codes at the top. |+| `ClosedCaseRestore.swift` | Brings the ordinary Bluetooth link up. |+| `ClosedCaseAirPods.swift` | Finds the paired AirPods. |+| `ClosedCaseSession.swift` | Runs a session, reads motion data, and moves the cursor. |+| `ClosedCase/Orientation.js`, `MotionLearning.swift` | Motion math. |+| `ClosedCaseTap.swift` | Finds taps and learns their direction. |+| `AudioOutputGuard.swift` | Keeps sound and the microphone off the AirPods during a session. |+| `CursorSize.swift` | Grows a small cursor while you point. |+| `PointerShortcut.swift` | The shortcut and its control in Settings. |+| `AirPointer.swift`, `AppHome.swift` | Start the app and connect the session to its windows. |+| `AirPointerHome.swift`, `StatusBarUI.swift`, `NotchFlow.swift` | The window and Settings, the menu bar, and the notch. |+| `SetupAssistant.swift`, `AccessibilityGuide.swift`, `CaseLessons.swift` | Setup, the panel over System Settings, and calibration. |+| `RemoteKit.swift` | Shared interface components. |+| `TapTest.swift` | The Tap Test, for developers. |+| `Checks.swift`, `HomeChecks.swift`, `ClosedCase/TapFixtures.csv` | Offline checks and their test data. |+| `Assets/` | Images, sounds and the 3D case model. See [Assets/README.md](Assets/README.md). |+| `render-closed-case.py`, `seat-earbuds.py` | Make the onboarding case images from the 3D model. These need Blender. The app uses the finished images. |++[DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) has the rules for the interface.++## Data on your Mac++The app keeps its data in `~/Library/Application Support/AirPointer/`.++| File | Contents |+|---|---|+| `closed-case-target.txt` | The AirPods to use |+| `closed-case-grip.json` | Saved screen edges |+| `closed-case-sensor-calibration.json` | Saved sensor offset, kept for one week |+| `PointerSessions/` | Logs from the newest ten sessions |+| `TapTests.jsonl` | Tap Test scores |++The app does not send any of this anywhere.++In a session's `native.log`:++- `STEP` lines show the time of each connection step.+- `HOLD` lines show the motion rate and delay, about once a second.+- `tap` lines explain each tap.+- The `EXIT` line shows why the session ended.++## Troubleshooting++| Problem | What to do |+|---|---|+| The app does not connect | Turn off Bluetooth on your iPhone. Your iPhone can hold the AirPods. |+| "Connecting" does not end | Open the lid and keep it open until the app tells you to close it. |+| The pointer lags or motion stops | Make sure no other app, such as OBS or a browser call, uses the AirPods as a microphone. |+| The pointer stutters just after you connect | This is normal for about 20 seconds. |+| "Set it down" takes a long time | Use a firm, flat surface and do not touch the case. |+| Taps do not click | Go to Settings > Teach Tap. Do this again if you change how you hold the case. |++## Tap Test++Taps are tuned on one person so far, so your score may differ.++Connect, then go to **File > Developer > Tap Test**. The test takes about 75+seconds and tells you when to tap.++To also save a session's raw motion, run this before you connect. A session+records up to about 20 MB.++```sh+defaults write local.airpointer recordMotion -bool true+```++## Offline checks++These checks do not use Bluetooth.++```sh+AirPointer.app/Contents/MacOS/AirPointer --check-home+AirPointer.app/Contents/MacOS/AirPointer --check-pointer-settings+AirPointer.app/Contents/MacOS/AirPointer --check-closed-case-native+AirPointer.app/Contents/MacOS/AirPointer --check-audio-output-policy+AirPointer.app/Contents/MacOS/AirPointer --check-closed-case-tap ClosedCase/TapFixtures.csv+AirPointer.app/Contents/Resources/ClosedCaseMotion.bin --self-test+```++## Uninstall++Quit AirPointer, delete this folder, then run:++```sh+rm -rf ~/Library/Application\ Support/AirPointer+defaults delete local.airpointer+tccutil reset Accessibility local.airpointer+tccutil reset BluetoothAlways local.airpointer+```diff --git a/build.sh b/build.shnew file mode 100755index 0000000..6c17cf6--- /dev/null+++ b/build.sh@@ -0,0 +1,40 @@+#!/bin/zsh+set -euo pipefail+cd -- "${0:A:h}"+mkdir -p AirPointer.app/Contents/MacOS AirPointer.app/Contents/Resources+airpointer_build_mode="${AIRPOINTER_OPTIMIZATION:--O}"+airpointer_signing_identity="${AIRPOINTER_SIGNING_IDENTITY:--}"+cp Assets/CaseFront.png Assets/AppIcon.icns AirPointer.app/Contents/Resources/+for frame in Assets/CaseLid/lid-*.png; do cp "$frame" "AirPointer.app/Contents/Resources/Case${frame:t:r:s/lid/Lid/}.png"; done+cp Assets/TapClick/click.wav AirPointer.app/Contents/Resources/TapClick.wav+cp Assets/NotchShimmer.wav AirPointer.app/Contents/Resources/NotchShimmer.wav+clang -fobjc-arc -Wall -Wextra -Werror -framework Foundation -framework CoreBluetooth -framework IOBluetooth ClosedCase/CaseSustainedRenewal.m -o AirPointer.app/Contents/Resources/ClosedCaseMotion.bin+xcrun swiftc -swift-version 5 -O ClosedCaseRestore.swift -o AirPointer.app/Contents/Resources/ClosedCaseRestore.bin -framework Foundation -framework CoreBluetooth -framework IOBluetooth+cp ClosedCase/Orientation.js AirPointer.app/Contents/Resources/ClosedCaseOrientation.js+# The app finds the paired AirPods itself; no address is built in.+cat > AirPointer.app/Contents/Info.plist <<'PLIST'+<?xml version="1.0" encoding="UTF-8"?>+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">+<plist version="1.0"><dict>+<key>CFBundleExecutable</key><string>AirPointer</string>+<key>CFBundleIdentifier</key><string>local.airpointer</string>+<key>CFBundleName</key><string>AirPointer</string>+<key>CFBundleIconFile</key><string>AppIcon</string>+<key>CFBundlePackageType</key><string>APPL</string>+<key>CFBundleShortVersionString</key><string>0.2</string>+<key>CFBundleVersion</key><string>2</string>+<key>LSMinimumSystemVersion</key><string>14.0</string>+<key>NSHighResolutionCapable</key><true/>+<key>NSBluetoothAlwaysUsageDescription</key><string>AirPointer connects to your paired AirPods to keep motion available with the case closed.</string>+</dict></plist>+PLIST+xcrun swiftc -swift-version 5 "$airpointer_build_mode" AirPointer.swift ClosedCaseSession.swift ClosedCaseTap.swift TapTest.swift ClosedCaseAirPods.swift AudioOutputGuard.swift AppHome.swift AirPointerHome.swift RemoteKit.swift SetupAssistant.swift AccessibilityGuide.swift PointerShortcut.swift CursorSize.swift StatusBarUI.swift NotchFlow.swift HomeChecks.swift MotionLearning.swift CaseLessons.swift Checks.swift -o AirPointer.app/Contents/MacOS/.AirPointer-next -framework AppKit -framework JavaScriptCore -framework QuartzCore -framework ApplicationServices -framework Carbon -framework AVFoundation -framework CoreAudio -framework CoreBluetooth+mv -f AirPointer.app/Contents/MacOS/.AirPointer-next AirPointer.app/Contents/MacOS/AirPointer+if [[ "$airpointer_signing_identity" != "-" ]]; then+ codesign --force --sign "$airpointer_signing_identity" --timestamp=none --identifier local.airpointer.closed-case-motion AirPointer.app/Contents/Resources/ClosedCaseMotion.bin+ codesign --force --sign "$airpointer_signing_identity" --timestamp=none --identifier local.airpointer.closed-case-restore AirPointer.app/Contents/Resources/ClosedCaseRestore.bin+fi+codesign --force --sign "$airpointer_signing_identity" --timestamp=none AirPointer.app+/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -f "$PWD/AirPointer.app"+AirPointer.app/Contents/MacOS/AirPointer --self-test+AirPointer.app/Contents/MacOS/AirPointer --check-closed-case-tap ClosedCase/TapFixtures.csv