Install Freerouting on Ubuntu 14.04 – 16.04

Introduction

Freerouting was a web application created and maintained by Alfons Wirtz at his website, here.  It allowed us to import a design file from kicad and then auto-route the project based on some design preferences.  It was basically a free auto-router for kicad.  Hence the name!

For “various reasons” the author has decided to drop the project, and it is no longer available as a web application at his site.  However, he has been kind enough to open-source the project and he encourages users to run it as a local application.

There are some wikibooks instructions for installation of the Freerouting application here.  I have recently attempted to follow these instructions, but there are some stumbling-blocks which prevented me from being able to run a working application.  I believe these same stumbling blocks will face lots of people; at least those who decide to install it on a recent Ubuntu variant.

This blog will detail all of the instruction steps necessary to run a working local copy of Freerouting.  My instructions are based on those at Wikibooks, but with some extra steps to get around the stumbling blocks.

The Pre-Requisites

You can skip this part if you already have installed a recent version of:

  1. Git
  2. Java JDK
  3. Netbeans

Otherwise, read on!

Installation of Git

Use your package manager, as follows:

sudo apt-get install git

Installation of Java JDK & Netbeans

This post used to direct you to install the JDK and Netbeans packages separately, but all of a sudden this method stopped working.  When I queried it with the Netbeans team they refused to admit any problem, but suggested the “combined package” instead.  Well, I don’t agree there isn’t a problem but the combined package does work so let’s do that instead!

First you need to locate the JDK & Netbeans combined package.  At the time of writing this post, you can get it here.

Once you’ve downloaded it, you need to make sure that you have permissions to execute it.  To do that, ‘cd’ to the directory where you downloaded the installer, and then type the following command, substituting for your version of netbeans if it’s different from mine:

chmod u+x jdk-8u111-nb-8_2-linux-x64.sh

Then execute the installer:

./jdk-8u111-nb-8_2-linux-x64.sh

You should see a screen something like this:

JDK & Netbeans Combined Installer
JDK & Netbeans Combined Installer

Walk through the installer dialogue to completion.

Installation of Freerouting Dependancies

The freerouting application depends on a couple of things to work.  It requires jh.jar and netx.jar.  To get those, install the following:

sudo apt-get install javahelp2 icedtea-netx-common

Installing FreeRouting & Running in NetBeans

Downloading FreeRouting

Now you need to download freerouting.  It’s available on github, so you just need to ‘cd’ to a directory where you want to download the project, and then enter the following command:

git clone https://github.com/nikropht/FreeRouting

Loading FreeRouting into NetBeans, Compiling and Running

Now you need to start netbeans (should be under ‘Development’ in the application launcher) and import the FreeRouting project.

  1. With netbeans open, select File -> New Project or use the keyboard shortcut CTRL-SHIFT-N.
  2. In the Categories window, select ‘Java’.  In the Projects window, select ‘Java Project with Existing Sources’.
    Select Next.
  3. Give your project a name.  e.g. FreeRouter, and choose a path.  e.g. $HOME/programming/netbeans_projects/
    Select Next.
  4. In the Source Package Folders area, select Add Folder and browse to the place where you downloaded the FreeRouting sourcecode from git.
    Select Finish.  Netbeans will create the project.
  5. Select File->Project Properties.
    In the categories area, select Libraries.  Then, with the compile tab displayed in the area on the right, select ‘Add JAR/Folder’.  Browse to and choose /usr/share/java/jh.jar.
  6. This next part is not explained in the wikibooks instructions I linked to at the beginning of the post.  But it is absolutely necessary in order for FreeRouting to work.  While still in the Libraries area, Select ‘Add JAR/Folder’ again.  Now browse to /usr/share/icedtea-web/netx.jar.
  7. Now, contrary to the instructions in the wikibooks link, we are NOT going to use Web Start:
    While still in project properties (File->Project Properties), select from the categories area, underneath Application, ‘Web Start’.   Make sure this check box is NOT enabled.  Then Select ‘Run’ from the categories area and make sure the Configuration pull down menu is set to <default config>
    Select OK to exit Project Properties.
  8. Now from the netbeans main menu, choose Run and select “clean and build project”.  If all has gone well, it will conclude with “BUILD SUCCESSFUL”.  Now you can run the application: select the green triangle or press F6 to run the project.  You should see the following:

