Tuesday, September 24, 2013

How to test the assembly module [updated]

While assembly tools are not available in the official packages, you can compile FreeCAD yourself  with the assembly module enabled.
Note: the module is unfinished, unstable and buggy. 

Instructions are similar to those provided in the older post. Alternatively you can use the dubstar-04's script.

Update 30.06.2014: This post is outdated now, the assembly module looks different, and there is no jriegel/dev-assembly branch anymore. As stated here:
* jriegel/dev-assembly-old is the old data model with the working solver of ickby and the new PartDesign of jreinlaender
* jriegel/dev-assembly2 is the new data model with the solver temporarelly switched of. Also this branch is at the moment not usably.....

Update: There is more up-to-date GitHub repository

Clone sources:

git clone

Change the directory and checkout the "assembly" branch:

cd FreeCAD_constraint
git checkout assembly

Repeat the normal steps:

mkdir Build && cd Build
cmake - DCMAKE_BUILD_TYPE=Debug ../
make -j8

Additional informations in that forum thread.

Old post:
Install development packages listed on the FreeCAD wiki. Then you can clone the sources from GitHub:

git clone git:// free-cad-code

Change the directory:

cd free-cad-code/

Now you can list available remote branches:

git branch -r
  origin/HEAD -> origin/master

Switch to the "jriegel/dev-assembly" branch:

git checkout jriegel/dev-assembly

Create a new directory for a build:

mkdir Build && cd Build

Run cmake and enable debug build (FreeCAD may be a little slower but easier for debugging):

cmake - DCMAKE_BUILD_TYPE=Debug ../

Compile, the number should be equivalent to the number of threads in your CPU:

make -j8

Run FreeCAD:


Example 1: an assembly created from external STEP files.

You have to download four STEP files:
All parts (piston, conrod, pin and pinring) was created in FreeCAD and then exported to the STEP files.

Open the Assembly module and create a new file. Double click on the Product in the Tree view to activate it. If the Product does not exist, you can create one choosing Add a new Component.
Next we have to add an part from an external file. Select Add a existing Component or File to the active Assembly and choose the piston.stp file.

Select a surface on the piston and use the Fix a part in its rotation and translation constraint. The piston cannot move now. Notice the new constraint in the Tree view.

In a exactly same way add the pin.stp file. You need two constraints between piston and pin.

Select a side face of pin and a corresponding face of piston (inside pin ring groove) using [Ctrl]. Then use the Align the selected entities constraint.
You have three options:
  • Equal - both faces normal vectors are equal,
  • Opposite - vectors are opposite,
  • Parallel - vectors are equal or opposite. 
In our case please select Equal.

In the next step select cylinder surfaces on pin and inside piston. Use the Make the selected entities coincident (Equal).

