# MiniProfiler Host Application

Python-based host application for real-time embedded profiling visualization.

## Quick Start with uv

### 1. Setup
```bash
# Create virtual environment
uv venv

# Activate it
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# Install package
uv pip install -e .
```

### 2. Run
```bash
# Start the web server
miniprofiler

# Or with options
miniprofiler --host 0.0.0.0 --port 8080 --verbose
```

### 3. Test with Sample Data
```bash
cd tests
python sample_data_generator.py
```

Open http://localhost:5000 in your browser.

## Using the Makefile

From the project root:

```bash
make install    # Install with uv
make run        # Run the server
make sample     # Generate sample data
make clean      # Clean build artifacts
```

## Documentation

- [../README.md](../README.md) - Project overview
- [../docs/SETUP.md](../docs/SETUP.md) - Detailed setup guide
- [../docs/GETTING_STARTED.md](../docs/GETTING_STARTED.md) - Usage guide
- [../docs/PROTOCOL.md](../docs/PROTOCOL.md) - Protocol specification

## Development

Install with dev dependencies:

```bash
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black miniprofiler tests

# Lint code
ruff check miniprofiler tests
```

## Project Structure

```
host/
├── miniprofiler/           # Main package
│   ├── __init__.py
│   ├── protocol.py         # Binary protocol
│   ├── serial_reader.py    # Serial communication
│   ├── symbolizer.py       # ELF/DWARF parsing
│   ├── analyzer.py         # Data analysis
│   ├── web_server.py       # Flask + SocketIO server
│   └── cli.py              # CLI entry point
│
├── web/                    # Web interface
│   ├── templates/
│   │   └── index.html
│   └── static/
│       ├── css/style.css
│       └── js/app.js
│
├── tests/                  # Tests and utilities
│   └── sample_data_generator.py
│
├── .venv/                  # Virtual environment (created by uv venv)
├── pyproject.toml          # Project configuration
└── run.py                  # Quick start script
```

## Requirements

- Python 3.8+
- uv (recommended) or pip
- Serial port access for real hardware

## Features

✅ Binary protocol with command-response structure
✅ Real-time serial communication
✅ ELF/DWARF symbol resolution
✅ Three visualization modes:
  - Flame graph (d3-flame-graph)
  - Timeline/flame chart (Plotly.js)
  - Statistics table
✅ WebSocket-based real-time updates
✅ Sample data generator for testing

## Next Steps

1. Connect to STM32 device (Phase 2 - embedded module TBD)
2. Load .elf file for symbol resolution
3. Start profiling and view real-time visualizations