Tutorial

Creating a C Function Block in Scicos

Phil Schmidt
March 7, 2009
This work is licensed under the Creative Commons Attribution-Share Alike !0 "nited States #icense! To view a co$% o&
this license, visit htt$'((creativecommons!or)(licenses(b%-sa(!0(us( or send a letter to Creative Commons, *7* Second
Street, Suite 00, San +rancisco, Cali&ornia, 9,*0-, "SA!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *
Table of Contents
* /ntroduction!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2 0e&inin) the Model!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2!* 12uations &or The 13am$le 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
2!2 Modes, Sur&aces and 5ero-Crossin)s!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!,
Creatin) the Com$utational +unction!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!,
!* The Code!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-
!2 Commentar% on the Code!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!6
, Com$ilin) and #inkin)!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!7
,!* Startin) Scilab!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!7
,!2 /nvokin) the Com$iler and #inker!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!9
- Testin) the 7ew 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*0
-!* 4lock 0ia)ram!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*0
-!2 4lock Con&i)urations!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!**
-!2!* #e&t8and C#9C:;c 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!**
-!2!2 <i)hthand C#9C:;c 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!**
-!2! =17S><;& 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*2
-!2!, Middle =17;S>< 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*2
-!2!- 4ottom =17;S>< 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*2
-!2!6 CMSC9P1 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*
-!2!7 )eneric;block 4lock!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*,
-! <unnin) the Simulation!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*-
6 Creatin) the /nter&acin) +unction!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*6
6!* The Code!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*6
6!2 Commentar% on the Code!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*?
7 Testin) the /nter&acin) +unction!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*9
? 0ebu))in)!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!2*
?!* +irst Ste$s!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!2*
?!2 Startin) a 0ebu))in) Session!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!2
9 Conclusion!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!2-
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 2
1 Introduction
This document is a tutorial that describes the $rocess o& creatin) a custom Scicos &unction block in
C! Scicos is a )ra$hical d%namic s%stem modelin) tool that is contained within Scilab, a Matlab-like
numerical anal%sis and simulation $acka)e!
/ have created this tutorial &or a cou$le reasons! +irst, this is m% wa% to leave breadcrumbs &or
m%sel&, so that whenever / create m% own &unction blocks, / have an e3am$le to &ollow! Second, /
&ound that the available Scicos documentation is sorel% lackin) in com$lete e3am$les with thorou)h
descri$tions o& the ste$s to take! / s$ent man% hours $orin) over what documentation / could &ind,
$ostin) 2uestions to the Scilab news)rou$, and en)a)in) in $lain trial-and-error, be&ore / was able to
success&ull% build m% own &unction blocks! / ho$e that b% creatin) this tutorial, / can com$ress %our
learnin) curve and hel$ %ou to 2uickl% become $roductive!
<e)ardin) the develo$ment environment, / have used Scicos#ab ,! on "buntu #inu3 to create the
e3am$le $resented in this tutorial! /& %ou are usin) @indows, / canAt sa% whether this stu&& will work
e3actl% the same, thou)h most o& it should!
So, letAs )et startedB
2 Defining the Model
2.1 Equations for The Example Bloc
+or this tutorial, we will create a custom inte)rator block that has constant hi)h and low limits, and
variable )ain! The e2uations o& the block are as &ollows'
x=g
p
u L
hi
x0
x=g
p
u x=L
hi
, u0
x=g
n
u 0xL
lo
x=g
n
u x=L
lo
, u0
x=0 xL
hi
,u0
x=0 xL
lo
,u0
C*D
where u, g
p
and g
n
are in$uts to the block and #
hi
and #
lo
are block $arameters!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e
/n addition to de&inin) the blockAs state, we will also want to de&ine its out$ut! @e will choose the
state variable as one out$ut, and the blockAs current )ain C g
p
, g
n
or EeroD as a second out$ut!
7otice in e2uations C*D the care&ul de&inition o& the discontinuities in the derivative at #
hi
and #
lo
!
This care&ul de&inition is im$ortant &or the numerical inte)rator in Scicos, which needs to know where
the discontinuities are in order to $ro$erl% simulate the s%stem! This leads us to the ne3t section!!!
2.2 Modes! "urfaces and #ero$Crossings
=enerall%, Scicos needs to know where there are discontinuities in the derivatives o& the s%stem in
order to $ro$erl% simulate the s%stem! To de&ine these, Scicos makes use o& modes and sur&aces, which
%ou must de&ine in %our block code, to determine where those discontinuties are and what to do on
either side o& them!
A sur&ace is sim$l% a variable in %our s%stem that has values that cross discontinuities in the s%stem!
Scicos detects that a sur&ace is crossin) a discontinuit% b% detectin) that the sur&ace variable crosses
Eero!
A mode is a variable that holds values re$resentin) each distinct re)ion that e3ist in a sur&ace! So, i&
a sur&ace has a sin)le Eero-crossin), then there would be two mode values to re$resent that the s%stem
is on one or the other side o& the Eero crossin)!
/n the s%stem in e2uations C*D, there are three sur&aces, de&ined as s
0
F x G #
hi
, s
1
F x G #
lo
and s
2
F x,
The three sur&aces there&ore each have a Eero crossin)H one at #
hi
, one at Eero and one at #
lo!
There is a
sin)le mode variable that can have &our discrete values re$resentin) each o& the &our Eero-crossin)
re)ions! @e will make the &ollowin) de&initions &or mode'
mode=* xL
hi
mode=2 0xL
hi
mode= L
lo
x0
mode=, xL
lo
C2D
% Creating the Computational &unction
9nce %ouAve de&ined the e2utions &or the block, %ou are read% to write the C code that im$lements
it! /n the code will be a &unction that Scicos calls to com$ute the behavior o& the block! This is called
the com$utational &unction!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e ,
%.1 The Code
+or our e3am$le block, / will sim$l% $resent the code here, and then comment on ke% $arts o& the
code! So, here is the code, saved in the &ile lim_int_comp.c'
1 // This is the computational function for a Scicos model block.
2 // The model is of a variable-gain integrator with hard high and low limits.
3
4
!include "scicos/scicos#block4.h"
$ !include %math.h&
' !include %stdio.h&
( !include %stdlib.h&
)
1* !define r#+,-n. i/ --0et1eal+n2ort2trs-blk. n31//4-i/5/
11 !define r#67T-n. i/ --0et1eal6ut2ort2trs-blk. n31//4-i/5/
12
13 // parameters
14 !define 8hi -0et1par2trs-blk/4*5/ // integrator high limit
1 !define 8lo -0et1par2trs-blk/415/ // integrator low limit
1$
1' // inputs
1( !define in -r#+,-*.*// // integrator input
1) !define gainp -r#+,-1.*// // integrator gain when 9 & *
2* !define gainn -r#+,-2.*// // integrator gain when 9 %: *
21
22 // states
23 !define 9 -0etState-blk/4*5/ // integrator state
24 !define 9dot -0et;erState-blk/4*5/ // derivative of the integrator output
2
2$ // outputs
2' !define out -r#67T-*. *// // integrator output
2( !define +gain -r#67T-1. *// // integrator gain
2)
3* // other constants
31 !define surf* -0et02trs-blk/4*5/
32 !define surf1 -0et02trs-blk/415/
33 !define surf2 -0et02trs-blk/425/
34 !define mode* -0et<ode2trs-blk/4*5/
3
3$
3' // if 9 is greater than 8hi. then mode is 1
3( // if 9 is between 8hi and =ero. then mode is 2
3) // if 9 is between =ero and 8lo. then mode is 3
4* // if 9 is less than 8lo. then mode is 4
41 !define mode#>h=l 1
42 !define mode#h>=l 2
43 !define mode#h=>l 3
44 !define mode#h=l> 4
4
4$ void lim#int-scicos#block ?blk. int flag/
4' @
4( double gain : *A
4)
* switch -flag/
1 @
2 case *B
3 // compute the derivative of the continuous time state
4 if --mode* :: mode#>h=l CC in % */ DD mode* :: mode#h>=l/
gain : gainpA
$ else if --mode* :: mode#h=l> CC in & */ DD mode* :: mode#h=>l/
' gain : gainnA
( 9dot : gain ? inA
) breakA
$*
$1 case 1B
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e -
$2 // compute the outputs of the block
$3 if -9 &: 8hi DD 9 %: 8lo/
$4 +gain : *A
$ else if -9 & */
$$ +gain : gainpA
$' else
$( +gain : gainnA
$) out : 9A
'* breakA
'1
'2 case )B
'3 // compute =ero crossing surfaces and set modes
'4 surf* : 9 - 8hiA
' surf1 : 9A
'$ surf2 : 9 - 8loA
''
'( if -get#phase#simulation-/ :: 1/
') @
(* if -surf* &: */
(1 mode* : mode#>h=lA
(2 else if -surf2 %: */
(3 mode* : mode#h=l>A
(4 else if -surf1 & */
( mode* : mode#h>=lA
($ else
(' mode* : mode#h=>lA
(( E
() breakA
)* E
)1 E
%.2 Commentar' on the Code
Line 5: 4e sure to Iinclude Jscicos;block,!hK! This header de&ines macros that are used to access data
elements in the scicos_block data structure! The macros used in this e3am$le are GetRealInPortPtrs
Cline *0D, GetRealOutPortPtrs Cline **D, GetRparPtrs Clines *,-*-D, Gettate Cline 2D, Get!ertate
Cline 2,D, GetGPtrs Clines *-D and Get"odePtrs Cline ,D! CMore in&ormation on these and other
macros is available &rom the Scilab online hel$! T%$e help at the Scilab command $rom$t, then )o to
Scicos: Bloc diagram editor and simulator | whatis scicos | C Macros!D
Lines 10- de&ine a bunch o& macros that make it easier to access elements o& the Scicos block data
structure! / &ind it much easier to use names that corres$ond to each o& m% blockAs $arameters, states,
in$uts and out$uts, rather than to be constantl% workin) with anon%mous $ointers and arra% elements!
Lines 10-11 are hel$er macros &or accessin) block in$uts and out$uts!
Lines 1-15 name the u$$er and lower limit o& the inte)rator! The limits are $assed to the block as real
$arameters!
Lines 1!-"0 name the in$uts to the inte)rator block! +or this block, all the in$uts are real-valued
values!
Lines "#-" name the blockAs state and derivative!
Lines "$-"! name the out$uts o& the inte)rator block! +or this block, all the out$uts are real-valued
values!
Lines #1-## name the three sur&aces in the block!
Line # names the sin)le mode variable o& the block!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 6
Lines 1- name the &our mode values that the mode variable ma% hold!
Lines %-&1 is the &unction that im$lements the behavior o& the new block!
Line %' The &unction name, lim_int, will be used later when linkin) the code into Scicos!
Line 5"-5&: @hen &la) is Eero, the Scicos inte)rator is re2uestin) the block to com$ute its derivative!
The derivative e2uation to be used de$ends on the mode, which can be seen in lines -7 and -9!
Com$are the e2uations in this section o& the code to the e2uations )iven in sections 2 and !
Lines %1-$0: @hen &la) is one, the Scicos inte)rator is re2uestin) the block to com$ute its out$uts! As
%ou can see, the mode is not used to determine which )ain value to use as out$ut! / could not &ind
documentation e3$lainin) whether mode should be used, but in all the e3am$le code / looked at, it was
not used, so m% assum$tion is that it should not be used here!
Lines $"-!&: @hen &la) is nine, the Scicos inte)rator is re2uestin) in&ormation about modes and Eero
crossin)s! Sur&ace in&ormation is needed at ever% call, while mode in&ormation is onl% needed durin)
simulation $hase *!
Lines $-$%: The values o& the three sur&aces are assi)ned here!
Line $!: This is the test &or simulation $hase one!
Lines !0-!$: Modes are calculated here based on the $ositions o& the sur&ace values!
4 Compiling and Linking
@ith the C code in hand, %ou are now read% to com$ile and link it into Scilab!
(.1 "tarting "cilab
+irst, run Scilab! Lou will need to have Scilab runnin) in the director% that contains %our source
&ile! The easiest wa% to do that is to Must o$en a terminal in %our workin) director%, and invoke Scilab
&rom there! 9therwise, use the chdir() &unction inside the Scilab console to chan)e to %our workin)
director%!
The screenshots below show how / invoke Scilab &or this tutorial'
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 7
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e ?
(.2 In)oing the Compiler and *iner
9k, so Scilab is runnin) and is in the ri)ht director%! Com$ilin) and linkin) is done sim$l% b%
invokin) the &ollowin) command in Scilab'
ilib#for#link-Flim#intF.Flim#int#comp.oF.45.FcF.F<akelibF.Floader.sceF.FF.FF.F-gF/A
This is kind o& a scar% lookin) command, but itAs $rett% sim$le once %ou break it down Cand note that
%ou can )et hel$ on this command &rom ScilabAs built-in hel$ browser in the #tilities cate)or%D!
The &irst $arameter, Flim#intF, is the name o& the &unction we want linked into Scilab!
The 2nd $arameter, Flim#int#comp.oF, is the name o& the obMect &ile that will be created when
our source code is com$iled!
The rd $arameter, 45, is a list o& e3tra libraries needed &or linkin)! 9ur e3am$le does not need
an%, so an em$t% matri3 is $assed!
The ,th $arameter, FcF, tells Scilab that this is a C &unction Cas o$$osed to a +ortran &unctionD!
Parameters - and 6, F<akelibF and Floader.sceF, are the names o& the make&ile and loader &ile
res$ectivel%! 4oth o& the values / used are also the de&ault values!
Parameters 7 and ? are the libname and ld&la)s! +or this e3am$le, / Must $ass em$t% strin)s,
which also ha$$en to be the de&aults!
+inall%, $arameter ? is a list o& the c&la)s to $ass to the C com$iler! / $ass in a F-gF to make the
com$iler )enerate debu))in) in&ormation! This is absolutel% necessar% i& %our C code has run-
time errors, so that %ou can use )db to debu) it!
@hen %ou run the command, %ou should )et somethin) that looks like the &ollowin) $icture'
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 9
ThatAs itB The C &ile is com$iled and linkedB
+ Testing the ,e- Bloc
7ow that weAve linked the code, it would be nice to run it to tr% it out! @e can do a 2uick-and-dirt%
test usin) the =171</C block in Scicos! Create a new Scicos dia)ram, and &ollow the instructions
below!
+.1 Bloc Diagram
The &ollowin) $icture shows the block dia)ram &or the s%stem! 9$en the Palette Tree and $lace the
necessar% blocks onto the dia)ram and connect them as shown! Lou will need two CL'C()c blocks,
one *+,S-.)/ block, two *+,)S-. blocks, one generic)0lock# block and a CMSC'1+ block!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *0
+.2 Bloc Configurations
+.2.1 *eft.and C*/C01c Bloc
+.2.2 2ighthand C*/C01c Bloc
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e **
+.2.% 3E,"421f Bloc
+.2.( Middle 3E,1"42 Bloc
+.2.+ Bottom 3E,1"42 Bloc
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *2
+.2.5 CM"C/6E Bloc
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *
+.2.7 generic1bloc% Bloc
The con&i)uration &or this block deserves some e3$lanation'
Simulation &unction' This is the name o& the linked C com$utational &unction that
im$lements the block!
+unction t%$e' A C block is t%$e ,!
/n$ut $orts siEes' The block has three *3* CscalarD in$uts!
/n$ut $orts t%$e' The three in$uts are o& t%$e real!
9ut$ut $orts siEes' The block has two *3* CscalarD out$uts!
9ut$ut $orts t%$e' The two out$uts are o& t%$e real!
The block has no in$ut or out$ut events!
The initial condition &or the blckAs state is 0!2-!
There are no discrete states, thus no initial condition!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *,
/nitial obMect state' I ha$e not %igured out &hat this is 'et(
The blockAs $arameters Cu$$er and lower limitD are real $arameters!
There are no inte)er $arameters!
There is one mode variable!
There are three Eero crossin) sur&aces!
The block has direct &eedthrou)h, i!e!, it can &orm $art o& an al)ebraic loo$!
The block is time de$endent, as it has a continuous state!
+.% 2unning the "imulation
7ow that our model is built, we can run it! +irst, set u$ the simulation $arameters &rom the
Simulate N Setu$ menu in the Scicos editor'
Then run the simulation CSimulate N <unD, to )et the &ollowin) $lot'
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *-
And there %ou have it, a custom block written in C!
This is all )reat, but it would be nice to have a customiEed )ra$hical block to )o with the custom
com$utational &unction! The ne3t section shows how to do this!
5 Creating the Interfacing &unction
The inter&acin) &unction is written in Scilab lan)ua)e, and is used to de&ine the a$$earance and
behavior o& the )ra$hical elements o& the block in the Scicos editor! As / did with the com$utational
&unction earlier, / will sim$l% $resent the code, and then $rovide commentar% a&terwards!
5.1 The Code
Save the &ollowin) code into the &ile lim)int)int/2sci!
1 function 4>.G.tGp5 : 8+<+,T-Hob. arg1. arg2/
2
3 > : 45A
4 G : 45A
tGp : 45A
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *6
$
' //disp-Hob/
(
) select Hob
1* case FplotF then
11 standard#draw-arg1/
12
13 case FgetinputsF then
14 4>.G.tGp5 : standard#inputs-arg1/
1 //disp-sci2e>p->//
1$
1' case FgetoutputsF then
1( 4>.G.tGp5 : standard#outputs-arg1/
1) //disp-sci2e>p->//
2*
21 case FgetoriginF then
22 4>.G5 : standard#origin-arg1/
23 //disp-sci2e>p->//
24
2 case FsetF then
2$ //message-sci2e>p-arg1//
2' > : arg1
2( graphics : arg1.graphics
2) e>prs : graphics.e>prs
3* model : arg1.model
31 while It do
32 4ok.8hi.8lo.9initial.e>prs5 : getvalue-FSet funnG integrator parametersF...
33 4Fhigh limitFAFlow limitFAF9initialF5...
34 list-FvecF.1.FvecF.1.FvecF.1/...
3 e>prs/
3$ if Jok then break.end
3' model.state : 49initial5
3( model.rpar : 48hiA8lo5
3) graphics.e>prs : e>prs
4* >.graphics : graphics
41 >.model : model
42 break
43 end
44
4 case FdefineF then
4$ //message-Fin defineF/
4' 8hi : 1.*
4( 8lo : -1.*
4) 9initial : *
* model : scicos#model-/
1 model.sim : list-Flim#intF.4/
2 model.in : 41A1A15
3 model.out : 41A15
4 model.state : 49initial5
model.dstate : 4*5
$ model.rpar : 48hiA8lo5
' model.blocktGpe : FcF
( model.nmode : 1
) model.n=cross : 3
$* model.dep#ut : 4It It5
$1
$2 e>prs : 4string-48hiA8loA9initial5/5
$3 gr#i : 4F>:orig-1/.G:orig-2/.w:s=-1/.h:s=-2/FA
$4 Ft>t:4FFKunnGFFAFF+ntegratorFF5FA
$ F>stringb->3*.2?w. G3*.2*?h. t>t. *.*?w. *.$*?h. FFfillFF/FA
$$ Ft>t:4FFinFFAFFFFAFFgainpFFAFFFFAFFgainnFF5FA
$' F>stringb->3*.*2?w. G3*.*(?h. t>t. *.2?w. *.(*?h. FFfillFF/FA
$( Ft>t:4FFFFAFFoutFFAFFFFAFFgainFFAFFFF5FA
$) F>stringb->3*.'3?w. G3*.*(?h. t>t. *.2?w. *.(*?h. FFfillFF/FA
'* 5
'1 > : standard#define-44 25.model.e>prs.gr#i/
'2
'3 end
'4
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *7
' endfunction
5.2 Commentar' on the Code
4e&ore / be)in with the commentar%, let me $oint out that much o& whatAs in the inter&acin)
&unction / donAt &ull% understand! / have started with known workin) e3am$les and the available
documentation to come u$ with this &unction! 8owever, documentation is slim Cwhich is one reason
/Am writin) this tutorialBD! So, / will e3$lain onl% what / understand!
Line 1: The name o& the &unction, #/M/7T, will be used inside the Scicos editor to access the &unction
block! :ee$ this in mind &or later!
Lines $3 153 1&3 "#3 "%3 %: These are debu))in) lines! /& %ou uncomment them, %ou will be able to see
debu))in) in&ormation in the Scilab console and in dialo) bo3es while %ou construct and run the
model!
Lines 103 1#3 1$3 "1: These cases Must use the JstandardK &unctions that are $rovided with Scilab! =ood
luck &indin) documentation on how these &unctions work Cand i& %ou do &ind it, $lease let me knowBD
Lines "5-#: This case de&ines the behavior o& the dialo) bo3 that a$$ears when %ou double-click the
block! /t uses the )etvalueCD &unction in lines 2-- to dis$la% the dialo) and return the values entered!
The initial condition o& the model state is assi)ned in line 7, while the $arameters, #hi and #lo, are
assi)ned to the model in line ?! All the return values are stored in the structure variable 3 in lines ,0
and ,*!
Lines 5-$1: This case de&ines the a$$earance o& the &unction block and initialiEes all the model
variables when the block is &irst $laced into the Scicos dia)ram!
Lines 50-%0 de&ine the blockAs model $ro$erties! Com$are closel% the assi)nments in lines -*-60 with
the initialiEers in the =171</C C)eneric;blockD block shown earlier'
#ine -* corres$onds to Simulation /unction and Function t45e!
#ine -2 corres$onds to 6n5ut 5orts si7es!
#ine - corres$onds to 'ut5ut 5orts si7es!
#ine -, corres$onds to 6nitial continuous state!
#ine -- corres$onds to 6nitial discrete state! / &ound that this cannot be an em$t% vector, thus /
assi)ned a value Cwhich is unused b% the com$utational &unctionD to make Scilab ha$$%!
#ine -6 corres$onds to .eal 5arameters 8ector!
#ine -? corres$onds to ,um0er o/ modes!
#ine -9 corres$onds to ,um0er o/ 7ero crossings!
#ine 60 corres$onds to 9irect /eedthrough and Time de5endence!
Line %" de&ines the initial values that will be dis$la%ed in the blockAs con&i)uration dialo)!
Lines %#-$0 de&ine the Scilab code that will be e3ecuted to draw the blockAs )ra$hical and te3t
elements! The code must be ca$tured as a list o& strin)s! 4e care&ul about 2uotin)B
Line $1 creates the block, includin) both its )ra$hical and model elements! The siEe o& the block is
s$eci&ied b% the &irst $arameter o& the standard;de&ineCD &unction!
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *?
7 Testing the Interfacing Function
7ow that we have written the inter&acin) &unction, it is a sim$le matter to use it! Assumin) %ou
still have Scicos o$en, activate the Scilab window C&rom the Scicos Tools menuD and enter the
&ollowin) command to create the inter&acin) &unction in Scilab'
e:ec lim)int)int/2sci;
=o back to Scicos b% clickin) the mouse in the Scicos window, o$en the dialo) &rom the +dit |
<dd new 0lock menu, and enter #/M/7T into the dialo)! Then sim$l% $lace the new block into the
dia)ram, and connect it u$! The $icture below shows what this looks like'
8ereAs the con&i)uration dialo) &or the CMSC9P1 block'
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e *9
9nce a)ain, run the model! Lou should )et the &ollowin) $lot'
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 20
As e3$ected, the out$uts o& the two blocks are the same because the% use the same com$utational
&unction! CoolB
8 Debugging
All the above is well and )ood, however, when %ouAre writin) %our own &unctions, it is likel% that
%ou will have errors, and will need to debu) them! / showed in the inter&acin) &unction how to dro$ in
sim$le debu))in) lines, so / wonAt discuss that an% &urther! 8owever, &or C code, s$rinklin) $rint&CD
calls into the code ma% not be su&&icient or ma% not work at all, es$eciall% i& %our Scilab instance is
runnin) as a se$arate $rocess, as stdout ma% not )o to a console! So, %ou will need to use )db! /n this
section, /All )ive %ou a Cver%D hi)h level overview o& the $rocess! And remember, what / describe here
is what / do on m% "buntu s%stem! /t will likel% work the same on most Oni3 s%stems, but is liable not
to work the same on @indows s%stems!
8.1 First teps
/n order to make %our li&e much easier, we will start b% makin) a macro &ile &or )db that will
dis$la% Scicos model values! Create a &ile in %our workin) director% called )db;cmd, and $ut the
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 2*
&ollowin) content into it'
define show+nputs
printf "+nputsB "
set Li : *
while Li % Larg* -& nin
printf "inIi : Ig ". Li. ?-double?/Larg* -& inptr4Li5
set Li : Li 3 1
end
printf "Mn"
end
define show6utputs
printf "6utputsB "
set Li : *
while Li % Larg* -& nout
printf "outIi : Ig ". Li. ?-double?/Larg* -& outptr4Li5
set Li : Li 3 1
end
printf "Mn"
end
define show2arms
printf "r2armsB "
set Li : *
while Li % Larg* -& nrpar
printf "rpIi : Ig ". Li. Larg* -& rpar4Li5
set Li : Li 3 1
end
printf "Mn"
printf "i2armsB "
set Li : *
while Li % Larg* -& nipar
printf "ipIi : Ii ". Li. Larg* -& ipar4Li5
set Li : Li 3 1
end
printf "Mn"
end
define showState
printf "StateB "
set Li : *
while Li % Larg* -& n>
printf ">Ii : Ig ". Li. Larg* -& >4Li5
set Li : Li 3 1
end
printf "Mn"
printf ";erivB "
set Li : *
while Li % Larg* -& n>
printf ">dIi : Ii ". Li. Larg* -& >d4Li5
set Li : Li 3 1
end
printf "Mn"
end
define show<N
printf "=OrossB "
set Li : *
while Li % Larg* -& ng
printf "gIi : Ig ". Li. Larg* -& g4Li5
set Li : Li 3 1
end
printf "Mn"
printf "H1ootB "
set Li : *
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 22
while Li % Larg* -& ng
printf "HIi : Ig ". Li. Larg* -& Hroot4Li5
set Li : Li 3 1
end
printf "Mn"
printf "<odeB "
set Li : *
while Li % Larg* -& nmode
printf "mIi : Ii ". Li. Larg* -& mode4Li5
set Li : Li 3 1
end
printf "Mn"
end
define Show
show+nputs-blk/
show6utputs-blk/
show2arms-blk/
show<N-blk/
showState-blk/
end
define hook-stop
Show
end
break lim#int
continue
Pust a 2uick comment on the scri$t above' 7otice that the ho& &unction $asses the name blk to the
various sho&))) &unctionsH blk is the ver% same blk $arameter in the lim_int*+ C com$utational
&unction!
8.! tarting a Debugging ession
"sin) the e3am$le block we created in this tutorial, &ollow these ste$s to debu) the model'
*! Start Scilab as %ou did earlier! 9nce in Scilab, start Scicos, and load the e3am$le model &ile
lim;int;test!
2! /n the console, enter the command 5s u: | gre5 scile:! Scile3 is the name o& the Scilab
e3ecutable!
! <un )db!
,! Attach )db to the scile3 $rocess!
-! Source the )db;cmd &ile into )db!
6! 7ow )o to Scicos and run the model!
At this $oint, Scicos has been sto$$ed at a break$oint at the com$utational &unction lim;intCD! This
whole interaction will look like the &ollowin) screenshots'
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 2
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 2,
7otice in the above screenshot that the values o& the block data structure elements are dis$la%ed!
The% will a$$ear each time that )db breaks $ro)ram e3ecution!
+rom here, %ou will use the standard )db commands to ins$ect code and ste$ throu)h it! The hel5,
ste5 and continue commands will be ver% use&ul! +or &urther details on )db debu))in), use its online
hel$ or consult the co$ious documentation that is available on the web!
" Conclusion
This concludes this tutorial! / ho$e it has been hel$&ulB
Tutorial: Creating a C Function Block in Scicos
Phil Schmidt, email'$hil&arm.&astmail!&m Pa)e 2-