Metadata-Version: 2.4
Name: mtk-thermal-parser
Version: 0.1.0
Summary: Decode, parse, manipulate, and validate MediaTek thermal.conf files
Author: mtk-thermal-parser contributors
License-Expression: MPL-2.0
Project-URL: Source, https://github.com/anomalyco/mtk-thermal-parser
Project-URL: Bug Tracker, https://github.com/anomalyco/mtk-thermal-parser/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: wheel>=0.40; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install mtk-thermal-parser
```

Requires Python 3.9+.  No external runtime dependencies.

## CLI Usage

```bash
# 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)

```bash
# 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

```python
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
