How PowerSampler Reads SMC Sensor Data for System Watts in vorssaint-utils

The PowerSampler class in vorssaint-utils reads system watts directly from the macOS SMC using the "PSTR" key, validates the data through a plausible range filter, and returns it as part of a PowerReading struct.

The vorssaint-utils repository provides macOS system monitoring capabilities through Swift implementations that interface directly with hardware controllers. The PowerSampler component specifically handles power consumption metrics by querying the System Management Controller (SMC) for raw sensor data. Understanding how this class extracts and processes system wattage reveals the low-level mechanisms behind real-time power monitoring on Apple hardware.

SMC Client Initialization and Setup

When instantiating a PowerSampler, the initializer accepts an optional SMCClient instance via init(smc: SMCClient?). This client serves as the thin wrapper around macOS's low-level SMC interfaces, providing the bridge between Swift code and kernel-level hardware communication. The sampler retains this client for the duration of its lifecycle, using it to resolve keys and read sensor values during each sampling cycle.

Resolving SMC Keys for Power Metrics

On the first call to sample(), the sampler resolves two specific SMC keys defined as static constants within the class. According to the source in Sources/Vorssaint/Services/Metrics/PowerSampler.swift (lines 50-54), these keys are:

• "PSTR" for system power consumption
• "PDTR" for adapter power consumption

The resolution occurs through the SMC client's key(named:) method:

systemKey = smc.key(named: Self.systemPowerKey)   // "PSTR"
adapterKey = smc.key(named: Self.adapterPowerKey) // "PDTR"

Reading and Validating Wattage Values

Once keys are resolved, PowerSampler reads raw double values and applies validation logic through the private plausibleWatts(_:) helper method. Located at lines 33-36 in PowerSampler.swift, this function filters out impossible readings by checking that values are greater than 0 watts and less than 1000 watts.

The validated values are then stored in a PowerReading struct:

reading.systemWatts = plausibleWatts(systemKey)
reading.adapterWatts = plausibleWatts(adapterKey)

These assignments occur inside the sample() method implementation (lines 68-76).

Post-Processing and Battery Integration

After obtaining raw SMC values, PowerSampler processes them through MetricFormat.systemPowerWatts(...) to apply adjustments for battery states and external power sources. This post-processing step (lines 25-31) ensures accurate reporting whether the Mac runs on battery or AC power.

For machines with internal batteries, the sampler queries the AppleSmartBattery IORegistry entry via resolvedBatteryService(). This provides supplementary data including charging state, health metrics, and capacity information. The presence of an internal battery is cached once per boot using the hasInternalBattery property (lines 34-42), avoiding redundant registry lookups during subsequent sampling cycles.

Implementation Example

The following pattern demonstrates proper PowerSampler instantiation and usage, mirroring the integration found in SystemMonitor.swift (lines 887-891):

import Vorssaint

// Obtain an SMC client (typically injected by the app lifecycle)
let smcClient = SMCClient()

// Create the sampler with the SMC client
let powerSampler = PowerSampler(smc: smcClient)

// Grab a fresh reading
let reading = powerSampler.sample()

if let watts = reading.systemWatts {
    print("System is consuming \(watts) W")
}

Summary

• PowerSampler initializes with an SMCClient instance that provides low-level hardware access without requiring elevated permissions
• System wattage is read from the SMC key "PSTR" and adapter power from "PDTR", resolved via smc.key(named:)
• The plausibleWatts(_:) helper validates readings fall within the 0-1000W range before accepting them into the PowerReading struct
• Raw values undergo post-processing via MetricFormat.systemPowerWatts(...) to handle battery and power adapter states
• Battery-equipped systems receive supplementary data from AppleSmartBattery IORegistry queries, with presence cached via hasInternalBattery to optimize performance

Frequently Asked Questions

What SMC key does PowerSampler use to read system watts?

The PowerSampler reads system watts from the SMC key "PSTR" (system power total). It also reads "PDTR" for adapter power metrics. These keys are resolved through the SMC client's key(named:) method during the first call to sample(), as implemented in PowerSampler.swift.

How does PowerSampler validate SMC sensor readings?

The class validates readings using the private plausibleWatts(_:) helper method defined at lines 33-36, which filters out values less than or equal to 0 watts or greater than or equal to 1000 watts. This ensures only physically possible power consumption values are returned in the PowerReading struct.

Does PowerSampler require special permissions to access SMC data?

According to the vorssaint-utils source code, reading SMC keys for power metrics does not require elevated user permissions. The SMCClient wrapper handles the low-level kernel communication transparently, allowing the sampler to provide real-time data without privileged access.

How does the sampler handle Macs with internal batteries?

For battery-equipped systems, PowerSampler queries the AppleSmartBattery IORegistry entry via resolvedBatteryService() to supplement power readings with charging state and health data. The presence of an internal battery is cached in hasInternalBattery once per boot to optimize performance across multiple sampling cycles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}