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.
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.
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`python smc_analyzer.py sample_dumps/example.csvThis 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 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.csvThis 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".
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: 0No 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 37Byte 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.
| 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.
CPU, GPU, Memory, Fan, SSD, Power, Battery, Logic Board,
Ambient, Platform, Thermal, Unknown.
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.
- Raw 2-byte sentinel patterns
0x8000/0x8100/0x8200→ invalid (sentinel_value), regardless of whether the key is known. - A decoded temperature of exactly
-127.0or-128.0for asp78/sp96/fpe2/fp88reading whose key starts withT→ 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.
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-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.
- Continuous watch mode:
--livetoday 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 existinglive.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 inanalyzer.py/report.pywas 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_bitfieldandKeyInfo.bitfield_labels(now populated forMSAL/SPHR/SPHT/SBF/SIS!) aren't wired into--explain/reports yet — today you'd decode a bit manually against the key's documented meaning.
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)
pip install -r requirements.txt
pytest tests/ -v