KiCAD ERC and DRC
Tuesday, April 23rd, 2024
2024 saw the release of KiCAD version 8. This release brings a number of new features to both the user interface and the command line interface. One useful feature has been made easier to use, namely the ability to run the Electrical Rules Checks (ERC) and Design Rules Checks (DRC).
What are ERC and DRC?
ERC checks are run on the schematic and the checks verify the schematic against a number of common mistakes. Examples include:
- Pins not connected to a net (but not marked as not connected)
- Pin conflicts
- Missing drivers
DRC runs against the PCB layout and checks the design rules specified in the design. These rules will vary between fabrication houses and include properties such as:
- Minimum track width
- Minimum track spacing
- Hole-to-track spacing limits
Both types of check can be run through the user interface and from the command line. It is the command line interface that we will look at here as this will allow the checks to be run as part of a continuous integration pipeline (in this case a GitHub Action).
KiCAD Docker Container
Initial thoughts about running these checks is to use a docker container. This will allow the use of a script to run the same commands from the desktop as well as through CI. Luckily, the KiCAD project maintain a docker container for just this purpose.
First step, create a script file containing the two commands that we need to run the checks. Our script file will look something like this:
#!/bin/bash set -e scriptdir="$( cd "$(dirname "$0")" ; pwd -P )" kicad-cli sch erc --severity-all --exit-code-violations -o "$scriptdir/erc.rpt" Meadow-Feather-OLED.kicad_sch kicad-cli pcb drc --severity-all --exit-code-violations -o "$scriptdir/drc.rpt" Meadow-Feather-OLED.kicad_pcb
If we save this file as say run-erc-drc.sh then we can run the checks from the command line using docker to run the script. The command to run the script would look something like this:
docker run --platform linux/amd64 --rm -v $PWD:/project -w /project kicad/kicad:8.0.1 ./run-erc-drc.sh
Note that the –platform option allows the container to run on Apple Silicon Macs as well as Intel platforms. Running the above command will show the following output:
Running ERC... Checking sheet names... Checking bus conflicts... Checking conflicts... Checking units... Checking footprints... Checking pins... Checking labels... Checking for unresolved variables... Checking no connect pins for connections... Checking for library symbol issues... Checking for off grid pins and wires... Checking for undefined netclasses... Found 0 violations Saved ERC Report to /project/erc.rpt Loading board Running DRC... Found 0 violations Found 0 unconnected items Saved DRC Report to /project/drc.rpt
The run-erc-drc.sh script will generate two report files, one for the ERC and one for the DRC. Checking the erc.rpt file contents will, for a successful run, will show something like this:
ERC report (2024-04-22T18:38:28+0000, Encoding UTF8) ***** Sheet / ** ERC messages: 0 Errors 0 Warnings 0
Great, so we now have the docker container created and the report is being generated based upon the current design and PCB layout. The next step is to integrate this into a GitHub Action.
GitHub Action
The first attempt at performing the checks in a GitHub Action resulted in the following yaml file:
name: Run ERC and DRC checks
on:
repository_dispatch:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout source code
uses: actions/checkout@v4
- name: Run the checks
run: docker run --platform linux/amd64 --rm -v $PWD:/project -w /project kicad/kicad:8.0.0 ./run-erc-drc.sh
id: run-the-checks
The theory was to use the same script file in a GitHub Action as was used on the desktop. This will ensure that the checks performed are consistent on both platforms. It would also mean that only one script would need to be maintained.
“Houston We Have a Problem”
Saving a new version of the schematic and pushing the changes to GitHub ran the action and resulted in the following log entries:
11:33:55: Error: can't open file 'erc.rpt' (error 13: Permission denied) Running ERC... Checking sheet names... Checking bus conflicts... Checking conflicts... Checking units... Checking footprints... Checking pins... Checking labels... Checking for unresolved variables... Checking no connect pins for connections... Checking for library symbol issues... Checking for off grid pins and wires... Checking for undefined netclasses... Found 0 violations Unable to save ERC report to erc.rpt Error: Process completed with exit code 4.
Some time later…
After spending some time with Google and the GitHub help system yielded nothing too helpful regarding solving the issue and removing the error. It was however, discovered that someone had already created a GitHub Action to run the checks anyway. The sparkengineering/kicad-action@v1 action can be used to run the checks. The following yaml file will run the action and perform the ERC and DRC checks:
name: Run ERC and DRC checks
on:
repository_dispatch:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
RunChecks:
runs-on: ubuntu-latest
steps:
- name: Checkout source code
uses: actions/checkout@v4
- name: Run KiCad ERC
id: erc
uses: sparkengineering/kicad-action@v1
if: '!cancelled()'
with:
kicad_sch: Meadow-Feather-OLED.kicad_sch
sch_erc: true
- name: Run KiCad DRC
id: drc
uses: sparkengineering/kicad-action@v1
if: '!cancelled()'
with:
kicad_pcb: Meadow-Feather-OLED.kicad_pcb
pcb_drc: true
The results of the checks can be shown on the repository home page by creating a badge for the workflow. The badge is then added to the README.md file. The badge will show the status of the checks and will be updated each time the checks are run.
Conclusion
The ready built action does perform the checks required and the badge shows the results of the check workflow. While the method of running the checks are different, both will run the checks giving and indication of success or failure. The desktop script has the advantage of producing a report file that can be reviewed, along with the schematic and PCB layout, to resolve any design issues.
It was disappointing to find that the docker image could not be used within the GitHub Action. There will surely be a simple solution it is just having the time to find it.
An example of the GitHub Action script and a PCB design and layout can be found in the Meadow OLED Feather board repository.
