pinviz 0.9.2

Programmatically generate Raspberry Pi GPIO connection diagrams

PinViz

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.

Example Diagram

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:

uv tool install pinviz

Or as a project dependency:

# Using uv
uv add pinviz

# Using pip
pip install pinviz

Quick Start

Try a Built-in Example

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

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:

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

Python API

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

# 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

# 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

# List all boards, devices, and examples
pinviz list

# JSON output for programmatic use
pinviz list --json

Configuration Management

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

# View current configuration
pinviz config show

# Edit config file
pinviz config edit

Shell Completion

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

# Show completion script
pinviz completion show

Global Options

All commands support these global options:

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

Documentation

Full documentation: nordstad.github.io/PinViz

• Installation Guide - Detailed installation instructions
• Quick Start Tutorial - Step-by-step getting started guide
• CLI Usage - Command-line interface reference
• YAML Configuration - Complete YAML configuration guide
• Python API - Programmatic API reference
• Examples Gallery - More example diagrams and configurations
• API Reference - Complete API documentation

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Adding new devices: See guides/DEVICE_CONFIG_GUIDE.md for device configuration details.

License

MIT License - See LICENSE file for details

Credits

Board and GPIO pin SVG assets courtesy of Wikimedia Commons

Author

Even Nordstad

• GitHub: @nordstad
• Project: PinViz
• Documentation: nordstad.github.io/PinViz