Changes to set up the host python app with uv

2025-11-28 08:26:21 +05:30
parent 852957a7de
commit 3d4c3f7f04
10 changed files with 853 additions and 61 deletions
--- a/host/README.md
+++ 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