Please add conrod.stp selecting Add a existing Component or File to the active Assembly. As in earlier pair use the Align the selected entities (but this time select "Opposite) and the Make the selected entities coincident.

The conrod can be rotated in a specified angle relative to piston. To set the angle select the bottom conrod face.

Then, holding [Ctrl] key, select the top piston face and use the Set the angle between two selected entities. The angle will be 160.

Finally you have to insert pin rings. The procedure is similar to pin adding. You need an align constraint.

And a coincident constraint.

Repeat the procedure for the second pin ring.

Download file.

Download RAW Video. (Right click to save as...)

Example 2: an assembly created from the Part Design-created files.

In this example we will create an assembly containing fully parametric, Part Design parts. They will be created during assembly designing process - there is no graphical import tool for files containing feature tree yet.

Open the Assembly workbench and activate the Product object (double click in the Tree view). Add two new parts using Add a new Part into the active Assembly.

Add two new parts using Add a new Part into the active Assembly.

Expand the first part (click on the small triangle in the tree) and activate the Body. An active workbench should be changed to Part Design automatically. The Body is a container for all features.  

Select the XY plane and create a new sketch. Important: in the current implementation first sketch have to lie on XY. Subsequent sketches can be placed on other planes.

Draw a rectangle, constrain it and close the sketch.

Pad the sketch.

Select a face on the cuboid and place a second sketch.

Sketch a circle.

Use the Pocket tool to create an hole.

You finished the first part, let's try create another one. Expand Part001 and double click on the Body001 to activate it.

As before, select the XY plane and sketch a rectangle.

Revolve the rectangle on horizontal axis to create a cylinder.

You have two parts: a box with a hole and a cylinder. Try place the cylinder in the hole. Double click on the Product in the tree to activate. The Assembly workbench should be active now.

Select a surface on the box and use the Fix a part in its rotation and translation constraint.
Select cylinder surfaces on the both parts with [Ctrl] and use the Make the selected entities coincident (Parallel) tool.

Next use planar surfaces to align parts.

What if you want change something? Try translate the hole position. Activate the Body and then the Sketch001 inside the Pocket feature.

Edit the circle position and close the sketch.

Note: editing works fine only for features placed on the XY plane at this moment. This is a known issue.

Download file, download video.

More information

Assemebly Basic Tutorial - FreeCAD wiki
PartDesign Bearingholder Tutorial I (very useful!)
PartDesign Bearingholder Tutorial II

Used FreeCAD version:

Version: 0.14.2654 (Git)
Branch: jriegel/dev-assembly
Hash: 3d4dd4f64f24255dbaec25767cff7b74bb98fc6d

Trivia: today examples was created on fully open machine (except x86 microcode and some firmware;) - FreeCAD on Ubuntu x86-64 with R600g graphics driver.


  1. Thanks for this great tutorial. I was looking for something like this. Hope this assembly feature will soon be in the official releases.

  2. I've some problems when I run "cmake - DCMAKE_BUILD_TYPE=Debug ../". It seems that a lot of libraries are missing... I tried to figure out but nothing. Can you give me some helps please?

  3. I don't know you operating system, but for Ubuntu there is a list

  4. In Example 2, at the point of selecting the part body, it errors saying the no body was found. I have a screen shot if it is of interest. Example 1 worked fine.

  5. I should have watched the video first. I now see that it is a know issue. I guess it can be ignored without any problems?

  6. Hy Guys! I tried to compile the source code for 3 times using both the build scripts and the step-by-step tutorial. In both cases I got errors after make was started. I would ask you to share your successfully compiled version (either for Ubuntu or for Windows), because I realy need the assembly mode for a big robotics project at my university. I could then write a tutorial on this topic, that can help you to popularize your great CAD! Thanks a lot in advance! (belov(at)

  7. I cannot reproduce this error (0.14.2917 e4c8a8d20d6d15dfeccc6c7cf2597d189e227bb4). Are sure that all libraries are installed?

    Not sure about backslash. On Linux it is used to remove special meaning of characters, eg. before spaces.

  8. I did the examples as per the videos, no problems to speak of. Then I tried an assembly of my own with some success, but not really. My assembly uses a number of flat plates (step files), 10mm thick, to make a chamber. A larger 8 sided plate is the foundation, and I locked the rear surface of this plate, as per the piston example. Then the intention was to arrange eight copies of a smaller rectangular plate just inside the rim of the base plate and at 90deg. to it, so as to make an open top eight sided box. I was able to get some of the plates into place after much trial and error, but have yet to get them all into place.

    Sometimes a constraint will work as I would expect, but more often nothing will change, and on rare occasion very strange things will happen.

    I went looking at the source code to take a look at the code for the constraints, found what at first looked like the right files, but they were very small files with almost nothing in them. I did not figure out where the actual code for the constraints is? in the Part Design module?

    Thanks both for the work so far and for any help/direction.


  9. Hello,

    for sure the assembly solver has some severe bugs, I'm still working on it heavily. If you want to see the relevant source for the solver it is in src/workbench/assembly/app/opendcm . The constraints equations are in the module3d folder, see distance.hpp (for distance), parallel.hpp (for orientation) etc., but be aware that the structure is complicated, it will take quite some work to realize how everything works.

    Another tipp: open the report view, currently all errors will be printed there (no popups!) Also I would be glad if you report bugs and stuff with a detailed description and a file on the freecad forum so that I can have a look.



  10. OK, I might be able to do that this week.

  11. When I do a git pull, it always comes back immediately and says it is up to date, to quick for any network activity on my slow link. Am I doing something wrong?

    terry@terry-OptiPlex-GX620:~/src/FreeCAD-Assembly-master$ git pull
    Already up-to-date.

  12. Constraints must be on faces only?

    Not corners (points) or edges?

    I seem to be unable to get two corners to coincide. Referring to the image in my earlier post, I started over. Opened FreeCAD to the Part Design workbench, switch to the Assembly workbench, added the end plate file, selected the rear face and put a lock constraint on it. Then added the file for one of the smaller plates with the big hole. I selected the front face of the fixed end plate, then also selected an edge face of the small plate, added an alignment constraint of opposite? So far so good. I next selected an edge face of the end plate, and a side face of the small plate and applied an alignment constraint of parallel?, this worked. Now the small plate is 90 deg. to the big plate with it's outside face even with the outer edge of the big plate, but the center line of the small plate is shifted half the width of the plate to one side. I do not seem to be able to find a constrain that will move the plate so it is centered on the other plate?

    All attempts to create "alignment" or "coincide" constraints on any edges or corners result in "Solver failed with error 3: step size below limit" as reported in the report view window. BTW, this message lacks any end of line, so they stack up on the same line...

  13. Hello,

    Constraints work on planar faces, strait edges and vertices. Of course not all constraints are defined for all kind of geometry. (for example two vertices can not have a orientation constraint, but a distance constraint)

    The solver message indicates a unsolvable system, which is most likely due to conflicting constraints (or a bug, of course :) ). Be aware that two alignment or coincident constraints fix all rotational constraints of freedom, therefore a third one is always a overconstraint for the rotational dof's. Hence it must be carefully alignt with the first two. It is easier to just use a distance constraint for the last step, as this on only resolves the last remaining translational degree of freedom.

    Apart from that you should share your file together with this description, please do that on the freecad forum which is a more appropriate place for this discussion. I'm glad to have a look if I have the file.


  14. there have been no changes on the assembly branches lately, so your code is most likely up to date. Git can do this check very fast as it only compares two hash tags.

  15. Hello,

    constraitns work on planar and cylindrical faces, straight edges and vertices. However, not every constraint is defined for every pair of geometry.

    The solver message you see indicates a unsolvable system. Thats most likely due to conflicing constraints, but can also happen throug implementation errors. Note that 2 align or coincident constraints fix all rotational degrees of freedom between two geometries. Therefore a third align/coincident will overdefine the rotational dof's and needs therefore be placed very carefully. Better is to use a distance constraint to fix the last remaining translational dof.

    I could say more if you can share your file on the freecad forum, so that I can have a look. This is also the more appropriate place for this discussion

  16. Could you post your issues on the FreeCAD forum?

  17. IMO, everything is OK, no changes during last few days. My Freecad shows:
    Version: 0.14.2939 (Git)
    Branch: assembly
    Hash: d62d1c03daa0a464787dab587a3f57c94eefaf97

  18. My membership there is awaiting approval ...
    In the meantime ...

  19. My membership on the FreeCAD forum is still awaiting approval, or something.
    How long does it take?
    It says to contact the forum admin about problems, but there is no indication as to who that is?

  20. After several failed attempts, I did finally get all eight sides of the crankcase assembled onto the endplate. I was first trying to put the side pieces on one after the other, next to each other, but after three or four pieces it would glitch.

    What finally worked was to avoid putting more the three in a group, as long as possible, then finally put the last ones in place. After getting the first side in place, and putting the second side next to it, I put the third plate on the other side of the first, instead of next to the second. Then put the forth opposite all of them, so it was by itself, and so on. The solver seemed to have much less problems with this approach.

    I did notice on the last two pieces, that as the first constraints were added, they were placed way out in space, away form everything else, but as the last constraint was added they would pop into place.

    See image in earlier post. Using the ickby branch.

    BTW, my account on the FreeCAD forum has yet to be approved, so I can not post there.

  21. I will ask moderator about your account...

  22. Have you posted something on the FC forum? It it necessary to the account approve.

  23. Hi, just downloaded the GIT version from as of today.

    I couldn't figure out how to add a "product" to the tree view. (Could not find an "Add a new component" entry or button)

    However, many thanks for this documentation - this looks very promising and if FreeCAD develpoment progresses as fast as it does now, it will change the situation for mecahanical construction completely with the never-before-seen availability of a real 3D CAD package for everyone. This is huge..

  24. Hi,
    some names (and icons) have changed during development. You should have "Assembly" instead "Product" and "Add a new Part"instead "Add a new component. The module is still alpha and many things can change in future,..

  25. Hm, when I follow the tutorial I receive a cyclic system exception trying to make the coincident mate between the pin and conrod.

    Equal alignment b/t piston and pin
    Equal coincident b/t piston and pin
    Opposite alignment b/t pin and conrod
    Coincident b/t pin and conrod (exception for equal/parallel/opposite)

    The tutorial is pretty clear, so I'm not sure what is getting messed up. I'm not sure how the above four mates could even produce a cyclic system.

  26. I recently disabled all cyclic constraint systems as those work not very reliable up to now. I will reenable them when I implemented the needed changes to handle such cases. If you are sure that you did not create a cyclic system please post your file on the freecad forum so that I can have a look.According to your description it should not be cyclic. But if you for example accedently make the last coincident between piston and conrod it would be.

  27. I have posted a topic @

  28. I did a fresh Ubuntu 13.10 load with the goal of having FreeCAD .14 with the Assembly Module in mind. FreeCAD .14 in Linux is SO much better than .13 was in Windows, but I'm really struggling to get the Assembly module to compile using the "" repository.

    I started out by fully updating Ubuntu 13.10, then installed FreeCAD .14 by the Daily PPA. Then I added the list of depencencies from here:
    ...and followed the guide on this page, using . I get all the way through the "cmake - DCMAKE_BUILD_TYPE=Debug ../" step without error, but when I go to do the "make -j8" step, I see lots of errors, and it only gets about 14% of the way built before it stops.

    I really feel like I'm missing something... Is there a guide somewhere on how to get FreeCAD .14 with the Assembly module working when you're starting from scratch with a fresh Ubuntu 13.10 install?


  29. 14%? Hmm, Maybe Pivy error?

    Please install cmake-gui fon convenience and check FREECAD_USE_EXTERNAL_PIVY flag.

  30. So, I did some more hammering away on this, and using the new repository, still got about the same % through the build - even when using the FREECAD_USE_EXTERNAL_PIVY flag and fixing the libcoin path for libcoin80.

    Then it ocurred to me to try the make with a -j1, and I saw it... was pointing at a file that was pointing at a file that was just a renamed pointer file. I had installed the AMD Catalyst binary drivers earlier (laptop has switchable Intel/AMD graphics) and it looks like it messed up the libGL stuff. Who knows what else it might have messed up, so I'm starting from scratch once again with a fresh Ubuntu 13.10 load - this time without proprietary graphics drivers. All my files are saved on Ubuntu One, so no big deal re-installing. I'll post back here after trying it again with the new repository.

  31. ...and that totally worked. This time I was able to install all the depencenies and compile. Now to do some assembling!

  32. Here
    providing you free tutorials and reference
    manuals with examples.You got more information regarding any topic.

    for more visit

  33. hey,

    thanks for the nice tut. first time i used git :)

    I used the branch, dev-assembly does not exist anymore.

    have a nice day

  34. dev-assembly2 is not functional, refer to

    You need to compile this branch instead: