Core Motion

CoreMotion

Read device sensor data -- accelerometer, gyroscope, magnetometer, pedometer, activity recognition, altitude, headphone motion, batched motion, and submersion depth -- on iOS and watchOS. CoreMotion fuses raw sensor inputs into processed device-motion data and provides pedometer/activity APIs for fitness and navigation use cases. Targets Swift 6.3 / iOS 26+.

Contents

• Setup
• CMMotionManager: Sensor Data
• Processed Device Motion
• CMPedometer: Step and Distance Data
• CMMotionActivityManager: Activity Recognition
• CMAltimeter: Altitude Data
• Update Intervals and Battery
• Common Mistakes
• Review Checklist
• References

Setup

Info.plist

Add NSMotionUsageDescription to Info.plist with a user-facing string explaining why your app needs motion data. Without this key, the app crashes on first access.

<key>NSMotionUsageDescription</key>
<string>This app uses motion data to track your activity.</string>

Authorization

Use the matching manager's authorizationStatus() or authorizationStatus property when an API exposes one (CMPedometer, CMMotionActivityManager, CMAltimeter, headphone motion, batched sensors, and submersion). Raw CMMotionManager accelerometer/gyro/device-motion streams have no explicit authorization request API; still ship the usage string and handle errors from start/update callbacks.

import CoreMotion

let status = CMMotionActivityManager.authorizationStatus()
switch status {
case .notDetermined:
    // Will prompt on first use
    break
case .authorized:
    break
case .restricted, .denied:
    // Direct user to Settings
    break
@unknown default:
    break
}

CMMotionManager: Sensor Data

Create exactly one CMMotionManager per app. Multiple instances degrade sensor update rates.

import CoreMotion

let motionManager = CMMotionManager()

Accelerometer Updates

guard motionManager.isAccelerometerAvailable else { return }

motionManager.accelerometerUpdateInterval = 1.0 / 60.0  // 60 Hz

motionManager.startAccelerometerUpdates(to: .main) { data, error in
    guard let acceleration = data?.acceleration else { return }
    print("x: \(acceleration.x), y: \(acceleration.y), z: \(acceleration.z)")
}

// When done:
motionManager.stopAccelerometerUpdates()

Gyroscope Updates

guard motionManager.isGyroAvailable else { return }

motionManager.gyroUpdateInterval = 1.0 / 60.0

motionManager.startGyroUpdates(to: .main) { data, error in
    guard let rotationRate = data?.rotationRate else { return }
    print("x: \(rotationRate.x), y: \(rotationRate.y), z: \(rotationRate.z)")
}

motionManager.stopGyroUpdates()

Polling Pattern (Games)

For games, start updates without a handler and poll the latest sample each frame:

motionManager.startAccelerometerUpdates()

// In your game loop / display link:
if let data = motionManager.accelerometerData {
    let tilt = data.acceleration.x
    // Move player based on tilt
}

Processed Device Motion

Device motion fuses accelerometer, gyroscope, and magnetometer into a single CMDeviceMotion object with attitude, user acceleration (gravity removed), rotation rate, and calibrated magnetic field.

When giving device-motion guidance, show the runtime frame check in the snippet instead of hard-coding a corrected, magnetic-north, or true-north frame. Fall back to .xArbitraryZVertical when the preferred frame is unavailable.

guard motionManager.isDeviceMotionAvailable else { return }

let availableFrames = CMMotionManager.availableAttitudeReferenceFrames()
let frame: CMAttitudeReferenceFrame = availableFrames.contains(.xArbitraryCorrectedZVertical)
    ? .xArbitraryCorrectedZVertical
    : .xArbitraryZVertical

motionManager.deviceMotionUpdateInterval = 1.0 / 60.0

motionManager.startDeviceMotionUpdates(
    using: frame,
    to: .main
) { motion, error in
    guard let motion else { return }

    let attitude = motion.attitude       // roll, pitch, yaw
    let userAccel = motion.userAcceleration
    let gravity = motion.gravity
    let heading = motion.heading         // degrees relative to the current frame

    print("Pitch: \(attitude.pitch), Roll: \(attitude.roll)")
}

motionManager.stopDeviceMotionUpdates()

Attitude Reference Frames

For simple tilt controls, use .xArbitraryZVertical or .xArbitraryCorrectedZVertical; they avoid magnetometer/location dependencies. Before requesting corrected, magnetic-north, or true-north frames, call CMMotionManager.availableAttitudeReferenceFrames() and fall back to an available frame.

