mlog_tool

Python MLog Tool

Python desktop and CLI tool for parsing Firmament mlog binary files, exporting buses and parameters to CSV, and plotting signals in a Qt GUI.

Features

• Parse binary mlog files into structured bus data.
• Export each bus group to an individual CSV file and all parameters to a separate CSV file.
• Inspect and compare signals in a PySide6 + PyQtGraph desktop GUI.
• View parsed parameter groups directly in the GUI.
• Build a platform-native single-file executable with PyInstaller.

Project Layout

python_mlog_tool/
├── README.md
├── pyproject.toml
├── mlog_tool_qt.spec
├── scripts/
│   ├── build_qt_exe.sh
│   └── build_qt_exe.ps1
├── examples/
│   └── example_usage.py
├── src/
│   ├── qt_gui_entry.py
│   └── mlog_tool/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       ├── constants.py
│       ├── exporters.py
│       ├── models.py
│       ├── parser.py
│       ├── plotting.py
│       ├── qt_gui.py
│       ├── qt_plot_widget.py
│       ├── services.py
│       └── utils.py
└── tests/
    └── test_parser.py

MATLAB Mapping

• mlog_parser(logfile) -> MLogParser.parse(log_path)
• generate_MAT(...) -> CsvExporter.export_all(parsed_log, output_dir)
• get_param_val(...) -> ParsedLog.get_parameter(group_name, param_name)

Install

Install the base dependencies into the local virtual environment:

uv pip install --python ./.venv/bin/python -e .

Install the Qt GUI dependencies:

uv pip install --python ./.venv/bin/python ".[qt]"

Install the packaging dependency:

uv pip install --python ./.venv/bin/python ".[bundle]"

Quick Start

Parse a sample log and open the Qt GUI:

PYTHONPATH=src ./.venv/bin/python -m mlog_tool parse ../mlog16.bin
PYTHONPATH=src ./.venv/bin/python -m mlog_tool.qt_gui

Run From Source

CLI:

PYTHONPATH=src ./.venv/bin/python -m mlog_tool parse ../mlog16.bin
PYTHONPATH=src ./.venv/bin/python -m mlog_tool export ../mlog16.bin ./csv_output

Qt GUI:

PYTHONPATH=src ./.venv/bin/python -m mlog_tool.qt_gui

Build Executable

Build the Qt GUI into a single executable:

Linux:

./scripts/build_qt_exe.sh

Windows PowerShell:

.\scripts\build_qt_exe.ps1

Output:

dist/mlog-tool-qt
dist/mlog-tool-qt-v<version>-linux-<arch>
dist/mlog-tool-qt.exe
dist/mlog-tool-qt-v<version>-windows-<arch>.exe

Run it with:

./dist/mlog-tool-qt

Windows:

.\dist\mlog-tool-qt.exe

On first launch, PyInstaller will unpack its runtime files into a temporary directory automatically.

The build script also creates a versioned copy that is convenient for release delivery.

Notes

• The Qt GUI parses the selected log immediately after opening the file.
• CSV export writes one file per bus. When parameter groups are present, it also writes parameters.csv with group, name, type, and value columns (or parameters_1.csv, etc. if the name conflicts with a bus).
• The left panel is split into Parameters and Buses.
• Parameter details are viewed in the lower-right table and are not plottable.
• Cursor mode supports left-click freeze and right-click release directly on the plot.
• src/qt_gui_entry.py exists only as a PyInstaller-friendly GUI entry point for the onefile build.

Release Checklist

1. Update project.version in pyproject.toml.
2. Rebuild with ./scripts/build_qt_exe.sh on Linux or .\scripts\build_qt_exe.ps1 on Windows.
3. Deliver the versioned file from dist/.
4. Keep the unversioned dist/mlog-tool-qt as the latest local convenience build.