Freerouter_004

Success!

Now you just need to learn how to use Freerouter! I got it routing a PCB pretty quickly without instructions so I think it is pretty intuitive to run.  However, it may not be so intuitive to choose all the correct options for your PCB.  That’s for another post, maybe.

Installing daily build of KiCAD [Ubuntu]

I noticed, recently, that KiCAD footprint libraries now carry the .pretty extension, and that these files cannot be read by the latest stable release of KiCAD.  In order to make use of these libraries it is necessary to install a recent build of KiCAD, which has undergone a significant overhaul of its footprint library support.

As a new Ubuntu user, it was not clear to me how one would go about installing a daily build of KiCAD.  The instructions on the KiCAD website state:

Old stable should be in the official Ubuntu repo. Daily builds are available in js-reynaud’s PPA.

But how can you go about adding this PPA? And, once the PPA has been added, how do you then use it to install a new-build of KiCAD?

Here are the steps you need to take.

Adding the PPA

First you need to add the PPA.  You are going to run a command that will add a new PPA for KiCAD to your linux sources list, so that apt-get will use it to install future versions of KiCAD.  To add the PPA, open a terminal and type:

sudo add-apt-repository ppa:js-reynaud/ppa-kicad

Follow the on-screen instructions, and your result should look something like:

Add reynaud PPA
Add reynaud PPA

 

Install daily build

Once the PPA has been added, you first need to update apt so that it knows about the new versions of KiCAD in your PPA.  To do that, type:

sudo apt-get update

You will see a lot of output in the console.  Don’t worry; the apt service is just busy hitting all of your sources and updating itself so that it knows about all the latest software.  When it gets to the PPA you just added, it’ll update its knowledge of available KiCAD versions.

Once apt has updated, installing the daily build is then as simple as typing the following into your terminal:

sudo apt-get install kicad

Follow the instructions, agreeing where necessary, and then you should be up and running with a new version of KiCAD

Resolving duplicate part name problems in KiCAD

The Problem

In KiCAD, a problem occurs when you try to create a new schematic symbol for a custom library and you happen to give it the same name as another part that exists in a different library.

IC-Example
An Example of a custom IC

For example, let’s say you decide to create a part called “MAX3232”, and there happens to be another part in a different library already called “MAX3232”.  This can happen for a number of reasons; you may not have noticed that this part already existed in the standard library set, or you may have seen it but decided that you’d rather make your own.  This happens to me quite often – for example, I have a bit of a personal standard for the way I like ICs to look on my schematic.  I like my ICs to have a thicker border than on normal components, and I like them to be filled in yellow.  Additionally, I often have preferences about the pin layouts.  It is unlikely that an existing part in a different library will satisfy all of my personal preferences, so usually I’ll cook my own.

When you first set up the custom part, KiCAD will create your part for you and add it to your custom library using the name you chose at the beginning.  If this name is the same as an existing part in another library, KiCAD doesn’t complain – it adds it to your custom library as requested and initially there is no obvious conflict.
The trouble starts when you come to add the component to your schematic.  You select the “Place a component” button, choose your custom library, and select the part you just created.  KiCAD highlights the part and shows a preview of it, which matches the custom symbol that you intend to place.  So all looks well.  However, when you actually try to place the part you’ve selected something unexpected can occur.  It places the part without complaint, but sometimes it will place the existing part from the standard library instead of the custom part you intended!

Pulling Hair OutClearly there is a conflict here that KiCAD hasn’t warned us about.  When you actually try to place the part, you’d think that KiCAD would dive straight into the appropriate library and pick out the part you actually selected.  But this is not what happens.  Instead, KiCAD searches through its entire set of libraries and picks the first part whose name matches the one you selected.  If your custom library is scanned first, it picks the part you intended.  If the other library is scanned first, it picks the existing part that you didn’t want!

Workarounds

I haven’t managed to find a completely satisfactory solution to this problem.  But it is possible to get close to a satisfactory solution using one of two optional workarounds that I will describe here.

#1 The nomenclature workaround