Check available frames before use:

let available = CMMotionManager.availableAttitudeReferenceFrames()
if available.contains(.xTrueNorthZVertical) {
    // Safe to use true north
}

CMPedometer: Step and Distance Data

CMPedometer provides step counts, distance, pace, cadence, and floor counts.

let pedometer = CMPedometer()

guard CMPedometer.isStepCountingAvailable() else { return }

// Historical query
pedometer.queryPedometerData(
    from: Calendar.current.startOfDay(for: Date()),
    to: Date()
) { data, error in
    guard let data else { return }
    print("Steps today: \(data.numberOfSteps)")
    print("Distance: \(data.distance?.doubleValue ?? 0) meters")
    print("Floors up: \(data.floorsAscended?.intValue ?? 0)")
}

// Live updates
pedometer.startUpdates(from: Date()) { data, error in
    guard let data else { return }
    print("Steps: \(data.numberOfSteps)")
}

// Stop when done
pedometer.stopUpdates()

Availability Checks

CMMotionActivityManager: Activity Recognition

Detects whether the user is stationary, walking, running, cycling, or in a vehicle.

let activityManager = CMMotionActivityManager()

guard CMMotionActivityManager.isActivityAvailable() else { return }

// Live activity updates
activityManager.startActivityUpdates(to: .main) { activity in
    guard let activity else { return }

    if activity.walking {
        print("Walking (confidence: \(activity.confidence.rawValue))")
    } else if activity.running {
        print("Running")
    } else if activity.automotive {
        print("In vehicle")
    } else if activity.cycling {
        print("Cycling")
    } else if activity.stationary {
        print("Stationary")
    }
}

activityManager.stopActivityUpdates()

Historical Activity Query

let yesterday = Calendar.current.date(byAdding: .day, value: -1, to: Date())!

activityManager.queryActivityStarting(
    from: yesterday,
    to: Date(),
    to: .main
) { activities, error in
    guard let activities else { return }
    for activity in activities {
        print("\(activity.startDate): walking=\(activity.walking)")
    }
}

CMAltimeter: Altitude Data

Altimeter access is covered by NSMotionUsageDescription; handle denied motion access through unavailable data and update-handler errors.

let altimeter = CMAltimeter()

guard CMAltimeter.isRelativeAltitudeAvailable() else { return }

altimeter.startRelativeAltitudeUpdates(to: .main) { data, error in
    guard let data else { return }
    print("Relative altitude: \(data.relativeAltitude) meters")
    print("Pressure: \(data.pressure) kPa")
}

altimeter.stopRelativeAltitudeUpdates()

Absolute altitude is altitude relative to sea level, not GPS-based altitude. First check availability. Absolute altitude is available only on supported hardware such as iPhone 12 or later and Apple Watch Series 6, Apple Watch SE, or later.

guard CMAltimeter.isAbsoluteAltitudeAvailable() else { return }

altimeter.startAbsoluteAltitudeUpdates(to: .main) { data, error in
    guard let data else { return }
    print("Altitude: \(data.altitude)m, accuracy: \(data.accuracy)m")
}

altimeter.stopAbsoluteAltitudeUpdates()

Update Intervals and Battery

Use the lowest frequency that meets your needs. Do not assume a fixed maximum sample rate across devices. For high-frequency workout motion, use CMBatchedSensorManager where supported and read its reported accelerometerDataFrequency or deviceMotionDataFrequency instead of assigning those read-only properties.

Common Mistakes

DON'T: Create multiple CMMotionManager instances

// WRONG -- degrades update rates for all instances
class ViewA { let motion = CMMotionManager() }
class ViewB { let motion = CMMotionManager() }

// CORRECT -- single instance, shared across the app
@Observable
final class MotionService {
    static let shared = MotionService()
    let manager = CMMotionManager()
}

DON'T: Skip sensor availability checks

// WRONG -- crashes on devices without gyroscope
motionManager.startGyroUpdates(to: .main) { data, _ in }

// CORRECT -- check first
guard motionManager.isGyroAvailable else {
    showUnsupportedMessage()
    return
}
motionManager.startGyroUpdates(to: .main) { data, _ in }

DON'T: Forget to stop updates

// WRONG -- updates keep running, draining battery
class MotionVC: UIViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        motionManager.startAccelerometerUpdates(to: .main) { _, _ in }
    }
    // Missing viewDidDisappear stop!
}

// CORRECT -- stop in the counterpart lifecycle method
override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    motionManager.stopAccelerometerUpdates()
}

