pelican: pedestian controlled crossing example

8/13/2019 PELICAN: PEdestian CONtrolled Crossing Example

1/17

QP state machine framework example

Application NotePEdestrian LIghtCONtrolled (PELICAN)Crossing Example

oc!ment "e#ision $e%r!ar& '

Copyright Quantum Leaps, LLC

www.quantum-leaps.com

www.state-machine.com
http://www.quantum-leaps.com/http://www.state-machine.com/http://www.quantum-leaps.com/http://www.state-machine.com/


2/17

i

*a%le of Contents

Introd!ction +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++++ ++++ ' "e,!irements ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

- esign -3.1 Step 1: Sequence Diagrams ...................................................................................................................... 33. Step : Signals, !"ents, an# $cti"e %&'ects ......................................................................................... ..... (3.3 Step 3: Designing State )achines o* $cti"e %&'ects .................................................................................. +3.( Step (: nitialiing the Q $pplication /main/00 ........................................................................................... 3.+ Step +: mplementing $cti"e %&'ects .......................................................................................................... 12

. "eferences ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ .

/ Contact Information +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++ /

Copyright Quantum Leaps, LLC. $ll ights eser"e#.


3/17

o* /

Introd!ction4his $pplication 5ote #escri&es the !#estrian Lght C%5trolle# /!LC$50 crossing as an e6ampleapplication *or the Q state machine *ramewor7. 4he !LC$5 crossing e6ample #emonstrates a non-tri"ial hierarchical state machine. 4his $pplication 5ote #escri&es step-&y-step how to #esign an#implemente# o* !LC$5 with Q-nano.

NO*E04his $pplication 5ote assumes the Q-nano *ramewor7 an# uses e6ample co#e in C to e6plainimplementation #etails. 8owe"er, the #esign part o* the #iscussion applies equally to Q9C an# Q9C*ramewor7 types.

' "e,!irements;irst, your always nee# to un#erstan# what your application is suppose# to accomplish. n the case o* asimple application, the requirements are con"eye# through the pro&lem speci*ication, which *or the!LC$5 crossing /see ;igure 10 is as *ollows.

$ig!re PEdestrian LIght CONtrolled (PELICAN) Crossing+



4/17

' o* /

$pplication 5ote:!lican Lght C%5trolle# Crossing !6ample


4he !LC$5 crossing starts with cars ena&le# /green light *or cars0 an# pe#estrians #isa&le# /al7? signal *or pe#estrians0. 4o acti"ate the tra**ic light change, a pe#estrian must push the &utton at thecrossing, which generates the PEDS_WAITINGe"ent. n response, the cars get the yellow light, whicha*ter a *ew secon#s changes to re# light. 5e6t, pe#estrians get the al7? signal, which shortly therea*terchanges to the *lashing al7? signal. >hen the al7? signal stops *lashing, cars get the

green light again. $*ter this cycle, the tra**ic lights #on=t respon# to the PEDS_WAITING&utton pressimme#iately, although the &utton


5/17

- o* /



- esign

-+ 1tep 0 1e,!ence iagrams

$ goo# starting point in #esigning any e"ent-#ri"en system is to #raw sequence #iagrams *or the mainscenarios /main use cases0 i#enti*ie# *rom the pro&lem speci*ication. 4o #raw such #iagrams, you nee# to&rea7 up your pro&lem into acti"e o&'ects with the main goal o* minimiing the coupling among acti"eo&'ects. @ou see7 a partitioning o* the pro&lem that a"oi#s resource sharing an# requires minimalcommunication in terms o* num&er an# sie o* e6change# e"ents.

4he sequence #iagram in;igure shows two most representati"e scenarios o* the !LC$5 crossingoperation. n panel /a0, you see the scenario in which the initial minimal green light *or cars elapseswithout the pe#estrian generating the PEDS_WAITINGe"ent. n panel /&0 you see the situation where thepe#estrian generates the PEDS_WAITINGe"ent #uring the minimal green light *or cars. 4he e6planationsection imme#iately *ollowing ;igure highlights the most interesting points.

$ig!re ' 1e,!ence diagrams of the PELICAN application+ PE123AI*IN4 e#ent after the minim!mgreen light for cars (a)5 and PE123AI*IN4 e#ent d!ring the minim!m green light for cars (%)+

http://www.state-machine.com/http://www.state-machine.com/


6/17

. o* /



/20 4he Q in*rastructure initialies all acti"e o&'ects /state machines0 in the system. 4he !LC$5 statemachine starts in the


7/17

/ o* /



!i"n#e" pelican_$ !#e"ine pelican_$

%&' en(m PelicanSi)nals *%+' PEDS_WAITING_SIG , -_.SE/_SIG 122_SIG 1N_SIG 34

5 acti7e o9ects ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5%;' exten st(ct PelicanTa) A1_Pelican4%=' exten st(ct Pe#Ta) A1_Pe#4

%' 7oi# Pelican_cto%7oi#'4%6' 7oi# Pe#_cto%7oi#'4

!en#i" 5 pelican_$ 5

Listing 1ignals and acti#e o%6ects in the PELCAN application (filepelican.h)

/10 $ll signals are #e*ine# in one enumeration, which automatically guarantees the uniqueness o* signals.

/0 5ote that the user signals must start with the o**set -_.SE/_SIGto a"oi# o"erlapping the reser"e# Qsignals.

/3-(0 $ll acti"e o&'ect instances in the system are #eclare# as e6tern "aria&les. 4hese #eclarations arenecessary *or the initialiation o* the -2_acti7e?@array /see upcoming section a&out the main%'*unction an# Q initialiation0.

NO*E04he acti"e o&'ect structures /e.g., st(ct PelicanTa)0 #o not nee# to &e #e*ine# glo&ally in

the application hea#er *ile. nitialiation o* the Q /#iscusse# later0 nee#s only pointers to the acti"eo&'ects, which the compiler can resol"e without 7nowing the *ull #e*inition o* the acti"e o&'ect structure.

@ou shoul# a"oi# #eclaring acti"e o&'ect structures glo&ally. nstea#, you can #eclare the acti"e o&'ectstructures in the *ile scope o* the speci*ic acti"e o&'ect mo#ule /e.g., st(ct PelicanTa)is #eclare# inthe pelican:c*ile scope0. 4hat way, you can &e sure that each acti"e o&'ect remains *ully encapsulate#.

/+-0 !"ery acti"e o&'ect in the system must pro"i#e a


8/17

8 o* /



-+-+ PELICAN state machine

;igure 3shows the complete !LC$5 crossing state machine. 4he e6planation section *ollowing the#iagram #escri&es how it wor7s.

$ig!re - *he PELICAN state machine+


operational

entry 9 C$3SG3!DH .!DSGD%54G>$LB

o**line

entry 9

e6it 9

cars!na&le#

e6it 9

pe#s!na&le#

e6it 9

carsAreen

entry 9 C$3SGA3!!5

e6it 9

cars@ellow

entry 9 C$3SG@!LL%>

e6it 9

pe#s>al7

entry 9 .!DSG>$LB

e6it 9

pe#s;lash

entry 9

e6it 9

carsAreen5o.e#

entry 9

carsAreennt

entry 9

carsAreen.e#>ait

entry 9

%;;

4!3)5$4! 9

.!DSG>$45A

QG4)!%F4

.!DSG>$45A

QG4)!%F4

QG4)!%F4