The first workaround, and the easiest (though neither are difficult), is to simply be careful when you’re choosing names for your custom parts.  For example, I could decide to append all of my custom parts with “_BJH” for the rest of eternity.  Then, when I want to create a custom MAX3232, I would create it with the name “MAX3232_BJH” instead.  It’s unlikely that another part in some different library is going to match this name, so I can feel pretty confident that no conflict will ever occur and the custom part I intend to use will be placed on my schematic every time.
An alternative that I’ve seen suggested on other websites is to append your library name to each of your parts.  So if your custom library was called “Devices_BJH”, then you’d call your part “MAX3232_DevicesBJH”.

A problem with the nomenclature workaround

This works fine, but when you place your part it ends up being titled “MAX3232_BJH”.  There are two problems with this.  One is that it’s just plain messy; who in their right mind would want all their component names appended with workaround text? The second problem is that somebody else, reading your schematic, may be fooled into thinking that the appended text has some other importance – for example, they might think the “BJH” is a specific variant of the part which they need to pay attention to.  So clearly we will want to do something about this.

Fortunately it’s quite easy to solve this problem, with one exception which I will talk about in a minute.  If the part you’ve created is a regular schematic part (resistor, IC, diode, custom component, etc) then you can select the component on your schematic, select “edit”, (or hover over the component and press e on your keyboard) and then you will be presented with the following dialogue box:

KiCAD-Edit-Window

 

As you can see, all you have to do in order to change the way the title looks for your custom component is change the Value.  This allows you to call your part “MAX3232” while KiCAD still refers to it by the conflict-free name that you chose earlier.  The annoying thing with this workaround is that you have to repeat this process for each part you add to your schematic, and you leave yourself open to the possibility of accidentally naming multiples of the same part differently.  For example you might end up with two MAX3232 parts on your circuit, one with a Value of “MAX3232” and the other with a value of “max3232”.  A trivial issue, yes, but one that would annoy the heck out of me!

 An exception

PSU-Rail-Symbol-standard
A standard KiCAD PSU Rail symbol

There is at least one exception to this workaround which I have discovered.  The other day I decided that I wanted to create my own power symbols.  KiCAD already has a suite of power symbols to choose from, but I find that the supply rail symbols (the ones which are a pin with a circle on top like that shown to the left) are too small for my liking.  Power supply rails are quite important connections, and I think they should be displayed more prominently.  I also have issues with the legacy “VCC, VDD, VSS” power rail nomenclature, which is a rant for another day.

Having created my new power rails, and taken care to append them all with “_BJH”, I thought I would be able to use the edit dialogue box in the same way as for my other components to change the Value field so it was displayed, for example, as “+3V” instead of “+3V_BJH”.  Unfortunately, if you try this for yourself, you will discover that the Value field is greyed out for power pins.  You can’t change it! To solve this problem we must move on to workaround #2, which is now my preferred method which I am going to use for all my custom symbols from now on (or until the KiCAD team fix the naming conflict problem).

#2 The Custom Field Workaround

Since we can’t change the Value field on power pins, we need some other way of changing how KiCAD displays the name of our custom parts.  Thankfully, we can do it quite easily using custom fields.  You have two options here.  The first option is to apply a custom field manually to each custom part after placing it on your schematic.  The second option is to generate the custom field when you’re actually creating or editing the custom symbol in the library editor.  The second option makes the most sense by far, because this way you can set up exactly how you want your symbol’s title to be displayed, position it just-so, and then it will be automatically repeated in exactly the same way for every single part you lay down with no need to go about maintaining it retrospectively.  The second option also shields you from the horror of accidentally naming your parts in slightly different ways (capitals here, dashes there, etc).  For these reasons I am only going to talk about the second option, but the principle is exactly the same anyway so you can pick your poison for yourself.

Generating custom fields in the library editor

Assuming you know how to edit components in the library editor (if you don’t then I guess your problem starts at how to create symbols, not how to tweak their names), launch the library editor and open up your custom component.
Along the top toolbar you will find a T-shaped button FieldPropertiesButton for editing custom fields.  Select this button and then you will be presented with the fields dialogue box shown below.

Now, at the moment KiCAD is using the Value field – which on power pins you can’t edit – to display a title for your component on the schematic.  So the first thing you want to do is select this field and change its visibility setting so that the “show” checkbox is no longer checked.  This will stop it displaying on your schematics.

