KinJector 1.0.0 documentation

# Welcome to KinJector’s documentation!

## KinJector

Inject/eject JSON/YAML data to/from KiCad Board files.

- Free software: MIT license

- Documentation: https://devbisme.github.io/kinjector

### Features

- Parameters in one or more JSON or YAML files can be injected into a KiCad PCB file.

- Parameters from a KiCad PCB file can be extracted and stored in a JSON or YAML file.

- The currently-supported set of parameters can control the design rules, net classes, assignment of netclasses to particular nets, plotting options, and (X,Y)/orientation/top-bottom-side position of part footprints.

- Subsets of parameters can be used to restrict the scope of effects upon the PCB.

- A script is provided to allow injection/ejection of JSON/YAML data to/from a KiCad PCB file. In addition, the `kinjector` module can be used within other Python scripts to manipulate KiCad PCB files.

## Installation

KinJector needs KiCad’s `pcbnew` Python module to run. For this reason, you’ll probably want to install it in KiCad’s Python environment. Under Windows, you can do this by opening a terminal and issuing the command:

    $ set path=C:\Program Files\kicad\bin;%path%

Then to install KinJector, run this command in your terminal:

    $ pip install kinjector

This is the preferred method to install KinJector, as it will always install the most recent stable release. However, if you want the latest features before a stable release is made, you can get that with this command:

    $ pip install git+https://github.com/devbisme/kinjector

## Usage

### Command Line

KinJector comes with a command-line script called (appropriately enough) `kinjector`. It can be used in two ways:

1. To inject data stored in a JSON or YAML file into a KiCad board file

    $ kinjector -from data.json -to test.kicad_pcb

2. To extract data from a KiCad board file and store it in a JSON or YAML file

    $ kinjector -from test.kicad_pcb -to data.yaml

The data file can contain information on:

- Design rule settings (allowable track widths, via sizes, etc.);

- Enabled board layers and layer visibility;

- Net class definitions;

- Assignments of nets to net classes;

- Plot settings (format, output layers, etc.);

- Part information such as (X,Y) position, angle of orientation, and location on the top or bottom side of the PCB.

The easiest way to comprehend the structure of the data is to extract an example from an existing board and look at the resulting JSON/YAML file as follows:

    board:
      board setup:
        design rules:
          blind/buried via allowed: true
          hole to hole spacing: 678976266
          min track width: 320000
          min uvia diameter: 470000
          min uvia drill size: 120000
          min via diameter: 120000
          min via drill size: 110000
          prohibit courtyard overlap: false
          require courtyards: false
          uvia allowed: true
        layers:
          '# copper layers': 4
          board thickness: 3200000
          enabled:
          - 0
          - 1
          - 2
          - 31
          - 32
          - 33
          - 34
          - 35
          - 36
          - 37
          - 38
          - 39
          - 49
          visible:
          - 0
          - 31
          - 32
          - 33
          - 34
          - 35
          - 36
          - 37
          - 38
          - 39
          - 49
        net classes:
          net class assignments:
            ? ''
            : Default
            Net-(D1-Pad1): new_new_class
            Net-(D1-Pad2): Default
            Net-(R1-Pad2): Default
            Net-(R2-Pad1): new_new_class
          net class definitions:
            Default:
              clearance: 600000
              description: ''
              diff pair gap: 450000
              diff pair width: 400000
              track width: 350000
              uvia diameter: 800000
              uvia drill: 300000
              via diameter: 900000
              via drill: 800000
            new_new_class:
              clearance: 220000
              description: ''
              diff pair gap: 255000
              diff pair width: 150000
              track width: 225000
              uvia diameter: 330000
              uvia drill: 110000
              via diameter: 880000
              via drill: 455000
        solder mask/paste:
          solder mask clearance: 34000
          solder mask min width: 570000
          solder paste clearance: 1
          solder paste clearance ratio: -0.2
        tracks, vias, diff pairs:
          diff pair dimensions list: []
          track width list:
          - 1990000
          - 456000
          via dimensions list:
          - diameter: 480000
            drill: 841000
      modules:
        D1:
          position:
            angle: -120.0
            side: bottom
            x: 172517000
            y: 90297000
        R1:
          position:
            angle: -30.0
            side: top
            x: 161528000
            y: 102248000
        R2:
          position:
            angle: 120.0
            side: top
            x: 166187222
            y: 99187111
        R3:
          position:
            angle: 30.0
            side: bottom
            x: 277187000
            y: 203137000
      plot:
        autoscale: true
        color: null
        coordinate format: 4
        default line width: 150000
        do not tent vias: true
        drill marks: 2
        exclude pcb edge: false
        force a4 output: true
        format: 2
        generate gerber job file: true
        hpgl pen num: 2
        hpgl pen size: 16.0
        hpgl pen speed: 30
        include netlist attributes: true
        layers:
        - 0
        - 1
        - 2
        - 31
        - 34
        - 35
        - 36
        - 37
        - 38
        - 39
        - 44
        mirrored plot: true
        negative plot: true
        output directory: ''
        plot border: true
        plot footprint refs: false
        plot footprint values: false
        plot in outline mode: false
        plot invisible text: true
        plot mode: 1
        plot pads on silk: true
        scale: 2.0
        scaling: 3
        skip npth pads: true
        subtract soldermask from silk: true
        text mode: 2
        track width correction: 1
        use aux axis as origin: true
        use protel filename extensions: true
        use x2 format: true
        x scale factor: 2.0
        y scale factor: 1.2

