Tutorial 5: Electrical motor contactor
In this tutorial you will:
- Use electrical ports
- Create a more complex behavior
- Add a component symbol
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 disconnet 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.
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).
In Simumatik, an electrical port represents one single wire and has a configurable voltage, frequency and phase difference. For DC, we just set the frequency and phase difference to 0.
Let's add the different ports by right-clicking the component element and picking electric_input and electric_output.
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.
These ports names are not following the ISO nomenclature. They have just an informative purpose for this tutorial.
Now that the ports are ready, let's start by creating the behavior, which will run the component's logic. Right-click 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.
Let's add the different variables by right-clicking 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.
Electric ports uses data of type smtk_vector3. In order to connect the variables to the ports later, both need to have the same type. More documentation about different data-types will be published in the future.
Next, we will add the outputs variables, so let's create 3, as we need as many as output ports (3 phases). For each of them, repeate 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 picking output.
Variable Type is input by default and this is why we didn't do any change when adding the input types.
First, 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 again to the 3D 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, now you should be seeing the 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 and x0.
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.
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 add the symbol element by right-clicking the component element and selecting symbol.
Go again to the 3D tab. Inside the symbol element, click on the image element and finally on the Value field at the bottom to pick the asset.
In the editor, you should be seeing now 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:
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 uploaded as an asset.
Go again to the 3D tab and change the geometry element inside the base_link's visual to mesh. Then, in model pick the asset we just uploaded.
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.
Save and test
Your motor contactor is now finished! Let's take a screenshot of your newest component and save it.
You can now add it to a library and start using it. In the example below, you can see that the port x1 (DC+) is set to 0V, and therefore the ports L1_out, L2_out and L3_out are set to 0.
Once you set x1 to 24V, L1_out, L2_out and L3_out will be connected to L1_in, L2_in and L3_in, so the same values are displayed.