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.

If the board file can be inferred from the current directory, pinion template can be run without --board. When --output is omitted, it writes to <project>_pinion.yaml. Pinion refuses to overwrite that inferred output path; pass --output explicitly if you want to replace an existing file.

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.

When you run Pinion from a KiCad project directory, Pinion can infer the input file names. It first looks for a board named after the current directory, such as MyBoard.kicad_pcb in a directory named MyBoard. If that file does not exist, Pinion uses the only *.kicad_pcb file in the current directory. If there are multiple board files, pass --board explicitly. Similarly, the specification defaults to MyBoard_pinion.yaml or MyBoard_pinion.yml, or to the only *_pinion.yaml/*_pinion.yml file in the current directory.

With those names, the commands can be shortened to:

pinion generate plotted <path to output directory>
pinion generate rendered <path to output directory>

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.

By default, Pinion generates both board sides. If you only need one side, pass --side front or --side back to pinion generate. Single-side diagrams hide the front/back side switch in the widget.

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.

The widget includes pin search. Use the search box to find pins by name, description, or group; matching pins are highlighted on the current board side, and selecting a result pins it in the diagram.

If you need a diagram that works directly from the local filesystem without a web server, pass --embed to pinion generate. This creates a standalone index.html file with the widget, styles, specification, and board images embedded. This mode is convenient for sharing a single file, but the regular multi-file output is usually better for websites as browsers can cache the files separately. Standalone embedded diagrams also support direct highlight links. Append #group=Group name or just #group-name to the generated index.html URL to open the diagram with the matching group highlighted. You can also select a board side with #group=Group name&side=front or #group=Group name&side=back.

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>
    const pinionWidget = 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 point to the output directory created by pinion generate. This is not the KiCAD project directory; it is the generated diagram directory that contains the files Pinion widget loads. The path can be relative to the web page or absolute.

pinion.setup returns a controller object for programmatic control:

pinionWidget.highlightGroup("I2C");
pinionWidget.setGroupVisibility(["I2C", "SPI"], true);
pinionWidget.clearHighlights();
pinionWidget.setSide("front");

highlightGroup replaces the current highlighted groups and includes nested groups. Group matching first tries the exact group name, then a case-insensitive match, then a URL-friendly slug such as power-leds for Power LEDs. If your page has a single Pinion widget and you want it to react to location.hash, call pinion.setupHashHandler(pinionWidget).

GitHub does not run JavaScript embedded directly in README files, but the same HTML and JavaScript works from GitHub Pages or another static website.

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