Metadata-Version: 2.3
Name: pinviz
Version: 0.9.2
Summary: Programmatically generate Raspberry Pi GPIO connection diagrams
Keywords: raspberry-pi,gpio,diagram,wiring,visualization,electronics,svg,raspberry-pi-5,hardware,circuit-diagram
Author: Even Nordstad
Author-email: Even Nordstad <even.nordstad@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Dist: drawsvg~=2.4
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: mcp>=1.22.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: structlog>=24.1.0
Requires-Python: >=3.12
Project-URL: Bug Tracker, https://github.com/nordstad/PinViz/issues
Project-URL: Changelog, https://github.com/nordstad/PinViz/blob/main/CHANGELOG.md
Project-URL: Documentation, https://nordstad.github.io/PinViz/
Project-URL: Homepage, https://nordstad.github.io/PinViz/
Project-URL: Repository, https://github.com/nordstad/PinViz
Description-Content-Type: text/markdown

# PinViz

<p align="center">
  <img src="https://raw.githubusercontent.com/nordstad/PinViz/main/assets/logo_512.png" alt="PinViz Logo" width="120">
</p>

<p align="center">
  <a href="https://github.com/nordstad/PinViz/actions/workflows/ci.yml"><img src="https://github.com/nordstad/PinViz/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://nordstad.github.io/PinViz/"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Documentation"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+"></a>
  <a href="https://pypi.org/project/pinviz/"><img src="https://img.shields.io/pypi/v/pinviz.svg" alt="PyPI version"></a>
  <a href="https://pepy.tech/projects/pinviz"><img src="https://static.pepy.tech/personalized-badge/pinviz?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads" alt="PyPI Downloads"></a>
</p>

**Programmatically generate beautiful Raspberry Pi GPIO connection diagrams in SVG format.**

PinViz makes it easy to create clear, professional wiring diagrams for your Raspberry Pi projects. Define your connections using simple YAML/JSON files or Python code, and automatically generate publication-ready SVG diagrams.

<p align="center">
  <img src="https://raw.githubusercontent.com/nordstad/PinViz/main/scripts/demos/output/quick_demo.gif" alt="PinViz Quick Demo" width="800">
</p>

## Example Diagram

<p align="center">
  <img src="https://raw.githubusercontent.com/nordstad/PinViz/main/images/bh1750.svg" alt="BH1750 Light Sensor Wiring Diagram" width="600">
</p>

## Features

- 📝 **Declarative Configuration**: Define diagrams using YAML or JSON files
- 🎨 **Automatic Wire Routing**: Smart wire routing with configurable styles (orthogonal, curved, mixed)
- 🎯 **Color-Coded Wires**: Automatic color assignment based on pin function (I2C, SPI, power, ground, etc.)
- ⚡ **Inline Components**: Add resistors, capacitors, and diodes directly on wires
- 🔌 **Built-in Templates**: Pre-configured boards (Raspberry Pi 4, 5 & Pico) and common devices
- 🐍 **Python API**: Create diagrams programmatically with Python code
- 🤖 **MCP Server**: Generate diagrams from natural language with AI assistants
- 📦 **SVG Output**: Scalable, high-quality vector graphics
- ✨ **Modern CLI**: Rich terminal output with progress indicators and colored messages
- 🔧 **JSON Output**: Machine-readable output for CI/CD integration
- ⚙️ **Configuration Management**: TOML config file support with precedence rules
- 🚀 **Shell Completion**: Auto-complete for bash, zsh, and fish shells

## Installation

Install as a standalone tool with global CLI access:

```bash
uv tool install pinviz
```

Or as a project dependency:

```bash
# Using uv
uv add pinviz

# Using pip
pip install pinviz
```

## Quick Start

### Try a Built-in Example

```bash
# Generate a BH1750 light sensor wiring diagram
pinviz example bh1750 -o bh1750.svg

# See all available examples
pinviz list
```

### Create Your Own Diagram

Create a YAML configuration file (`my-diagram.yaml`):

```yaml
title: "BH1750 Light Sensor Wiring"
board: "raspberry_pi_5"

devices:
  - type: "bh1750"
    name: "BH1750"

connections:
  - board_pin: 1     # 3V3
    device: "BH1750"
    device_pin: "VCC"

  - board_pin: 6     # GND
    device: "BH1750"
    device_pin: "GND"

  - board_pin: 5     # GPIO3 (I2C SCL)
    device: "BH1750"
    device_pin: "SCL"

  - board_pin: 3     # GPIO2 (I2C SDA)
    device: "BH1750"
    device_pin: "SDA"
```

