Cables Create Custom Connector

For Cable Connector objects the main presets file is named connectorpresets.csv. Download the connectorpresets.csv file from the Cables Workbench source code and place it in the $FREECAD_USER_DIR/Cables/ folder created in the previous step.

Edit the connectorpresets.csv file with your favorite text editor. I recommend the Kate editor which has a nice built-in coloring of edited CSV files.

Inside the connectorpresets.csv file remove all lines which DO NOT start with a '#' sign (empty lines can be left as they are). This is to avoid duplicate connectors which already exist in built-in library.

IMPORTANT: The connectorpresets.csv file has to be created only once. This file can contain base definitions for all custom-created connectors. Each connector is defined by a single line in this file. If a new connector is added in the future, you will simply need to add a new line to this file. There are some additional files needed in the lib/ subfolder, but this will be explained in the next steps.

The connector type of Fixed PresetType is not parametric and requires an external shape loaded from a STEP file every time a new connector is created.

As an example the Micro-Fit 3.0 Plug for 2 circuits with Panel Mount Ears will be used in this tutorial. Download it in STEP AP242 format.

VERY IMPORTANT: Some STEP files will probably do not load properly into the connector. The CableConnector STEP File describes how to deal with this problem.

After downloading, change the file name to Micro-Fit3_DualRow-PME-2.step (the name can be anything, but it should describe the connector model as precisely as possible). Place the file in the $FREECAD_USER_DIR/Cables/lib/ folder.

NOTE: Since the name of the connector has been established, it has to be used consequently in all steps below especially inside the csv files. For example the Name and Connector Class fields in the connectorpresets.csv file are used by the software to look for a valid connector name (if Name = DualRow-PME-2, Connector Class = Micro-Fit3, and the CSV description file has to be named Connector Class_Name.csv, this results in Micro-Fit3_DualRow-PME-2.csv for this example).

Each STEP model used to build a Cable Connector should have its own CSV description file. This file contains additional information about model placement, CableTerminals and SuppLines attached to the model. In this tutorial the CSV description file will have the name Micro-Fit3_DualRow-PME-2.csv.

Download the Connector_Dummy.csv file from the Cables Workbench source code and place it in the $FREECAD_USER_DIR/Cables/lib/ folder. Change its name to Micro-Fit3_DualRow-PME-2.csv.

Edit the Micro-Fit3_DualRow-PME-2.csv file with a text editor. Inside the Micro-Fit3_DualRow-PME-2.csv file remove all lines which DO NOT begin with a '#' sign (empty lines can be left as they are). The new necessary lines will be created in the next steps.

Edit the connectorpresets.csv file once again. Create a new line below the following lines:

# Fixed Preset Type
# Name,Fixed,Connector Class,StepFileName,NrOfTerminals,NrOfSuppLines

and add a text as the one below:

DualRow-PME-2,Fixed,Micro-Fit3,Micro-Fit3_DualRow-PME-2.step,2,1

It contains the information that this connector will have 2 CableTerminals and 1 SuppLines cross. To learn more about the rules for this line, have a look at CableConnector More details about Fixed PresetType in connectorpresets.csv file.

Then edit the Micro-Fit3_DualRow-PME-2.csv file. Create a new line below the following lines:

# Connector Element Type
# Name,ExtShape,Class,Offset X,Offset Y,Offset Z,Rotation Yaw(Z),Rotation Pitch(Y), Rotation Roll(X)

and add the text:

DualRow-PME-2,ExtShape,Micro-Fit3,0.0,0.0,0.0,0.0,0.0,0.0

then below the lines:

# Terminal Element Type
# Name,Terminal,Class,Offset X,Offset Y,Offset Z,Rotation Yaw(Z),Rotation Pitch(Y), Rotation Roll(X),NrOfConnections,Length,Spacing

add 2 lines:

Pin001,Terminal,Terminal,-10.0,0.0,0.0,0.0,0.0,0.0,1,10.0,1.0
Pin002,Terminal,Terminal,10.0,0.0,0.0,0.0,0.0,0.0,1,10.0,1.0

and finally below the lines:

# SupportLines Element Type
# Name,SupportLines,Class,Offset X,Offset Y,Offset Z,Rotation Yaw(Z),Rotation Pitch(Y), Rotation Roll(X)

add 1 line:

SuppLines001,SupportLines,SupportLines,0,0,30.0,0,0,0

The lines added above define the starting positions of connector body, 2 terminals and 1 supplines cross. In the next steps the final positions of all elements will be established.

