Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Apple Intel SMC Analyzer

Licensed under the MIT License. See LICENSE for details.

An open-source, dependency-free command-line tool for decoding and classifying Apple SMC (System Management Controller) dumps from Intel-based Macs. Built for real hardware diagnostics — not just as a curiosity.

Guiding principle

Apple has never publicly documented the SMC key namespace or its diagnostic codes. This tool is deliberately objective, not diagnostic:

  • It decodes what the raw bytes objectively mean (given a documented type code), classifies sensors it can positively identify, and flags values against mechanical rules (sentinel bytes, expected ranges).
  • It never guesses what an undocumented key means. Unknown keys are reported as Unknown — full stop — instead of a plausible-sounding guess.
  • It never asserts a root cause. "Suspicious" means "a mechanical rule fired", not "this is broken."

See walkroad.md for the full background and rationale.

Install

Runtime dependencies: none (Python 3.9+ standard library only). pytest is only needed to run the test suite.

pip install -r requirements.txt   # only needed for `pytest`

Usage

python smc_analyzer.py sample_dumps/example.csv

This prints a terminal report and, by default, also writes report.html and unknown_keys.csv next to it.

python smc_analyzer.py <dump_file> [options]
python smc_analyzer.py --live [--save-dump smc_dump.csv] [options]

  --live               read SMC directly from Linux's applesmc sysfs
                        interface instead of a dump file (see "Live mode")
  --save-dump PATH     with --live, also save the raw readings as a CSV
                        dump to PATH, for offline re-analysis or archiving
  --json PATH          write a JSON report (list of per-key assessments)
  --csv PATH           write a flat CSV report
  --html PATH          HTML report path (default: report.html)
  --no-html            skip the HTML report
  --unknown-csv PATH   unknown-key list path (default: unknown_keys.csv)
  --no-unknown-csv     skip the unknown-keys CSV
  --cross-check        best-effort compare CPU temps against Linux coretemp
                        (only meaningful for a dump captured just now, on
                        this machine — see "Cross-validation" below)
  --explain KEY        print the Raw Data Explorer view for one key and exit

Live mode (Linux only)

--live reads every SMC key directly from the applesmc kernel driver's sysfs interface — no dump file, no shell loop:

sudo python3 smc_analyzer.py --live --save-dump smc_dump.csv

This finds /sys/devices/platform/applesmc.*, reads key_count, and for each index writes key_at_index then reads back key_at_index_name/_type/_data_length/_data — the exact mechanism a manual shell loop over that sysfs tree would use, just automated. Selecting a key by index requires root, same as the shell version. The resulting readings feed the same decoder → dictionary → validator → analyzer → report pipeline as a CSV dump — parser.py isn't involved at all for --live, so there's exactly one analysis engine regardless of where the data came from. --save-dump is optional and only for archiving a snapshot (e.g. to later compare a known-good machine against a suspect one — see "Roadmap").

This is a one-shot snapshot, not continuous monitoring: it reads the SMC once, analyzes it, and reports. A refresh-every-second watch mode remains future work — see "Roadmap".

Raw Data Explorer

For debugging a single key:

$ python smc_analyzer.py sample_dumps/example.csv --explain TC0c
Key: TC0c

Type: sp78

Raw: 2700

Integer: 9984

Decoded: 39.0°C

Name: CPU Proximity Temperature
Category: CPU
Source: User-provided (walkroad.md, iMac16,1 research)
Confidence: HIGH
Status: OK
Severity: 0

Dump file format

No external tool's exact format was specified, so this project defines its own — documented here so any SMC dumper can target it.

CSV (preferred): a header row plus one row per key. Column names are matched case-insensitively; any of these aliases work:

Field Accepted column names
key key, smc_key, name
type type, datatype, data_type
size size, length, len (optional — inferred from the byte payload if omitted)
bytes bytes, value, hex, raw, hexbytes, rawbytes, data
key,type,size,bytes
TC0c,sp78,2,27 00
F0Ac,ui16,2,05 37

