Making a diagram

To make a diagram you have to:

• specify which pins and components should be highlightable. This is done via specifying a simple YAML file.
• Build the diagram. This will generate a directory with several files.
• Embed it in your webpage/documentation.

Basic concepts

Pinion consists of two parts - diagram generator pinion (that you run on your computer) and a Javascript library that you include on your webpage, which reads and displays the diagram (pinion-widget).

Pinion can highlight components and pins of components. Each of these objects can have assigned a verbose description. This description is shown on mouse hover/click. Each object can belong to any number of groups. The user has the ability to highlight a given group.

Defining a diagram

The diagram is specified via YAML file with the following structure:

name: <name of the diagram>
description: <diagram description>
components: # A dictionary of component reference to component description
    <componentRef>:
        description: <component description>
        groups: <a list of groups>
        highlight: true/false
        highlightBoth: true/false # Forces that the component can be highlighted on both front and back
        pins: # A dictionary of pin names to pin description
            <pinName>:
                name: <human readable name of the pin>
                description: <pin description>
                alias: <pinName> # Use description of other pin. Alternative for description
                groups: <a list of groups>
groups: # An optional dictionary specifying tree structure of the groups, e.g.:
    Peripherals:
        - Adc
        - SPI
        - I2C
    Pins:
        - Digital
        - Analog

Note that you can use markdown in descriptions to make them pretty. You should specify only the pins and components you want to be highlightable.

It you remember the example diagram, it was generated by the this YAML file.

To save you some typing, Pinion can generate a template for your. Simply invoke:

pinion template \
    --board <path to .kicad_pcb file> \
    --output <path to YAML file> \
    --components <reqular expression for the reference>
    --components <you can specify multiple patterns if you need to>

Then you can modify the template as you need.

Building the diagram

To build the diagram, simply invoke:

# For stylized image style:
pinion generate plotted \
    --board <path to .kicad_pcb file> \
    --specification <your YAML file> \
    <path to output directory>

# For 3D rendered
pinion generate rendered \
    --board <path to .kicad_pcb file> \
    --specification <your YAML file> \
    <path to output directory>

This will generate all files required. Note that the board image is generated via PcbDraw. Therefore, if you struggle to generate the board image correctly, try using PcbDraw directly first to locate the issue.

Note that you can also specify the option --pack that will include pinion-widget and a simple, stand-alone page with the diagram. You should upload the entire directory on your web page.

Options for stylized diagrams

You can pass PcbDraw options to pinion generate to e.g., remap your components, specify color scheme or point PcbDraw to the right libraries. You read more about the details at PcbDraw documentation.

The supported options are: - --dpi to specify image DPI - --style to specify style (i.e., color scheme) - --libs to specify the footprint library - --remap to remap component footprints - --filter to hide some footprint on the board.

Options for 3D-rendered diagrams

The 3D rendered diagrams currently work only on Linux due to technical limitations of KiCAD. You can also specify the following options:

- `--renderer [raytrace|normal]`: Specify what renderer to use (the OpenGL preview or raytracing)
- `--projection [orthographic|perspective]`: Specify projection
- `--no-components`: Exclude components from from rendering
- `--transparent `: Make transparent background of the image (so, e.g., the shadow of the image can be properly rendered)

Testing the diagram

When you invoke pinion generate with --pack you can test the diagram without embedding it in a web page. The option --pack will pack the diagram with Pinion widget and a simple page that includes the widget. Then simply invoke pinion serve -b --directory <diagram directory> to preview the diagram in your browser.

Including the pinion widget on your webpage

Including pinion on a web page is simple. Just include the pinion-widget script, stylesheets and set it up:

<div id="pinionDemo"></div>

<script src="resources/pinion.js"></script>
<link rel="stylesheet" href="resources/pinion.css">

<script>
    pinion.setup(document.getElementById("pinionDemo"), {
        source: "resources/alksDemo"
    });
</script>

The first block creates a container in which we will the widget will be included. It can be anywhere on the page. Note that we will later need to reference this container, so we specify an id for it.

The second block loads pinion code and styles. You can either host these files by yourself or use CDN (will be specified later). The precise location depends on your setup.

In the third block, we start the widget. The first argument of pinion.setup is the container for the widget and the second argument is a dictionary that configures the widget. Currently, the only option is source that has to contain a location to the source directory (note that it can also be an absolute path).

And this is it. When you load your page, the diagram should be running!