The next thing you want to do is create your custom field.  Select the “Add Field” button, and then set the Field Value to something sensible that denotes your component in some pedantic way of your choosing.  Set the text size, its style, and set the position.  Once you’re happy, make certain that you set its visibility checkbox to “show” so that it’ll display on your schematic.  Then you can exit the dialogue box.

Custom Field Properties
Custom Field Properties

Done!

That’s it! You’re done.  Save your component back to the library, and update it.  You’ll probably also need to close the schematic editor and open it back up again.  From now on, you can place your custom component without any nasty surprises and it will display with a sensible name of your choosing.

Have a FAB old time with your PCBs! <groan>

Digital Multimeter Accuracy Explained

Introduction

The digital multimeter is the most widely used test instrument in the electronics industry.  It is the standard tool for electronics Technicians and it’s usually the first test/diagnosis tool that a newcomer to electronics will purchase.
Despite this, multimeter capabilities and especially the concepts of multimeter accuracy are often misunderstood or ignored.  I have worked in the electronics trade for 14 years and it has been my experience that surprisingly few people actually understand (or care about) their multimeter specifications.  In particular, I have discovered that a large number of Technicians and even Engineers are ‘blissfully’ ignorant of their instrument’s capabilities and the implications for the measurements they make.

If you don’t know and understand your instrument specifications, how can you choose the right tool for the job? And, more importantly, how will you know when you’re using the wrong tool for the job?!

Digital Multimeter Specifications Explained

Modern digital multimeter accuracy specifications are actually quite easy to understand once you become familiar with all the jargon.  It is important that you fully understand what is meant by counts, digits, and the effects they have on instrument resolution and accuracy.  In terms of resolution and accuracy, there is an important distinction to be made here as well – in my experience lots of people get them confused.
In this tutorial we’ll tackle counts and digits first, and this will allow us to very easily interpret the accuracy specifications afterwards.

Digits, Counts and Resolution

Resolution

When we talk about resolution we’re talking about the smallest possible change that the instrument can detect.  This means we’re looking at the least significant digit.  The resolution at any given time is the amount that a single count of the least significant digit is worth.  So, for example, if the display is showing us ‘4.0005‘ volts, then one count of the least significant digit is worth 100µV (0.0001V).  This means that the instrument’s resolution for that particular measurement is 100µV.  The resolution will change depending on what range you select, but for the most accurate results you should always use the lowest possible range, which gives maximum resolution.  I’ll show you why this is important for accuracy (accuracy is a different concept) later.

Counts

My Fluke 28II multimeter is a twenty-thousand count, 4½ digit instrument.  This refers to my instrument’s resolution, but what does it mean? Well, the counts and digits are effectively two ways of saying the same thing, but both terminologies are in common use so it’s good to have a handle on both.  I’ll tell you my personal preference and offer justification for it later.  In this section let’s deal with the counts first.
To start with, it should be noted that the practical count figure is almost always one count less than the naming convention we use to refer to it.  For example, in my case (for a Fluke 28II), the practical resolution of my instrument is 19,999 counts.  That is what the instrument is actually capable of.  However, when we refer to the counts by name we call this “twenty-thousand count”, and this is purely because a round number is easier to say! What we mean in practice is one less than that.  The instrument specifications will usually quote you the practical counts as an actual figure, so with a well written specification there should be no ambiguity:

Fluke 28II Resolution Specifications
Fluke 28II Resolution Specifications
Displaying 1.9999V with 100uV Resolution
Displaying 1.9999V with 100uV Resolution

The implications in terms of multimeter resolution are that the Fluke 28II is capable of displaying a maximum of 19999 on its screen.  A point to note here is that the most significant digit can ONLY be a 0 or a 1.  It can of course move a decimal point to indicate different orders of magnitude.  So if we’re measuring <2V, the instrument can display up to 1.9999V.  What happens when we try to measure voltages higher than this? Well, the instrument has to abandon the most significant digit because it can’t display a ‘2’.  This has the following consequences:
In the case of a 1.9999V measurement the least significant digit being displayed is worth 100µV per count (0.0001V), and therefore the instrument has 100µV resolution up to 1.9999V.  Once we enter the 2V realm the instrument has to sacrifice some resolution because the most significant digit cannot display a ‘2’.  Therefore in order to display 2V it has to shift the displayed measurement to the right, and the current least significant digit gets bumped off the end of the display in the process (i.e. we lose it).
The displayed voltage would be 2.000V, and the least

