Thermal metrics
Sources: Collectors/PowerThermalGPU.swift (ThermalLevel, PowerMath.batteryFields, SensorCapabilityResolver), Metrics/Metric.swift, App/Sources/Features/SystemViews.swift (ThermalView), App/Sources/Features/DashboardView.swift (ThermalText, ThermalScale).
Position
ORIX Monitor reports the thermal state — the operating system's own assessment — and nothing it would have to obtain from the System Management Controller. It shows no CPU temperature, no GPU temperature and no fan speed. Those rows appear on the Thermal & Sensors page marked "Unavailable" with the sentence "Not available through supported system interfaces."
Stored metrics
Key (MetricID) |
Name | Unit | Quality | Source API | Stored value | Refresh |
|---|---|---|---|---|---|---|
thermal.state (thermalState) |
Thermal state | level | measured | ProcessInfo.thermalState |
0 = nominal, 1 = fair, 2 = serious, 3 = critical | every tick of the fast tier (2 s by default while a window is visible) |
battery.temperature (batteryTemperature) |
Battery temperature | °C | bestEffort | IORegistry AppleSmartBattery (Temperature) |
value / 100 |
slow tier (30 s by default); only when the key exists |
thermal.state is the only metric that is always present in a tick's values: it needs no baseline and no hardware.
Thermal state
ThermalLevel.current() wraps ProcessInfo.processInfo.thermalState:
| Level | Raw value | Text shown (ThermalText.explanation) |
Colour role |
|---|---|---|---|
| Nominal | 0 | The system is within its normal thermal range. | success |
| Fair | 1 | The system is slightly warm. Performance is not affected. | primary text |
| Serious | 2 | The system is hot. macOS may reduce performance. | warning |
| Critical | 3 | The system is very hot. macOS is reducing performance to cool down. | danger |
An unknown future case of the system enum maps to nominal.
Properties of this signal:
- It is ordinal, not a temperature. There is no conversion to degrees and ORIX Monitor attempts none.
- It is the state macOS itself uses to decide about throttling, which makes it the relevant signal for "is heat affecting performance".
- It is stored as a number so it can be charted, aggregated per bucket (min / avg / max) and used in rules. Bucket averages can be fractional (for example 1.4 when the minute was partly fair and partly serious), so thresholds are placed halfway between levels:
- default alert:
thermal.stateabove 1.5 for 30 s → critical alert ("at or above Serious"); thermalPressurefinding: bucket average above 1.5 for at least 60 s; critical if the peak reached 3. See alerts.
- default alert:
- A change of thermal state (
ProcessInfo.thermalStateDidChangeNotification) also forces the slow-tier readings to refresh on the next tick.
There is no percentage convention for either thermal metric.
Display
| Place | Content |
|---|---|
| Thermal & Sensors page, "Thermal state" | Level name (large), caption "The system's own assessment", a four-step scale (ThermalScale), the explanation sentence |
| "Thermal state over time" | Live chart with the y axis labelled by level names (ticks at 0, 1, 2, 3) |
| Dashboard "Thermal state" widget | Level and scale |
| Menu bar panel header | Level name |
| History, Incident and System Overview reports | Stored series; the preview and PDF print level names |
The level name is always written out; the scale and the colour are secondary cues.
Battery temperature
The one temperature ORIX Monitor may display, and only as a best-effort value.
- Source: the
Temperatureproperty of theAppleSmartBatteryregistry entry (orBatteryData.Temperature), read withIORegistryEntryCreateCFProperties. The property name is not documented by Apple. - Conversion: hundredths of a degree Celsius →
value / 100. - Validation:
PowerMath.batteryFieldsdiscards the value unless it lies within −40…150 °C and is non-zero. An implausible reading yieldsnil, not a number (flatBatteryLayoutAndImplausibleTemperaturechecks that 99999 is rejected). - Gate: read only when "Read undocumented system properties" is on and the Mac has a battery.
- Formatting:
ValueFormatter.temperatureformats throughMeasurement<UnitTemperature>with the user's locale, one decimal.
On the audited Mac (MacBook Pro Mac17,6, macOS 27.0) the key is not published. The page then shows an unavailable row: "The battery gauge on this Mac and macOS version publishes no temperature." No battery.temperature series exists on that machine. The code path that displays the value is exercised by unit tests on a synthetic registry dictionary, not by a live reading.
A battery temperature is not a proxy for CPU temperature and is not presented as one.
The capability table
The Thermal & Sensors page also hosts "Sensor and metric availability on this Mac": the thirty rows of SensorCapabilityResolver.resolve() with a filter field. Columns: metric (with an explanatory note), area, access class (Public API / Needs your permission / System command / Needs a privileged helper / Not exposed / Estimate / Best effort), whether it could be read on this Mac just now, and the source. It is evaluated once at launch. The classification of every row is documented in the capability matrix.
Thermal-category rows:
| id | Name | Class | Present |
|---|---|---|---|
thermal.state |
Thermal state | Public API | always |
cpu.temperature |
CPU temperature | Not exposed | never |
gpu.temperature |
GPU temperature | Not exposed | never |
thermal.fans |
Fan speed | Not exposed | never |
battery.temperature |
Battery temperature | Best effort | when the registry key exists |
The live test capabilityMatrixIsHonest asserts that no row classified unavailable is ever marked present, and that fans and CPU temperature are classified unavailable.
Why no SMC readings
Stated on the page itself:
Chip temperatures and fan speeds exist only behind the System Management Controller and private sensor services. ORIX Monitor does not use them: they are undocumented, differ between Mac models, and can break with any update. The thermal state above is the supported signal.
In more detail:
- No documentation. SMC keys are four-character codes whose meaning Apple does not publish. Mappings in circulation come from reverse engineering.
- Model-specific. The set of keys and what each one measures changes between Mac models and chip generations. A table that is right on one Mac can be silently wrong on another.
- Wrong keys fail silently. A mis-identified sensor returns a plausible number. ORIX Monitor's rule is that a displayed number must be traceable to a supported interface or be labelled otherwise; an unlabelled plausible-but-wrong temperature is the exact outcome that rule exists to prevent.
- No stability guarantee. A system update can change or remove the interface.
- A supported alternative exists for the question users actually have ("is my Mac throttling because of heat?"): the thermal state.
A UI test (testUnavailableSensorsAreDeclaredNotInvented) opens this page and fails if the unavailable sentence is missing or if any text matching an "rpm" value is displayed.
Quality classes
measured— thermal state.bestEffort— battery temperature.unavailable— CPU temperature, GPU temperature, fan speed (displayed as such; not metrics).
Limitations
- Four levels only. The thermal state cannot distinguish "comfortably cool" from "about to become fair"; it gives no early warning in degrees.
- Sampled. A brief change of state between two samples is missed by the series, although the change notification still triggers a slow-tier refresh.
- No cause attribution. The state says the system is hot, not which component or process is responsible. The Insights text suggests checking vents and placement and states that one event does not indicate a hardware fault.
- Battery temperature availability depends on model and macOS version, and was absent on the only Mac audited.
- No fan information of any kind, including whether the Mac has fans.
Deliberately not shown
| Item | Reason |
|---|---|
| CPU temperature (die, cores, clusters) | SMC / private HID sensor services only. |
| GPU temperature | Same. |
| SSD / NAND temperature | NVMe SMART or SMC only. See disk. |
| Fan speed (RPM), fan count | SMC only. |
| Fan control | Would require writing to the SMC; out of the question for an app that installs no helper. |
| Ambient, palm-rest, airflow and other sensors | SMC only. |
| A temperature estimated from load or thermal state | It would be an invented number. |
| A "thermal pressure percentage" | The system publishes a level; no percentage exists to report. |