Changes to set up the host python app with uv

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

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!** 🚀

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

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

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 <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/`

host/.python-version

@@ -0,0 +1 @@
+3.11

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

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:

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"

host/setup.py

@@ -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",
-        ],
-    },
-)