📱 iOS App Guide

📋 Requirements

✨ App Features

🛠️ Project Setup

Step 1: Create New Xcode Project

1. Open Xcode
2. File → New → Project
3. Choose iOS → App
4. Configure project:
   • Product Name: FitnessSensorController
   • Interface: SwiftUI
   • Language: Swift
   • Minimum iOS: 16.1

Step 2: Add Source Files

Copy these files to your project:

Step 3: Project Structure

FitnessSensorController/
├── FitnessSensorControllerApp.swift
├── Views/
│   ├── ContentView.swift
│   ├── DeviceControlView.swift
│   ├── WorkoutScenarioListView.swift
│   ├── WorkoutScenarioView.swift
│   └── WorkoutDetailView.swift
├── Models/
│   ├── HomeManager.swift
│   ├── WorkoutScenarios.swift
│   └── WorkoutController.swift
├── Info.plist
├── Entitlements.entitlements
└── Assets.xcassets/

⚙️ Configuration

A. Signing & Capabilities

1. Select your project in Xcode
2. Select target → Signing & Capabilities
3. Enable Automatic Signing (or configure manual)
4. Select your Team
5. Add capabilities by clicking + Capability:
   • ✅ HomeKit
   • ✅ Background Modes (optional)

B. Info.plist Configuration

Add these privacy descriptions:

<key>NSHomeKitUsageDescription</key>
<string>Control your fitness sensor via Matter</string>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Required for Matter device commissioning</string>

<key>NSLocalNetworkUsageDescription</key>
<string>Communicate with Matter devices on local network</string>

<key>NSBonjourServices</key>
<array>
    <string>_matter._tcp</string>
    <string>_matterc._udp</string>
</array>

C. Entitlements Configuration

Ensure Entitlements.entitlements contains:

<key>com.apple.developer.homekit</key>
<true/>

<key>com.apple.developer.matter.allow-setup-payload</key>
<true/>

🔨 Building & Running

Build the App

1. Connect your iPhone via USB
2. Select your device as the build target
3. Press ⌘R or click Run
4. Accept HomeKit permission when prompted

Common Build Errors

🔗 Pairing Your Sensor

Prerequisites

• ✅ nRF52840 device flashed and powered on
• ✅ Thread border router active (HomePod mini/Apple TV)
• ✅ iPhone and device on same network
• ✅ Bluetooth enabled on iPhone

Option 1: Via App (Recommended)

1. Open the app
2. Tap "Get Started" (first launch)
3. Tap "+" button in top-right
4. Tap "Open Home Settings"
5. In Settings → Home, tap "Add Accessory"
6. Scan QR code OR enter code: 20202021-3840
7. Follow on-screen instructions
8. Name device: "Bike Sensor"
9. Return to app - sensor should appear

Option 2: Via Home App

1. Open Home app
2. Tap "+" → "Add Accessory"
3. Scan QR code or enter setup code
4. Complete pairing process
5. Open FitnessSensorController app
6. Sensor appears automatically

Option 3: Via Settings

1. Open Settings app
2. Tap Home
3. Select your home
4. Tap "Add Accessory"
5. Scan or enter code

📲 Using the App

Main Control Screen

Test Workouts

1. Tap "Test Workouts" button
2. Browse 10 pre-built scenarios
3. Tap any workout to view details
4. Review segment breakdown
5. Tap "Start Workout"
6. Monitor real-time progress
7. Use controls:
   • Pause - Temporarily stop
   • Stop - End workout early
   • Skip - Jump to next segment

Quick Test Suite

1. Tap "Test Workouts"
2. Tap "Run Quick Test Suite"
3. Automatically tests all scenarios (2 min)
4. View pass/fail results

Siri Commands

Once paired, use voice commands:

Home Automations

Create automations in Home app:

When: 6:00 AM (Weekdays)
Actions:
  - Turn on Bike Sensor
  - Set intensity to 100
  - Turn on HomeKit lights
  - Play workout playlist

1. Turn on Bike Sensor
2. Set intensity to 127
3. Wait 5 seconds
4. Open Zwift app

🐛 Troubleshooting

App Issues

Pairing Issues

Debug Mode

Enable verbose logging in Xcode:

// In HomeManager class
func setOnOff(for accessory: HMAccessory, enabled: Bool, completion: @escaping (Bool) -> Void) {
    print("DEBUG: Setting power to \(enabled)")
    print("DEBUG: Accessory: \(accessory.uniqueIdentifier)")
    // ... existing code
}

View console output:

1. Window → Devices and Simulators
2. Select your device
3. Click Open Console

🎨 Customization

Change Theme Colors

// In DeviceControlView
.tint(.green)  // Change to .blue, .purple, etc.

Update Accent Color

1. Open Assets.xcassets
2. Select AccentColor
3. Change color in Attributes Inspector

Add Custom Workouts

// In WorkoutScenarios.swift
static func customWorkout() -> WorkoutScenario {
    let segments = [
        WorkoutSegment(duration: 300, intensityLevel: 100, name: "Warm-up"),
        WorkoutSegment(duration: 600, intensityLevel: 200, name: "Main Set"),
        WorkoutSegment(duration: 300, intensityLevel: 70, name: "Cool-down")
    ]
    return WorkoutScenario(type: .custom, segments: segments)
}

🚀 Advanced Features

HealthKit Integration (Future)

import HealthKit

func saveWorkout() {
    let workout = HKWorkout(
        activityType: .cycling,
        start: startDate,
        end: endDate
    )
    // Save to Health app
}

Apple Watch Companion (Future)

• Quick controls on wrist
• Real-time workout metrics
• Start/stop workouts
• View sensor status

📊 App Architecture

┌─────────────────────────────────────┐
│         SwiftUI Views               │
│  (ContentView, DeviceControlView)   │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│       HomeManager                   │
│  (ObservableObject State Manager)   │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│       HMHomeManager                 │
│    (Apple HomeKit Framework)        │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│      Matter/Thread Protocol         │
└──────────────┬──────────────────────┘
               │
         nRF52840 Device

✅ Development Checklist

• Xcode 14+ installed
• iOS 16.1+ device
• Apple Developer account
• Project created with correct settings
• Info.plist configured
• Entitlements added
• HomeKit capability enabled
• nRF52840 firmware flashed
• Device commissioned to HomeKit
• App builds successfully
• Sensor paired and visible
• Controls working