DON'T: Use unnecessarily high update rates

// WRONG -- 100 Hz for a compass display
motionManager.deviceMotionUpdateInterval = 1.0 / 100.0

// CORRECT -- 10 Hz is more than enough for a compass
motionManager.deviceMotionUpdateInterval = 1.0 / 10.0

DON'T: Assume all CMMotionActivity properties are mutually exclusive

// WRONG -- checking only one property
if activity.walking { handleWalking() }

// CORRECT -- multiple can be true simultaneously; check confidence
if activity.walking && activity.confidence == .high {
    handleWalking()
} else if activity.automotive && activity.confidence != .low {
    handleDriving()
}

Review Checklist

• [ ] NSMotionUsageDescription present in Info.plist with a clear explanation
• [ ] Single CMMotionManager instance shared across the app
• [ ] Sensor availability checked before starting updates (isAccelerometerAvailable, etc.)
• [ ] Authorization status checked before pedometer/activity APIs
• [ ] Update interval set to the lowest acceptable frequency
• [ ] All start*Updates calls have matching stop*Updates in lifecycle counterparts
• [ ] Handlers dispatched to appropriate queues (not blocking main for heavy processing)
• [ ] CMMotionActivity.confidence checked before acting on activity type
• [ ] Error parameters checked in update handlers
• [ ] Device-motion snippets call CMMotionManager.availableAttitudeReferenceFrames() before requesting a specific attitude frame
• [ ] Attitude reference frame chosen based on actual need (not defaulting to true north unnecessarily)

References

• Extended patterns (SwiftUI integration, batched sensor manager, headphone motion, water submersion): references/motion-patterns.md
• CoreMotion framework
• CMMotionManager
• CMPedometer
• CMMotionActivityManager
• CMDeviceMotion
• CMAltimeter
• CMAbsoluteAltitudeData
• CMBatchedSensorManager
• CMHeadphoneMotionManager
• CMWaterSubmersionManager
• Accessing submersion data
• Getting processed device-motion data

CoreMotion Extended Patterns

Overflow reference for the core-motion skill. Contains advanced patterns that exceed the main skill file's scope.

Contents

• SwiftUI Integration with `@Observable`
• CMBatchedSensorManager (High-Frequency)
• Headphone Motion
• Pedometer SwiftUI View
• Activity-Based Navigation
• Water Submersion (watchOS)

SwiftUI Integration with @Observable

Motion Manager Service

import CoreMotion
import SwiftUI

@Observable
@MainActor
final class MotionService {
    static let shared = MotionService()

    private let manager = CMMotionManager()

    var pitch: Double = 0
    var roll: Double = 0
    var yaw: Double = 0
    var userAcceleration: CMAcceleration = CMAcceleration()
    var isActive = false

    func startDeviceMotion(interval: TimeInterval = 1.0 / 60.0) {
        guard manager.isDeviceMotionAvailable, !isActive else { return }

        manager.deviceMotionUpdateInterval = interval
        manager.startDeviceMotionUpdates(
            using: .xArbitraryZVertical,
            to: .main
        ) { [weak self] motion, error in
            guard let self, let motion else { return }
            self.pitch = motion.attitude.pitch
            self.roll = motion.attitude.roll
            self.yaw = motion.attitude.yaw
            self.userAcceleration = motion.userAcceleration
        }
        isActive = true
    }

    func stop() {
        manager.stopDeviceMotionUpdates()
        isActive = false
    }
}

SwiftUI View Using Motion

struct TiltView: View {
    @State private var motionService = MotionService.shared

    var body: some View {
        VStack {
            Circle()
                .fill(.blue)
                .frame(width: 60, height: 60)
                .offset(
                    x: motionService.roll * 100,
                    y: motionService.pitch * 100
                )

            Text("Roll: \(motionService.roll, format: .number.precision(.fractionLength(2)))")
            Text("Pitch: \(motionService.pitch, format: .number.precision(.fractionLength(2)))")
        }
        .onAppear { motionService.startDeviceMotion() }
        .onDisappear { motionService.stop() }
    }
}

Level Indicator

struct LevelIndicator: View {
    @State private var motionService = MotionService.shared

    private var isLevel: Bool {
        abs(motionService.pitch) < 0.05 && abs(motionService.roll) < 0.05
    }

