New component
Let’s start by creating a new component in the Library page. If you don’t know how to do it, please take a look to Creating a new component.
In order to provide some background, a motor contactor works as an electric motor’s switch. Its main role is to connect or disconnect the electrical conducting path, remaining disconnected by default. It is controlled by DC, meaning that a voltage difference (I.e 20V) is needed to enable it. As it controls an electric motor, it uses 3phase connections.
Ports
In Simumatik, connections between components are made with the help of ports. Each component can have ports of a certain type (e.g. electric, pneumatic, etc) which can be configured as inputs or outputs.
The rule for making a connection is simple: Two components can be connected if their ports are the same type (e.g. electric) and the connection is made from an output to an input port. Also, one output port can be connected to several input ports.
A motor contactor works as a 3phase switch controlled by DC voltage. That means that we will need five electrical input ports (3 phases + positive/negative DC) and three electric output ports (3 phases).
Let’s add the different ports by opening the options menu of the component element and pick electric_input five times and electric_output three times.
Once you have added them, rename them as in the picture below. Left-click on each port and click on the Name field located at the bottom, a pop-up will be shown and you will be able to modify the name there.
Behavior
Now that the ports are ready, let’s start by creating the behavior, which will run the component’s logic. Open the options menu on components and choose the behavior element.
The logic is isolated from the rest of the component, and therefore it is necessary to create local variables that mirror the inputs and outputs ports values to allow some interaction. Later on, we will connect these variables to the ports, so the behavior can read and write them.
Variables
Let’s add the different variables by opening the options menu on the behavior element and picking variable. We will start with the input variables, so let’s create 5, as we need as many as input ports (3 phases + positive/negative DC).
Once you have added all of them, rename them with the same names as the ports, by clicking on the Name field at the bottom, and finally change their data_type to smtk_vector3, by clicking on the Data type field at the bottom too.
Next, we will add the output variables, so let’s create 3, as we need as many as output ports (3 phases). For each of them, repeat the previous rename and data-type selection steps. Finally, we will also need to change Variable Type by clicking on Type, at the bottom, and pick output.
Script
Next, let’s look at the script. Let’s download the script with the logic by right-clicking here and selecting Save Link As... Go back to the Component Information tab and upload it as an asset.
Go back to the Editor tab. Inside the behavior element, click on the script and finally on the Value field at the bottom to pick the logic asset. If you did it correctly, you should see the following logic code in the editor.
The motor contactor logic is following the statement below:
If we detect that the voltage difference between x1 (DC+) and x0 (DC-) is greater than 20V, then we will connect L1_out, L2_out and L3_out to L1_in, L2_in and L3_in. Otherwise, these outputs will be set to 0V.
In the script, x1 and x0 are arrays (smtk_vector3) that will show the electric port values: voltage value, frequency and phase (in that order). For DC we only need to compare the voltage, so that’s why we only read x1[0] and x0[0].
Connections
To manage the connections, it is as easy as drag-and-drop any element from the tree to a variable of the behavior. For example, in the electric input port L1_in, we are interested in the voltage information (value, frequency and phase), so let’s drag-and-drop it to L1_in, next to the code. Now, you will see the connection details next to the variable.
Let’s drag-and-drop all the ports‘ voltages to the variables in the behavior with the same name. The result should be the same as in the following picture, where inputs are on the left side and outputs on the right:
Each time an input port changes, the variable in the behavior will change too and the logic will be rerun. Each time an output variable changes, the output port value will be updated.
Symbol
As we are creating an electrical component, let’s add its symbol to the component. This will allow to match the component’s ports to the symbol parts, so we are always sure how to do the connections later.
First, let’s download the symbol image by right-clicking here and selecting Save Link As... Go back to the Component Information tab and upload it as an asset.
Next, let’s go back to the Editor tab and add the symbol element by opening the options menu of the component element and selecting symbol.
Inside the newly created symbol element, click on the image element and then on the Value field at the bottom to pick the asset.
In the editor, you should now see the symbol image. Next to it, there is some black dots. If you hover it, you will see it has a port name.
Drag-and-drop each dot to the corresponding place:
Visual
Finally, let’s add a 3D model to the component. First, download the 3D from here and then go back to the Component Information tab to upload the 3D as an asset.
Go back to the Editor tab and change the geometry element inside the base_link’s visual to mesh. Then, in model pick the asset we just uploaded.
3D ports
Now that all ports and visual elements are added, it’s time to take a look at the port positions in the 3D world. By modifying the origin of the input/output ports we can give them the correct position.
The inputs (red cones) should point into the component, while the outputs (black cones) should point out from the component.
