Editing Sci cosim

= Octave-Scilab co-simulation package =

Toolbox provides the functions for variable exchange between Octave and Scilab workspaces, and for the remote commands execution in Scilab, such as starting xcos simulation.
The main goal of this toolbox is to make an alternative for Simulink in Octave from Scilab xcos. But it can be also used to uses functions from Scilab toolboxes, that are unavailable for Octave.

== Installation ==
1. Install Octave (version 4.0.0 or higher) and Scilab v.5.5.2 _specifically_ (note: the BackDoor module is currently not supported for the new SciLab v6.0.0 version) 

2. Install the `sockets` package in Octave by executing 

''pkg install -forge sockets''

3. Download the `sci_cosim` package from  https://github.com/amromanov/sci_cosim 

4. Install the `sci_cosim` package in Octave by executing 

''pkg install sci_cosim_0.1.3.tar.gz''

5. Start the Scilab GUI and install the `Backdoor` toolbox from the main menu: Applications → Module manager - ATOMS → Technical → Backdoor → Install

6. Restart Scilab. If every thing was done correctly, after restarting there will be a message in the command window "BackDoor: listening to connections on TCP port"

You _may_ encounter an error that the files "backdoor.start" / "backdoor.quit" cannot be found. This occurs if the files are named e.g. "BackDoor.start" on the disk (i.e. case-sensitive). Simply rename the files to lowercase and restart SciLab.

== Running demo ==

1. Download demo from https://github.com/amromanov/sci_cosim/raw/master/demo.tar.gz

2. Extract it to any folder, where your user has read/write rights

3. Run Scilab. It doesn't matter for the co-simulation package if you are using GUI version (scilab) or console one (scilab-adv-cli).

4. Run Octave and change folder to the one, where you have extracted demo

5. Load the two packages ''pkg load sockets'' and ''pkg load sci_cosim'' in octave.

6. Run sci_sim_example.m

== Function description ==
 ''sci_connect''     - connects to running SciLab with Toolbox Backdoor. It should be used at least once per Octave session.

 ''sci_disconnect''  - disconnects from SciLab with Toolbox Backdoor. 

 ''sci_setvar''      - transfers variables, which names are listed in function arguments, from Octave to Scilab workspace.  

 ''sci_getvar''      - transfers variables, which names are listed in function arguments, from Scilab to Octave workspace.

 ''sci_cmd''         - executes single command in Scilab. 

 ''sci_sim''        - starts xcos simulation in Scilab. In the most cases, .xcos file should be in the Octave current directory. To set simulation duration use End block in Xcos and transfer its parameter as variable from Octave, using sci_setvar.

For more detailed usage description execute ''help FUNCTION_NAME'' in Octave.

== Usage cases ==
In all usage case, described below, user doesn't need to have any knowledge about using Scilab interface and in the most cases he doesn't have to know Scilab scripting language. You can use only Xcos and do the rest of things in Octave. 

1. Simple dynamic systems rapid prototyping. 