Generate your diagram:

```bash
pinviz render my-diagram.yaml -o output.svg
```

### Python API

```python
from pinviz import boards, devices, Connection, Diagram, SVGRenderer

board = boards.raspberry_pi_5()
sensor = devices.bh1750_light_sensor()

connections = [
    Connection(1, "BH1750", "VCC"),  # 3V3 to VCC
    Connection(6, "BH1750", "GND"),  # GND to GND
    Connection(5, "BH1750", "SCL"),  # GPIO3/SCL to SCL
    Connection(3, "BH1750", "SDA"),  # GPIO2/SDA to SDA
]

diagram = Diagram(
    title="BH1750 Light Sensor",
    board=board,
    devices=[sensor],
    connections=connections
)

renderer = SVGRenderer()
renderer.render(diagram, "output.svg")
```

## CLI Commands

PinViz provides a modern CLI with rich terminal output and machine-readable JSON support.

### Rendering Diagrams

```bash
# Generate diagram from YAML config
pinviz render examples/bh1750.yaml -o output.svg

# With JSON output for CI/CD
pinviz render examples/bh1750.yaml --json
# Output: {"status": "success", "output_path": "output.svg", "validation": {...}}
```

### Validation

```bash
# Validate diagram configuration
pinviz validate examples/bh1750.yaml

# Strict mode (warnings as errors)
pinviz validate examples/bh1750.yaml --strict

# Machine-readable output
pinviz validate examples/bh1750.yaml --json
```

### List Templates

```bash
# List all boards, devices, and examples
pinviz list

# JSON output for programmatic use
pinviz list --json
```

### Configuration Management

```bash
# Create config file (~/.config/pinviz/config.toml)
pinviz config init

# View current configuration
pinviz config show

# Edit config file
pinviz config edit
```

### Shell Completion

```bash
# Install shell completion (bash, zsh, fish)
pinviz completion install

# Show completion script
pinviz completion show
```

### Global Options

All commands support these global options:

```bash
--log-level [DEBUG|INFO|WARNING|ERROR]  # Set logging verbosity
--log-format [console|json]            # Log output format
--version                              # Show version
--help                                 # Show help
```

## MCP Server (AI-Powered)

PinViz includes an **MCP (Model Context Protocol) server** that enables natural language diagram generation through AI assistants like Claude Desktop. Generate diagrams with prompts like "Connect a BME280 temperature sensor to my Raspberry Pi 5" with intelligent pin assignment, automatic I2C bus sharing, and conflict detection.

**[→ Full MCP documentation](https://nordstad.github.io/PinViz/mcp-server/)**

## Documentation

**Full documentation:** [nordstad.github.io/PinViz](https://nordstad.github.io/PinViz/)

- [Installation Guide](https://nordstad.github.io/PinViz/getting-started/installation/) - Detailed installation instructions
- [Quick Start Tutorial](https://nordstad.github.io/PinViz/getting-started/quickstart/) - Step-by-step getting started guide
- [CLI Usage](https://nordstad.github.io/PinViz/guide/cli/) - Command-line interface reference
- [YAML Configuration](https://nordstad.github.io/PinViz/guide/yaml-config/) - Complete YAML configuration guide
- [Python API](https://nordstad.github.io/PinViz/guide/python-api/) - Programmatic API reference
- [Examples Gallery](https://nordstad.github.io/PinViz/guide/examples/) - More example diagrams and configurations
- [API Reference](https://nordstad.github.io/PinViz/api/) - Complete API documentation

## Contributing

Contributions are welcome! Please see our [Contributing Guide](https://nordstad.github.io/PinViz/development/contributing/) for details.

**Adding new devices:** See [guides/DEVICE_CONFIG_GUIDE.md](guides/DEVICE_CONFIG_GUIDE.md) for device configuration details.

## License

MIT License - See [LICENSE](LICENSE) file for details

## Credits

Board and GPIO pin SVG assets courtesy of [Wikimedia Commons](https://commons.wikimedia.org/)

## Author

Even Nordstad

- GitHub: [@nordstad](https://github.com/nordstad)
- Project: [PinViz](https://github.com/nordstad/PinViz)
- Documentation: [nordstad.github.io/PinViz](https://nordstad.github.io/PinViz/)