Displaying 2.000V with 1mV Resolution

significant digit is now worth 1mV per count.  It’ll then maintain this 1mV resolution all the way up to 19.999V after which it’ll be forced to drop a least significant digit again and the resolution will become 10mV per count.
You can see, then, that once you know your instrument’s maximum number of counts you can use this information to determine what the maximum resolution will be for any measured voltage.  The resolution will decrease in discrete steps as the measured voltage increases. The point that the steps occur and their effect on the resolution are determined by the maximum number of counts.

Digits

So how does all this relate in terms of digits? Very simple.  The multimeter is a 4½ digit instrument because it is capable of displaying four full digits (0-9) plus one half digit.  The most significant digit is called a half digit in this case because it is only capable of displaying 0 or 1.

4.5 Digit Multimeter Display
4.5 Digit Multimeter Display

Some instruments are capable of displaying higher numbers in their most significant digit.  Commonly you will see a ¾ digit quoted, and this usually refers to a digit that can display up to and including a numeric value of 3.  So, for example, a 4¾ digit multimeter could display up to 39999 on its display.  This would be called a “forty-thousand-count” instrument, and it is an improvement over the 19999 count display because it can go further into its range before it has to compromise its resolution by dropping a least significant digit.

There is a caveat here though – although a ¾ digit typically refers to a digit capable of displaying values between 0 and 3, this is not a safe assumption and in fact it can mean any digit up to 6.  This means that there is some ambiguity surrounding the use of fractional digits to define resolution.

Counts And Digits Are Equivalent And Interchangeable

Counts and digits effectively mean the same thing.  A twenty-thousand-count instrument is capable of displaying practical values of up to 19999 which is four full digits plus one half digit = 4½ digit.
Due to the uncertainty of meaning surrounding fractional (in particular ¾) digits, it is my opinion that the use of counts to define resolution is preferable because it accurately defines the instrument’s capabilities and leaves no room for ambiguity.

The Display is not the limiting factor!

Before I leave my explanation of multimeter counts, digits and resolution, I want to clear up a common misconception.  Some might reasonably question why the instrument manufacturer would choose to hamper themselves with a most significant digit that can only display a 0 or a 1.  Would it not be easier to have a full digit there as well, thereby avoiding the complications and maintaining better resolution for more of the range?
Well, the answer is that the display is not the limiting factor here.  The display itself is almost certainly quite capable of indicating numerals from 0-9.  The limiting factor is the measurement circuitry in the instrument itself .  All instruments obviously have a finite resolution, and it is this limiting factor that causes the instrument manufacturer to be tied to a smaller MSD.

The Meterman 37XR, for example, has a ten-thousand-count display (actual counts 9999).  The ten-thousand-counts refers to the resolution capabilities of the instrument itself (the lower the number, the less resolution the instrument provides), and in this case the consequence for the display is that it can indicate up to 9999V + decimal point.  So in this case the most significant digit really can display 0-9, and there is no fractional digit there to complicate matters.  But we only have 4 digits of displayable resolution across the range.  We don’t have access to an extra ½ digit or ¾ digit at all, so we never get to exploit the extra resolution that this part-digit would provide.  A part-digit that offers an order of magnitude better resolution for part of the measurement range, is better than no digit at all.

Multimeter Accuracy Specifications

Now that we fully understand the meaning behind counts, digits and resolution, we can quite easily interpret a digital multimeter’s accuracy specs.

What does ‘accuracy’ mean?

The accuracy of a measurement refers to how closely it reflects the true value of the property being measured.  Whenever you measure something in real life, the measurement you take is always an approximation of the actual property itself, and therefore there’ll be some uncertainty involved.  Today’s digital multimeters are very accurate instruments – the uncertainty in their measurements is extremely low – but there will always be some uncertainty in the measurement.
What will the error be? Well, it’s impossible to quantify the error exactly.  If you think about it, if we could determine the exact magnitude of the measurement error then we’d just correct for it in software and then we’d have no error at all!  That’s why we refer to it as “uncertainty” instead of “error”.
In practice all we can really do is provide a figure of uncertainty about the measurement which gives us a range for which the measurement can potentially be in error.   The multimeter specifications give us these limits, and they’re called the accuracy specifications.

