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 =gp u x =gp u x =gnu x =gnu x =0 x =0

Lhi x 0 x = Lhi , u 0 0 x Llo x = Llo , u0 x Lhi ,u 0 x Llo ,u 0

C*D

where u, gp and gn 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 gp, gn 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 s0 F x G #hi, s1 F x G #lo and s2 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 =* mode =2 mode= mode =, x Lhi 0 x Lhi Llo x 0 x Llo

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 $3 $4 $ $$ $' $( $) '* '1 '2 '3 '4 ' '$ '' '( ') (* (1 (2 (3 (4 ( ($ (' (( () )* )1

// compute the outputs of the block if -9 &: 8hi DD 9 %: 8lo/ +gain : *A else if -9 & */ +gain : gainpA else +gain : gainnA out : 9A breakA case )B // compute =ero crossing surfaces and set modes surf* : 9 - 8hiA surf1 : 9A surf2 : 9 - 8loA if -get#phase#simulation-/ :: 1/ @ if -surf* &: */ mode* : mode#>h=lA else if -surf2 %: */ mode* : mode#h=l>A else if -surf1 & */ mode* : mode#h>=lA else mode* : mode#h=>lA E breakA

%.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, Get tate Cline 2 D, Get!er tate 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)o ing the Compiler and *in er

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 runtime 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

$ ' ( ) 1* 11 12 13 14 1 1$ 1' 1( 1) 2* 21 22 23 24 2 2$ 2' 2( 2) 3* 31 32 33 34 3 3$ 3' 3( 3) 4* 41 42 43 44 4 4$ 4' 4( 4) * 1 2 3 4 $ ' ( ) $* $1 $2 $3 $4 $ $$ $' $( $) '* '1 '2 '3 '4

//disp-Hob/ select Hob case FplotF then standard#draw-arg1/ case FgetinputsF then 4>.G.tGp5 : standard#inputs-arg1/ //disp-sci2e>p->// case FgetoutputsF then 4>.G.tGp5 : standard#outputs-arg1/ //disp-sci2e>p->// case FgetoriginF then 4>.G5 : standard#origin-arg1/ //disp-sci2e>p->// case FsetF then //message-sci2e>p-arg1// > : arg1 graphics : arg1.graphics e>prs : graphics.e>prs model : arg1.model while It do 4ok.8hi.8lo.9initial.e>prs5 : getvalue-FSet funnG integrator parametersF... 4Fhigh limitFAFlow limitFAF9initialF5... list-FvecF.1.FvecF.1.FvecF.1/... e>prs/ if Jok then break.end model.state : 49initial5 model.rpar : 48hiA8lo5 graphics.e>prs : e>prs >.graphics : graphics >.model : model break end case FdefineF then //message-Fin defineF/ 8hi : 1.* 8lo : -1.* 9initial : * model : scicos#model-/ model.sim : list-Flim#intF.4/ model.in : 41A1A15 model.out : 41A15 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 e>prs : 4string-48hiA8loA9initial5/5 gr#i : 4F>:orig-1/.G:orig-2/.w:s=-1/.h:s=-2/FA 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 > : standard#define-44 25.model.e>prs.gr#i/ end

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;block D 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

end

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"

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-