Bodies and joints
=================
.. container:: c-code
.. highlight:: c
Bodies and joints define the tree structure of the multibody systems
Bodies
------
- They are fully defined by:
- The mass
- The position of center of mass
- The inertia matrix
- Particular points of a body can be identified using anchor points
- Each body must be connected to one and only one parent joint
Joints
------
- A joint defines the relative motion between two bodies
- A joint can be attached to
- The base
- An anchor point
- Another joint
Example: the pendulum-spring-mass system
----------------------------------------
.. figure:: figure/PendulumSpringExample.png
:alt: The initial example model consists of a pendulum with a mass sliding along
Pendulum spring illustration
..
REMARK:
In Robotran right handed coordinates convention is used. In this
case, on the figure, positive rotations are anticlockwise
Model data
~~~~~~~~~~
The example model is composed of the following elements:
- Two bodies
- the pendulum
- Mass: 5 kg
- Inertia along axis \ :math:`\hat{I}_{2}`\ : 0.1 kg.m2
- the slider
- Mass: 2 kg
- Two joints
- A revolute joint between the pendulum and the base
- A prismatic joint between the pendulum and the slider
- A linear spring-damper element
- Will be implemented as a joint force
- Stiffness: 100 N/m
- Damping: 2 Ns/m
- Free length: 0.1 m
Geometrical data is given in the figure above.
The following initial conditions are considered:
- Rotation of the pendulum: 1 rad
- Translation of the slider with respect to point A: 0.2 m
Step 1: Draw your multibody system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Draw a base body:
- Click the body button
- Select a shape
- Click in the drawing area (for a rectangle: click twice: once for 1st
corner and once for 2nd corner)
- In the right panel, set the z component of the gravity to 9.81m/s2
.. figure:: figure/bodiesJoint_snapshot_bodyShapes.png
:alt: Create a new body by clicking the Body menu
Body drop down menu
..
REMARK:
The shape of bodies in the 2D diagram does not influence the dynamics
Draw a R2 joint:
- Click the joint button
- Select R2
- Click in the drawing area to draw the joint
- Activate the joint properties panel by clicking on the joint
- Give a name to the joint, for instance “R2_pendulum”
.. figure:: figure/bodiesJoint_snapshot_jointType.png
:alt: Create a new joint by clicking the Joint menu
Joint drop down menu
..
REMARK:
In the R2 naming:
- “R” stands for revolute
- “2” stands for axis 2 (y-axis)
..
WARNING:
be careful when giving name to the elements: use only alphanumeric
characters, always start with a letter (as for any variable in a
program code).
Draw the pendulum body:
- Same procedure as for the base body
- Attach this body to the R2 joint
- Activate the body properties panel by clicking on the body
- In the right panel, give a name to the body and fill the dynamic
properties
- Center of Mass coordinates in the body-fixed frame, it is aligned
with the local Z axis
- Inertia matrix in the body-fixed frame, with respect to the center
of mass
.. figure:: figure/bodiesJoint_snapshot_drawBody.png
:alt: Create the pendulum body
Pendulum body snapshot
..
REMARK:
When drawing a body, you can select the joint it will be attached to
by coming close to this joint (which will be highlighted).
..
REMARK:
For each body, there is a body-fixed frame: this frame move with the
body and is fixed at the position of the parent joint. Its axis are
aligned with the axis of the parent body when joint positions between
the 2 bodies are set to 0.
Draw an anchor point on the pendulum body:
- Click the Anchor Point button
- Click in the drawing area on the pendulum body
- Fill the point coordinates in the right panel (coordinates in the
body fixed frame, it is aligned with the local Z axis)
- This anchor will be reference point for the prismatic joint.
.. figure:: figure/bodiesJoint_snapshot_drawAnchorPoint.png
:alt: Create an anchor point
Anchor point snapshot
Complete the diagram:
- Draw a T3 joint attached to the anchor point using the same procedure
as for the R2 joint
- Draw a body for the slider (Don’t forget to fill in its dynamical
properties)
.. figure:: figure/bodiesJoint_snapshot_pendulumSpringFull.png
:alt: Full MBsysPad diagram of the Pendulum sping example
Snapshot of the complete diagram
..
REMARK:
In the T3 naming:
- “T” stands for translation
- “3” stands for axis 3 (z-axis) of the pendulum fixed-frame
Set initial conditions for the joints:
- Click on the joint you want to edit
- Enter the initial value at the bottom of the right panel
Save your project
..
REMARK:
All the data entered in MBsysPad are saved in a \*.mbs file which is
located in the dataR subfolder of your project. The \*.mbs file uses
an XML format.
Step 2: Generate your multibody equations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Click on the menu Tools > Generate Symbolic Files
.. figure:: figure/bodiesJoint_snapshot_generateMenu.png
:alt: Access the symbolic generation interface via the menu Tools/Generate Symbolic Files
Snapshot of the Generate symbolic file menu
- Enter your username and password
- Select your programming language: C
- The language is case-sensitive;
- Several language can be generated, split them with a coma;
- The language of the template has te be included;
- Keep other options to default
- Click on the Generate button
- Check that symbolic files have been downloaded to the symbolicR
subfolder of your project
.. figure:: figure/bodiesJoint_snapshot_generateGui.png
:alt: Enter your username and password in to the symbolic generation gui
Snapshot of the symbolic generation gui
..
REMARKS:
If you don’t have an account you can either use demo account (usr =
demo, pw = demo) or ask one via the online form *Need an account ?*
on the `Robotran website `__
You can save you configuration (username, password, language …) by
clicking on the “Save To File” button
You can reset your parameters by clicking on “Settings->Reset
password for symbolics”
Step 3: Write your user function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container:: c-code
- Implement the spring-damper law
- Edit the *user_JointForces* function (located in the
user_JointForces.c file from the userfctR subfolder of your
project
- Write the force equations with a stifness K of 100 [N/m] and a
damping C of 2 [Ns/m]
.. code:: c
double* user_JointForces(MbsData *mbs_data, double tsim)
{
//...
// set the joint force in joint 2
int id = 2;
double K = 100;
double C = 2;
double L0 = 0.1;
mbs_data->Qq[id] = - ( K*(mbs_data->q[id]-L0) + C*mbs_data->qd[id] );
//...
}
..
NB :
- mbs_data->q is the joint position
- mbs_data->qd is the joint speed
- ``id`` is a python build-in function, avoid to replace it by a
variable.
..
REMARK:
A joint force/torque is a force/torque acting along the axis of a
joint. It is thus:
- a force for a prismatic joint,
- a torque for revolute joint.
Joint forces correspond to the Qq vector in the equations of motion:
:math:`\begin{matrix} M(q)\ddot{q} + c(q, \dot{q}, frc, trq, g) = Q(q, \dot{q}) + J^T\lambda \\ h(q) = 0 \end{matrix}`\
Qq is the force/torque acting from the parent body to the child body.
The reaction is automatically taken into account by the multibody
formalism.
Step 4: Run your simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. container:: c-code
.. rubric:: Adapt the files
:name: adapt-the-files
Open the *main.c* file located in your workR/src folder:
- Set the end of simulation at 5 seconds :
``mbs_dirdyn->options->tf = 5.0;``
- Check that the name of the project at the line
``mbs_data = mbs_load(PROJECT_SOURCE_DIR"/../dataR/...", BUILD_PATH);``
is the same as your .mbs file
- MBsyspad should have create the file with your project name
(and path) already included.
- You have to update the name if you retrieve the file from an
older project (or change the directories).
Open the *CmakeLists.txt* file located in your workR folder:
- Check that the name of the project at the line
``project (ProjectName)`` is the same as your .mbs file
- MBsyspad should have create the file with your project name
already included.
- Set the path to your Robotran common files
- MBsyspad should have create the file with the default version
of MBsysC you’ve set (see Tools > Edit preference)
- You have to update the path to MBsysC if you want to use a
specific version of MBsysC, put it at this line:
.. highlight:: cmake
::
set(TRIAL_PATHS_MBSYSC
${PROJECT_SOURCE_DIR}/PATH_TO_MBsysC/MBsysC/
)
..
.. highlight:: c
.. rubric:: Build and run the project
:name: build-and-run-the-project
You first need to install CMake. More information is provided on the
`official CMake website `__. Once this is done,
you can generate a project with the *CMakeLists.txt* file located in
the *workR* folder.
The basic steps consists in :
- Create a build directory in the */workR/* folder
- Compile the project
- Run the file
This can be done using a Unix Terminal (Linux, Mac OS) or trough a
Gui interface (Windows, Linux, Mac OS).
.. rubric:: Compiling in terminal (Unix, MacOS)
:name: compiling-in-terminal-unix-macos
These are the command lines on a Unix Terminal (on Mac OS, the
Terminal is located in the *Applications/Utilities* folder):
.. highlight:: bash
::
cd workR # go in workR folder
mkdir build # create a folder named build
cd build
cmake .. # generate a Makefile
make # build the projects
./exe_PendulumSpring # run the project
.. highlight:: c
.. rubric:: Compiling with the CMake Gui interface (Windows, Unix,
MacOS)
:name: compiling-with-the-cmake-gui-interface-windows-unix-macos
To use the CMake Gui interface, you first need to run the
corresponding application (look for *CMake* in your applications).
Then, click on *Browse Source…* and select the location of the main
*CMakeLists.txt* file, i.e. your workR folder. Click on *Browse
Build…* and select an empty folder where the binaries will be
automatically created. This can be inside your project (inside the
*workR/build* folder in the Unix Terminal example above) or anywhere
on your computer, like on *Desktop/build*, as you can see in the next
illustration.
.. figure:: figure/cmake_gui_1.PNG
:alt: Source and Build selected
Source and Build selected
Click on the *Configure* button and select the type of generator
(IDE…) you want to use. Pay attention to use a 64 bit configuration
if your OS is 64 bit (same thing for 32 bit).
.. figure:: figure/cmake_gui_2.PNG
:alt: Generator
Generator
The configuration panel will appear. **Red does not mean that
something went wrong**. Check the lines below the *Configure* button
to check if all libraries were found. Otherwise, look at the
*Installation tutorial*. *Symbolic … not found, linking to void
function* is not an error, it means that this function was not
generated because you do not use it in your project.
.. figure:: figure/cmake_gui_3.PNG
:alt: Project configuration
Project configuration
You can change some options like selecting the Real-time featues in
the next figure. You then need to press again the *Configure* button.
.. figure:: figure/cmake_gui_4.PNG
:alt: Selecting real-time features
Selecting real-time features
Finally, click on the *Generate* button. Your project will be created
inside the *build* folder you specified. In this folder, you can
click on the project to launch it (*projectRobotran* as a `Visual
Studio `__ project in the following
example).
.. figure:: figure/cmake_gui_5.PNG
:alt: Binaries created by CMake
Binaries created by CMake
If you use `Visual Studio `__ on
Windows (recommended), right click on *exe_projectRobotran* and
select *Set as StartUp project*. You can then choose between
``Debug`` and ``Release`` before compiling.
To launch the project, go in ``DEBUG`` and launch ``Start Debugging``
(for ``Debug`` mode) or ``Start Without Debugging`` (for ``Release``
mode). You can also go inside your *build* folder (folder you
configured in *CMake* for the binaries) and launch the executable
``exe_projectRobotran`` in the ``Debug`` folder (for *Debug* version)
or the one in the ``Release`` folder (for *Release* version).
Finally, to launch the *Debug* version, you can also click on
``Local Windows Debugger``.
Importantly, to run the ``Debug`` version, you might have to remove
the Java visualization features (part of the real-time features).
This can be done in ``userfctR/realtime/user_realtime_options.c``
with the line ``options->flag_visu = 0;``.
Step 5: Animate your 3D MBS
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Draw your MBS system in 3D
^^^^^^^^^^^^^^^^^^^^^^^^^^
You can customize the 3D view of your system as follows:
- Open your \*.mbs file in MBsysPad
- Click on the Design 3D model button
.. figure:: figure/design3D_snapshot_designIcon.png
:alt: Open the Design 3D frame using the toolbar button
Snapshot of the Design 3D icon
- Activate the body you want to edit
- Click on the body in the 2D view
- Or go to the 3D view and, in the right panel, use the drop down
menu of the Comp tab
.. figure:: figure/design3D_snapshot_selectBody.png
:alt: Select the object you want to edit
Snapshot of the 3D object selection menu
- Add a shape and edit its properties
- The shape inline allow to add a 3D part exported from CAD
software. The part must be saved in the VRML format (extension
\*.wrl). Only VRML 2.0 or VRML 97 are supported (not VRML 1.0).
.. figure:: figure/design3D_snapshot_editBody.png
:alt: Edit the 3D properties of a body and add shapes to its representation
Snapshot of the 3D properties panel for bodies
- Use the ViewPt to add registered viewpoint
- Use the Light tab to add lights to the scene
..
REMARK:
Attaching a viewpoint or a light to a joint will make them follow the
motion when animating the model.
Animate your results
^^^^^^^^^^^^^^^^^^^^
You can view a 3D animation of the system using MBSysPad as follows:
- Open your \*.mbs file in MBsysPad
- Click on the Animate 3D model button
.. figure:: figure/animate3D_snapshot_animateIcon.png
:alt: Open the Animate 3D frame using the toolbar button
Snapshot of the Animate 3D icon
- Load the result file
- Click on the Open button
- Select the \*.anim file located in the animationR subfolder of
your project
.. figure:: figure/animate3D_snapshot_openFileIcon.png
:alt: Select the animation file via the open file button
Snapshot of the Open file button
- Use the control buttons to run the animation
.. figure:: figure/animate3D_snapshot_controlButtons.png
:alt: Control the animation using the toolbar
Snapshot of the Control toolbar of the Animate 3D frame
..
REMARK:
Navigating in the 3D view:
- Rotation : Mouse motion + left button
- Zoom : Mouse motion + middle button (OR ALT + mouse motion +
single button)
- Translation : Mouse motion + right button
Check the results
~~~~~~~~~~~~~~~~~
Plot the graph of the joint position (results ares avilaible in
resultsR/ folder) and check your results with the following graph.
.. figure:: figure/bodiesJoint_curves_q1q2.png
:alt: Plot the time history of the joint position of the pendulum spring example
Time history of the joint position