    var body: some View {
        ZStack {
            Circle()
                .stroke(isLevel ? .green : .gray, lineWidth: 3)
                .frame(width: 200, height: 200)

            Circle()
                .fill(isLevel ? .green : .red)
                .frame(width: 20, height: 20)
                .offset(
                    x: motionService.roll * 100,
                    y: motionService.pitch * -100
                )
        }
        .onAppear { motionService.startDeviceMotion(interval: 1.0 / 30.0) }
        .onDisappear { motionService.stop() }
    }
}

CMBatchedSensorManager (High-Frequency)

CMBatchedSensorManager delivers batches of high-frequency accelerometer and device-motion data for workout-style motion analysis, such as golf swings or bat swings. The async update sequences are watchOS 10+ APIs; check availability and authorization before starting updates.

AsyncSequence Pattern

import CoreMotion

@Observable
@MainActor
final class BatchedMotionService {
    private let batchedManager = CMBatchedSensorManager()
    private var updateTask: Task<Void, Never>?

    var latestAcceleration: CMAcceleration?

    func startBatchedAccelerometer() {
        let authorization = CMBatchedSensorManager.authorizationStatus
        guard CMBatchedSensorManager.isAccelerometerSupported,
              authorization != .denied,
              authorization != .restricted else { return }

        updateTask = Task {
            for await batch in batchedManager.accelerometerUpdates() {
                guard !Task.isCancelled else { break }
                // Process entire batch
                for sample in batch {
                    // sample.acceleration, sample.timestamp
                }
                // Update UI with most recent
                if let latest = batch.last {
                    latestAcceleration = latest.acceleration
                }
            }
        }
    }

    func stop() {
        updateTask?.cancel()
        updateTask = nil
        batchedManager.stopAccelerometerUpdates()
    }
}

Reading Frequency

let batchedManager = CMBatchedSensorManager()

// Start updates, then read the frequency the device reports.
batchedManager.startAccelerometerUpdates()
let reportedHz = batchedManager.accelerometerDataFrequency

accelerometerDataFrequency and deviceMotionDataFrequency are read-only. Do not assign them; use the reported values to size buffers, throttle UI updates, or downsample processed results.

Headphone Motion

Track head motion using AirPods Pro / AirPods Max via CMHeadphoneMotionManager. On iOS and macOS, include NSMotionUsageDescription. Use connection-status updates when the app needs connect/disconnect events outside an active motion session.

import CoreMotion

@Observable
@MainActor
final class HeadphoneMotionService: NSObject {
    private let headphoneManager = CMHeadphoneMotionManager()

    var isConnected = false
    var headPitch: Double = 0
    var headYaw: Double = 0

    func start() {
        guard headphoneManager.isDeviceMotionAvailable else { return }

        headphoneManager.delegate = self
        headphoneManager.startConnectionStatusUpdates()
        headphoneManager.startDeviceMotionUpdates(to: .main) { [weak self] motion, error in
            guard let self, let motion else { return }
            self.headPitch = motion.attitude.pitch
            self.headYaw = motion.attitude.yaw
        }
    }

    func stop() {
        headphoneManager.stopDeviceMotionUpdates()
        headphoneManager.stopConnectionStatusUpdates()
    }
}

extension HeadphoneMotionService: CMHeadphoneMotionManagerDelegate {
    nonisolated func headphoneMotionManagerDidConnect(
        _ manager: CMHeadphoneMotionManager
    ) {
        Task { @MainActor in isConnected = true }
    }

    nonisolated func headphoneMotionManagerDidDisconnect(
        _ manager: CMHeadphoneMotionManager
    ) {
        Task { @MainActor in isConnected = false }
    }
}

Pedometer SwiftUI View

Step Counter Dashboard

import CoreMotion
import SwiftUI

@Observable
@MainActor
final class PedometerService {
    private let pedometer = CMPedometer()

    var todaySteps: Int = 0
    var todayDistance: Double = 0
    var floorsAscended: Int = 0

    func fetchToday() {
        guard CMPedometer.isStepCountingAvailable() else { return }

        let startOfDay = Calendar.current.startOfDay(for: Date())

        pedometer.queryPedometerData(from: startOfDay, to: Date()) { [weak self] data, error in
            guard let self, let data else { return }
            Task { @MainActor in
                self.todaySteps = data.numberOfSteps.intValue
                self.todayDistance = data.distance?.doubleValue ?? 0
                self.floorsAscended = data.floorsAscended?.intValue ?? 0
            }
        }
    }

