Merge branch 'simulink_readme' into 'dev'

Simulink readme

Add a readme file to explain how to compile and use the simulink interface.

See merge request !94

MBsysC/mbs_interface/mbs_simulink/ReadMe.md

+Information about using the Simulink interface can be fount in the 
+[MBsysC/readme_aux/interface_simulink.md file](../../readme_aux/interface_simulink.md).

MBsysC/mbs_interface/mbs_simulink/test.mdl

@@ -7,7 +7,7 @@ Model {
     NumRootInports	    0
     NumRootOutports	    0
     ParameterArgumentNames  ""
-    ComputedModelVersion    "1.40"
+    ComputedModelVersion    "1.41"
     NumModelReferences	    0
     NumTestPointedSignals   0
     NumProvidedFunctions    0
@@ -32,7 +32,7 @@ Model {
       $ObjectID		      2
       $ClassName	      "Simulink.WindowInfo"
       IsActive		      [1]
-      Location		      [957.0, 171.0, 942.0, 842.0]
+      Location		      [758.0, 118.0, 942.0, 842.0]
       Object {
 	$PropName		"ModelBrowserInfo"
 	$ObjectID		3
@@ -68,9 +68,9 @@ Model {
   ModifiedByFormat	  "%<Auto>"
   LastModifiedBy	  "ndocquier"
   ModifiedDateFormat	  "%<Auto>"
-  LastModifiedDate	  "Fri Aug 12 11:39:02 2016"
-  RTWModifiedTimeStamp	  392902726
-  ModelVersionFormat	  "1.%<AutoIncrement:40>"
+  LastModifiedDate	  "Thu Oct 06 21:04:00 2016"
+  RTWModifiedTimeStamp	  397688612
+  ModelVersionFormat	  "1.%<AutoIncrement:41>"
   ConfigurationManager	  "none"
   SampleTimeColors	  off
   SampleTimeAnnotations	  off
@@ -924,7 +924,7 @@ Model {
   }
   System {
     Name		    "test"
-    Location		    [957, 171, 1899, 1013]
+    Location		    [758, 118, 1700, 960]
     Open		    on
     ModelBrowserVisibility  off
     ModelBrowserWidth	    200
@@ -1121,7 +1121,7 @@ Model {
       Position		      [500, 80, 650, 420]
       ZOrder		      2
       FunctionName	      "MBsysC_SF_dirdyn"
-      Parameters	      "'../../../MBprojects/PendulumSpringC/dataR/PendulumSpringC.mbs'"
+      Parameters	      "'../../../ExampleProjects/PendulumSpringC/dataR/PendulumSpringC.mbs'"
       SFunctionDeploymentMode off
       EnableBusSupport	      off
     }
@@ -1189,22 +1189,22 @@ Model {
       "gr.Configuration('Core','General UI',true),extmgr.Configuration('Core','Source UI',true),extmgr.Configuration('S"
       "ources','WiredSimulink',true,'DataLoggingLimitDataPoints',true,'DataLoggingSaveFormat','StructureWithTime','Data"
       "LoggingDecimation','1','DataLoggingDecimateData',true,'DataLogging',true,'DataLoggingVariableName','q'),extmgr.C"
-      "onfiguration('Visuals','Time Domain',true,'SerializedDisplays',{struct('MinYLimReal','-0.52027','MaxYLimReal','0"
-      ".59195','YLabelReal','','MinYLimMag','0.00000','MaxYLimMag','0.59195','LegendVisibility','On','XGrid',true,'YGri"
+      "onfiguration('Visuals','Time Domain',true,'SerializedDisplays',{struct('MinYLimReal','-0.51959','MaxYLimReal','0"
+      ".59143','YLabelReal','','MinYLimMag','0.00000','MaxYLimMag','0.59143','LegendVisibility','On','XGrid',true,'YGri"
       "d',true,'PlotMagPhase',false,'AxesColor',[0 0 0],'AxesTickColor',[0.686274509803922 0.686274509803922 0.68627450"
       "9803922],'ColorOrder',[1 1 0.0666666666666667;0.0745098039215686 0.623529411764706 1;1 0.411764705882353 0.16078"
       "431372549;0.392156862745098 0.831372549019608 0.0745098039215686;0.717647058823529 0.274509803921569 1;0.0588235"
       "294117647 1 1;1 0.0745098039215686 0.650980392156863],'Title','%<SignalLabel>','LinePropertiesCache',{{}},'UserD"
       "efinedChannelNames',{{}},'NumLines',5,'LineNames',{{'dirdynared s-function/1:1','dirdynared s-function/1:2','dir"
       "dynared s-function/1:3','dirdynared s-function/1:4','dirdynared s-function/1:5'}},'ShowContent',true,'Placement'"
-      ",1)},'DisplayPropertyDefaults',struct('MinYLimReal','-0.52027','MaxYLimReal','0.59195','YLabelReal','','MinYLimM"
-      "ag','0.00000','MaxYLimMag','0.59195','LegendVisibility','On','XGrid',true,'YGrid',true,'PlotMagPhase',false,'Axe"
+      ",1)},'DisplayPropertyDefaults',struct('MinYLimReal','-0.51959','MaxYLimReal','0.59143','YLabelReal','','MinYLimM"
+      "ag','0.00000','MaxYLimMag','0.59143','LegendVisibility','On','XGrid',true,'YGrid',true,'PlotMagPhase',false,'Axe"
       "sColor',[0 0 0],'AxesTickColor',[0.686274509803922 0.686274509803922 0.686274509803922],'ColorOrder',[0.07450980"
       "39215686 0.623529411764706 1;1 0.411764705882353 0.16078431372549;1 1 0.0666666666666667;0.717647058823529 0.274"
       "509803921569 1;0.392156862745098 0.831372549019608 0.0745098039215686;0.0588235294117647 1 1;1 0.074509803921568"
       "6 0.650980392156863]),'TimeRangeSamples','20','TimeRangeFrames','20'),extmgr.Configuration('Tools','Plot Navigat"
       "ion',true),extmgr.Configuration('Tools','Measurements',true,'Version','2016a')),'Version','2016a','Position',[13"
-      "3 237 683 528])"
+      "3 209 683 528])"
     }
     Block {
       BlockType		      Scope

MBsysC/mbs_interface/mbs_simulink/two_model_test.mdl

@@ -7,7 +7,7 @@ Model {
     NumRootInports	    0
     NumRootOutports	    0
     ParameterArgumentNames  ""
-    ComputedModelVersion    "1.21"
+    ComputedModelVersion    "1.22"
     NumModelReferences	    0
     NumTestPointedSignals   0
     NumProvidedFunctions    0
@@ -68,9 +68,9 @@ Model {
   ModifiedByFormat	  "%<Auto>"
   LastModifiedBy	  "ndocquier"
   ModifiedDateFormat	  "%<Auto>"
-  LastModifiedDate	  "Fri Aug 12 11:38:27 2016"
-  RTWModifiedTimeStamp	  392902703
-  ModelVersionFormat	  "1.%<AutoIncrement:21>"
+  LastModifiedDate	  "Thu Oct 06 21:31:09 2016"
+  RTWModifiedTimeStamp	  397690220
+  ModelVersionFormat	  "1.%<AutoIncrement:22>"
   ConfigurationManager	  "none"
   SampleTimeColors	  off
   SampleTimeAnnotations	  off
@@ -868,7 +868,7 @@ Model {
       Position		      [325, 58, 450, 272]
       ZOrder		      2
       FunctionName	      "MBsysC_SF_dirdyn"
-      Parameters	      "'../../../MBprojects/MultiplePendulum/dataR/MultiplePendulum.mbs'"
+      Parameters	      "'../../../ExampleProjects/MultiplePendulum/dataR/MultiplePendulum.mbs'"
       SFunctionDeploymentMode off
       EnableBusSupport	      off
     }
@@ -880,7 +880,7 @@ Model {
       Position		      [330, 315, 450, 565]
       ZOrder		      9
       FunctionName	      "MBsysC_SF_dirdyn"
-      Parameters	      "'../../../MBprojects/PendulumSpringC/dataR/PendulumSpringC.mbs'"
+      Parameters	      "'../../../ExampleProjects/PendulumSpringC/dataR/PendulumSpringC.mbs'"
       SFunctionDeploymentMode off
       EnableBusSupport	      off
     }

MBsysC/readme_aux/interface_simulink.md

+# Simulink interface to Robotran/MBsysC modules
+
+The Simulink/MBsysC interface enables to introduce a Robotran model
+into a Simulink block diagram using a S-function. This document explains
+ how to compile and how to use this interface.
+ 
+## Compiling the interface
+
+* First, the MBsysC momdules must be compiled already
+* Go to the `MBsysC/mbs_interface/mbs_simulink` folder
+* Create a *build* directory: `mkdir build`
+* Configure the Cmake project: `cmake ..`
+* Build the interface: `make`
+
+Those operations should produce a file *MBsysC_SF_dirdyn.mexa64* (the
+extension will change depending on the OS). This file must be compiled
+only once and can then be used for any project (assuming 
+FLAG_SEPARATE_BUILD was set to ON when building the project)
+
+
+## Compiling the project
+
+The project must be compiled as usual but **the FLAG_SEPARATE_BUILD 
+must be set to ON**.
+
+
+## Building a Simulink block diagram with a Robotran model
+
+* Add the `MBsysC/mbs_interface/mbs_simulink` folder to your matlab path. 
+  In matlab: `addpath('paht/to/MBsysC/mbs_interface/mbs_simulink')`
+* Create a new Simulink block diagram or poen an existing one
+* Insert a S-function block from the Simulink library (it can be found in the
+  Simulink/User-Defined Functions). Alternatively, you can copy/paste
+  the block from an existing diagram such as the examples project availabl in 
+  the `MBsysC/mbs_interface/mbs_simulink` folder.
+* Double-click on the S-function block and edit the propeties as follows:
+  * **S-function name**: type `MBsysC_SF_dirdyn` (the name of the compiled
+      file withou the extension)
+  * **S-function parameters**: enter the path to the *.mbs file surrounded
+       by single quotes
+  * **S-function modules**: keep the default setting
+* Connect the input/port of the block to the diagram:
+  * 1st input  is ...
+  * 2nd input  is ...
+  * 1st output contains the joint positions 
+  * 2nd output contains the joint velocities 
+  * 3rd output contains the joint accelerations 
+* Complete the Simulink diagram as desired
+* Run the simulation           
+
+## Adding input/output ports
+
+Custom input or output ports can be added to the block.
+
+* Define input/output (IO) by editing the *.mbs model with a text editor (this 
+can not be done in MBsysPad presently). Add a *user_variables* (with s!) section or
+complete the existing one (after the user_models section). Add as many
+user_variable (without s) section as IO number desired as illustrated
+by the following example:
+  ```xml
+  <user_variable>
+    <user_variable>
+      <varname>Fsusp</varname>
+      <type>out</type>
+      <size>4</size>
+    </user_variable>
+    <user_variable>
+      <varname>motorTorque</varname>
+      <type>in</type>
+      <size>1</size>
+    </user_variable><user_variable>
+  ```
+  * **varname** contains the name of the IO. The data will be 
+     readable/editable in the code via `mbs_data->userIO->varname`.
+  * **type** determines wether it is an input or an output  
+  * **size** defines the number of element in the IO. If size=1, the IO
+    will be a scalar (double). If size>1n the IO will be an array (double *) 
+
+* (Re-)generate the userIO.c and userIO.h files. This is done via
+  MBsysPad using the menu *Tools/Generate C-specific user files/All* 
+  (check that the *user_file_generation* utility in the 
+  `MBsysC/mbs_app` folder has been compiled before)
+  
+* Rebuild your project (the Simulink interface must NOT be rebuilt)
+
+* Reload the simulink diagram (or simply edit the properties of the 
+  S-function block). The new ports will then be visible.
+
+## Status
+
+* Simulation of several different model in the same diagram: OK
+* Platform
+  * Linux: OK
+  * Windows and MacOS: not tested
+* Type of building
+  * Separate build: OK  
+  * Monolithic build: not tested
+* Realtime features
+  * Not working. Should be implemented differently  
+* To be done
+  * improve integration with existing function (compute_model is duplicated)
+  * improve user interface (cf JFC work in MBsysLab/mbs_simulink)