pinviz 0.4.0

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.

Features

📦 PinViz Package (Python Library & CLI)

• Declarative Configuration: Define diagrams using YAML or JSON files
• Programmatic API: Create diagrams with Python code
• Automatic Wire Routing: Smart wire routing with configurable styles (orthogonal, curved, mixed)
• Inline Components: Add resistors, capacitors, and diodes directly on wires
• Color-Coded Wires: Automatic color assignment based on pin function (I2C, SPI, power, ground, etc.)
• Built-in Templates: Pre-configured boards (Raspberry Pi 5) and common devices (BH1750, IR LED rings, etc.)
• GPIO Pin Reference: Optional GPIO pinout diagram for easy reference
• SVG Output: Scalable, high-quality vector graphics

🤖 MCP Server (AI-Powered)

• Natural Language Diagram Generation: Generate diagrams from conversational prompts like "Connect BME280 and LED to my Raspberry Pi"
• Intelligent Pin Assignment: Automatic I2C bus sharing, SPI chip select allocation, and conflict detection
• 📚 Device Database: 25+ pre-configured devices (sensors, displays, HATs, components) with automatic pin mapping
• 🔗 URL-Based Device Discovery: Add new devices by parsing datasheets from manufacturer websites
• AI Assistant Integration: Works with Claude Desktop, GitHub Copilot, and other MCP-compatible clients

📥 Installation

For CLI Usage (Recommended)

Install as a standalone tool with global access to the CLI:

uv tool install pinviz

After installation, pinviz will be available globally in your terminal. See Quick Start below to generate your first diagram.

As a Project Dependency

If you want to use PinViz as a library in your Python project:

# Using uv
uv add pinviz

# Using pip
pip install pinviz

Note: If you install with uv add, the CLI tool will only be available via uv run pinviz. For direct CLI access, use uv tool install instead.

🚀 Quick Start

1. Try a Built-in Example

The fastest way to get started is to generate one of the built-in examples:

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

# See all available examples
pinviz list

This creates an SVG file you can open in any web browser or vector graphics editor.

Note: If you installed with uv add instead of uv tool install, prefix commands with uv run:

uv run pinviz example bh1750 -o bh1750.svg

2. Create Your Own Diagram

Once you've seen what PinViz can do, create your own configuration file my-diagram.yaml:

title: "BH1750 Light Sensor Wiring"
board: "raspberry_pi_5"  # or "raspberry_pi_zero_2w" for Pi Zero

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"

show_gpio_diagram: true  # Optional: include GPIO pin reference

Generate your diagram:

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

3. Using Python API

For programmatic diagram generation in your Python projects:

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

# Create board and device
board = boards.raspberry_pi_5()  # or boards.raspberry_pi_zero_2w()
sensor = devices.bh1750_light_sensor()

# Define connections
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
]

# Create and render diagram
diagram = Diagram(
    title="BH1750 Light Sensor Wiring",
    board=board,
    devices=[sensor],
    connections=connections,
    show_gpio_diagram=True  # Optional: include GPIO pin reference
)

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

Custom Wire Colors

Use the WireColor enum for standard electronics wire colors:

from pinviz import (
    boards, devices, Connection, Diagram, SVGRenderer, WireColor
)

# Define connections with custom colors
connections = [
    Connection(1, "BH1750", "VCC", color=WireColor.RED),
    Connection(6, "BH1750", "GND", color=WireColor.BLACK),
    Connection(5, "BH1750", "SCL", color=WireColor.BLUE),
    Connection(3, "BH1750", "SDA", color=WireColor.GREEN),
]

# Or use hex colors directly
connections = [
    Connection(1, "BH1750", "VCC", color="#FF0000"),  # Red
]

Available colors: RED, BLACK, WHITE, GREEN, BLUE, YELLOW, ORANGE, PURPLE, GRAY, BROWN, PINK, CYAN, MAGENTA, LIME, TURQUOISE

💻 CLI Commands

See the Quick Start section for basic usage. All examples below assume you installed with uv tool install pinviz or pip install pinviz. If you installed with uv add, prefix all commands with uv run.

Rendering Custom Diagrams

# From YAML/JSON file with specified output
pinviz render my-diagram.yaml -o output.svg

# Short form (output defaults to <config-name>.svg)
pinviz render my-diagram.yaml

Working with Built-in Examples