    func startLiveUpdates() {
        guard CMPedometer.isStepCountingAvailable() else { return }

        let startOfDay = Calendar.current.startOfDay(for: Date())

        pedometer.startUpdates(from: startOfDay) { [weak self] data, error in
            guard let self, let data else { return }
            Task { @MainActor in
                self.todaySteps = data.numberOfSteps.intValue
                self.todayDistance = data.distance?.doubleValue ?? 0
                self.floorsAscended = data.floorsAscended?.intValue ?? 0
            }
        }
    }

    func stopLiveUpdates() {
        pedometer.stopUpdates()
    }
}

SwiftUI Dashboard View

struct StepDashboard: View {
    @State private var pedometerService = PedometerService()

    var body: some View {
        List {
            Section("Today") {
                LabeledContent("Steps") {
                    Text("\(pedometerService.todaySteps)")
                }
                LabeledContent("Distance") {
                    Text(
                        Measurement(value: pedometerService.todayDistance, unit: UnitLength.meters),
                        format: .measurement(width: .abbreviated)
                    )
                }
                if CMPedometer.isFloorCountingAvailable() {
                    LabeledContent("Floors Climbed") {
                        Text("\(pedometerService.floorsAscended)")
                    }
                }
            }
        }
        .onAppear { pedometerService.startLiveUpdates() }
        .onDisappear { pedometerService.stopLiveUpdates() }
    }
}

Activity-Based Navigation

Switch between driving and walking modes automatically:

import CoreMotion

@Observable
@MainActor
final class NavigationModeService {
    private let activityManager = CMMotionActivityManager()

    enum Mode: String {
        case walking, driving, cycling, unknown
    }

    var currentMode: Mode = .unknown

    func startMonitoring() {
        guard CMMotionActivityManager.isActivityAvailable() else { return }

        activityManager.startActivityUpdates(to: .main) { [weak self] activity in
            guard let self, let activity,
                  activity.confidence != .low else { return }

            Task { @MainActor in
                if activity.automotive {
                    self.currentMode = .driving
                } else if activity.cycling {
                    self.currentMode = .cycling
                } else if activity.walking || activity.running {
                    self.currentMode = .walking
                } else if activity.stationary {
                    // Keep previous mode when stationary (e.g., at a stoplight)
                }
            }
        }
    }

    func stopMonitoring() {
        activityManager.stopActivityUpdates()
    }
}

Water Submersion (watchOS)

Track water depth and temperature for dive apps on supported Apple Watch hardware. Use waterSubmersionAvailable rather than hard-coding model checks: Apple Watch Ultra supports submersion data, and Apple Watch Series 10 supports the Shallow Depth and Pressure capability.

Setup checklist:

• Add NSMotionUsageDescription.
• Add the Shallow Depth and Pressure capability for dives up to 6 meters, or

apply for the full Submerged Depth and Pressure entitlement for dives up to 40 meters.

• Add WKBackgroundModes with underwater-depth so the app can remain

frontmost and eligible for dive autolaunch.

• Check availability before instantiating CMWaterSubmersionManager.

import CoreMotion

@Observable
@MainActor
final class DiveService: NSObject {
    private var submersionManager: CMWaterSubmersionManager?

    var isSubmerged = false
    var currentDepth: Double?
    var waterTemperature: Double?

    func start() {
        guard CMWaterSubmersionManager.waterSubmersionAvailable else { return }
        let manager = CMWaterSubmersionManager()
        manager.delegate = self
        submersionManager = manager
    }
}

extension DiveService: CMWaterSubmersionManagerDelegate {
    nonisolated func manager(
        _ manager: CMWaterSubmersionManager,
        didUpdate event: CMWaterSubmersionEvent
    ) {
        Task { @MainActor in
            isSubmerged = event.state == .submerged
        }
    }

    nonisolated func manager(
        _ manager: CMWaterSubmersionManager,
        didUpdate measurement: CMWaterSubmersionMeasurement
    ) {
        Task { @MainActor in
            currentDepth = measurement.depth?.value
        }
    }

    nonisolated func manager(
        _ manager: CMWaterSubmersionManager,
        didUpdate temperature: CMWaterTemperature
    ) {
        Task { @MainActor in
            waterTemperature = temperature.temperature.value
        }
    }

    nonisolated func manager(
        _ manager: CMWaterSubmersionManager,
        errorOccurred error: any Error
    ) {
        print("Submersion error: \(error)")
    }
}

Important: CMWaterSubmersionManager requires the Shallow Depth and Pressure capability or the full Submerged Depth and Pressure entitlement. If the app lacks the entitlement, the delegate receives CMError.notEntitled and no submersion data.