QG4)!%F4

I/me-J*lashCtr K 1F0 2FM 9

NS.Gsignal.e#s/.!DSGD%54G>$LB0H

IelseM 9

NS.Gsignal.e#s/.!DSGNL$5B0H

Ime-J*lashCtr O 2FM 9

--me-J*lashCtrHIelseM

QG4)!%F4

I/me-J*lashCtr K 1F0 2FM 9

C$3SG3!DH .!DSGD%54G>$LBH

IelseM 9 C$3SGNL$5BH .!DSGNL$5BH

QG4)!%F4 9

Q$cti"eGarm/Kme-Jsuper,

%5

4!3)5$4! 9

1

3

(

+

E

12

11

1

13

1(

1+

1

1


9/17

9 o* /



/10 Fpon the initial transition, the !LC$5 state machine enters the hen it=s o##, the al7?signal is turne# o**. !ither way the counter is always #ecremente#.



10/17

: o* /



/1(0;inally, when the meB>pe#2las$Ctcounter reaches ero, the -_TIE1.Te"ent triggers the transitionto the $45A e"ent, as well as a switch to generate the %59%;; e"ents. Nut many #e"elopment&oar#s ha"e no push-&uttons or any other way to pro"i#e e6ternal inputs. ;or such &oar#s, you nee# tosim!latethe pe#estrian9operator in a separate state machine. 4his is actually a goo# opportunity to

#emonstrate how to incorporate a secon# state machine /acti"e o&'ect0 into the application.4he e#estrian acti"e o&'ect is "ery simple. t perio#ically posts the !DG>$45A e"ent to the!LC$5 acti"e o&'ect an# *rom time to time it turns the crossing o**line &y posting the %;; e"ent*ollowe# &y the %;; e"ent. $s an e6ercise, you shoul# #raw the state #iagram o* the e#estrian statemachine *rom the source co#e *oun# in the *ile \qpn\examples\msp=;0\ia\pelicanBe=;0\pe#:c, *oun# in the Stan#ar# Distri&ution o* Q. lease note that such


11/17

< o* /



5 -2_acti7e?@ aaH #e"ines all acti7e o9ect contol locs BBBBBBBBBBBBBB5%6' -Acti7eCF const -_/1 -_/1_A/ -2_acti7e?@ , *%J' * %-Acti7e '0 %-E7ent '0 0 3%8' * %-Acti7e 'KA1_Pelican l_pelican-(e(e -_DI%l_pelican-(e(e' 3%L' * %-Acti7e 'KA1_Pe# l_pe#-(e(e -_DI%l_pe#-(e(e' 3 34

5 mae s(e t$at t$e -2_acti7e?@ aaH matc$es -2_AM_ACTIE in qpn_pot:$ 5%&0' -_ASSE/T_C1PIE%-2_AM_ACTIE ,, -_DI%-2_acti7e' B &'4

5::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5 7oi# main %7oi#' *%&&' Pelican_cto%'4 5 instantiate t$e Pelican A1 5%&+' Pe#_cto%'4 5 instantiate t$e Pe# A1 5

%&;' FSP_init%'4 5 initialiOe t$e oa# 5

%&=' -2_(n%'4 5 tans"e contol to -2 5

3

Listing ' *he filemain.cof the PELICAN crossing application+

/10 !"ery application C-*ile that uses Q must inclu#e the qpn_pot:$hea#er *ile. 4his hea#er *ilecontains the speci*ic a#aptation o* Q to the gi"en processor an# compiler, which is calle# a port.4he Q port is typically locate# in the application #irectory.

/0 4he sp:$hea#er *ile contains the inter*ace to the Noar# Support ac7age an# is locate# in theapplication #irectory.

/30 4he pelican:$hea#er *ile contains the #eclarations o* e"ents an# other *acilities share# among thecomponents o* the !LC$5 application. 4his hea#er *ile is locate# in the application #irectory.

/(-+0 4he application must pro"i#e storage *or the e"ent queues o* all acti"e o&'ects use# in theapplication. n Q the storage is pro"i#e# at compile time through the statically allocate# arrays o*e"ents. !"ents are represente# as instances o* the -E7entstructure #eclare# in the\incl(#e\qepn:$hea#er *ile, inclu#e# *rom qpn_pot:$. !ach e"ent queue o* an acti"e o&'ectcan ha"e a #i**erent length an# you nee# to #eci#e this length &ase# on your 7nowle#ge o* theapplication.

/0 !"ery Q application must pro"i#e the constant array -2_acti7e?@, which #e*ines all acti"e o&'ectcontrol &loc7s in the application. 4he control &loc7 -Acti7eCFstructure groups together: /10 thepointer to the correspon#ing acti"e o&'ect instance, /0 the pointer to the e"ent queue &u**er o* theacti"e o&'ect, an# /30 the length o* the queue &u**er.

Q uses e"ery opportunity to place #ata in %) rather than in the precious $). 4he -Acti7eCF

structure contains #ata elements 7nown at compile time, so that these elements can &e place# in %),as oppose# to placing them in the acti"e o&'ect structure /$)0. 4hat way, you can sa"e anywhere *rom12 to 2 &ytes o* $), #epen#ing on the num&er o* acti"e o&'ects an# the pointer sie o* the target CF.

4he -_/1macro is necessary on some CF architecture to en*orce placement o* constant o&'ects, suchas the -2_acti7e?@array, in %). %n 8ar"ar# architecture CFs /such as 2+1 or $P0, the co#e an##ata spaces are separate an# are accesse# through #i**erent CF instructions. 4he const 7eywor# is notsu**icient to place #ata in %), an# "arious compilers o*ten pro"i#e speci*ic e6ten#e# 7eywor#s to#esignate the co#e space *or placing constant #ata, such as the


12/17

o* /



4he -_/1_A/macro #e*ines the compiler-speci*ic #irecti"e *or accessing a constant o&'ect in %).)any compilers *or -&it )CFs pro"i#e #i**erent sie pointers *or accessing o&'ects in "arious memories.Constant o&'ects allocate# in %) o*ten man#ate the use o* speci*ic-sie pointers /e.g., *ar pointers0 toget access to %) o&'ects. 4he macro -_/1_A/speci*ies the 7in# o* the pointer to &e use# to accessthe %) o&'ects. $n e6ample o* "ali# -_/1_A/macro #e*inition is: __"a/;reescale 8C/S02

compiler0.

/0 4he *irst entry /-2_acti7e?0@0 correspon#s to acti"e o&'ect priority o* ero, which is reser"e# *or thei#le tas7 an# cannot &e use# *or any acti"e o&'ect.

/-E0 4he -2_acti7e?@entries starting *rom in#e6 one #e*ine the acti"e o&'ect control &loc7s in theor#er o* their relati"e priorities. 4he ma6imum num&er o* acti"e o&'ects in Q cannot e6cee# .

NO*E04he or#er or the acti"e o&'ect control &loc7s in the -2_acti7e?@array #e*ines the priorities o*acti"e o&'ects. 4his is the only place in the co#e where you assign acti"e o&'ect priorities.

/1204his compile-time assertion /see Chapter in ISiCCM0 ensures that the #imension o* the

-2_acti7e?@array matches the num&er o* acti"e o&'ects -2_AM_ACTIE#e*ine# in the qpn_pot:$hea#er *ile.

n Q, -2_AM_ACTIE#enotes the e6act num&er o* acti"e o&'ects use# in the application. 4he macro-2_AM_ACTIEmust &e #e*ine# in qpn_pot:$hea#er *ile, &ecause Q uses the macro to optimie theinternal algorithms &ase# on the num&er o* acti"e o&'ects. 4he compile-time assertion in line /120 ma7essure that the con*igure# num&er o* acti"e o&'ects in#ee# matches e6actly the num&er o* acti"e o&'ectcontrol &loc7s #e*ine# in the -2_acti7e?@array.

NO*E0$ll acti"e o&'ects in Q-nano must &e #e*ine# at compile time. 4his means that all acti"e o&'ectse6ist *rom the &eginning an# cannot &e starte# /or stoppe#0 later, as it is possi&le in the *ull-"ersion Q.

/11-10 4he main%'*unction must *irst e6plicitly calls all acti"e o&'ect constructors.

/1304he &oar# support pac7age /NS0 is initialie#.

/1(0$t this point, you ha"e initialie# all components an# ha"e pro"i#e# to the Q *ramewor7 all thein*ormation it nee#s to manage your application. 4he last thing you must #o is to call the *unction-2_(n%'to pass the control to the Q *ramewor7.

%"erall, the application startup is much simpler in Q than in *ull-"ersion Q. 5either e"ent pools, norpu&lish-su&scri&e lists are supporte#, so you #on=t nee# to initialie them. @ou also #on=t start acti"eo&'ects e6plicitly. 4he Q *ramewor7 starts all acti"e o&'ects #e*ine# in the -2_acti7e?@arrayautomatically 'ust a*ter it gets control in -2_(n%'.

-+/ 1tep /0 Implementing Acti#e O%6ects

mplementing acti"e o&'ects with Q is "ery similar to the *ull-"ersion Q. @ou #eri"e the concrete acti"eo&'ect structures *rom the -Acti7e&ase structure pro"i#e# in Q. @our main 'o& is to ela&orate the statemachines o* the acti"e o&'ects, which is also "ery similar as in the *ull-"ersion Q. 4he only important#i**erence is that state han#ler *unctions in Q #o not ta7e the e"ent pointer as the secon# argument. n*act, Q state han#lers ta7e only one argumentthe


13/17

o* /



Listing 3shows the implementation o* the Pelicanacti"e o&'ect *rom the !LC$5 crossing application,which illustrates all aspects o* implementing acti"e o&'ects with Q. lease correlate this implementationwith the !LC$5 state #iagram in ;igure 3.

!incl(#e qpn_pot:$

!incl(#e sp:$ !incl(#e pelican:$

5 Pelican class BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB5%&' tHpe#e" st(ct PelicanTa) *%+' QActive super4 5 #ei7e# "om -Acti7e 5 (int8_t "las$Ct4 5 pe#estian "las$ co(nte 5 3 Pelican4

%;' static -State Pelican_initial %Pelican me'4%=' static -State Pelican_o""line %Pelican me'4 static -State Pelican_opeational %Pelican me'4 static -State Pelican_casEnale# %Pelican me'4

static -State Pelican_casGeen %Pelican me'4 static -State Pelican_casGeenNoPe# %Pelican me'4 static -State Pelican_casGeenPe#Wait%Pelican me'4 static -State Pelican_casGeenInt %Pelican me'4 static -State Pelican_casellow %Pelican me'4 static -State Pelican_pe#sEnale# %Pelican me'4 static -State Pelican_pe#sWal %Pelican me'4 static -State Pelican_pe#s2las$ %Pelican me'4

en(m PelicanTimeo(ts * 5 7aio(s timeo(ts in tics 5 CA/S_G/EEN_IN_T1.T , FSP_TICQS_PE/_SEC 8 5 min )een "o cas 5 CA/S_E1W_T1.T , FSP_TICQS_PE/_SEC ; 5 Hellow "o cas 5 PEDS_WAQ_T1.T , FSP_TICQS_PE/_SEC ; 5 walin) time "o pe#s 5 PEDS_2ASR_T1.T , FSP_TICQS_PE/_SEC 5 5 "las$in) timeo(t "o pe#s 5

PEDS_2ASR_N. , + 5 n(me o" "las$es "o pe#s 5 122_2ASR_T1.T , FSP_TICQS_PE/_SEC 5 + 5 "las$in) timeo(t w$en o"" 5 34

5 Gloal o9ects BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB5%' Pelican A1_Pelican4 5 t$e sin)le instance o" t$e Pelican acti7e o9ect 5

5::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5 7oi# Pelican_cto%7oi#' *%6' QActive_ctor((QActive *)&AO_Pelican, (QStateHandler)&Pelican_initial)4 3

5 RS #e"inition BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB5

-State Pelican_initial%Pelican me' *%J' return Q_TA!(&Pelican_operational)" 3 5::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5 -State Pelican_opeational%Pelican me' *%8' switc$ %Q_S#$(me)' * case -_ENT/_SIG * FSP_si)nalCas%CA/S_/ED'4 FSP_si)nalPe#s%PEDS_D1NT_WAQ'4%L' return Q_HA!%'%()4 3 case -_INIT_SIG *



14/17

' o* /



return Q_TA!(&Pelican_cars'naled)4 3 case 122_SIG * return Q_TA!(&Pelican_oline)4 3 3%&0' return Q_SP'(&QHsm_top)4 3 5::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5 -State Pelican_casEnale#%Pelican me' * switc$ %-_SIG%me'' * case -_EMIT_SIG * FSP_si)nalCas%CA/S_/ED'4 return Q_HA!%'%()4 3 case -_INIT_SIG * return Q_TA!(&Pelican_cars$reen)4 3 3

return Q_SP'(&Pelican_operational)4 3 5::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::5 -State Pelican_casGeen%Pelican me' * switc$ %-_SIG%me'' * case -_ENT/_SIG *%&&' QActive_arm((QActive *)me, +AS_$''!_#!_TOT)" FSP_si)nalCas%CA/S_G/EEN'4 return Q_HA!%'%()4 3 case -_INIT_SIG * return Q_TA!(&Pelican_cars$reen!oPed)4 3 3 return Q_SP'(&Pelican_cars'naled)4 3 : : : 5 ot$e state $an#les ::: 5

Listing - *he PELICAN acti#e o%6ect definition (filepelican.c)+ =oldface indicates QP facilities+

/10 4his structure #e*ines the .elicanacti"e o&'ect.

/0 4he .elicanacti"e o&'ect structure #eri"es *rom the *ramewor7 structure -Acti7e, as #escri&e# in thesi#e&ar


15/17

- o* /



NO*E0Q assumes that all glo&al or static "aria&les without e6plicit initialiation "alue are initialie# toero upon the system startup, which is a requirement o* the $5S-C stan#ar#. @ou shoul# ma7e surethat your startup co#e clears the :FSSsection &e*ore calling main%'.

/0 $s always, the #eri"e# structure is responsi&le *or initialiing the part inherite# *rom the &ase struc-ture. 4he


16/17

. o* /



. "eferences

oc!ment Location

ISiCCM


17/17

/ o* /



/ Contact Information

Q!ant!m Leaps5 LLC123 Co&&le i#ge Dri"eChapel 8ill, 5C +1FS$1 (+2 L!$ /toll *ree, FS$ only01 E1E E-EE /;$U0e-mail: in*oVquantum-leaps.com>!N : http:99www.quantum-leaps.com http:99www.state-machine.com

pelican: pedestian controlled crossing example

Documents