Skip to content

reference-index.md

Latest commit

 

History

History
268 lines (191 loc) · 11.7 KB

reference-index.md

File metadata and controls

268 lines (191 loc) · 11.7 KB
Raw

Developer Apple Reference Index

This document serves as a comprehensive index of Apple Developer documentation references used throughout HomeAtlas. All citations link to canonical HomeKit framework documentation.

Framework Overview

Core Types

Home Manager

Context Entities

Home

Room

Zone

Accessories

Services

Characteristics

Automation

Action Sets & Triggers

Error Handling

Testing

Entitlements & Privacy

Platform Availability

  • iOS: 8.0+
  • iPadOS: 8.0+
  • macOS: 10.14+ (via Mac Catalyst)
  • tvOS: 10.0+
  • watchOS: 2.0+
  • visionOS: 1.0+

Additional Resources

Snapshot Export API

Overview

The Snapshot Export API allows developers to serialize HomeKit home graphs to deterministic JSON format for debugging, backups, and data export scenarios.

  • Public API: HomeAtlas.encodeSnapshot(_:options:) async throws -> Data
  • Purpose: Export Home entities, relationships, and state to JSON
  • Thread Safety: @MainActor annotation ensures main-thread execution (required for HomeKit API access)
  • Performance: Typical export time ≤2 seconds for ~100 accessories with ~1000 characteristics

Usage

import HomeAtlas
import HomeKit

@MainActor
func exportHomeSnapshot(_ home: HMHome) async throws {
    // Basic export
    let jsonData = try await HomeAtlas.encodeSnapshot(home)

    // With anonymization for privacy
    let options = SnapshotOptions(anonymize: true)
    let anonymizedData = try await HomeAtlas.encodeSnapshot(home, options: options)

    // Save to file
    try jsonData.write(to: URL(fileURLWithPath: "home-snapshot.json"))
}

Typed Snapshots with Macros (HomeAtlas)

Swift 6 macros generate type-safe snapshot types for HomeAtlas classes using @Snapshotable. Generated types are suffixed with AtlasSnapshot to avoid conflicts with generic snapshot models.

@Snapshotable
public final class LightbulbService: Service { /* ... */ }

// Generated by macro:
public struct LightbulbServiceAtlasSnapshot: Codable, Sendable { /* typed fields */ }

// Example usage (async):
@MainActor
func captureTypedServiceSnapshot(_ service: LightbulbService) async throws -> LightbulbServiceAtlasSnapshot {
  try await LightbulbServiceAtlasSnapshot(from: service)
}

Applies to: Home, Room, Zone, Accessory, Service subclasses, Characteristic subclasses.

Snapshot Options

  • SnapshotOptions.anonymize: When true, redacts user-identifiable names and UUIDs while preserving structure
    • Home/Room/Accessory/Service names are hashed
    • UUIDs remain intact for relationship tracking
    • Metadata (manufacturer, model, firmware) preserved

Output Schema

JSON output follows the HomeAtlas Home Snapshot Schema:

{
  "id": "home-uuid",
  "name": "My Home",
  "rooms": [
    {
      "id": "room-uuid",
      "name": "Living Room",
      "accessories": [...]
    }
  ],
  "zones": [...],
  "metadata": null
}

Characteristic Value Handling

Characteristics follow @MainActor read semantics per HMCharacteristic.readValue():

  • Readable characteristics: Value captured if properties contains HMCharacteristicPropertyReadable
  • Permission-restricted: value: null, reason: "permission" when read access denied
  • Unavailable devices: value: null, reason: "unavailable" when device unreachable
  • Unknown errors: value: null, reason: "unknown" for other failures

Reference: Apple Developer - HMCharacteristic

Deterministic Ordering

All entities sorted lexicographically by name to ensure stable JSON output across exports:

  • Rooms sorted by name (ascending)
  • Zones sorted by name (ascending)
  • Accessories sorted by name (ascending)
  • Services sorted by serviceType, then name (ascending)
  • Characteristics sorted by characteristicType (ascending)

JSON keys output using JSONEncoder.outputFormatting = .sortedKeys for reproducibility.

Platform Availability

#if canImport(HomeKit)
// Full snapshot export available on iOS 18+, macOS 15+, etc.
#else
// Fallback: throws HomeKitError.platformUnavailable
#endif
  • HomeKit platforms: iOS 18.0+, macOS 15.0+, watchOS 11.0+, tvOS 18.0+
  • Non-HomeKit platforms: API available but throws HomeKitError.platformUnavailable with descriptive reason

Error Handling

All errors map to HomeKitError enum cases:

  • .homeManagement(operation:underlying:): Home/Room/Zone traversal failures
  • .accessoryOperation(accessoryID:operation:): Accessory/Service reading failures
  • .characteristicOperation(characteristicID:operation:): Characteristic value read failures
  • .platformUnavailable(reason:): HomeKit framework not available on current platform

Reference: HomeKitError.swift

Privacy Considerations

Personally Identifiable Information (PII) in snapshots:

  • Home/Room/Zone/Accessory/Service names (user-defined strings)
  • UUIDs (device-specific identifiers)

Recommendation: Use SnapshotOptions(anonymize: true) when sharing snapshots for debugging or support to redact PII.

Performance Notes

  • Export time scales linearly with accessory/characteristic count
  • Typical performance: 100 accessories with 1000 characteristics export in <2 seconds
  • Use async context to avoid blocking UI during large exports
  • Consider background queue for very large homes (200+ accessories)

Citation Format

All Developer Apple references in HomeAtlas source code follow this format:

/// Brief description.
///
/// - Reference: [Apple Developer - Type/Method Name](https://developer.apple.com/documentation/homekit/...)

For example:

/// A strongly-typed wrapper for HMAccessory.
///
/// - Reference: [Apple Developer - HMAccessory](https://developer.apple.com/documentation/homekit/hmaccessory)
@MainActor
public final class Accessory { ... }

Last Updated: November 11, 2025 Related: Service Extension, Troubleshooting Guide