So we have dispelled the jargon, and this makes our life easy.  Let’s now look at some practical accuracy specifications and determine what they mean.  Staying with the Fluke 28II, let’s have a look at its accuracy specifications for the VDC range:

Fluke 28II DC SpecificationsFluke 28II DC Specifications

As you can see, the Fluke 28II’s DC voltage range is quoted as being accurate to “±0.05% of the reading +1”.  The ‘+1’ refers to an additional uncertainty in terms of ‘numbers of counts’.  Some manufacturers refer to this uncertainty as ‘numbers of digits’, but they both mean exactly the same thing – it’s basically the number of counts in the least significant digit.  In this case we’re only talking about one count of uncertainty but some instruments suffer more than that.  I prefer the former terminology (counts) because it sounds less confusing! Notice that the +1 count is contained within the ± bracket so the actual uncertainty in terms of counts is plus or minus 1 count.  The easiest way to understand what this means in terms of measurement uncertainty is to take an example.

Example: Measurement uncertainty for a known 1.8000V source with the Fluke 28II.

Let’s imagine we decide to measure a voltage reference whose true voltage is known to be 1.8000V.  If we measure this with the Fluke 28II using the most appropriate range (more on this later!) we can expect that the instrument’s measurement uncertainty will be:

Effect of 0.05% accuracy on 1.8000V measurement

This means we should expect a measurement of somewhere between 1.7991V and 1.8009V.  However, this isn’t all of the uncertainty we can expect to see on the display because we also have an additional uncertainty (which is due to ADC errors, offsets, noise etc) of ±1 count, and this gets added on to the least significant digit being displayed.  So, adding that to the measurement uncertainty we get 1.7990V to 1.8010V.  We should expect to see a measurement on the display that is somewhere between these two values.  Easy! Let’s have a look at what this means for an instrument with slightly lower resolution and accuracy specifications:

Example: Measurement error for a known 1.8000V source with the Meterman X37R

Let’s try this same task with the Meterman X37R.  The specifications for the VDC range are:

ACCURACY: ±(0.1% Reading + 5 digits)

RESOLUTION: It’s a 4 digit instrument (no partial digits) which is 9999 count so our maximum resolution when the most appropriate range is used for this particular measurement will be 0.001V = 1mV.

Using all this information, the uncertainty in our measurement will be:

Measurement uncertainty for 0.1% accuracy on 1.800V

 

This means we should expect a measurement somewhere between  1.798V to 1.802V.  But then we have the additional uncertainty of 5 counts on top.  Not only is there a greater uncertainty of counts to add in this case but now they’re more meaningful too because the least significant digit is more significant than it was for the same measurement with the Fluke 28II – the 37XR has less resolution.  The 5 counts get added to the 1mV column, where as the Fluke’s ±1 count uncertainty only got added to the 100μV column!
This gives us an overall expectation of a displayed reading on the 37XR of somewhere between 1.793V to 1.807V.  You can see how an instrument with lower accuracy and lower resolution can start to make a difference.

Always use the most appropriate range!

There’s a consequence for all this here that we haven’t talked about, and it refers mainly to the count (or digit) errors quoted in the specifications.  You must always use the most appropriate (highest resolution) range for the property being measured.  If you don’t, the resulting measurement errors can end up being quite large because the count uncertainties carry more weight.  Let’s say we do the same experiment with the 37XR, but this time we use the 1000V range to take the measurement.  The displayed measurement will then be somewhere around 1.8V – we’ll be wasting the other two digits that are set to take tens and hundreds units, because there are no tens or hundreds to measure!  We’ll still end up with the same measurement error in this case (it’s still ±0.1% Reading + 5 digits), but the 0.1% uncertainty is too small to be registered on such a low resolution display.  The counts, however, do register because they always affect the least significant digit being displayed – which in this case is the 100mV digit (the 8).  So the actual reading displayed could be between 1.3V and 2.3V! That’s a total error of ±28% which, as I’m sure you’ll agree, is completely unacceptable.  So watch out for that and always make sure you make use of the best possible measurement range!

That’s all folks!

So there you have it, digital multimeter specifications explained.  It’s really quite simple once you get down to it.  The topic is a little bit more hard work for analogue instruments – I’ll tackle that little minefield in a separate tutorial.

Good luck, and happy measurements!