View Altium Circuits In Your Browser With GitHub

GitHub and Gitlab are becoming popular revision control tools, but did you know you can use them to render your circuit designs in the browser? This can be extremely helpful for quickly browsing through revisions or sharing your designs with people that might not have otherwise necessary software installed.

Altium schematic Rendered in GitHub

In this this article we will:

1. Install AllSpice render tool

2. Set up a pre-commit hook to generate visible svgs

AllSpice Render Tool

The first step in this process step is to download and install AllSpice Diff and Render Tool. We'll use this to generate a vector image for each schematic file that GitHub can render.

After installing, you should see the following:

Intro screen post AllSpice install

We're not going to use the GUI for this, so you can exit the application.

Setting Up a Pre-commit Git Hook

The next step is setting up a pre-commit git hook that will call AllSpice render CLI, generate svgs, and add them to the project repo each time you commit changes to your Altium project.

By default, git will look for hooks in your `.git/hooks/` directory, which is not committed to the repo. However, I recommend creating a new location for this hook and adding it to the repository so that you can ensure everyone who commits to the project in the future will create an up-to-date rendering for your schematics.

Create a folder in your base repo called `.githooks` and add it to git with:

git config core.hooksPath .githooks

Note: this configures the git hook for your local repository. You will need to run this command for each git repo you want to enable the hook in. Best practice is to add this command to a README file.

Now we can add the pre-commit hook. The file needs to be named `pre-commit`.

The full pre-commit hook and example directory can be found here.

You can download the raw file above, place into the directory we created, and add it to the git repo. For example, using:

git add .githooks/pre-commit

However, if you're interested in understanding what's going on behind the scenes, I'll explain how it works below.

Finally, commit the git hook file to your repository with:

git commit -m "Add git hook to render schematics"

and you should see an svg rendered and added for each schematic in your repository.

Root repository after .githook folder is created and added to git index

The Result

After pushing the file to your remote you'll find a viewable rendering for your product CAD data.

Demo: https://github.com/AllSpiceIO/Archimajor

This pairs very well with File Icon for GitHub and GitLab Chrome extension.

What's Next?

Next, we'll utilize the design renderings to recommend best-practices for conducting a design review or pull request in GitHub.

SVG schematic diff used for remote design review

[Bonus] Understanding The Git Hook Script

The first half of the githook resolves the install path for the allspice render tool.

#!/bin/sh
#
# Runs before commit message is added
# Exit non-zero to abort commit
# bypass with git commit --no-verify
# Needs executable permissions
# No arguments are passed to pre-commit

# Locate AllSpice
unameOut="$(uname -s)"
case "${unameOut}" in
    Linux*)     machine=Linux;;
    Darwin*)    machine=Mac;;
    CYGWIN*)    machine=Cygwin;;
    MINGW*)     machine=MinGw;;
    MSYS*)      machine=Win;;
    *)          machine="UNKNOWN:${unameOut}"
esac

if [ ${machine} == Win ] || [ ${machine} == MinGw ] || [ ${machine} == Cygwin ]; then ALLSPICE=~/AppData/Local/Programs/allspice/resources/utils/allspice.dist/allspice
elif [ ${machine} == Mac ] || [ ${machine} == Linux ]; then
ALLSPICE=/Applications/allspice/MacOS/allspice/resources/utils/allspice.dist/allspice
else
  echo "Unsupported machine ${machine}"; exit 1
fi

Next, there is a special case for the first commit, which needs to diff against an empty object.

# Handle initial commit: diff against an empty tree object
if git rev-parse --verify HEAD >/dev/null 2>&1; then
  against=HEAD
else
  against=$(git hash-object -t tree /dev/null)
fi 

We then build an array for the modified schematics, as well as the entire list of schematics in the repository.

modifiedSchematics=$(git diff --cached --diff-filter=M --name-only $against | grep -i \**.schdoc$)
allSchematics=$(git ls-files --cached | grep -i \**.schdoc$)

Finally, we traverse the modified array to generate new svgs using the allspice CLI

and the entire array list to generate an svg for any new schematics

# Render each modified schematic file
for f in $modifiedSchematics; do 
  outfile="${f%.*}"
  echo "Generating ${outfile}.svg"
  "${ALLSPICE}" convert --svg --no-json --output "$outfile" "$f"
  git add --force "${outfile}.svg"
done

# Render each schematic file that does not have an svg
for f in $allSchematics; do
  outfile="${f%.*}"
  if [ ! -f "${outfile}.svg" ]; then
    echo "Generating ${outfile}.svg"
    "${ALLSPICE}" convert --svg --no-json --output "$outfile" "$f"
    git add --force "${outfile}.svg"
  fi
done

If you'd like to see anything else or have any issues, feel free to reach out at info@allspice.io