pinviz 0.8.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.

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

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

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