mtk-thermal-parser

Decode, parse, manipulate, validate, and diff MediaTek thermal configuration files (thermal.conf).

The codec uses a position-dependent Caesar cipher on the printable ASCII range 32-122. The document pipeline preserves all syntactic elements — section order, key order, comments, blank lines, original whitespace, and unknown directives — enabling lossless round-trips.

Tested Scope

The codec and lossless document pipeline have been validated against nine thermal policy files from a MediaTek MT6789 device (Android T), with byte-identical decode/encode round trips for every file.

Tested against the currently available reference implementation and policy set. Other MediaTek generations or vendor variants may use different formats.

Installation

pip install mtk-thermal-parser

Requires Python 3.9+. No external runtime dependencies.

CLI Usage

# Decode an encoded thermal.conf to plaintext
mtk-thermal decode thermal.conf -o decoded.conf

# Encode a plaintext file to encoded format
mtk-thermal encode decoded.conf -o thermal.conf

# Inspect configuration structure and typed values
mtk-thermal inspect thermal.conf

# Validate configuration (syntax, structure, semantics)
mtk-thermal validate thermal.conf

# Get a value
mtk-thermal get thermal.conf charger-cooler mode

# Set a value and write modified output
mtk-thermal set thermal.conf charger-cooler mode disabled -o modified.conf

# Diff two configurations
mtk-thermal diff original.conf modified.conf

# Reformat (canonicalize serialization)
mtk-thermal format thermal.conf -o canonical.conf

Device Commands (requires ADB and a connected Android device)

# Inspect thermal service status
mtk-thermal device status

# List available policies
mtk-thermal device list

# Show current / permanent policy
mtk-thermal device current

# Apply a policy by index (0=normal, 1=coolers-off, 2=performance)
mtk-thermal device apply 0

# Apply a custom policy by name
mtk-thermal device apply my-policy

# Push a local config to the device
mtk-thermal device push my-policy.conf

# Pull a policy from the device
mtk-thermal device pull thermal.conf -o backup.conf

# Clear a data-override policy
mtk-thermal device clear thermal.conf

Python API

from mtk_thermal_parser import ThermalCodec, Parser, SemanticModel

# Decode
decoded = ThermalCodec.decode(encoded_bytes)

# Lossless parse
doc = Parser.parse(decoded.decode('ascii'))

# Typed inspection
model = SemanticModel(doc)
for section in model:
    print(f"[{section.name}]")
    for key in section.keys:
        typed = section.typed(key)
        print(f"  {key}: {typed}")

# Round-trip: decode -> parse -> serialize -> encode
serialized = doc.serialize()
re_encoded = ThermalCodec.encode(serialized.encode('ascii'))
assert re_encoded == original_encoded_bytes

Key Features

• Lossless parsing — preserves section order, key order, comments, blank lines, whitespace, unknown directives
• Exact round-trip — decode → parse → serialize → encode reproduces the original bytes
• Auto-detection — distinguishes encoded vs plaintext input automatically
• Typed values — TemperatureValue (m°C), CurrentValue (mA), EnabledValue, IntListValue, StringListValue
• Validation — syntax, structure (duplicate keys), semantics (list types, parallel array lengths)
• Semantic diff — per-key and per-list-element comparison
• Optional device integration — ADB-based policy management

Safety Considerations

Structural validation confirms that a file is syntactically correct; it is not a thermal-safety certification.

Some vendor policies disable cooling, raise temperature thresholds to extreme values, or disable hardware protection. Always verify the behavior of a policy on your specific hardware before making persistent changes. Use the device debug_only mechanism where available to test policies without side effects.

Known Limitations

• Characters {|}~ (0x7B-0x7E) are outside the 91-character encoding range and cannot round-trip. These characters do not appear in known MediaTek thermal configurations.
• Tested against MT6789 (Android T) policies. Other MediaTek SoCs or Android versions may use different formats or encoding variants.
• Device integration requires ADB and root access for some operations.
• The thermal_intf IPC protocol is internal; no direct socket access by userspace callers has been confirmed.

License

MPL-2.0