Core Motion

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

Access Core Motion accelerometer, gyroscope, magnetometer, device-motion, pedometer, activity-recognition, altitude, headphone motion, batched high-frequency workout motion, and water-submersion/depth data. Use when reading device sensors, counting steps, detecting walking/running/driving/cycling, tracking altitude, building motion interactions, handling AirPods head tracking, or implementing watchOS dive/depth features.

Instructions onlySoftware Development

AI-generated overview

Guides Swift developers in reading Apple Core Motion sensor data, including accelerometer, gyroscope, pedometer, activity, and altitude.

What it does: This skill provides reference guidance and code snippets for using Apple's Core Motion framework in Swift 6.3 on iOS 26 and later. It covers setup requirements, authorization, CMMotionManager sensor streams, processed device motion, CMPedometer, CMMotionActivityManager, CMAltimeter, update intervals, common mistakes, and a review checklist. It produces instructional documentation rather than executable code.
When to use it: Use when implementing or reviewing iOS/watchOS features that read device sensors, count steps, detect walking or driving, track altitude, or handle headphone and submersion motion. It is intended for developers working with Core Motion APIs who need setup, authorization, and best-practice guidance.
Requirements: No scripts or runtime dependencies beyond an AI agent. The guidance targets Swift 6.3 and iOS 26+, and mentions Info.plist configuration and device sensor availability.

CoreMotion

Read device motion, pedometer/activity, altitude, headphone, batched-workout, and submersion sensors with Core Motion. Scope: Swift 6.3, iOS 26+.

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.

xml

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

<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.

swift

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

import CoreMotion
let status = CMMotionActivityManager.authorizationStatus()switch status {case .notDetermined:    // Will prompt on first use    breakcase .authorized:    breakcase .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.

Accelerometer Updates

swift

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()

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

swift

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()

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:

swift

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

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.

swift

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()

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.

Frame	Use Case
`.xArbitraryZVertical`	Default. Z is vertical, X arbitrary at start. Most games.
`.xArbitraryCorrectedZVertical`	Same as above, corrected for gyro drift over time.
`.xMagneticNorthZVertical`	X points to magnetic north. Requires magnetometer.
`.xTrueNorthZVertical`	X points to true north. Requires magnetometer + location.

Check available frames before use:

swift

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

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.

swift

let pedometer = CMPedometer()
guard CMPedometer.isStepCountingAvailable() else { return }
// Historical querypedometer.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 updatespedometer.startUpdates(from: Date()) { data, error in    guard let data else { return }    print("Steps: \(data.numberOfSteps)")}
// Stop when donepedometer.stopUpdates()

let pedometer = CMPedometer()
guard CMPedometer.isStepCountingAvailable() else { return }
// Historical querypedometer.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 updatespedometer.startUpdates(from: Date()) { data, error in    guard let data else { return }    print("Steps: \(data.numberOfSteps)")}
// Stop when donepedometer.stopUpdates()

Availability Checks

Method	What It Checks
`isStepCountingAvailable()`	Step counter hardware
`isDistanceAvailable()`	Distance estimation
`isFloorCountingAvailable()`	Barometric altimeter for floors
`isPaceAvailable()`	Pace data
`isCadenceAvailable()`	Cadence data

CMMotionActivityManager: Activity Recognition

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

swift

let activityManager = CMMotionActivityManager()
guard CMMotionActivityManager.isActivityAvailable() else { return }
// Live activity updatesactivityManager.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()

let activityManager = CMMotionActivityManager()
guard CMMotionActivityManager.isActivityAvailable() else { return }
// Live activity updatesactivityManager.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

swift

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)")    }}

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.

swift

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()

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.

swift

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()

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

Retain one app-level CMMotionManager; competing instances can reduce update rates.

DON'T: Skip sensor availability checks

Apply the matching is...Available gate immediately before starting each sensor stream.

DON'T: Forget to stop updates

Pair every start with the matching stop in the counterpart lifecycle or task cancellation path.

DON'T: Use unnecessarily high update rates

Choose the lowest rate that meets the interaction and use the Update Intervals and Battery table as a starting point.

DON'T: Assume all CMMotionActivity properties are mutually exclusive

swift

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

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

Review Checklist

References

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

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/core-motionat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

Interval	Hz	Use Case	Battery Impact
`1.0 / 10.0`	10	UI orientation	Low
`1.0 / 30.0`	30	Casual games	Moderate
`1.0 / 60.0`	60	Action games	High
`1.0 / 100.0`	100	Max rate (iPhone)	Very High

Core Motion

CoreMotion

Contents

Setup

Info.plist

Authorization

CMMotionManager: Sensor Data

Accelerometer Updates

Gyroscope Updates

Polling Pattern (Games)

Processed Device Motion

Attitude Reference Frames

CMPedometer: Step and Distance Data

Availability Checks

CMMotionActivityManager: Activity Recognition

Historical Activity Query

CMAltimeter: Altitude Data

Update Intervals and Battery

Common Mistakes

DON'T: Create multiple CMMotionManager instances

DON'T: Skip sensor availability checks

DON'T: Forget to stop updates

DON'T: Use unnecessarily high update rates

DON'T: Assume all CMMotionActivity properties are mutually exclusive

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices