Pinouts and doc

A project log for DIY Power for all - OwnTech

A fully open-source digital power electronics technology framework for fast prototyping switch-mode power supplies

guigurguigur 10/09/2022 at 01:270 Comments

A quick presentation.

A good project is NOTHING without good and understandable documentation. I've always loved good pinouts of dev boards, I think they save so much time and effort that they are a necessity.

I've searched a bit online and found PCBDraw by Jan Mrázek ( It's a fantastic tool from which you can convert your KiCAD PCB to a Vectorial image. 

Happy and full of myself with my nice SVG image, I then search for a good pinout maker software, and no dice. Such projects do exist but didn't fulfill my needs. 

Some (too much) coffee later, I made a little program in Python that does just that!

The program takes a JSON file describing all the functions of all the pins you want to document and generates a nice SVG image. My code is quite messy and not well documented (ironic ?) but it was made specifically to meet the deadline of the Hackaday wildcard challenge. 

What 3 nights of not enough sleep gets you? 

I'm glad you asked, this is our dev board SPIN!

SPIN Pinout
SPIN Pinout

Be aware that some assembly is required. The current version of this program only generates the "pins" and the legend. All the images, text, license, and adjustments are made after the fact on Inkscape!

So what this piece of kit does deliver?

This is a sample output file untouched straight from the program:

Raw unfiltered SPIN Pinout
Raw unfiltered SPIN Pinout

Pretty neat hun? I like to think this is pretty similar to buying a piece of Swedish furniture and putting it together yourself. Jokes aside, a later version of the software could take care of a lot of messing around but I need some rest.

How do I feed this monster?

Each pin is made of labels, and each label has a style and may have categories.

Buckle up it's going to be quite the ride from now.

A style.json file describes all the available styles present in your pinout. They define the color of the label as such as the skewed factor and special capabilities (hidden label, dummy label, only text label).

The legend plot the label in the same order as they are described in the style.json.

A sample of the styles of labels in styles.json
A sample of the styles of labels in styles.json

And for the pins themselves, we define the side (the orientation Left to right or Right to left), PWM capabilities, and most importantly the functions.

Each function is a label but is not necessarily plotted in the final image. We have to enter each name of the label in the name field, each style corresponding with a style in style.json, and so forth.

And finally, the categories able you to filter and omit categories of pins to simplify your pinout without redoing this file each time you change your mind (trust me it's a real-time saver).

Sample of spin_pins_L.json
Sample of spin_pins_L.json

Without this feature, our SPIN board would flood like this monster! And the last thing I want from a doc is to get a headache.

Way too much information for me
Way too much information for me

How about TWIST?

TWIST is a similar story to SPIN, with this tool I was able to generate labels and a nice-looking pinout cheat sheet. I like to cut away pieces of the board SVG on Inkscape to enhance visibility. 
TWIST Pinout
TWIST Pinout

What's the name of this amazing life-changing tool?

I may have some talent for programming and electronics but finding a good name is not one of my forte. I was not able to think of a better name thank PinMaker...
So If you want to poke around my code and give me some advice, you can find the sources here
Keep in mind, this is still pretty unfinished and I hope to polish the project in the near future.
Happy pin-making!
(I really need to think of a better name for my next project)