# List all available built-in examples
pinviz list

# Generate a specific example
pinviz example bh1750 -o bh1750.svg
pinviz example ir_led -o ir_led.svg
pinviz example i2c_spi -o i2c_spi.svg

MCP Server (AI-Powered Diagram Generation)

PinViz includes an MCP (Model Context Protocol) server that enables natural language diagram generation through AI assistants like Claude Desktop.

What is the MCP Server?

The MCP server provides:

• Natural Language Parsing: Generate diagrams from prompts like "Connect BME280 and LED to my Raspberry Pi"
• Intelligent Pin Assignment: Automatic I2C bus sharing, SPI chip select allocation, and conflict detection
• Device Database: 25+ pre-configured devices (sensors, displays, HATs, components)
• URL-Based Device Discovery: Add new devices by parsing datasheets from URLs

Quick Start with Claude Desktop

Easiest Method (using Claude CLI):

# Install PinViz
pip install pinviz

# Add to Claude Desktop automatically
claude mcp add pinviz pinviz-mcp

# Restart Claude Desktop

Manual Method (edit config file):

1. Install PinViz:

   pip install pinviz
   

2. Configure Claude Desktop:

   Edit ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

   {
     "mcpServers": {
       "pinviz": {
         "command": "pinviz-mcp"
       }
     }
   }
   

3. Restart Claude Desktop

Start generating diagrams with natural language:

"Connect a BME280 temperature sensor to my Raspberry Pi 5"

GitHub Copilot (VS Code)

To use PinViz with GitHub Copilot in VS Code, add to your settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "pinviz": {
      "command": "pinviz-mcp"
    }
  }
}

Then reload VS Code and use @pinviz in Copilot Chat:

@pinviz Connect BME280 and LED to Raspberry Pi 5

See the Installation Guide for detailed setup instructions.

Example MCP Prompts

• Simple sensor: "Wire a BH1750 light sensor to my pi"
• Multiple devices: "Connect BME280, BH1750, and an LED on GPIO 17"
• Weather station: "Set up environmental monitoring with BME280 and DHT22"
• Device search: "What I2C displays are available?"
• Device info: "Tell me about the BME280 sensor pinout"

Available MCP Tools

• generate_diagram - Convert natural language to wiring diagrams (YAML/JSON/summary)
• list_devices - Browse 25+ devices by category/protocol
• get_device_info - Get detailed device specifications
• search_devices_by_tags - Find devices by tags
• parse_device_from_url - Add new devices from datasheet URLs
• get_database_summary - View database statistics

Documentation

• Installation Guide: src/pinviz_mcp/docs/INSTALLATION.md
• Usage Guide with Examples: src/pinviz_mcp/docs/USAGE.md
• Device Contribution Guide: src/pinviz_mcp/docs/CONTRIBUTING_DEVICES.md
• MCP Server README: src/pinviz_mcp/README.md

Key Features

Intelligent Pin Assignment:

• Automatic I2C bus sharing (multiple devices on SDA/SCL)
• SPI chip select allocation (CE0, CE1)
• Power distribution (cycles through 3.3V and 5V pins)
• Conflict detection and resolution

Hybrid Parsing:

• Regex patterns for common prompts (80% of cases, instant)
• Claude API fallback for complex prompts (20% of cases)

Device Database:

• 25+ devices covering sensors, displays, HATs, and components
• Categories: sensor, display, hat, component, actuator, breakout
• Protocols: I2C, SPI, UART, GPIO, 1-Wire, PWM

🖼️ Example Diagrams

LED with Resistor

Simple LED circuit with inline current-limiting resistor:

Multi-Device Setup

BH1750 light sensor + IR LED ring with custom wire colors:

Traffic Light

Three LEDs with individual resistors:

GPIO Details: With vs Without

You can control whether to show the GPIO pin reference diagram. Here's a comparison:

With GPIO Details (--gpio or show_gpio_diagram: true):

Shows complete GPIO pinout reference for easy wiring verification.

pinviz example bh1750 --gpio -o diagram.svg

Without GPIO Details (--no-gpio or default):

Cleaner, more compact diagram - 35% smaller file size.

pinviz example bh1750 --no-gpio -o diagram.svg

⚙️ Configuration Reference

Diagram Options

GPIO Pin Reference

Control whether to show the GPIO pin reference diagram on the right side. This displays all 40 GPIO pins with their functions and color-coded roles.

