tasmota-metrics

0.4.3 verified Fri May 01 auth: no python

Firmware size analysis tool for ESP-IDF based projects (e.g., Tasmota). Analyzes ELF/map files from ESP32/ESP8266 builds to report component-level flash and RAM usage. Current version 0.4.3, actively maintained on GitHub, infrequent releases.

pip install tasmota-metrics

Common errors

error ModuleNotFoundError: No module named 'tasmota_metrics' ↓

cause The package is installed as 'tasmota-metrics' (with hyphen) but imported as 'tasmota_metrics' (with underscore). Users often try to import using the hyphenated name.

fix

Install with 'pip install tasmota-metrics' and import as 'from tasmota_metrics import TasmotaMetrics'.

error ValueError: Unsupported chip type: esp32xx ↓

cause The chip parameter was misspelled or an unsupported variant was used.

fix

Use valid chip names: esp32, esp8266, esp32s2, esp32c3, esp32s3.

error FileNotFoundError: [Errno 2] No such file or directory: 'build/firmware.map' ↓

cause The firmware_path points to a missing file or incorrect path.

fix

Ensure the map file exists. Typically found in the build directory of your ESP-IDF project.

Warnings

gotcha The 'chip' parameter must match the target exactly ('esp32', 'esp8266', 'esp32s2', etc.). Unknown chip types cause runtime errors. ↓

fix Use only recognized chip identifiers: esp32, esp8266, esp32s2, esp32c3, esp32s3.

breaking In v0.3.4, Xtensa target detection pattern changed. Map files generated with older ESP-IDF versions may fail to parse correctly. ↓

fix Update your ESP-IDF toolchain or downgrade to v0.3.3 if you encounter parsing errors on older builds.

gotcha Requires Python >=3.7; no longer installable on Python 3.6 or earlier. ↓

fix Upgrade Python to 3.7 or later.

Imports

TasmotaMetrics
wrong
```
import tasmota_metrics
```
correct
```
from tasmota_metrics import TasmotaMetrics
```
Common mistake: importing the module directly without the class. Use 'from tasmota_metrics import TasmotaMetrics'.

Quickstart

Analyze a firmware map file for component memory usage.

from tasmota_metrics import TasmotaMetrics

metrics = TasmotaMetrics(
    firmware_path='build/firmware.map',
    chip='esp32'
)
report = metrics.analyze()
print(report)