# ESP Viewer Framework

A generic, profile-driven debugging and visualization framework for serial-based devices. 

[![PyPI version](https://img.shields.io/pypi/v/esp_viewer.svg)](https://pypi.org/project/esp_viewer/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

## 🚀 Overview

ESP Viewer is a modular tool designed to help developers visualize real-time data and control devices without writing custom GUI code. It bridges the gap between raw firmware development and sophisticated desktop monitoring.

### Why ESP Viewer?

- **Zero-Code GUI**: Define your interface in JSON. Rendering is handled automatically by either the Desktop or Web UI parsers.
- **Dual UI Paradigms**: Run natively as a PySide6 Desktop App, or launch the built-in Vue 3 Web UI (`--web` flag) for browser-based monitoring.
- **High Performance**: Optimized Qt/pyqtgraph backend for desktop, and hardware-accelerated Canvas for the browser.
- **Flexible Protocols**: Supports JSON-RPC, simple string templates, and custom CSV/Regex streams.
- **Hardware-Aware**: Specialized perspectives for deep ESP32 hardware inspection and firmware management.

## ✨ Core Features

*   **Real-time Visualization**: Plot multiple channels, markers, and events with high-frequency updates.
*   **Chip Info Diagnostics**: Deep inspection of ESP32 hardware including Model, Revision, Flash Identity, ADC Calibration, and eFuse dumps.
*   **Firmware Management**: Integrated `esptool.py` support for subprocess flashing and dynamic firmware binary downloads.
*   **Security Audit**: Real-time monitoring of Flash Encryption and Secure Boot status.
*   **Dynamic Controls**: Auto-generate sliders, combo boxes, and buttons from JSON profiles.
*   **Simulation Support**: Advanced Mock devices with persistent hardware data simulation (`mock_chip_info.json`).
*   **Data Logging**: Record raw IO or parsed streams to CSV/Log files.

## 📂 Directory Structure

*   `esp_viewer/core/`: Backend engine, protocol handling, and device drivers.
*   `esp_viewer/ui/`: PySide6-based Desktop UI and dynamic widget generation.
*   `esp_viewer/web/`: FastAPI-powered Web UI Alternative (Vue 3 + Vite).
*   `assets/profiles/`: Example configuration profiles for various use cases.
*   `core/mock_chip_info.json`: Persistent mock data for offline development.
*   `docs/`: Detailed technical specifications and [Architecture](docs/architecture.md).

## 🛠 Getting Started

### Installation

```bash
# Clone the repository
git clone https://github.com/espressif/esp_viewer.git
cd esp_viewer

# Install in editable mode
pip install -e .
```

### Usage

**Desktop Launcher (PySide6):**
```bash
python3 -m esp_viewer
```

**Web UI Dashboard (Vue 3):**
```bash
python3 -m esp_viewer --web --profile assets/examples/multi_plot_demo.json
# Access at http://localhost:8080
```

## 📖 Documentation

- [Profile Definition](docs/profile.md) - How to write your first JSON profile.
- [Communication Protocol](docs/protocol.md) - Detailed IPC and device-level contracts.
- [Architecture & Design](docs/architecture.md) - Deep dive into core modules and data flow.
- [Development & Build](docs/development.md) - Environment setup and UI compilation.
- [Agent Guide](docs/agent_guide.md) - Build on top of the framework using AI.