Byte payloads accept space- or comma-separated hex, with or without a 0x prefix (27 00, 0x27,0x00, and 2700 are all equivalent).

TXT: one reading per line, tolerant of the classic smc -l-style listing:

TC0c  [sp78]  27 00
F0Ac  [ui16]  05 37

Lines that don't match are skipped rather than aborting the whole dump — there is no #-prefix comment convention, since #KEY is itself a real SMC key.

See sample_dumps/ for complete, synthetic (not real hardware) examples of both formats.

Decoder reference

Type(s) Meaning Formula
fpXY unsigned fixed-point, 2 bytes raw_uint16 / 2**Y (X+Y=16)
spXY signed fixed-point, 2 bytes raw_int16 / 2**Y (X+Y=15, 1 sign bit)
ui8/ui16/ui32 unsigned big-endian int —
si8/si16/si32 signed big-endian int —
flag boolean 1 byte, nonzero = true
flt IEEE-754 float little-endian (the one exception to big-endian)
ch8* / ch... ASCII string trailing NULs stripped
anything else raw hex reported, not silently dropped

Verified against the project's own worked example (walkroad.md): key TC0c, raw 2700 → 0x2700 = 9984 as big-endian uint16; sp78 has 8 fractional bits, so 9984 / 256 = 39.0°C — exactly the stated result. This is also why the documented invalid sentinels decode the way they do: 0x8000 → -128.0, 0x8100 → -127.0 under this same sp78 formula.

flag/ui16 bitfields can be decomposed mechanically (decoder.decode_bitfield) into individual set/unset bits. A bit only gets a real label (e.g. "Fan Fail") when dictionary.py documents one for that specific key — otherwise it's reported as bit0, bit1, etc. Nothing is invented.

Categories

CPU, GPU, Memory, Fan, SSD, Power, Battery, Logic Board, Ambient, Platform, Thermal, Unknown.

Key dictionary & provenance

Every dictionary entry (dictionary.py) records where the name came from and how sure we are:

Key Name Source Confidence
TC0c CPU Proximity Temperature User-provided (walkroad.md, iMac16,1 research) HIGH
SPHR Active Prochot Requestor Bits Apple first-party (SMCKeysMacPro.html) MEDIUM
TQQQ (example) Unknown Inferred from key-namespace convention UNKNOWN

Confidence is one of HIGH / MEDIUM / LOW / UNKNOWN. ~200 entries were added from real web research into public, citable sources: Apple's own legacy SMC key table and libSMC.dylib sensor strings, Acidanthera's reverse-engineered key documentation, and iStat Menus' per-model sensor DB (all via acidanthera/VirtualSMC's Docs/ folder) — cross-referenced against this project's real iMac16,1 dump, not taken on faith. A handful of entries (MSAL, SPHR, SPHT, SBF, SIS!) also carry bitfield_labels with real per-bit meanings from that research (not yet rendered in reports -- see Roadmap). Extend the dictionary yourself as you decode more of your own dump, or merge in further entries you've cross-referenced against AppleSMC/OpenCore/VirtualSMC; add a new KeyInfo(name, category, source, confidence) entry, and don't overwrite the Unknown fallback logic.

Two case-insensitive collisions are expected and handled, not bugs: TL1V/ TL1v and MSTC/MSTc are each independently curated with genuinely different real meanings (confirmed by research), unlike the TC0c/TC0P "same sensor, different key revision" pattern elsewhere. When a curated uppercase form has more than one distinct entry, lookup() never guesses which one a new, differently-cased variant might match.

Category vs. name are inferred separately. A key with no dictionary entry still gets a category from the documented AppleSMC key-namespace convention (first letter = subsystem; for T-prefixed keys, the second letter narrows it to CPU/GPU/Memory/Ambient/Logic Board, else a generic Thermal bucket) — this is a structural fact about the namespace, not a guess about what the key measures, so its name stays Unknown regardless. #/$/R-prefixed keys infer Platform; F→Fan, B→Battery, P→Power. I/V (current/voltage) are deliberately not blanket-inferred: some real dump keys (ID2S) don't match the simple shape genuine current/voltage keys have (IC0C, VC0C), and guessing there would be exactly the kind of false claim this project exists to avoid — specific I/V keys are still individually curated once actually confirmed (ID2E, VD2R, VR3R, ...). See dictionary._infer_category. Both the category rule and the case-variant-sibling rule are also case-sensitive on purpose: the real dump has lowercase-prefixed keys (tt11, mSTC) that are demonstrably not the same namespace as their uppercase look-alikes.

