Metadata-Version: 2.4
Name: miwear
Version: 0.0.20
Summary: Python Miwear tools for extracting and handling archives/logs
Author-email: Junbo Zheng <3273070@qq.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Junbo-Zheng/miwear
Keywords: miwear,archive,log,extraction
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: serial
Requires-Dist: pyserial; extra == "serial"

# miwear

[![PyPI version](https://img.shields.io/pypi/v/miwear.svg)](https://pypi.org/project/miwear/)
[![Python](https://img.shields.io/pypi/pyversions/miwear.svg)](https://pypi.org/project/miwear/)
[![License](https://img.shields.io/pypi/l/miwear.svg)](./LICENSE)

> A Python toolkit for extracting, processing and analyzing MiWear archive and log files.

`miwear` bundles a set of small, focused command-line tools for the everyday chores of working with MiWear device dumps — unpacking `.tar.gz`/`.zip`/`.gz` bundles, merging rotated logs, parsing crash assertions, auditing resource directories, analyzing log patterns, and driving serial consoles.

## Features

- Batch extraction for `.tar.gz`, `.zip` and `.gz` archives with sensible defaults
- Log utilities: assertion extraction, gzipped log merging, pattern filtering
- Resource audit: duplicate detection, unused-asset scanning, two-directory diff, with Markdown + interactive HTML reports
- Log analyzer for AppID / screen transition entries, exportable to CSV or interactive HTML
- Optional serial console integration (miniterm, one-shot, periodic, or batch-file modes)
- Pure Python standard library — no dependencies for core tools
- Works on Python 3.10+ across Linux, macOS and Windows

## Installation

Install from PyPI:

```bash
pip install miwear
```

Enable the optional serial console tool:

```bash
pip install "miwear[serial]"
```

Install from source:

```bash
git clone https://github.com/Junbo-Zheng/miwear
cd miwear
pip install .
```

## CLI tools

After installation the following commands are on your `PATH`:

| Command | Purpose |
| --- | --- |
| `miwear_log` | Extract a MiWear log archive and merge its contents into a single log file |
| `miwear_assert` | Extract assertion information from a log |
| `miwear_gz` | Decompress and merge `.gz` log shards |
| `miwear_tz` | Batch-extract `.tar.gz` archives in a directory |
| `miwear_uz` | Batch-extract `.zip` archives in a directory |
| `miwear_check` | Resource audit (duplicates / unused / diff) with Markdown + HTML reports |
| `miwear_loganalyzer` | Parse AppID / screen log patterns into CSV or interactive HTML |
| `miwear_serial` | Serial console helper (requires `pyserial`) |

> [!TIP]
> Every command accepts `--help` for the full list of options and `--version` to print the installed version.

## Usage

### `miwear_log` — extract and merge log archives

```bash
# Positional path (recommended)
miwear_log ~/Downloads/log.tar.gz

# Explicit -f flag
miwear_log -f ~/Downloads/log.tar.gz

# Pull straight from an Android phone via adb
miwear_log --phone -f 123456_abc
```

### `miwear_assert` — extract assertion information

```bash
miwear_assert -i mi.log -o assert_log.txt
```

### `miwear_gz` — decompress and merge `.gz` shards

```bash
miwear_gz --path ./logs --log_file my.log --output_file merged.log
```

### `miwear_tz` / `miwear_uz` — batch extraction

```bash
miwear_tz --path ./logs
miwear_uz --path ./logs
```

### `miwear_check` — resource audit

Find duplicate files (default mode):

```bash
miwear_check -d ./resources -e bin
miwear_check -d ./resources -e bin png
miwear_check -d ./resources -e bin -p theme_ config_
miwear_check -d ./resources -e bin --action delete
```

Find unused resources (`-d` sets where resources live, `-c` sets where to look for references — defaults to `-d`):

```bash
miwear_check -m unused -d ./project -e bin
miwear_check -m unused -d ./project -c ./project/ota -e bin
miwear_check -m unused -d ./project -e bin --code-ext ".c,.h,.cpp,.java"
```

Run both checks together:

```bash
miwear_check -m both -d ./project -e bin
```

Diff two directories (e.g. design PNG vs. converted BIN):

```bash
miwear_check -m diff --path1 ./design --path2 ./converted
miwear_check -m diff --path1 ./design --path2 ./converted -i .git,node_modules
miwear_check -m diff --path1 ./design --path2 ./converted --sort count
```

> [!NOTE]
> When the scan directory contains `view/` and `view_XX/res*` variants, `miwear_check` prompts you to pick one (default: the variant with the most files). Use `-i` to skip the prompt.

Diff mode matches files by base name (everything before the first dot) under the same relative directory, so e.g. `confirm.indexed_8.png` and `confirm.bin` pair up automatically.

All modes emit a Markdown report and an interactive HTML report (with search / filter / sort), and optionally open the HTML in your browser when done:

```bash
miwear_check -d ./resources -e bin -o my_report.md
miwear_check -d ./resources -e bin --no-output
```

### `miwear_loganalyzer` — parse MiWear log patterns

```bash
# Default: all analyzers → miwear.csv
miwear_loganalyzer -f 1.log

# Interactive HTML report (opens in browser)
miwear_loganalyzer -f 1.log --html --open-browser

# Pick a single analyzer
miwear_loganalyzer -f 1.log -t appid
miwear_loganalyzer -f 1.log -t screen -o screens.csv
```

### `miwear_serial` — serial console helper

> [!IMPORTANT]
> Requires `pyserial`. Install via `pip install miwear[serial]`.

Open an interactive miniterm session (default):

```bash
miwear_serial -p /dev/ttyACM0 -b 921600
```

Send one command, optionally parsing the response:

```bash
miwear_serial -p /dev/ttyUSB1 -b 115200 -c "ps"
miwear_serial -p /dev/ttyUSB1 -b 115200 -c "ps" -r
```

Repeat on a timer:

```bash
miwear_serial -p /dev/ttyACM1 -i 1.0 -c "ps"
miwear_serial -p /dev/ttyACM1 -i 2.0 -c "ps" --count 5
```

Run batch commands from a file:

```bash
miwear_serial -f commands.txt
miwear_serial -f commands.txt -i 2.0 --count 5
```

Record output to a log file:

```bash
miwear_serial -p /dev/ttyACM0 -b 921600 -s              # miwear.log (default)
miwear_serial -p /dev/ttyACM0 -b 921600 -s log.txt      # custom path
```

Press `Ctrl+]` to exit miniterm.

## Requirements

- Python 3.10 or newer
- `pyserial` (only for `miwear_serial`)

## Author

Junbo Zheng — [3273070@qq.com](mailto:3273070@qq.com)
