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