Invalid sensor & range rules

  • Raw 2-byte sentinel patterns 0x8000 / 0x8100 / 0x8200 → invalid (sentinel_value), regardless of whether the key is known.
  • A decoded temperature of exactly -127.0 or -128.0 for a sp78 / sp96 / fpe2 / fp88 reading whose key starts with T → invalid (no_data).
  • CPU temperatures (same "T-prefixed key" requirement) outside 20–105°C → out of range.
  • Fan speed readings (any Fan-category key whose name contains "Speed") outside 1000–6000 RPM → out of range.

The "T-prefixed key" requirement matters: Apple reuses the exact same sp78/sp96/fpe2/fp88 fixed-point encodings for fan RPM and CPU current/power (confirmed against a real iMac16,1 dump — F0Ac is fpe2, IC0C is sp78, PC0C/PCPC are sp96), so the type code alone never tells you it's a temperature; only the key-namespace convention does.

These are mechanical checks, not conclusions — see "Guiding principle" above.

Severity scoring

Every flagged reading gets a severity score (0–100) used purely to sort the report — higher means "look at this first". It is a prioritization aid for a human investigator, not a diagnosis: a CPU-category sentinel value scores much higher than the same sentinel on an Unknown-category key that may just be an unpopulated sensor slot on this particular model. Tune analyzer._SEVERITY_TABLE as you learn more about your specific hardware.

Cross-validation (opt-in, Linux only)

--cross-check reads the current CPU temperatures from Linux's own coretemp hwmon driver (/sys/class/hwmon/hwmon*/) and reports the delta against the closest SMC CPU reading, purely as an informational data point (e.g. SMC 39.0°C vs coretemp:Core 0 39.0°C, Δ=0.0). This is only meaningful when the dump was captured right now, on the same machine — a delta against an old dump proves nothing. It returns gracefully with no comparison at all on non-Linux systems or if coretemp isn't loaded.

Roadmap (not implemented yet)

  • Continuous watch mode: --live today is a one-shot snapshot (read once, analyze, report). A refresh-every-second watch of CPU/GPU/Fan/Platform sensors — the original "smc live" idea, usable over SSH — would be a thin loop around the existing live.read_all_keys(), since the sysfs-reading and analysis layers are already separated.
  • Dump diff engine: compare a known-good dump against a suspect one and highlight differences, with the same severity scoring used here. The ReadingAssessment/JSON schema in analyzer.py/report.py was deliberately kept clean and serializable so this can be built by loading two reports and diffing them field by field — no changes needed upstream.
  • PDF report.
  • Bitfield display: decoder.decode_bitfield and KeyInfo.bitfield_labels (now populated for MSAL/SPHR/SPHT/SBF/SIS!) aren't wired into --explain/reports yet — today you'd decode a bit manually against the key's documented meaning.

Project layout

smc-analyzer/
├── smc_analyzer.py   CLI entrypoint / orchestrator
├── parser.py         CSV + TXT dump parsing
├── decoder.py        type decoders + bitfield decomposition
├── dictionary.py     key -> {name, category, source, confidence}
├── validator.py      sentinel/range rule checks (mechanical only)
├── cross_check.py    optional Linux coretemp cross-validation
├── analyzer.py       aggregation layer + severity scoring
├── report.py         terminal/JSON/CSV rendering
├── html_report.py    self-contained HTML rendering
├── live.py           reads SMC directly from Linux applesmc sysfs (--live)
├── tests/            pytest suite
└── sample_dumps/     synthetic example dumps (not real hardware data)

Running the tests

pip install -r requirements.txt
pytest tests/ -v

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages