SPB Git

Repository Public License

thermal.md 8.9 KB 134 lines markdown

1<!--2ORIX Monitor3File: docs/metrics/thermal.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Thermal metrics910Sources: `Collectors/PowerThermalGPU.swift` (`ThermalLevel`, `PowerMath.batteryFields`, `SensorCapabilityResolver`), `Metrics/Metric.swift`, `App/Sources/Features/SystemViews.swift` (`ThermalView`), `App/Sources/Features/DashboardView.swift` (`ThermalText`, `ThermalScale`).1112## Position1314ORIX 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."1516## Stored metrics1718| Key (`MetricID`) | Name | Unit | Quality | Source API | Stored value | Refresh |19|---|---|---|---|---|---|---|20| `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) |21| `battery.temperature` (`batteryTemperature`) | Battery temperature | °C | bestEffort | IORegistry `AppleSmartBattery` (`Temperature`) | `value / 100` | slow tier (30 s by default); only when the key exists |2223`thermal.state` is the only metric that is **always** present in a tick's values: it needs no baseline and no hardware.2425## Thermal state2627`ThermalLevel.current()` wraps `ProcessInfo.processInfo.thermalState`:2829| Level | Raw value | Text shown (`ThermalText.explanation`) | Colour role |30|---|---|---|---|31| Nominal | 0 | The system is within its normal thermal range. | success |32| Fair | 1 | The system is slightly warm. Performance is not affected. | primary text |33| Serious | 2 | The system is hot. macOS may reduce performance. | warning |34| Critical | 3 | The system is very hot. macOS is reducing performance to cool down. | danger |3536An unknown future case of the system enum maps to nominal.3738Properties of this signal:3940- It is **ordinal, not a temperature**. There is no conversion to degrees and ORIX Monitor attempts none.41- It is the state macOS itself uses to decide about throttling, which makes it the relevant signal for "is heat affecting performance".42- 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:43  - default alert: `thermal.state` above 1.5 for 30 s → critical alert ("at or above Serious");44  - `thermalPressure` finding: bucket average above 1.5 for at least 60 s; critical if the peak reached 3.45  See [alerts](../architecture/alerts.md).46- A change of thermal state (`ProcessInfo.thermalStateDidChangeNotification`) also forces the slow-tier readings to refresh on the next tick.4748There is no percentage convention for either thermal metric.4950### Display5152| Place | Content |53|---|---|54| Thermal & Sensors page, "Thermal state" | Level name (large), caption "The system's own assessment", a four-step scale (`ThermalScale`), the explanation sentence |55| "Thermal state over time" | Live chart with the y axis labelled by level names (ticks at 0, 1, 2, 3) |56| Dashboard "Thermal state" widget | Level and scale |57| Menu bar panel header | Level name |58| History, Incident and System Overview reports | Stored series; the preview and PDF print level names |5960The level name is always written out; the scale and the colour are secondary cues.6162## Battery temperature6364The one temperature ORIX Monitor may display, and only as a best-effort value.6566- **Source:** the `Temperature` property of the `AppleSmartBattery` registry entry (or `BatteryData.Temperature`), read with `IORegistryEntryCreateCFProperties`. The property name is not documented by Apple.67- **Conversion:** hundredths of a degree Celsius → `value / 100`.68- **Validation:** `PowerMath.batteryFields` discards the value unless it lies within −40…150 °C and is non-zero. An implausible reading yields `nil`, not a number (`flatBatteryLayoutAndImplausibleTemperature` checks that 99999 is rejected).69- **Gate:** read only when "Read undocumented system properties" is on and the Mac has a battery.70- **Formatting:** `ValueFormatter.temperature` formats through `Measurement<UnitTemperature>` with the user's locale, one decimal.7172**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.7374A battery temperature is not a proxy for CPU temperature and is not presented as one.7576## The capability table7778The 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](../research/macos-capability-matrix.md).7980Thermal-category rows:8182| id | Name | Class | Present |83|---|---|---|---|84| `thermal.state` | Thermal state | Public API | always |85| `cpu.temperature` | CPU temperature | Not exposed | never |86| `gpu.temperature` | GPU temperature | Not exposed | never |87| `thermal.fans` | Fan speed | Not exposed | never |88| `battery.temperature` | Battery temperature | Best effort | when the registry key exists |8990The live test `capabilityMatrixIsHonest` asserts that no row classified `unavailable` is ever marked present, and that fans and CPU temperature are classified `unavailable`.9192## Why no SMC readings9394Stated on the page itself:9596> 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.9798In more detail:991001. **No documentation.** SMC keys are four-character codes whose meaning Apple does not publish. Mappings in circulation come from reverse engineering.1012. **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.1023. **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.1034. **No stability guarantee.** A system update can change or remove the interface.1045. **A supported alternative exists** for the question users actually have ("is my Mac throttling because of heat?"): the thermal state.105106A UI test (`testUnavailableSensorsAreDeclaredNotInvented`) opens this page and fails if the unavailable sentence is missing or if any text matching an "rpm" value is displayed.107108## Quality classes109110- `measured` — thermal state.111- `bestEffort` — battery temperature.112- `unavailable` — CPU temperature, GPU temperature, fan speed (displayed as such; not metrics).113114## Limitations115116- **Four levels only.** The thermal state cannot distinguish "comfortably cool" from "about to become fair"; it gives no early warning in degrees.117- **Sampled.** A brief change of state between two samples is missed by the series, although the change notification still triggers a slow-tier refresh.118- **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.119- **Battery temperature availability depends on model and macOS version**, and was absent on the only Mac audited.120- **No fan information of any kind**, including whether the Mac has fans.121122## Deliberately not shown123124| Item | Reason |125|---|---|126| CPU temperature (die, cores, clusters) | SMC / private HID sensor services only. |127| GPU temperature | Same. |128| SSD / NAND temperature | NVMe SMART or SMC only. See [disk](disk.md). |129| Fan speed (RPM), fan count | SMC only. |130| Fan control | Would require writing to the SMC; out of the question for an app that installs no helper. |131| Ambient, palm-rest, airflow and other sensors | SMC only. |132| A temperature *estimated* from load or thermal state | It would be an invented number. |133| A "thermal pressure percentage" | The system publishes a level; no percentage exists to report. |134
Files main
Menu

Theme