pinviz 0.16.0

Programmatically generate Raspberry Pi GPIO connection diagrams

PinViz

Programmatically generate beautiful GPIO connection diagrams for Raspberry Pi and ESP32/ESP8266 boards in SVG format.

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

Example Diagram

→ See more examples

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, ESP32, ESP8266) and common devices
• 🐍 Python API: Create diagrams programmatically with Python code
• 🤖 MCP Server: Generate diagrams from natural language with AI assistants
• 🌙 Dark Mode: Built-in light and dark themes for better visibility
• 📦 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

Multi-Level Device Support ✨

New in v0.11.0: PinViz now supports device-to-device connections, enabling complex multi-level wiring diagrams!

What's New

• Connect devices to other devices (not just to the board)
• Automatic horizontal tier layout based on connection depth
• Supports power distribution chains, sensor chains, motor controllers, and more
• Backward compatible with existing configurations

Example: Power Distribution Chain

connections:
  # Board to regulator
  - from: {board_pin: 2}
    to: {device: "Regulator", device_pin: "VIN"}

  # Regulator to LED (device-to-device!)
  - from: {device: "Regulator", device_pin: "VOUT"}
    to: {device: "LED", device_pin: "VCC"}

See examples/multi_level_simple.yaml for a complete example.

Dark Mode 🌙

Generate diagrams optimized for dark backgrounds. Perfect for documentation displayed in dark themes.

title: "My Diagram"
board: "raspberry_pi_5"
theme: "dark"  # or "light" (default)
devices: [...]
connections: [...]

Or use the CLI flag:

pinviz render diagram.yaml --theme dark -o output.svg

See examples/bh1750_dark.yaml for a complete example.

Supported Boards

Board	Aliases	GPIO Pins	Description
Raspberry Pi 5	raspberry_pi_5, rpi5, rpi	40-pin	Latest Raspberry Pi with improved GPIO capabilities
Raspberry Pi 4	raspberry_pi_4, rpi4	40-pin	Popular Raspberry Pi model with full GPIO header
Raspberry Pi Pico	raspberry_pi_pico, pico	40-pin (dual-sided)	RP2040-based microcontroller board
ESP32 DevKit V1	esp32_devkit_v1, esp32, esp32_devkit	30-pin (dual-sided)	ESP32 development board with WiFi/Bluetooth
ESP8266 NodeMCU	esp8266_nodemcu, esp8266, nodemcu	30-pin (dual-sided)	ESP8266 WiFi development board
Wemos D1 Mini	wemos_d1_mini, d1mini, wemos	16-pin (dual-sided)	Compact ESP8266 development board

All boards include full pin definitions with GPIO numbers, I2C, SPI, UART, and PWM support.

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"
    color: "turquoise"  # Named color support (or use hex: "#50E3C2")

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 Examples

PinViz provides a modern CLI

Rendering Diagrams

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

Validation

# Validate diagram configuration
pinviz validate examples/bh1750.yaml

List Templates

# List all boards, devices, and examples
pinviz list

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