j0ono0/pinout

An open source Python package that generates hardware pinout diagrams as SVG images.

pinout

SVG diagram creation from Python code - pinout provides an easy method of creating pinout diagrams for electronic hardware.

Please visit pinout.readthedocs.io for the full quick start tutorial and detailed documentation on all options provided by the pinout package.

Quick start

pinout can be easily installed with pip and provides some sample files that demonstrate key features.

Install

Using a virtual environment is recommended; Start by installing the pinout package. Either clone this repo and pip install it or install from PyPi:

pip install pinout

# Or upgrade to the latest version
pip install --upgrade pinout

Duplicate sample files

A normal pinout diagram will include a hardware image, stylesheet, data file, and a Python script. Sample files are included with the package and can be duplicated for your use. Open a command line (with enabled virtual environment if you are using one) in the location you plan to work and enter the following:

py -m pinout.manager --duplicate quick_start

# expected output:
# >>> data.py duplicated.
# >>> hardware.png duplicated.
# >>> pinout_diagram.py duplicated.
# >>> styles.css duplicated.

Once you have these file a finished diagram can be generated from a command line py -m pinout.manager --export pinout_diagram diagram.svg. An SVG file is created and can be conveniently view in a browser.

For a detailed walk through pinout_diagram.py and more information on pinout please visit pinout.readthedocs.io.

pinout's Issues

access KiCad title_block content

title block content is an obvious source of content that might be useful in a pinout diagram - Providing access to the title block will remove need for doubling up on content input.

Diagram.add_svg_markup()

Enable users to insert arbitrary SVG markup into the document.
This will allow externally generated elements to be incorporated programmatically.

ClipPath - needs broader implementation

ClipPath feature is very limited in usage - limited to clipping SVGShape components.
Docs lack clear explaination of how to use clippath and where it can be used.

1. Expand ClipPath feature for use with groups and images.
2. Update ClipPath docs

Tomu Pinouts

Create a pinout template example that can be used for similar boards.
Use the Tomu family as an example.: https://tomu.im/

Project goals:

• Source data from spreadsheet(s)
• Maximise automation

Promo content: 0.0.10 realease

Make sample content to celebrate 0.0.10 release.

Double row connectors

I have not seen a sample with double row connectors.

Can Pinout work on boards like this one ?
https://github.com/infphyny/FpgaRiscV/blob/main/data/Deca/Deca.svg

Whitespace control for document layout

incorporate a method of controlling layout for all components on the page.
ie. features to document design grids.

Initial ideas:

• Add padding attribute to Component -- Probably would be adequate for an initial feature
• create a separate dedicated white-space component -- might provide better (more obvious) usage clarity to users. Opens opportunity for more complex white space control if/when required.

SVG board image not embedding properly

Hello,

Thank you for creating pinout! I just wanted to let you know of an issue I am currently running into an issue when embedding an SVG board image. After setting embed=True when running add_image(...), I'm getting an XML error in the output file:

Commenting out this line gives a scaled down version of the board:

It should look something like this (this is when embed is False and when using a png board file):

I do want to embed it though, as it makes it easier for moving it around (and due to CORS). All the code is currently on my github here. Let me know if there's anything I can do.

clip-path error in inkscape

Importing the Arduino SVG sample into inkscape displays an error with clip-path on components that have been 'flipped'.

• bug appears on a clip-path that is a and includes an arc.
• bug didn't reproduce on or path with only straight lines.
• inkscape may also have a display error where the arc is not displayed at some zooms - but still exports as png correctly

more testing required

Formatting: Label data and configuration

Most recent tests separated label data from the pinout script - This keeps the script concise and clear.
However the data file is overwhelmingly filled with repeated configuration settings. Ideally the file content should:

• Clearly document label content in a readable way
• Minimise visual clutter of repeated config settings (make it more DRY)
• Cater for single config variable changes that affect all relevant label configs

enable default settings

current method of documenting pin-labels is (possibly) unnecessary verbose where labels share many common geometry features.
Review and amend method of label configuration.

rewrite Legend documentation

Legend docs are lacking clarity and need rewrite.

Add Use to docs

Use component is missing from the docs - add it in.

Legend class rewrite: Entries as own class?

Entries as a separate class might divide and simplify the large number of parameters to construct a legend. Separate entries may also aid with more flexible legend layout.

Label customisations

Enable easier method of inserting custom components into a label if possible.
...or a method of 'assembling' labels from user defined elements

key ideal outcomes:

• custom label body
• custom leaderline

Enable export to other formats (PNG, PDF & PS

With the sightly arduous process for installing GTK on windows conquered - initial test show cairosvg works very well and I think is worth adding for more output options.

Random thoughts on 0.0.9

These are a few random thoughts I had while working with 0.0.9, not sure how useful they are, so take them as you will, 0.0.9 is great as-is anyways! :)

