Why kokopelli

There are two reasons why you'd want to learn how to modify and design your circuit boards in kokopelli:

  1. Because all the hello boards that Neil designs and are in this format. Sooner or later you will come across one of them. He probably does so because of reason number two.
  2. Your are in Fab Academy because you want to turn codes into things. Eagle is just a specialized drawing program that makes your life easier when drawing circuits. There is nothing you can program or automate with it. On the other hand kokopelli is pure code and hence it is the closer you will be for turning codes into things. In the future, if there is such a thing like a programmable digital material, you will program it with something like kokopelli.

A warning about kokopelli and fab modules versions

Fab modules, including kokopelli, are currently under heavy development by Matt Keeter and Neil Gershenfeld. This tutorial is only valid for kokopelli 0.05 version. The current version of fab modules includes kokopelli 0.2 which broke backwards compatibility with old cad files. At the moment of writing this tutorial there is no easy way to modify or design circuit boards with kokopelli 0.2. You can check your version number in kokopelli under Python/About menu. If you happen to have the new version and want to follow this tutorial, Matt has included a retro mode that runs kokopelli 0.05 which you can invoke with this command:

kokopelli -r

Updating fab modules

Once you install fab modules for the first time, there is no need to update them manually anymore. You can check the most up to date version of fab modules using this command:

fab_update check

If there is a newer version it will say so. You can install the new version (if there is any) using this command:

sudo fab_update install

Hands on: Modifiying a circuit board design in kokopelli

You could start from scratch but the best thing is to start with any .cad file from Neil's design that resembles your final board.

The .cad file is just an almost 4000 lines of code text file. There are three main sections in this code.

Adding a component

What you need to do to add a component in kokopelli is searching in the code for the definition of a matching class. For instance if you want to add a button, you guess... look for 'button' in the second section of the code and you will see a class named:

class button_6mm(part):

That is your boy. What you will do next is to define an instance of this button in the third section of code (give it an unique name like mybutton):

mybutton = button_6mm('My\nButton');

\n is used to break line in the name . You won't see anything on screen yet. Having done this you have to define the parameters for position and rotation of the instance created. It will always have this format:


Where x, y z are the coordinates of the component and angle is the angle of the component (counterclockwise positive because we are dealing with math and that is the way angles are defined in math). For example:


It should appear on screen now. The nice thing of kokopelli is that you can set the coordinates relative to other components or variables. Coordinates can be like this:

R2.x                #Coordinate x of R2 component
LED1.pad[2].y       #Coordinate y of the pad number 2 of LED1
-0.3                #Absolute coordinate
IC1.pad[5].x+.08    #0.08 inch to the right from a component pad

So it could be like this:


This is very useful when you want to keep a group of components together.

Placing wires

Now you only need to define wires that connect the pads of your component to other components or wires of the board. Wires always have this format:

pcb = wire(pcb,w,point1,point2,...,pointn)

The bold text is what you modify. w is the width parameter of the wires (which is defined at the beginning of the Section 3). You can use this w parameter or, maybe, for a certain wire, you might want to use a different one. You can have as many intermediate points as you want.

Every component has pad numbers. For instance the button_6mm class defines four pads left 1, right 1, right 2 and left 2 that correspond to numbers 1,2,3 and 4 (first pad defined is number 1 and so on). Lets say you want to connect pad 2 from the button, to pad 5 in the IC1:

pcb = wire(pcb,w,      #w is the width of the wire
mybutton.pad[2],   #From pad number 2 of mybutton
point(0,1,0),       #(Optional) intermediate point(x,y,z)
IC1.pad[5])           #End point: Pad number 5 of IC1

What I usually do is just guess a pad number and then change the number if it is not the correct pad. Be careful because this is one of the main source of errors when designing in kokopelli.

Wires never go oblique in kopopelli, they will only go in X and Y direction and the first movement will always be horizontal. That means that if you place a wire from A to B it will go like this:

       |           |    #This is an awesome ASCII drawing

If you want to change it, reverse the order of the points. So from B to A it will go like this:


That's it! The whole process is not that as hard as it might look like. It takes more time to explain it than actually doing it.