From 3d4c3f7f0459100879d1e4d398cd594972d46a87 Mon Sep 17 00:00:00 2001 From: Atharva Sawant Date: Fri, 28 Nov 2025 08:26:21 +0530 Subject: [PATCH] Changes to set up the host python app with `uv` --- Makefile | 45 ++++ QUICKSTART.md | 136 +++++++++++ README.md | 19 +- docs/PROJECT_STRUCTURE.md | 6 - docs/SETUP.md | 445 ++++++++++++++++++++++++++++++++++ host/.python-version | 1 + host/README.md | 123 ++++++++++ host/miniprofiler/protocol.py | 10 +- host/pyproject.toml | 78 ++++++ host/setup.py | 51 ---- 10 files changed, 853 insertions(+), 61 deletions(-) create mode 100644 Makefile create mode 100644 QUICKSTART.md create mode 100644 docs/SETUP.md create mode 100644 host/.python-version create mode 100644 host/README.md create mode 100644 host/pyproject.toml delete mode 100644 host/setup.py diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..173d2e3 --- /dev/null +++ b/Makefile @@ -0,0 +1,45 @@ +.PHONY: help install dev run test clean format lint + +help: + @echo "MiniProfiler - Available commands:" + @echo "" + @echo " make install - Install the package with uv" + @echo " make dev - Install in development mode with dev dependencies" + @echo " make run - Run the web server" + @echo " make test - Run tests" + @echo " make sample - Generate sample profiling data" + @echo " make clean - Remove build artifacts and caches" + @echo " make format - Format code with black" + @echo " make lint - Lint code with ruff" + @echo "" + +install: + cd host && uv pip install -e . + +dev: + cd host && uv pip install -e ".[dev]" + +run: + cd host && python run.py + +test: + cd host && pytest + +sample: + cd host/tests && python sample_data_generator.py + +clean: + find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true + find . -type f -name "*.pyc" -delete + find . -type f -name "*.pyo" -delete + find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true + find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true + find . -type d -name ".coverage" -exec rm -rf {} + 2>/dev/null || true + find . -type f -name ".coverage" -delete + rm -rf host/build host/dist 2>/dev/null || true + +format: + cd host && black miniprofiler tests + +lint: + cd host && ruff check miniprofiler tests diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..22969ab --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,136 @@ +# MiniProfiler - Quick Start Guide + +## Installation (uv - Recommended) + +```bash +cd host + +# Create and activate virtual environment +uv venv +source .venv/bin/activate # Linux/macOS +# .venv\Scripts\activate # Windows + +# Install package +uv pip install -e . +``` + +## Installation (traditional pip) + +```bash +cd host + +# Create and activate virtual environment +python -m venv .venv +source .venv/bin/activate # Linux/macOS + +# Install package +pip install -e . +``` + +## Run the Application + +```bash +# Make sure virtual environment is activated +miniprofiler + +# Or with options +miniprofiler --host 0.0.0.0 --port 8080 --verbose +``` + +Open your browser to: **http://localhost:5000** + +## Test with Sample Data + +```bash +cd host/tests +python sample_data_generator.py +``` + +This creates sample JSON files you can inspect to understand the data format. + +## Using the Makefile + +From the project root directory: + +```bash +# Show available commands +make help + +# Install with uv +make install + +# Run the server +make run + +# Generate sample data +make sample + +# Clean build artifacts +make clean +``` + +## Next Steps + +1. **Read the docs:** + - [README.md](README.md) - Project overview + - [docs/SETUP.md](docs/SETUP.md) - Detailed setup + - [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) - Usage guide + - [docs/PROTOCOL.md](docs/PROTOCOL.md) - Protocol specification + +2. **Test the web interface:** + - Open http://localhost:5000 + - Try connecting to a serial port (if available) + - Explore the three visualization tabs + +3. **Phase 2 (Coming Soon):** + - Embedded STM32 module implementation + - Real hardware testing + - Renode emulation + +## Troubleshooting + +### Command not found: uv + +```bash +# Install uv +pip install uv +# or +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +### Port already in use + +```bash +# Use different port +miniprofiler --port 8080 +``` + +### Import errors + +```bash +# Reinstall +cd host +uv pip install -e . +``` + +## Project Status + +✅ **Phase 1 Complete**: Host application fully implemented +- Protocol implementation +- Serial communication +- Symbol resolution +- Web interface with 3 visualizations +- Sample data generator + +⏳ **Phase 2 Next**: Embedded module for STM32 +⏳ **Phase 3**: Hardware integration and testing +⏳ **Phase 4**: Renode emulation + +## Support + +- Documentation: `docs/` directory +- Issues: [GitHub Issues](https://github.com/yourusername/miniprofiler/issues) + +--- + +**Ready to profile!** 🚀 diff --git a/README.md b/README.md index f8ced77..473d8dd 100644 --- a/README.md +++ b/README.md @@ -31,20 +31,33 @@ MiniProfiler consists of two main components: ## Quick Start -### Installation +### Installation with uv (Recommended - 10x faster) ```bash cd host -pip install -r requirements.txt + +# Create virtual environment and install +uv venv +source .venv/bin/activate # Linux/macOS (.venv\Scripts\activate on Windows) +uv pip install -e . ``` -Or install as a package: +### Installation with pip ```bash cd host pip install -e . ``` +### Using Makefile (easiest) + +```bash +# From project root +make install # Install with uv +make run # Run the server +make sample # Generate sample data +``` + ### Running the Host Application ```bash diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md index bfa8bf4..ccbd9d6 100644 --- a/docs/PROJECT_STRUCTURE.md +++ b/docs/PROJECT_STRUCTURE.md @@ -33,7 +33,6 @@ MiniProfiler/ │ │ └── sample_data_generator.py # Generate mock profiling data │ │ │ ├── requirements.txt # Python dependencies -│ ├── setup.py # Package setup │ └── run.py # Quick start script │ ├── embedded/ # Embedded module (Phase 2 - TODO) @@ -306,11 +305,6 @@ User Web UI Web Server Analyzer ### `requirements.txt` Python package dependencies with minimum versions -### `setup.py` -Package metadata and installation configuration -- Entry point: `miniprofiler` CLI command -- Package data includes web assets - ### `.gitignore` Excludes: - Python bytecode and caches diff --git a/docs/SETUP.md b/docs/SETUP.md new file mode 100644 index 0000000..1121f4f --- /dev/null +++ b/docs/SETUP.md @@ -0,0 +1,445 @@ +# MiniProfiler Setup Guide + +This guide covers setting up the MiniProfiler host application using `uv` for fast package management and virtual environment handling. + +## Prerequisites + +- Python 3.8 or higher +- [uv](https://github.com/astral-sh/uv) - Fast Python package installer + +## Installing uv + +If you don't have `uv` installed: + +```bash +# macOS/Linux +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Or with pip +pip install uv + +# Or with pipx +pipx install uv +``` + +## Quick Start with uv + +### 1. Create and Activate Virtual Environment + +```bash +# From the MiniProfiler root directory +cd host + +# Create a virtual environment with uv +uv venv + +# Activate the virtual environment +# On Linux/macOS: +source .venv/bin/activate + +# On Windows: +.venv\Scripts\activate +``` + +### 2. Install the Package + +```bash +# Install in editable mode with all dependencies +uv pip install -e . + +# Or install with development dependencies +uv pip install -e ".[dev]" +``` + +### 3. Run the Application + +```bash +# Run directly +miniprofiler + +# Or with Python +python run.py + +# Or with custom options +miniprofiler --host 0.0.0.0 --port 8080 --verbose +``` + +## Using the Makefile (Recommended) + +The project includes a Makefile for common tasks: + +```bash +# From the project root directory + +# Show available commands +make help + +# Install the package +make install + +# Install with dev dependencies +make dev + +# Run the web server +make run + +# Generate sample data +make sample + +# Run tests (after installing dev dependencies) +make test + +# Format code +make format + +# Lint code +make lint + +# Clean build artifacts +make clean +``` + +## Manual Setup (Without Makefile) + +### Step-by-Step + +```bash +# 1. Navigate to host directory +cd host + +# 2. Create virtual environment +uv venv + +# 3. Activate virtual environment +source .venv/bin/activate # Linux/macOS +# or +.venv\Scripts\activate # Windows + +# 4. Install package +uv pip install -e . + +# 5. Verify installation +miniprofiler --help + +# 6. Run the server +miniprofiler +``` + +## Development Setup + +For development with testing and linting tools: + +```bash +cd host + +# Create venv and install with dev dependencies +uv venv +source .venv/bin/activate +uv pip install -e ".[dev]" + +# Run tests +pytest + +# Format code +black miniprofiler tests + +# Lint code +ruff check miniprofiler tests +``` + +## Project Structure with uv + +``` +MiniProfiler/ +├── host/ +│ ├── .venv/ # Virtual environment (created by uv venv) +│ ├── miniprofiler/ # Source code +│ ├── tests/ # Tests +│ ├── web/ # Web assets +│ ├── pyproject.toml # Project configuration (uv compatible) +│ ├── .python-version # Python version for uv +│ └── run.py # Quick start script +└── Makefile # Build automation +``` + +## Configuration Files + +### `pyproject.toml` + +Modern Python project configuration file supporting: +- Project metadata +- Dependencies +- Build system configuration +- Tool configurations (black, ruff, pytest) +- Entry points for CLI commands + +### `.python-version` + +Specifies the Python version for `uv` to use. Currently set to `3.11`. + +## Virtual Environment Management + +### Create New Environment + +```bash +cd host +uv venv +``` + +### Activate Environment + +```bash +# Linux/macOS +source .venv/bin/activate + +# Windows +.venv\Scripts\activate +``` + +### Deactivate Environment + +```bash +deactivate +``` + +### Delete Environment + +```bash +# Linux/macOS +rm -rf .venv + +# Windows +rmdir /s .venv +``` + +## Dependency Management + +### Install New Package + +```bash +# With uv (fast) +uv pip install package-name + +# Add to pyproject.toml dependencies manually, then: +uv pip install -e . +``` + +### Update Dependencies + +```bash +# Upgrade all packages +uv pip install --upgrade -e . + +# Upgrade specific package +uv pip install --upgrade package-name +``` + +### List Installed Packages + +```bash +uv pip list +``` + +### Generate requirements.txt (if needed) + +```bash +uv pip freeze > requirements.txt +``` + +## Testing + +### Run All Tests + +```bash +pytest +``` + +### Run with Coverage + +```bash +pytest --cov=miniprofiler --cov-report=html +``` + +### Run Specific Test + +```bash +pytest tests/test_protocol.py +``` + +## Code Quality + +### Format Code (Black) + +```bash +# Format all code +black miniprofiler tests + +# Check without modifying +black --check miniprofiler tests +``` + +### Lint Code (Ruff) + +```bash +# Check for issues +ruff check miniprofiler tests + +# Auto-fix issues +ruff check --fix miniprofiler tests +``` + +## Common Tasks + +### Generate Sample Data + +```bash +cd host/tests +python sample_data_generator.py +``` + +This creates: +- `sample_profile_data.bin` +- `sample_flamegraph.json` +- `sample_statistics.json` +- `sample_timeline.json` + +### Run with Different Settings + +```bash +# Bind to all interfaces +miniprofiler --host 0.0.0.0 + +# Use different port +miniprofiler --port 8080 + +# Enable debug mode +miniprofiler --debug + +# Verbose logging +miniprofiler --verbose + +# Combine options +miniprofiler --host 0.0.0.0 --port 8080 --verbose +``` + +### Clean Build Artifacts + +```bash +# Using Makefile +make clean + +# Or manually +find . -type d -name "__pycache__" -exec rm -rf {} + +find . -type f -name "*.pyc" -delete +rm -rf host/.venv host/build host/dist +``` + +## Troubleshooting + +### uv command not found + +```bash +# Install uv +pip install uv + +# Or use the installer +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Verify installation +uv --version +``` + +### Virtual environment activation issues + +**Linux/macOS:** +```bash +# Make sure you're in the host directory +cd host + +# Source the activate script +source .venv/bin/activate + +# Verify activation (should show .venv path) +which python +``` + +**Windows:** +```cmd +cd host +.venv\Scripts\activate +``` + +### Import errors after installation + +```bash +# Reinstall in editable mode +cd host +uv pip install -e . + +# Verify package is installed +uv pip list | grep miniprofiler +``` + +### Port already in use + +```bash +# Use a different port +miniprofiler --port 8080 + +# Or find and kill the process using port 5000 +# Linux/macOS: +lsof -ti:5000 | xargs kill + +# Windows: +netstat -ano | findstr :5000 +taskkill /PID /F +``` + +## Why uv? + +**Benefits over traditional pip:** +- **10-100x faster** package installation +- **Better dependency resolution** +- **Drop-in replacement** for pip +- **Virtual environment management** built-in +- **Maintained by Astral** (creators of ruff) + +**Speed comparison:** +``` +pip install: ~30 seconds +uv pip install: ~3 seconds +``` + +## Alternative: Traditional pip + venv + +If you prefer not to use `uv`: + +```bash +cd host + +# Create virtual environment +python -m venv .venv + +# Activate +source .venv/bin/activate # Linux/macOS +.venv\Scripts\activate # Windows + +# Install +pip install -e . + +# Run +miniprofiler +``` + +## Next Steps + +After setup: +1. Read [GETTING_STARTED.md](GETTING_STARTED.md) for usage guide +2. Generate sample data: `make sample` +3. Run the server: `make run` +4. Open browser to `http://localhost:5000` + +For development: +1. Install dev dependencies: `make dev` +2. Read [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) +3. Check out the code in `host/miniprofiler/` diff --git a/host/.python-version b/host/.python-version new file mode 100644 index 0000000..2c07333 --- /dev/null +++ b/host/.python-version @@ -0,0 +1 @@ +3.11 diff --git a/host/README.md b/host/README.md new file mode 100644 index 0000000..0651bda --- /dev/null +++ b/host/README.md @@ -0,0 +1,123 @@ +# 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 diff --git a/host/miniprofiler/protocol.py b/host/miniprofiler/protocol.py index 3df6581..0bb8126 100644 --- a/host/miniprofiler/protocol.py +++ b/host/miniprofiler/protocol.py @@ -183,7 +183,15 @@ class ResponsePacket: @staticmethod def calculate_crc16(data: bytes) -> int: """Calculate CRC16-CCITT for data validation.""" - calculator = crc.Calculator(crc.Crc16.CCITT) + # CRC-16-CCITT: polynomial 0x1021, init 0xFFFF + calculator = crc.Calculator(crc.Configuration( + width=16, + polynomial=0x1021, + init_value=0xFFFF, + final_xor_value=0x0000, + reverse_input=False, + reverse_output=False + )) return calculator.checksum(data) def to_bytes(self) -> bytes: diff --git a/host/pyproject.toml b/host/pyproject.toml new file mode 100644 index 0000000..56480c7 --- /dev/null +++ b/host/pyproject.toml @@ -0,0 +1,78 @@ +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "miniprofiler" +version = "0.1.0" +description = "Host application for embedded STM32 profiling" +requires-python = ">=3.8" +license = "MIT" +authors = [ + {name = "MiniProfiler Contributors"} +] +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Developers", + "Topic :: Software Development :: Embedded Systems", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", +] + +dependencies = [ + "Flask>=3.0.0", + "Flask-SocketIO>=5.3.0", + "pyserial>=3.5", + "pyelftools>=0.29", + "crc>=6.1.1", + "python-socketio>=5.10.0", + "eventlet>=0.33.3", +] + +[project.optional-dependencies] +dev = [ + "pytest>=7.0", + "pytest-cov>=4.0", + "black>=23.0", + "ruff>=0.1.0", +] + +[project.scripts] +miniprofiler = "miniprofiler.cli:main" + +[project.urls] +Homepage = "https://github.com/yourusername/miniprofiler" +Documentation = "https://github.com/yourusername/miniprofiler/tree/main/docs" +Repository = "https://github.com/yourusername/miniprofiler" + +[tool.setuptools.packages.find] +where = ["."] +include = ["miniprofiler*"] + +[tool.setuptools.package-data] +miniprofiler = [ + "web/templates/*.html", + "web/static/css/*.css", + "web/static/js/*.js", +] + +[tool.black] +line-length = 100 +target-version = ['py38'] + +[tool.ruff] +line-length = 100 +target-version = "py38" +select = ["E", "F", "I", "N", "W"] +ignore = [] + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = "-v --cov=miniprofiler --cov-report=term-missing" diff --git a/host/setup.py b/host/setup.py deleted file mode 100644 index 50eea90..0000000 --- a/host/setup.py +++ /dev/null @@ -1,51 +0,0 @@ -"""Setup script for MiniProfiler host application.""" - -from setuptools import setup, find_packages - -with open("../README.md", "r", encoding="utf-8") as fh: - long_description = fh.read() - -setup( - name="miniprofiler", - version="0.1.0", - author="MiniProfiler Contributors", - description="Host application for embedded STM32 profiling", - long_description=long_description, - long_description_content_type="text/markdown", - url="https://github.com/yourusername/miniprofiler", - packages=find_packages(), - classifiers=[ - "Development Status :: 3 - Alpha", - "Intended Audience :: Developers", - "Topic :: Software Development :: Embedded Systems", - "License :: OSI Approved :: MIT License", - "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - ], - python_requires=">=3.8", - install_requires=[ - "Flask>=3.0.0", - "Flask-SocketIO>=5.3.0", - "pyserial>=3.5", - "pyelftools>=0.29", - "crc>=6.1.1", - "python-socketio>=5.10.0", - "eventlet>=0.33.3", - ], - entry_points={ - "console_scripts": [ - "miniprofiler=miniprofiler.cli:main", - ], - }, - include_package_data=True, - package_data={ - "miniprofiler": [ - "../web/templates/*.html", - "../web/static/css/*.css", - "../web/static/js/*.js", - ], - }, -)