The placement of imported STEP shape can be different then expected. Let's assume in this example that the plug should stand vertically, with the cables exiting upwards, and the bottom should touch the (0,0,0) point.

Let's forget about CableTerminals and SuppLines for a moment, select the connector in the Tree View and move it and rotate with TransformManip tool.

Its placement can be checked now in the Property View or in Python Console. Details on how to do this are presented in Placement. Choose the view of Yaw, Pitch and Roll in the Placement task panel. It will better present rotation results. The precise values can be entered manually.

The placement result should be like this: Placement [Pos=(0,0,8.445), Yaw-Pitch-Roll=(0,0,-90)]

Edit the Micro-Fit3_DualRow-PME-2.csv file again and modify the line:

DualRow-PME-2,ExtShape,Micro-Fit3,0.0,0.0,0.0,0.0,0.0,0.0

to:

DualRow-PME-2,ExtShape,Micro-Fit3,0.0,0.0,8.445,0.0,0.0,-90.0

and save the Micro-Fit3_DualRow-PME-2.csv file.

Delete all objects in current FreeCAD document and create the connector again choosing Micro-Fit3_DualRow-PME-2 preset. Its current placement should match what was just set. Note that the connector placement shown in the Property View or in Python Console is now Placement [Pos=(0,0,0), Yaw-Pitch-Roll=(0,0,0)]. This is correct because the connector shape placement has been set upon creation based on data in Micro-Fit3_DualRow-PME-2.csv file.

The final effect should be like on the image below.

Micro-Fit3_DualRow-PME-2 connector placed vertically.

Expand CableConnector in the Tree View. It should contain two terminal subobjects: CableConnector_Term001 and CableConnector_Term002. Both have to be adjusted to fit into connector.

Clear the Attachment Support property value of both terminals in the Property View. This is necessary to enable unattached movement of terminals.

Select the first terminal in the Tree View and change its Length to 6mm in the Property View. Then using TransformManip tool place it vertically inside connector making sure that Vertex1 of the terminal is facing up (this is important later during cable attachment). The vertex number is shown in bottom status line of FreeCAD while hovering cursor over the vertex in the 3D View. Repeat all moves for the second terminal.

Using the same methods as in previous step check if the placement of terminals match the values given below:

CableConnector_Term001: Placement [Pos=(0,1.5,12.0), Yaw-Pitch-Roll=(0,0,90)]

CableConnector_Term001: Placement [Pos=(0,-1.5,12.0), Yaw-Pitch-Roll=(0,0,90)]

Retype these values into the Micro-Fit3_DualRow-PME-2.csv file by replacing the lines:

Pin001,Terminal,Terminal,-10.0,0.0,0.0,0.0,0.0,0.0,1,10.0,1.0
Pin002,Terminal,Terminal,10.0,0.0,0.0,0.0,0.0,0.0,1,10.0,1.0

with these lines:

Pin001,Terminal,Terminal,0.0,1.5,12.0,0.0,0.0,90.0,1,6.0,1.0
Pin002,Terminal,Terminal,0.0,-1.5,12.0,0.0,0.0,90.0,1,6.0,1.0

Delete all objects in current FreeCAD document and create the connector again choosing Micro-Fit3_DualRow-PME-2 preset. Its current placement should match what was just set and should be similar to the image below.

Micro-Fit3_DualRow-PME-2 connector with terminals properly aligned. It is transparent for better visibility of terminals.

The single SuppLines object (CableConnector_SuppLines001 in this example) has the shape of a cross with a fixed predefined size. This object can be used as a fixing point for a cable attached to the connector. It is up to the user to use it or not.

The default placement of SuppLines cross in this tutorial is too high. Let's change its placement using methods described in previous steps.

The final placement of SuppLines may look like this: CableConnector_SuppLines001: Placement [Pos=(0,0,25), Yaw-Pitch-Roll=(0,0,0)]

Retype the above values into the Micro-Fit3_DualRow-PME-2.csv file by replacing the line:

SuppLines001,SupportLines,SupportLines,0,0,30.0,0,0,0

with this line:

SuppLines001,SupportLines,SupportLines,0,0,25.0,0,0,0

Once again delete all objects in current FreeCAD document and create the connector choosing Micro-Fit3_DualRow-PME-2 preset. The result should present all final adjustments of created objects.

The connector Micro-Fit3_DualRow-PME-2 preset definition is now ready to use in projects.