ESP Viewer Framework

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

🚀 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.

🛠 Getting Started

Installation

# 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):

python3 -m esp_viewer

Web UI Dashboard (Vue 3):

python3 -m esp_viewer --web --profile assets/examples/multi_plot_demo.json
# Access at http://localhost:8080

📖 Documentation

• Profile Definition - How to write your first JSON profile.
• Communication Protocol - Detailed IPC and device-level contracts.
• Architecture & Design - Deep dive into core modules and data flow.
• Development & Build - Environment setup and UI compilation.
• Agent Guide - Build on top of the framework using AI.