Feels a bit weird to have YAML and the py files, in the main branch the data is in py and just the style stuff is in CSS, that makes sense to me.
It also feels weird that half of the legend info (i.e. position) is in py but then width and radius are in YAML. I guess my confusion comes from the fact that the YAML mixes two types of information: styles (colors, fonts, etc.) and data (tag names).

It feels a bit weird that the tags info is spread between YAML and py, I get that the categories param for add_legend is optional and only useful if you want to hide some tags, but if you want to add a new tag, you have to do it in two places. Maybe it would be better to add a visible property to the tags in YAML, have them be true by default s you only set false for the ones you want to hide.

I wish I could provide colors as #112233 hex values for the tags :D

I was surprised to find out that the labels don't adjust their width to fit the whole text they contain, but I do understand it might be hard to calculate that dynamically with custom fonts, weights, and all that. Not a big deal.

It would be great to be able to provide background AND text colors for tags as I did in my fork. Some colors don't work as well with black text, but some do.

Can't wait to be able to add custom text in random places!

• the stuff I did in my work: parallelogram labels, a bullet at the end of the leaderline, hiding leaderlines between labels, having all the leaderlines be one color, and injecting raw svg code

Thanks!

Testing: 2nd arduino board

Test process of reusing and existing project setup.
Expectation:

• complete new data
• minor changes to config (pin position data)
• very minor script alterations - image, data and output name
  ...should yield a new diagram

PNG / SVG export differences

When exporting there is following differences of text not center aligned inside labels in the SVG version whereas PNG version left is Ok. Any clues?

Add CSS class(s) to clippaths

clip path associated with components need to be target-able in CSS.
use case: corner radius can be controlled in CSS but requires clip path to also be styled

NOTE: all style-geometry should be done with CSS
"style geometry" are attributes that do not affect layout calculations

Amend inconsistent interface styles

update all components to have better interface consistency.
review/update where and how a user inputs data and configurations

Include some example output diagrams in the README?

It would be awesome if you included some output diagrams examples in the README.

Enable export as png

pycairo is the most likely contender to include as a dependency.

Build GitHub actions based CI to publish to PyPI on releases

I would like to contribute by building a GitHub actions based CI to publish to PyPI on release tags. As a pre-requisite for this to ensure code quality and stability an appropriate PyCQA suite and Testing suite is necessary.

Reinstate style/css module

existing style tools require amending to work with latest default components.
update code and reinstate module.

Embed linked assets

Final files are difficult to work with outside the browser viewing environment, possibly due to images and styles being linked rather than embedded. Test if embedding assets enhances flexible usability.
Actions:

• embed CSS in style tag --if result still poor --> embed inline?
• base 64 encode images and embed in SVG

Test if appearance is improved in:

• Inkscape
• Adobe Illustrator
• Photoshop
• Gimp
• Recent browsers

If test work enable as an option to export embedded or linked.

Samples have inaccuracies: fix

annotations sample labels a micro usb-c --don't think this exists!
hardware board 'microcontroller' has an unlikely pin-count - add more pins to match a popular component.

Improve 0.0.15 docs

Docs lack good explanation of existing functionality.

• review/update all modules
• include more example code
• include diagrams to illustrate concepts where helpful

redesign legend component for 0.0.10

note comments in #16 - attempt to maintain separation of content, geometry, and styles.

SVGs of Arduino boards

As commented in Twitter (https://twitter.com/dcuartielles/status/1396565190007824385) there are some SVGs of Arduino boards available in Fritzing sources/packages: https://github.com/fritzing/fritzing-parts/tree/develop/svg/core/breadboard. Some other are available in the Arduino documentation site, but not all of the boards provide "Fritzing Files". See, for instance, https://docs.arduino.cc/hardware/nano-every and https://docs.arduino.cc/hardware/nano.

---

I was about to try using one of those with pinout, but the quick start is not working for me:

# git clone https://github.com/j0ono0/pinout
# cd pinout
# PYTHONPATH=$(pwd) python -m pinout.file_manager --duplicate quick_start
Traceback (most recent call last):
  File "C:/msys64/mingw64/lib/python3.8/runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:/msys64/mingw64/lib/python3.8/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "T:\pinout/pinout/file_manager.py", line 3, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

Title / text block

Enable a way for other supporting text to be added to the diagram.

testing slack intergration

Rewrite ClipPath documentation

ClipPath documentation is not clear, needs rewriting.

Predefined styles

Predefine sets of styles (primarily colour palettes).
Document visuals showing example outcome and 'styleguide' of unique aspects.
Provide easy method of incorporating these styles into an existing pinout project.

Differential pair pins: require unique label?

I'm attempting to find and ideal way to document differential pair pins with pinout.

If you have experience with them and opinions on how you would like to see them documented in a pinout diagram feel free to post and comment on the discussion here :)

