124 lines
2.7 KiB
Markdown
124 lines
2.7 KiB
Markdown
# 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
|