In YAML config:

show_gpio_diagram: true  # Include GPIO pin reference (default: false)

Via CLI:

# Show GPIO details (larger file, more complete reference)
pinviz example bh1750 --gpio -o diagram.svg

# Hide GPIO details (smaller file, cleaner look)
pinviz example bh1750 --no-gpio -o diagram.svg

# For config files (CLI flag overrides config value)
pinviz render diagram.yaml --gpio -o output.svg

Comparison:

• With GPIO (--gpio): ~130KB SVG, includes full pinout reference
• Without GPIO (--no-gpio): ~85KB SVG, 35% smaller, cleaner diagram

Board Selection

Currently supported boards:

• raspberry_pi_5 (aliases: rpi5, rpi) - Raspberry Pi 5 with 40-pin GPIO header
• raspberry_pi_zero_2w (aliases: raspberry_pi_zero, pizero, zero2w, zero, rpizero) - Raspberry Pi Zero / Zero 2 W with 40-pin GPIO header

Built-in Device Types

• bh1750 - BH1750 I2C light sensor
• ir_led_ring - IR LED ring module
• i2c_device - Generic I2C device
• spi_device - Generic SPI device
• led - Simple LED
• button - Push button/switch

Connection Configuration

Connections use physical pin numbers (1-40), not BCM GPIO numbers:

connections:
  - board_pin: 1           # Physical pin number (required)
    device: "Device Name"  # Device name (required)
    device_pin: "VCC"      # Device pin name (required)
    color: "#FF0000"       # Custom wire color (optional)
    style: "mixed"         # Wire style: orthogonal, curved, mixed (optional)
    components:            # Inline components (optional)
      - type: "resistor"
        value: "220Ω"
        position: 0.55     # Position along wire (0.0-1.0, default: 0.55)

Inline Components

Add resistors, capacitors, or diodes directly on wire connections:

connections:
  - board_pin: 11
    device: "Red LED"
    device_pin: "+"
    color: "#FF0000"
    components:
      - type: "resistor"   # Component type: resistor, capacitor, diode
        value: "220Ω"      # Display value (required)
        position: 0.55     # Position along wire path (0.0 = board, 1.0 = device)

Python API:

from pinviz import Component, ComponentType, Connection

connection = Connection(
    board_pin=11,
    device_name="Red LED",
    device_pin_name="+",
    color="#FF0000",
    components=[
        Component(
            type=ComponentType.RESISTOR,
            value="220Ω",
            position=0.55
        )
    ]
)

Custom Devices

Define custom devices inline:

devices:
  - name: "My Custom Sensor"
    width: 80.0
    height: 50.0
    color: "#4A90E2"
    pins:
      - name: "VCC"
        role: "3V3"
        position: {x: 5.0, y: 10.0}
      - name: "GND"
        role: "GND"
        position: {x: 5.0, y: 20.0}
      - name: "SDA"
        role: "I2C_SDA"
        position: {x: 5.0, y: 30.0}
      - name: "SCL"
        role: "I2C_SCL"
        position: {x: 5.0, y: 40.0}

Pin Roles

Supported pin roles (for automatic color assignment):

• 3V3, 5V - Power rails
• GND - Ground
• GPIO - General purpose I/O
• I2C_SDA, I2C_SCL - I2C bus
• SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CE0, SPI_CE1 - SPI bus
• UART_TX, UART_RX - UART serial
• PWM - PWM output

🔧 Development

Setup

# Clone repository
git clone https://gitlab.com/borkempire/pinviz.git
cd pinviz

# Install dependencies
uv sync --dev

Code Quality

# Lint and format
uv run ruff check .
uv run ruff format .

# Run tests
uv run pytest

📝 Examples

The examples/ directory contains:

• bh1750.yaml / bh1750_python.py - I2C light sensor
• bh1750_ir_led.yaml / bh1750_ir_led_python.py - Light sensor + IR LED ring
• led_with_resistor.yaml / led_with_resistor_python.py - LED with inline resistor
• traffic_light.yaml - Traffic light with 3 LEDs and resistors
• pi_zero_bh1750.yaml - BH1750 light sensor for Raspberry Pi Zero 2 W

All generated diagrams are in the images/ directory.

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Credits

Board and GPIO pin SVG assets courtesy of FreeSVG.org

👤 Author

Even Nordstad