Edit: added image with sample labeling as seen on twitter

Ceate pre-defined layouts

Build some obvious layouts to help users get a fast start creating diagrams.
This may tie in closely with issue #2

• x2 panels: main panel with title bar at bottom
• • x2 panels: main panel with title bar at right

Move geometry CSS into python code

Inkscape - the primary test and endorsed method for converting pinout diagrams to other formats - does not support Geometric attributes as style properties with "No plan to implement at moment." as their current status on the subject.

Info found here:
http://tavmjong.free.fr/SVG/INKSCAPE/

corner radius is the key attribute affected - incorporate it into the python code (rather than in CSS)

Extract KiCad data

Explore possibilities for extracting data direct from a kicad_pcb file.
Options/ideas:

• Create pinout KiCad footprint library for documenting label coordinates and content
• Add "pinout-data" to existing footprint instances (modules) as an "fp_text" entry
• Extract and draw CutLines and nominated components

Related Note: pcbdraw looks promising as a source for PCB images - as suggested by others. Windows (my dev env) is not well supported by current KiCad release and consequently I've not tried it out yet.

ideas for image x-y positional documentation

I had somewhat of a difficult time getting started with my first board. The issue was a repeated edit file, run pinout, reload image process as I tried to position pinout items on my image with a trial-and-error process. I wrote a little script to automate the first two (then manually refresh the browser):

#!/usr/bin/env bash

while  [ 1 -eq 1 ]; do 
  inotifywait -e modify styles.css pinout_ulx3s.py data.py
  echo "Change! $(date)"
  rm pinout_ulx3s.svg
  python3 -m pinout.manager --export pinout_ulx3s pinout_ulx3s.svg
done

Perhaps this would be useful to others... but I'm also wondering if better documentation on the positioning parameters would help? What do you think of taking the quickstart data file, and having it notated in an image with all the respective data file <x,y> coordinates as defined in the respective data file?

[Discussion] Decide on coding styles and apply PyCQA + Pytest

To improve consistency and readbility with external contributions let us add

• A contributors file
• Add some combination of linting and code-quality analysis via CI
• Start working on a small test suite to check stability on PR's

I would work on all these as time allows.

enable alternative units (in, cm, mm)

Enable users to input dimensions in physical units.

Might be desirable because aspects of the diagram are intrinsically measured in physical/defined scales:
PCBs are created according to physical dimensions
Diagrams are likely to be printed out on standardized paper sizes (and at dpi higher than screen dpi)

file based user config

Enable users to provide config settings in their own config module.
This will allow better styling portability between diagrams.
Potentially useful where entire config requires amendment/swapping - eg. where unit measurements are changed from px to mm, cm or in.

AND ...Update all modules to refer to revised config

0.0.10 docs

Amend docs for version 0.0.10.
consider inclusion of 'developers guide' to assist with extending and modifying the default setup.

Pin labels ancored up and down to board

Most cool boards have pinout location along more than just the left and right edges.
Enable pin labels to document pin headers located along the bottom and top of the board.

Labels for hardware annotations

a distinctly styled label for annotating hardware (or the diagram in general).

• suitable for easy reading if overlapping other graphics

auto-generated css colors: reject similar colors

The auto-generated css colors can create very similar colors by chance (even identical!) reducing clarity of label categories.
As colors are created they could be checked against existing colors to ensure there is enough difference.

reinstate annotation styled labels

Diagram background element

include an element to allow diagram background color and opacity to be user controlled

• Insert a into the SVG template covering the entire visible dimensions or the diagram to allow adding a background color.
• Set background color and opacity in config file

Update docs for v0.0.9

quick_start instructions do not work with Python 3.8.6

tried to follow instructions.
"Open a command line in the location you plan to work and enter the following:
py -m pinout.file_manager --duplicate quick_start"

I do not know how to fix this or what is complaining

$ py -m pinout.file_manager --duplicate quick_start

/usr/bin/py:16: DeprecationWarning: Using or importing the ABCs from 'collections' instead of from 'collections.abc' is deprecated since Python 3.3, and in 3.9 it will stop working (not working in 3.8.6!)
from collections import Iterable
usage: py [-x] [-l] [-c PRE_CMD] [-C POST_CMD] [-V] [-h] [expression]
py: error: unrecognized arguments: -m --duplicate quick_start

$ python --version
Python 3.8.6