|Name||Modified||Size||Downloads / Week||Status|
|Totals: 15 Items||33.9 MB||27|
OpenRTDynamics v1.00-svn -- Open Real-Time Dynamics - A framework for implementing real-time controllers and signal processing algorithms.
Version of this document: 28.6.2014
The Real-Time Dynamics Framework is a novel approach to the implementation of block- / signal-based schematics, commonly used in control engineering and signal processing, for real-time usage (like Real-Time Workshop® or Scicos Code Generation). This framework is suitable for time discrete signal processing algorithms, using the same principles like in Scicos/Xcos or Simulink. However, schematics are described by combining special Scilab functions provided by the framework.
In contrast to Xcos or Simulink, the framework does not require source code generation / compilation steps to create rt-programs and therefore does not rely on C-compilers for the target system that had to be installed on the development computer. Instead an efficient to online-interprete binary representation is assembled by the framework-provided Scilab functions and executed by the libortd real-time interpreter.
Due to the description using Scilab, well structured code can be achieved, whereby i.e. a filter design could be placed nearby the implementation for a better human-readability. Additionally, functional and object orientated design schemes can be realised. The latter feature enables the possibility to implement reusable parametrised sub-schematics that may also change in its structure based on parameters.
Further, along with the remote control interface and the ability to implement state machines, to run different simulations in threads (e.g. to distribute calculations across multiple CPUs) and to include Scilab-Code as computational functions (S-function like), ORTD is also ideally suited for laboratory automation. The ability to replace sub-schematics with new implementations and parameters during runtime removes the effort of restarting the main real-time program. Simulations running in threads can also be synchronised to sensor updates or other events e.g. variable timers.
Please Note: OpenRTDynamics does not depend on any part of Scicos/Xcos. ORTD uses algorithms for time-deterministic interpretation of simulations. Only the Scilab Scripting language is required for describing the schematics and only during development. During runtime, no more than standard C/C++ libraries are required, therefore ORTD is very uncomplicated to install and maintain, even on other platforms. The need for difficult and cryptic instructions for the installation of this framework was intentionally avoided.
The ORTD runtime library can be easily integrated into other simulation frameworks e.g. Scicos or used within other software by including a shared library.
Rev 495: A new framework for remote control / communication has been integrated called Packet Framework. This renders the old rt_server module obsolete (c.f. Sec. REMOTE CONTROL INTERFACE). Build e.g. web interfaces to your ORTD implementation! The command line option --master_tcpport can (and should) be omitted when calling the command ortd, if rt_server is not used.
Though it is used in some examples, do not use the block "ld_simnest" for running asynchronous simulations any more. These not updated examples may not terminate on Cntrl-C properly. Use ld_async_simulation instead.
--- The features that make this framework powerful ---
Nesting simulations (sub-controllers) into each other up to unlimited depth, using state machines (each state is represented by a simulation that is reset when the state is left), or asynchronously running (threaded) sub- simulations. Sub-simulations are included by special blocks that implement a framework for state machines or threads and take functions describing the sub-simulations as their arguments along with their I/O ports. (modules/nested)
Ability to synchronise threaded sub-simulations to external event sources, e.g. timers (modules/synchronisation), incoming network packages or sensor readings...
Online replacement of sub-controllers; Yes, can can exchange wires and blocks during the controller is running (modules/nested)
Communication with Scilab from the simulations (modules/scilab), e.g. for running calibration scripts on previously recorded data
--- Other nice features ---
PART I -- TECHNICAL INFORMATION
PART II -- BACKGROUND INFORMATION
APPENDIX -- GOOD TO KNOW
PART I -- TECHNICAL INFORMATION
On Linux one of the rare APIs that stayed (almost) compatible for more than several year are the ones of libc, pthreads, and the standard C++ - libraries :-) and :-(, as there could be more constant APIs. Since OpenRTDynamics is supposed to also stay functional in the long term future, this framework is only depending these very fundamental libraries. However, the functionally can be enhanced by additional libraries that are automatically detected and used.
Because of these relaxed dependencies, it should not be a big issue to port this framework to other (real-time) OSs.
LGPL, see COPYING / COPYING.LESSER
On the development host: * Linux (Ubuntu is tested) * Scilab 5.3. or above. It will be automatically installed via the graphical installer.
On the executing / real-time target (can also be the development host): * Linux (Ubuntu is tested, rt_preemption is supported but not required) * Nothing more than standard libraries (libc, libpthreads, C++ standard libs, ...) * Optional: An installation of Scilab, libblas, libgsl
For compiling the framework * Standard tools like: bash, gcc, g++, make, perl
Optional libraries * libgsl, libblas (If their corresponding development packages are installed, some additional functionality is gained. They are automatically detected when running make config)
Install some required packets (Ubuntu):
sudo apt-get install zenity g++ make subversion build-essential
Download the latest packet from http://sourceforge.net/projects/openrtdynamics/files/ and run it in your shell (self extractible archieve):
$ sh OpenRTDynamics_source_revXXX.sh
The framework will be unpacked into the current folder and installed automatically. It is a good idea to let the installer install Scilab for you, as the Scilab-Toolbox will be automatically set-up during this process.
The newest version is found in subversion and can be installed by a graphical user interface via pasting
wget openrtdynamics.sf.net/getit.sh -O - | bash
into your Terminal on Linux. You should also install Scilab if you're asked to do so as the ORTD toolbox for Scilab will be automatically installed.
Read section PRINCIPLES FOR DEVELOPING SCHEMATICS to learn the basics of ORTD-coding and have a look at the huge amount of examples.
Consider the files in examples/Template_rtcontrol/ as a starting point for setting up realtime control applications.
The suggested way is to use the automatic installation routine as described on their website. However, if you intent to do the compilation / installation by hand you can go on with the following procedure:
This will compile libortd.so and bin/ortd the generic schematic interpreter. Both files are copied to /usr/local/[bin,lib] respectively.
$ make install_toolbox
will ask you for your Scilab 5 installation directory (where the package from the Scilab Website was extracted) and installs the Scilab toolbox.
The manual way woulf be to link the "ld_toolbox" directory (not only its contents) to your <scilab installation directory>/share/scilab/contrib .
$ make scilabhelp
to generate help files for the Scilab help. (Try e.g. "help ld_gain" in Scilab to test it)
Cleaning up is done via
$ make clean
This should be executed when compiling and updated version from subversion.
make config # Configure the framework, e.g. check for libraries make # Compile make install # Install to /usr/local/[lib,bin] make homeinstall # Install the ortd binary into the home directory ( ~/bin ) make demo # run a demo make package # Create a self extracting and self compiling copy of the framework contained within a shell archieve OpenRTDynamics_source.sh which can be transfered to target platforms e.g. ARM-targets like the Beaglebone, Rasperry Pi, ... The archieve requires a build system on the target system. make scilabhelp # Update the help of the Scilab Toolbox make install_toolbox # Run the installer for the Scilab Toolbox make clean # Clean up, always use this after updating the framework e.g. via svn make cleanBuildFiles # remove all files generated during the build process, but not the resulting binaries make clearconfig # Delete the information gathered during make config. make update # Download the latest version from the subversion repository and complile it
To build a self extracting and self compiling archieve run:
$ bash <ORTDFolder>/AutoBuild/LINUX_source/build.sh this <openrtdynamics-source> <OpenRTDynamics_source>
from outside of the openrtdynamics-source directory or alternatively
$ make package
from within the source tree.
This gives a file called <OpenRTDynamics_source>.sh which inclues a copy of the cleaned up folder <openrtdynamics-source>. This can then be transfered to target systems, where the sources are compiled automatically. Of course a build system is required on the target system.
make update ; make install ; make homeinstall
to get a correct update. Remember to re-compile your plugings, if any.
Testet for Ubuntu 12.04, but should also work for Ångström-Linux.
On Ubuntu you could also install Scilab before:
sudo apt-get install scilab
Then proceed using:
Transfer this file to your BB and place it into a folder in which you would like to install the framework. A subdirectory will be created within this folder.
scp OpenRTDynamics_source_revXXX.sh email@example.com:/home/debian
From inside the chosen folder run: $ sh OpenRTDynamics_source_revXXX.sh; The source code will be automatically extracted and compiled.
In order to develop schematics ,you can prepare them on your PC using Scilab and the installed Toolbox and upload the *.[i,r]par files to your Beaglebone, where they get executed. For this it is suggested to use some file transfer protocol like SFTP to upload files. You can install the ssh-server on your Beaglebone using
$ sudo apt-get install openssh-server .
Then you can connect via Gnome "Connect to server" or whatever you like. For directly storing your whole project on the Beaglebone Filesystem you can also investigate the "~/.gvfs" folder and use it to edit / execute Scilab files directly on your PC, whereby the files are stored on your Beaglebone. By this you would not copy the irpar-files by hand every time. You also need an installation of ORTD on your host for development using Scilab (see above).
An example for accessing the BB hardware, is available in examples/beaglebone. To run it, do on the BB:
$ sh build.sh $ sudo sh run.sh
The LED should now blink randomly.
Hardware can be added via new blocks by the plugin interface or by adding your own module in the modules/ folder or by plugins (shared libraries).
See also section -- DEVELOPING MODULES & BLOCKS -- for an example.
Old information: For an example on plugins, please have a look at examples/plugin_example. For using plugins you need have the Target "Linux" enabled (see TARGET CONFIGURATION above).
The following targets can be choosen in target.conf:
Requires the executables from the NDK (http://developer.android.com/tools/sdk/ndk/index.html):
arm-linux-androideabi-gcc, arm-linux-androideabi-c++, arm-linux-androideabi-g++
Therefore, let the NDK create a toolchain for you and set the environment variables (as described in docs/STANDALONE-TOOLCHAIN.HTML of the NDK's documentation folder)
export PATH=<Path to AndroidArmToolchain>/bin/:$PATH
currently there is only the ortd & ortd_static executable available, which can be run from e.g. an android terminal application. (No nice App for now)
NOTE: at the moment, before compiling through "make" you need to remove the EDF-module as it does not compile for android: rm -rf modules/EDF
A not so recently updated and compiled versions are available from:
Only the static executable can be obtained from:
You can run the binary using an android terminal emulator like e.g. terminalIDE if you copy the executable "ortd_static" to a folder "bin" in the home directory. Also create the links
ln -s ortd_static ortd ln -s ortd_static libdyn_generic_exec
NOTE: The following is a work in progress and does not work for now, because hostnames are not resolved.
When you use the Terminal-App "terminalIDE" you can copy and paste the following lines to install the pre-compiled framework:
## Just install the executable cd mkdir bin cd bin rm -f ortd_static ortd rm -f libdyn_generic_exec_static rm -f libdyn_generic_exec wget http://openrtdynamics.sf.net/download/Android/current/ortd_static.gz gzip -d ortd_static.gz chmod +x ortd_static ln -s ortd_static ortd ln -s ortd_static libdyn_generic_exec ln -s ortd_static libdyn_generic_exec_static ## Install the whole compiled framework including the examples cd wget http://openrtdynamics.sf.net/download/Android/current/OpenRTDynamics_android.tgz tar xfvz OpenRTDynamics_android.tgz rm OpenRTDynamics_android.tgz # # OR simpler # wget http://openrtdynamics.sf.net/getitAndroid.sh -O - | bash
With help of the module "scilab" (modules/scilab) blocks can be implemented using the scilab language (example available in (modules/scilab/demo/ScilabRTTest). For this, Scilab is started as a separate process and interfaced by standard input / output streams.
A built-in path for the Scilab executable is chosen during compilation of the library (i.e. make) as follows:
1) The scilab executable from the Scilab installation that comes along the graphical installation of ORTD is used (configured in the file scilabdir.conf).
2) If there is a command "scilab" in the system this one is used if 1) was not successful.
3) No built-in path for the Scilab binary is included. However, the binary can be specified in the block "ld_scilab*" that includes the Scilab code.
Please Note: The hart module only supports Scilab 4.1.2. For newer Scilab versions the module has to be adapted a bit.
Compile & install the framework using the target "XCOS_RTAI_COMPATIBLE":
echo "XCOS_RTAI_COMPATIBLE" > target.conf make clean; make; make install
Link hart/hart_ortd to the modules/ directory of your HART-Toolbox.
ln -s hart/hart_ortd <hart-dir>/modules
WARNING: Do not make a copy -- otherwise some header files are not found during compilation.
ortd: (the new name of libdyn_generic_exec) executes schematics in real-time (rt_preempt) OR as fast as possible Schematics are getting some dummy in and outputs, but should not be used.
type "ortd --help" for help
ortd_static: The statically linked version of the executable (can be used without installing libraries into the system, runs nearly everywhere)
Have a look at documentation/List_of_Module_Blocks.txt. It is an automatically generated list of available blocks.
In Scilab try "help ld_gain" to get into the help folders for ORTD.
Modules are placed within the modules subdirectory. For now, you will find the following:
There is a template in examples/TemplateModule_V2. An older version is found in modules/template". For very basic block functionality you can also refer to modules/basic_ldblocks
IMPORTANT: Since there is no guarantee for a stable ABI (Application binary interface) you should re-compile any ORTD-plugin after updating ORTD. The API (defined by the ORTD-header files) however is going to stay compatible, so you do not have to change you source code for each new version of ORTD, which probably makes your life easier :-)
Within additional/joystick, there is a separate Python-Script to read out a connected joystick and feed the data directly to ORTD-schematics via the rt_server infrastructure. It can be used for an example to easily integrate other input devices. Only one simple Python-Script is needed for that.
Each block is represented by a call to a scilab function that includes a block or a set of blocks into a simulation:
[sim, u] = ld_play_simple(sim, ev, r=[1,2,3,4,5,4,3,2,1] ); [sim, y] = ld_gain(sim, ev, u, 1.5);
The description of the simulation is stored within the structure "sim". The variables "u" and "y" represent in- and output signals that are used to connect blocks. The prefix "ld_" denotes "lib dynamic", which is the name of the interpreter. The parameter "ev" is due to a design decision in the past that was then never used. It must be set to zero (ev=0) at the moment. In a next major revision this is likely that there will be new block interfaces where this will be removed. In this simple example, during each simulation time step k, the current value u[k]=r[k] is multiplied by 1.5 yielding y[k] = 1.5 * r[k].
It is important to note, that not the scilab commands are executed during runtime. They are only used to describe the blocks and their connections. Functions with the ld_-prefix are typically defined in the scilab_loader.sce files.
The OpenRTDynamics simulator provides a special callback-based API that allows one block in a simulation running in a thread to trigger simulation steps. This is used by some special blocks to trigger a simulation step of the simulation containing such a block. They are used to synchronise the simulation when e.g. an event occurs, e.g. when a network packet arrives, a certain amount of time has passed or the thread was signaled by another one or new sensor data is available (and more). Some of these blocks are:
Such blocks must be placed into simulations that are running in threads started by "ld_async_simulation".
Examples are e.g. given in
An template of the C++ - source code for such a block is given in
examples/TemplateModule_V2/Template_blocks.cpp, class SynchronisingTemplateBlock
Threads are initiated by
ThreadPrioStruct.prio1=ORTD.ORTD_RT_NORMALTASK; // or ORTD.ORTD_RT_NORMALTASK ThreadPrioStruct.prio2=0; // for ORTD.ORTD_RT_REALTIMETASK: 1-99 as described in man sched_setscheduler ThreadPrioStruct.cpu = 1; // -1 means dynamically assign CPU [sim, startcalc] = ld_initimpuls(sim, 0); // triggers your computation only once [sim, outlist, computation_finished] = ld_async_simulation(sim, 0, ... inlist=list(), ... insizes=, outsizes=, ... intypes=, outtypes=, ... nested_fn = Threadfn, ... TriggerSignal=startcalc, name="VisThread", ... ThreadPrioStruct, userdata=list() );
hereby the time-scheduling parameters like the thread's priority or CPU affinity can be configured. The ORTD-Superblock
function [sim, outlist, userdata] = Threadfn(sim, inlist, userdata) // This sub-simulation will run in a thread // wait for event [sim, signal ] = ld_RecvNotifications(sim, 0, ObjectIdentifyer="signal"); [sim, signal___] = ld_Int32ToFloat(sim, ev, signal ); // signal must be catched, otherwise ld_RecvNotifications will be optimised out [sim, R] = ld_read_global_memory(sim, ev, index=readI, ident_str="RotMat", datatype=ORTD.DATATYPE_FLOAT, ElementsToRead=9); [sim] = ld_printf(sim, ev, R, "R = ", 9); // output of schematic outlist = list(); endfunction
will then run in thread and the simulation is synchronised using ld_RecvNotifications to the occurrences of events sent to this thread (c.f. section "Blocks that synchronise simulations").
Type "make demo" in the main folder.
Examples can be found within the "examples" subdirectory.
FIXME: Update this
For a ready to run example go into the examples directory via shell and type:
$ sh sh_runoscillator
A second try could be to execute "simple_demo.sce" within scilab 5 or above. It will create *.[i,r]par files containing the schematic. Ensure that you loaded the "ld_toolbox" at first. Then run the command
$ ortd -s simple_demo -i 901 -l 100
within the "examples" directory. It will load the [i,r]par files, compile the schematic and start execution. This example will create several “.dat” output files.
You can also use simple_demo.sce as a template.
ORTD.DATATYPE_BINARY (Scilab), DATATYPE_BINARY (C) is "char" (8 Bit)
more to come ...
Nevertheless the majority of the available blocks only support DATATYPE_FLOAT by now. Especially the ld_statemachine block does not support datatypes other than DATATYPE_FLOAT. A block ld_statemachine2 is about to come...
For data conversion the following blocks are available up to now:
Simple datatypes: ld_roundInt32, ld_ceilInt32, ld_floorInt32, ld_Int32ToFloat Structures: ld_DisassembleData, ld_ConcateData
1) Please note that there are serveral blocks that call I/O operations of the OS. Among theses are ld_printf, ld_ReadAsciiFile, ld_UDPSocket_SendTo and many others. Such blocks can potentially disturbe the real-time execution by introducing unpredictable delays. If low jitter is allowed, you may consider using such blocks in separate simulations running in separated thread that communicate to the hard real-time simulation using rinfbuffers (ld_ringbuf) or shared memory (ld_global_memory). However, the blocks ld_savefile and ld_file_save_machine are suitable for running in real-time simulations to save data to disk, because they internally use a ringbuffer to communicate to a separated thread for calling the OS.
2) The execution time of one simulation step can be measured using ld_clock that reads the clock of the computer.
3) Apply the proper priorities to the threads. It is suggested to start with the template examples/Template_rtcontrol.
B) RECOMMENDED: A new (UDP-based) framework is available (Packet framework). An example that visualises data using a web-browser is available at https://github.com/christianausb/OpenRTDynamics/tree/master/Examples/nodejs_webinterface_Level2 or examples/PacketFramework
An example for a webinterface:
modules/basic_ldblocks/[basic_ldblocks.c,basicCppBlocks.cpp]: Most blocks for basic functionality. Could be also be used as templates / examples for block computational functions.
modules/basic_ldblocks/scilab_loader.sce Interfacing functions for most blocks for basic functionality. Could be also be used as templates / examples for block computational functions.
irpar.[c,h]: A small and efficient implementation for storing vectors of data, strings or other objects within a vector of "double" and another containing "int" values.
libdyn.[c,h]: The core simulator implementation, which reads the list of block interconnections, sets up all blocks, determines the order of execution and executes simulation steps.
libdyn_cpp.[cpp,h]: C++ wrapper for libdyn.c
irpar.sci: Scilab interface for irpar.c for encoding data structures that can be read by irpar.c
libdyn.sci: Scilab interface for creating and connecting blocks. The resulting schematic is stored within irpar.c data structures.
libdyn_generic_exec.cpp: Source code for the command "ortd", which runs schematics.
A benchmark to evaluate the real-time capabilities is available in
You could also consider this as an example on how to start multiple threads with different priorities and CPU assignments.
It is suggested to start at the file realtime.c in the main directory of the framework. There are some comment that give the necessary information. If you plan to port ORTD, consider to contact the author for support.
ID range | module -------- | ---------------- 11001 | muparser 14001 | rt_server 15001 | nested 15100 | synchronisation 15200 | scicos_blocks 15300 | ext_process 15400 | piplines 15500 | android 15800 | EDF 22000 | scilab 39001 | udp_blocks 39101 | Visualisation 39201 | Comedi 39301 | I2C 60001 | basic_ldblocks 69001 | matrix
PART II -- BACKGROUND INFORMATION
Since I'm working in the field of biomedical control engineering, my expectations on the reliability & flexibility of the software controlling something that is acting on the human body are very high.
When doing experiments, in clinical environments only limited time is available. Faults in the operation are critical up to some high extend and technical inadequacies like instable software that requires several attempts to fully run can simply not be accepted. It shall be possible to re-calibrate and make individual adaptations to the implementation in the shortest time possible. Therefore, instead of code generation, this framework uses an interpreter (the Scilab description is assembled faster than generating and compiling C-Code). Additionally, new sub-implementations can be designed and loaded on-line while e.g. the data acquisition devices stay up and running.
Also I don't like complicated installation procedures where one has to edit files, adapt directory paths and install numerous other libraries from their sources by hand. ORTD compiles and installs itself automatically from its source files on the individual target system. If there is a library installed that could enable additional functionality for ORTD, it is used. If not installed, ORTD doesn't complain.
If you find a bug in the software or things that you just do not find so nice, it would be very cool if give me a short notice/comment by Email. Even complaints like "I have to type so much commands when doing ..." are TOTALLY welcome. Every time the user of this framework is subjected to an higher programing effort than theoretically necessary, something could be improved! Thus let me know. ORTD is supposed be as smart and relaxed as possible.
APPENDIX -- GOOD TO KNOW
Contributions to this framework are gracefully welcome! Thus if you introduced support for some kind of hardware e.g. GPIO-interfaces from embedded system or missing blocks for the basic functionality, do not hesitate.
Christian Klauer Control Systems Group TU-Berlin, Germany Email: firstname.lastname@example.org Web: http://www.control.tu-berlin.de/User:Christian_Klauer
11.4.11 (v0.99b) - small Bug within ld_const function - a new printf block
v0.99c - Makefile - better dokumentation
v0.99d - Nicer Scilab interface
v0.99e - Modules support - muParser (http://muparser.sourceforge.net/) Block supporting math formula within simulations there is an example within examples/muparser.sce - HART-module (hart.sf.net) for using ORTD in Scicos simulations - remote control interface via TCP to set parameters via a new "ld_parameter" block enable it in libdyn_generic_exec by the --master_tcpport <port> option an example can be found under examples/remote_control.sce - Scicos block for integration of ortd schematics
v0.99f - sync and async nested ortd simulations (Module nested, experimental) - going on with rt_server - Joystick integration via a small Python-Script and the rt_server module
v0.99g (4.11.2011) - Improved rt_server module - Implemented port size checking during schematic generation within Scilab - Fixed bugs in nested and basic_blocks module - libdyn_generic_exec: Now runs also without RT-Preemption (no root access needed); there is now a static version libdyn_generic_exec_static - starting with scilab5/Xcos hart module - Added documentation parser - Some new blocks for vector manipulation
v0.99h ( not release by now ) - A new and nice graphical installer - Bugs: in vector manipulation blocks, ld_muparser_subst (still experimental) - Added new slides in documentation folder - Slightly changed the rt_server protocoll - Fixed a potential memory leak, when set-up of a schematic fails - Manipulation of the Makefile system (Introduced Target Systems) - a new ld_steps block and some other new blocks - a new ld_statemachine block, which enables a comfortable way of setting up a statemachine by use of nested simulations - libdyn.sci: more checks with libdyn_check_obj( ) - Nested schematics can now be exchanged online! (while the controller is running) this is done by loading new [i,r]par - files into the simulation nests - New Flag COMPF_FLAG_PREPARERESET, which comes before blocks are reset - Scicos Block Wrapper (module scicos_blocks) Experimental! - Clock-synchronised threaded simulations - run external processes and terminate them by the end of the simulation (module ext_process) - Global shared object class - Scilab help documentation - Again a fixed to online replaceable schematics. Now it runs smooth. - A nicer interface for Scilab, which looks very much like the Scicos Generic Block or a Matlab S-function. Please note that the state update flag will not be called.
By date as there will only be the svn-version