You don’t need to specify every field in order to inject data into a board: only the fields you want to change are needed. For example, this YAML file will change the minimum track width to 0.3 mm (300000 nm) and leave the rest of the board unchanged:

    board:
      board setup:
        design rules:
          min track width: 320000

### As a Package

To use the KinJector package in a Python project:

    import kinjector

This will give you access to the `Board` class that has two methods:

- `inject(self, data_dict, brd)`: This will inject the data in a dictionary into a KiCad `BOARD` object.

- `eject(self, brd)`: This will return a dictionary containing all the data that is currently supported from a `BOARD` object.

As an example, the code shown below will extract all the data from a KiCad PCB file and then inject it all back into the same board:

    import json
    import pcbnew
    import kinjector

    # Extract info from a KiCad board and store it in a data file.
    brd = pcbnew.LoadBoard('test.kicad_pcb')
    data_dict = kinjector.Board().eject(brd)
    with open('test.json', 'w') as data_fp:
        json.dump(data_dict, data_fp, indent=4)

    # Inject data from file back into board.
    brd = pcbnew.LoadBoard('test.kicad_pcb')
    with open('test.json', 'r') as data_fp:
        data_dict = json.load(data_fp)
    kinjector.Board().inject(data_dict, brd)
    brd.Save('test_output.kicad_pcb')

You can also inject data into a board using Python dicts. Just replicate the hierarchical structure and field labels shown above.

## Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

### Types of Contributions

#### Report Bugs

Report bugs at https://github.com/devbisme/kinjector/issues.

If you are reporting a bug, please include:

- Your operating system name and version.

- Any details about your local setup that might be helpful in troubleshooting.

- Detailed steps to reproduce the bug.

#### Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

#### Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

#### Write Documentation

KinJector could always use more documentation, whether as part of the official KinJector docs, in docstrings, or even on the web in blog posts, articles, and such.

#### Submit Feedback

The best way to send feedback is to file an issue at https://github.com/devbisme/kinjector/issues.

If you are proposing a feature:

- Explain in detail how it would work.

- Keep the scope as narrow as possible, to make it easier to implement.

- Remember that this is a volunteer-driven project, and that contributions are welcome :)

### Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.

2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

3. The pull request should work for Python 2.7 and 3.7.

## Credits

### Development Lead

- Dave Vandenbout <devb@xess.com>

### Other Contributors

## History

### 1.0.0 (2021-09-16)

- Decided this tool was mature to the point it could be called 1.0.0.

### 0.0.6 (2020-02-14)

- yaml.load() will accept a KiCad board file as legal YAML, so place additional checks to detect yaml files and prevent over-writing .kicad_pcb files with YAML.

### 0.0.5 (2019-06-19)

- Rearranged hierarchy of board data to more closely reflect KiCad board setup dialog.

### 0.0.4 (2019-06-10)

- Added ability to inject/eject plot settings (but not drill settings).

### 0.0.3 (2019-06-07)

- Added ability to inject/eject layer enables and visibility.

### 0.0.2 (2019-05-29)

- Added ability to inject/eject part (X,Y), orientation, and PCB top/bottom-side.

- Added ability to inject/eject board design rules.

- Now works with both JSON and YAML file formats.

- Unit tests added.

- Command-line tool added.

- Documentation added.

### 0.0.1 (2019-05-15)

- First release on PyPI.

# Indices and tables

- Index

- Module Index

- Search Page