In this case you, actually, we need only Xcos. In other cases, described below, we also assume that Xcos is used for dynamic system simulation. The good starting point is to read [http://www.scilab.org/content/download/1107/10095/file/Xcos_beginners.pdf "Xcos for very beginners" guide] (even if you are familiar with Simulink).

2. Dynamic system rapid prototyping, when systems parameters have to be calculated by script. 

In this case you write and execute all scripts you need using Octave, and then transfer scripts results to Scilab workspace. For example, we have Octave script "calc_pid_params.m" that can tune PID controller parameters and return them as Kp, Ki and Kd variables to Octave workspace. In case we want to use those parameters in Xcos simulation we should run in Octave 

''sci_setvar('Kp','Ki','Kd');''

After that we can use those varibles in Xcos simulation. Of course, before running ''sci_setvar'', you should setup connection with Scilab using Sciconnect

3. Dynamic system rapid prototyping, when simulation results should be processed by script. 

In this case we have to move all simulation results you need into Octave workspace and then process them with any Octave script. For example, if your Xcos simulation return two vectors "speed" and "pos", to transfer them into Octave you will need to run

''sci_getvar('speed','pos');''

After that two new variables with names "speed" and "pos" will appear in Octave. If there were variables with such name, they will be changed to the ones received from Scilab. After that you can use them, as if they were created in Octave.

4. Automated Dynamic system simulation
In this case we use Octave scripts for setting up dynamic model parameters and result analysis. The Xcos simulation can be started both from Xcos GUI or from Octave using ''sci_sim'' function. In case of using ''sci_sim'' function the current directory in Octave contain .xcos model file. The current directory in Scilab doesn't matter, because it will be changed automatically. If you don't need Xcos GUI, you can ran  Scilab in console mode, it will cause no problem for starting Xcos simulations from Octave. The example of this usage is distributed with Scilab co-simulation package as demo.

5. Using Scilab co-simulation package to use Scilab toolboxes

In this case you need to connect to Scilab using ''sci_connect'' function. Transfer function arguments to Scilab workspace with ''sci_setvar'' function. After that you can execute any of Scilab function from Octave with ''sci_cmd''. And when you need to return results from Scilab you have to use ''sci_getvar''. For example, you want to generate key for BlowFish chiper using Scilab Cryptography Toolbox from your Octave script. First of all, you should know, that any call of ''sci_setvar'', ''sci_getvar'' or ''sci_sim'' command will change Scilab current folder to the same you use in Octave, but ''sci_cmd'' won't. That means, if you use only sci_cmd function, you should change Scilab current folder, before running any scripts. It can be done directly from Octave by transferring any variable to Scilab using ''sci_setvar'' or with command 

''sci_cmd(['cd ' pwd]);''

After current folder in Scilab and Octave are synchronized you can generate the key by Octave command:

''sci_cmd('keyGen_blowfish("sampleKey", "sampleIV", "samplePublicKey", "samplePrivateKey");');''

As with Octave, Scilab is initially distributed without any toolboxes. That means, before using Scilab Cryptography Toolbox or any other toolbox for Scilab you need to install it with ATOMS manager.

== How to Run and Change an Xcos diagram ==

1) After installing Scilab and and the sci_cosim package and getting the Toolbox Backdoor for Scilab to work, then you can try this help section.

2) Download examples from the GitHub
https://github.com/amromanov/sci_cosim/raw/master/demo.tar.gz

3) Click in the sci_pid_model.zcos file to start Scilab and Xcos You should see a diagram of the control system.

4) Open the sci_pid_example.m file in your octave editor.

5) Run the sci_pid_example.m file 

You should see a plot that has the output of the plant  with no feedback, and the output of the plant in the feedback loop and the control action signal that has been clipped at 5 volts.

6) You can then play with the PID parameters in the M file and see how they affect the output.

7) In the loop diagram in Xcos click in the  "SATURATION"(clipper) box and change the clipping to be 10 Volts 

8) Rerun the M file and retune the PID.

9) Now for a little harder problem. Lets change the plant parameters to (s+1)*(s+5)

If you just click on the plant and try and do this, Xcos might complain that it doesn't know what k is, if this happens you have to first go to the Scilab main window and put k=1 there. k will be changed  from your M file later. Now you will be able to change the plant in both locations.

10) In the sci_pid_example.m file set k=5 and run the new system

11) Now lets add a time delay in the feedback part of the loop.

11.1)  Click on the wire that goes from the output of the plant back to an input of the summing junction. This should highlight the line as dashes.

11.2) Press the delete button to delete this wire.

11.3) Select the "view" menu tab at the top of the Xcos diagram.

11.4) Select the "palette browser"

11.5) In the new pop up window select  "Continuous time systems" then scroll down, select and move to the diagram, the "TIME_DELAY" box.

11.6) The input and outputs are on the wrong side, so we will mirror it.

Right click on the box and the select" format" and "Mirror"

11.7) Move the box to a convenient place to rewire it in the feedback loop,

11.8) Now rewire it:

On the left side of the delay box is an output black arrow point, click on this and drag the mouse to the left until you are to the left of the summing junction box.

Now let go of the left button and move the mouse pointer up to the height of the input pin of the summing box.

Click the left button  to place a corner in the wire.
     
Now move to the input pin until you get a green box around the input pin.
     
Click the left mouse button again to make the connection.

11.9) We now have to join a wire to an existing wire.

Place the mouse pointer on the wire from the output of the plant.

The wire should be highlighted but not selected.

Hold the left mouse button down and start drawing a wire.

Join it to the input of the delay

12)    Double click on the delay box and change the delay to be .1 seconds.

13)    Save your new model with a new name.

14)    In the M file change the line:
            sci_sim('sci_pid_model.zcos');     %Running xcos simulation
       to
            sci_sim('newname.zcos');           %Running xcos simulation

15) Rerun the M file and have fun tuning the PID.

== Author and Licensing ==
Author: Romanov Alexey (romanov at mirea.ru)

Moscow, Control Problems Department MIREA, 2015

Distributed under the New BSD License