Elmo Gold Maestro G-MAS User manual



G‐MAS–GoldMaestro
SoftwareUser’sManual











March2011(Ver.1.0)

www.elmomc.com


G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

1‐2
ImportantNotice
Thisdocumentisdeliveredsubjecttothefollowingconditionsandrestrictions:
•ThisdocumentiscopyrightedandallrightsarereservedbyElmoMotionControlLtd.This
productmaynot,inwholeorinpart,becopied,photocopied,reproduced,translated,orreduced
toanyelectronicmediumormachine‐readableformwithoutpriorconsent,inwriting,byElmo
MotionControlLtd.
•ThisdocumentcontainsproprietaryinformationbelongingtoElmoMotionControlLtd.Such
informationissuppliedsolelyforassistingusersofGoldMaestroNetworkMotionController.
•Thetextandgraphicsincludedinthisdocumentareforthepurposeofillustrationandreference
only.Thespecificationsonwhichtheyarebasedaresubjecttochangewithoutnotice.
•ElmoMotionControlandtheElmoMotionControllogoaretrademarksofElmoMotionControl
Ltd.
Documentno.XXXXXXXXXXXXXXXXX
Copyright©2011
ElmoMotionControlLtd.
Allrightsreserved.


G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

1‐1
Tableofcontents
Chapter1: AbouttheG‐MASandthismanual..............................................................1‐3
1.1. WhatistheG‐MAS ........................................................................................1‐3
1.2. G‐MASFeatures ............................................................................................1‐4
1.3. WhattheDocumentCoversandHowtoUseIt ................................................1‐5
Chapter2: JustBeforeStartingUp ..............................................................................2‐6
2.1. PreparingYourComputer ..............................................................................2‐6
2.2. UsingtheManual’sExamples .........................................................................2‐6
Chapter3: ProgrammingPracticesandGuidelines .......................................................3‐9
3.1. Projectsandfiles...........................................................................................3‐9
3.1.1. ProjectLocationandNaming........................................................ 3‐10
3.1.2. Project’sFiles .............................................................................. 3‐11
3.1.3. Project’sDescriptionFiles ............................................................ 3‐11
3.2. Functions,VariablesandConstants...............................................................3‐12
3.3. CandHeaderFiles.......................................................................................3‐12
3.4. Wrapperfunctions ......................................................................................3‐13
3.4.1. HidingComplexand/orNotImportantCodeSegments................... 3‐13
3.4.2. HidingRepeatedSegmentsofCode............................................... 3‐14
3.4.3. ProvidingEasierInterfaces ........................................................... 3‐14
3.5. Implementingmachinesequences................................................................ 3‐15
3.5.1. Themain()programstructure....................................................... 3‐17
3.5.2. TheMachineSequences()Function................................................ 3‐18
3.5.3. TheMachineSequencesTimer()function........................................ 3‐20
3.6. Handlingerrors ...........................................................................................3‐28
3.7. Samplecode ...............................................................................................3‐30
Chapter4: G‐MASsoftwarestructureandinterfaces..................................................4‐46
4.1. TheHost.....................................................................................................4‐47
4.2. TheG‐MAS .................................................................................................4‐49
4.2.1. FunctionBlocksInterfaces............................................................ 4‐50
4.2.2. Multi‐AxisMotionControlCoreStructure...................................... 4‐50

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

1‐2
4.3. Thedevicenetwork.....................................................................................4‐53
4.4. Additionaltools...........................................................................................4‐54
4.4.1. KPAStudio .................................................................................. 4‐54
4.4.2. IPConfigurationoverUSB ............................................................ 4‐54
Chapter5: TheXYZrobotexample ............................................................................5‐55
Chapter6: FurtherProgrammingExamples................................................................6‐56
Chapter7: PCSoftwareInstallationandhowtouse ...................................................7‐57

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

1‐3
Chapter 1: About the G-MAS and this manual
ThischapterdescribestheG‐MASproductandtheorganizationofthismanual.Personsbeginningto
understandtheG‐MASandprogramit,shouldreadthismanualcarefully.However,experienced
G‐MASusersmayomitthischapter.
1.1. What is the G-MAS
TheGoldMaestro–G‐MASisanadvancedmulti‐axismachinecontroller.
Itisaprogrammablecontrolunit,withbuilt‐in,ready‐to‐use,standardized
functionalitiesforcommunications,motions,emergencies,timing,eventsandall
thatisrequired(anddesired)toimplementacompletemulti‐axismotioncontrol
system.
Thefigurebelowpresentsthestructureofamotioncontrol
systembasedontheG‐MASandElmo’sdigitaldrives.This
systemisbasedonthefollowingthreelayers:
•Hostcomputer(orPLCorHMIPanel)
•G‐MAS
•Devices(DigitalDrives,I/Ocontrollers,networkencoders…)

Themachine’shostcomputer(orPLC,HMIpanel)typicallyexecutestheinterfacestothemachine
operatorandperformshigh‐levelmanagementandmachinealgorithms,asnecessary.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

1‐4
Digitalservodrivescontrolanddrivemotors,witheachdrivegenerallyresponsibleforasingleaxis
(control,motions,safety,limits,etc.),aswellassomeI/Osthatmaybeconnectedtothedigitalservo
drive.WithElmointelligentdigitalservodrives,eachdrivecanbeprogrammedtoperformsimple
andadvancedprocesses,whichisonlylimitedtoaxislevelprocess(incontrasttomachine,ormulti‐
axeslevel).
I/Ocontrollersandotherdevicescanbeaddedtothedevicenetwork.
Thehostcomputer(orPLC,HMIpanel)isresponsibleforuserinterfacesandhigh‐levelmachine
processes,whereasthedigitalservodrives(andI/Oscontrollers)executeaxisorI/Olevelprocesses.
Therefore,anintermediarylayerisnecessarytoperformthemachine’ssequencesandmulti‐axis
synchronizedmotions.ThisisexactlywheretheG‐MAScomesin.
TheG‐MASislocatedintheintermediarylayer.Itreceiveshigh‐levelcommandsfromthehost
computer,performstherequiredmachinesequences,calculatesmulti‐axismotionsand,
opportunely,communicatesviathedevicenetworktosynchronouslysendcommandstoeachaxis.
Obviously,theG‐MASalsocollectsstatusesfromthenetworkdevicesandinturnsendsitsown
statusestothehostcomputer.
Fromthenetworkdevicesview,theG‐MASisimportant,sinceeachnetworkdeviceviewsonlyavery
narrow(axis,I/O)portionoftheoverallsystemandthereforecannotcreateorcontroloverallsystem
sequencesormulti‐axissynchronizedmotions.ThenetworkdevicesrequireadeviceliketheG‐MAS
totakethisresponsibility.
Fromthehostcomputer(orPLC,HMIPanel)view,theG‐MASisnotasimportant,asintheory,one
canimplementallthefunctionsoftheG‐MASintothehostcomputer.However,thisentailsavariety
ofsignificantdrawbackse.g.hugedevelopmenttime,significantrisks,non‐modularimplementation,
“inventingthewheel”etc.thatareeasilyandelegantlysolvedusingtheG‐MAS.
Withitsturnkey,in‐builtfunctionality(standardimplementationof:PLCopenmotions,Ethernet
communications,CANopen,CANopenoverEtherCAT,etc.)andsupportforCuserprograms,toeasily
implementamulti‐axismotioncontrolsystem,youonlyneedtowriteyourfirstCprogramfortheG‐
MAS.Thisisprobablywhyyouarenowreadingthismanual…
1.2. G-MAS Features
ThefollowingpresentssomeoftheG‐MASfeatures.YoumayrefertoElmo’swebsiteat
www.elmomc.comforadditionaldetailedinformationandbrochures.
•Highperformance,distributedmulti‐axisnetworkcontroller,withreal‐timeextensionofthe
Linuxoperatingsystem.
•Controlsupto100axesoverdevicenetworkwithahighlevelofsynchronizationandaccuracy.
•Hostcommunicationchannelsandprotocols:
Ethernet,TCP/IP,UDP(fastbinaryprotocols,MODbus,Ethernet/IP,Telnet,FTP,HTTP)
USB2.0
•Devicenetworks(fieldbuses)andprotocols:
EtherCATreal‐timedevicenetworking(CoE,Distributedclock),or:

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

1‐5
CANopen:DS‐301,DS‐305,DS‐401(I/Odeviceprofile),DS‐402(driveandmotioncontrol
deviceprofile)
•Built‐infunctionalblocklibraries:
Communicationwithhost
CANopenoverCANandEtherCAT
PLCopenmotion
Events
Datarecording
•Programming:
Nativeapplication'C'programmingonthetarget
IEC61131‐3,PLCopen(futurefeature)
•Packageandpowersupply:
Verycompact,spacesavingpackage.TheGoldLionforembeddedmilitaryapplications.
DCpowered:14Vto196V.
ItisimportanttonotethatoneofthemaincriteriathatguidedtheG‐MASdevelopment(together
withallElmo’sGoldfamilyproducts)wastousemarket‐leadingstandardswhereverpossible.
Furthermore,eachstandardwasaccuratelyimplemented,ensuringmandatorycomplete
implementationofthestandard.WithElmo’sGoldproductfamily,thiscanbefound,forexample,in
thehostcommunication(MODbus,Ethernet/IP),DeviceNetwork(CANopen,CANopenover
EtherCAT),safety,PLCmotionlibrary,I/Osinterfacecircuits,etc.
1.3. What the Document Covers and How to Use It
ThismanualisorganizedtocreateaprogressivepathfortheuserstartingfromtheG‐MASbasicsto
graduallyachievethepotentialforadvancedandcomplexsystemsprogramming.
ThemanualbeginsexplainingtheG‐MASstructureandprogrammingguidelinesandcontinueswitha
detailedexplanationofanApplicationprogramwrittenforanXYZrobot.
Theexplanationstartswiththetop‐levelcodestructureandlater,systematically,immersesintothe
codedetails.Therefore,forbeginners,itisrecommendedtoreadthismanualchapter‐by‐chapter.
Themanualanditscodeexamplesareorganizedtoallowthereadertolearn,chapterbychapter,
firstlyabouttheG‐MASfunctionsandeaseofuse,andthenprogressively,aboutthedetailsof
implementation,withincreasingdetailsrevealedinlaterchaptersorexplanation.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

2‐6
Chapter 2: Just Before Starting Up
ThischapterpresentstherequiredpreparationsbeforeyoucanstartusingtheG‐MASanditsPC
softwareenvironment.
Inaddition,itexplainshowtheincorporatedexamplesrelatetoElmo’sdemosuitcase,andhowthey
canbeadaptedtomatchyourspecificsystem.

Thischaptermustberead,andthepreparationsdescribedwithin,implemented,tobe
properlyproficientinoperatingtheG‐MASanddevelopinguserprogramsforit.

2.1. Preparing Your Computer
ThePCsoftwareenvironmentfortheG‐MASincludestheEAS(ElmoApplicationStudio)andtheC
programmingdevelopmentenvironment.Theseapplicationmodulesmustbeinstalledtobeableto
operatewiththeG‐MAS.
TheEASisElmo’ssetupandmaintenanceapplicationfortheGoldlineproducts,includingtheG‐MAS
andGoldDrives.AsaG‐MASuser,youwillneedthisapplicationtoconfigureyoursystem(network,
devices,etc.),communicatewiththeG‐MAS,andtoperformavarietyoffeaturesincorporated
withinEAS,e.g.tocreate,recordanddisplaymulti‐axismotions.
TheCprogrammingdevelopmentenvironmentisnecessarytodevelop(write,download,debug)C
programsfortheG‐MAS.
PleaserefertoChapter7:PCSoftwareInstallationandhowtousefordetailsregardingthe
installationoftherequiredG‐MASsoftwareprocess,andhowtousethesesoftwaremodules.

Pleasecontinueusingthismanualonlyafterproperlyinstallingtheapplicationsandunderstanding
howtousethem.Theremainderofthismanualassumesthattheuserisfamiliarwiththeapplication
environments.

2.2. Using the Manual’s Examples
TheentireCprogramsexamples(unlessspecificallymentionedotherwise)includedwithinthis
manualweredevelopedfor,andtestedwithElmo’sdemosuitcase.ThissuitcaseconsistsofaG‐MAS
andtwoElmodigitalservodrives(andmotors)connectedtoitoveradevicenetwork.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

2‐7
TheGoldLinedemosuitcaseincludestwoGoldlinedigitalservodrivesconnectedtotheG‐MASover
EtherCATwhiletheSimplIQLinedemosuitcaseincludestwoSimplIQdrivesconnectedtotheG‐MAS
overtheCANbus.
Therefore,theexamplesprovidedwithinthismanualareadjustedtoeitherconfiguration,whether
GoldorSimplIQdemosystem,andismentionedwithineachexample.However,notallexamples
mayworkforadifferentsystemconfiguration.

Itisthereforerecommendedtoconsiderpurchasingofademosuitcase(GoldorSimplIQ,depending
onyourneeds)forconvenientlypracticingthismanual’sexamples.PleaseaddressyourlocalElmo’s
saleschanneltoorderademosuitcase.
Ifyouprefertouseyourownsystemforpracticingthismanual’sexamples,youwillneedtoslightly
modifythemaccordingtothestructureofyourownsystem.Usetheguidelinesdescribedwithinthe
followingthetabletoproperlymodifythismanual’examples.


YourSystemStructureNecessarymodificationsfor
exampleswrittenforCAN
Necessarymodificationsforexamples
writtenforEtherCAT
G‐MASwith2xSimplIQ
drivesoverCANbusNone
Resourcefilethatrepresentsthe
system.
ShouldcalltheGetCommStatistics()
APIinordertocheckthatthenetwork
setupisOK.Thisisinsteadof
NetworkInfo()whichisforCAN.
ChangeoperationmodetoCyclic
PositionmodeandnotInterpolated
Position.
G‐MASwith1xSimplIQdrive
overCANbus
Newresourcefile.Orchangethe
secondaxistovirtualmode.
Asaboveplusthechangestotheleft
forthesingleaxis.
G‐MASwithNxSimplIQ
drivesovertheCANbus
(N>2)
AsaboveAsabove
G‐MASwith2xGolddrives
overtheCANbus
Currently,weuseinterpolation
mode,asdefinedinDS402ver.
II.Thenewstandardusescyclic
positioninstead.
Currently,weuseinterpolationmode,
asdefinedinDS402ver.II.Thenew
standardusescyclicpositioninstead.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

2‐8
YourSystemStructureNecessarymodificationsfor
exampleswrittenforCAN
Necessarymodificationsforexamples
writtenforEtherCAT
G‐MASwith1xGolddrive
overtheCANbusAsaboveAsabove
G‐MASwithNxGolddrives
overtheCANbus(N>2)AsaboveAsabove

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐9
Chapter 3: Programming Practices and Guidelines
ThischapterdescribesthepracticesandguidelinesusedbyElmo’steamtodevelopedexamplesand
applicationprogramsfortheG‐MAS.TheseguidelinesarebasedonworldwidecommonC
programmingpracticeswithsomeexpansionsrequiredtocreateacompletesetofguidelinesand
conceptsfortheG‐MASCprogramming
Mostoftheguidelinesdonotreallyaffecttheexecutionofthecode(donotdirectlyimprovecode
size,orspeed,orperformanceingeneral),so,whyisitsoimportanttousethem?Forthefollowing
reasons:
1.Mostoftheguidelinesrelatetocodereadability,portability,easeofdevelopment,and
debugging.Thismeansthatyourdevelopmentprocessisassumedfasterandeasierwith
theseguidelines.
2.Someoftheguidelines,especiallythosethatrelatetoprogrammingconcepts,aremore
thanjust“howtomakemycodeclearer”.Theyreallyaffecttheeaseofimplementation,
executionperformance,andthetime‐to‐marketofyourproject.Oneoftheseguidelinesis
theconceptofStatesMachineprogramming,asyouwillseelateronthismanual.Itisone
offewpossiblemethodstoimplementmachinesequences,andpractically,itproveditself
thesimplestandthemostsuccessfulmethodtouse.
3.YoucanbetterusetheexamplesandCaseStudiesprovidedbyElmo,astheyareallwritten
accordingtotheseguidelinesandprogrammingconcepts.
4.Andmostimportant,toenablethebestsupportyoucangetfromElmo.Application
programsmaybecomelargeandquitecomplexforsignificantprojects.Usingyourown
programmingconcepts,asgoodastheysurelyare,willmakeitmuchmoredifficultfor
Elmo’ssupportengineerstoperformin‐depthanalysis.Youmayneedtosendusyourcode,
orpartsofit,atsomepointinthefuture,anditmaybecomeimpossibleforustoanalyze
andtrackitsdetailsunlessitiswrittenaccordingtotheguidelinesandconceptsdescribed
inthischapter.

Itisthereforestronglyrecommendedtousetheseguidelines,practicesand
programmingconceptswhendevelopingyourownCprogramsfortheG‐MAS.


3.1. Projects and files
Thissectiondescribessomeguidelinesregardingorganizationandnamingofprojectsandfiles.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐10
3.1.1. Project Location and Naming
Allprojects(applications)shallbelocatedundertheC:\GMAS\MyGMASProjectsdirectory,whichis
createdduringthesoftwareenvironmentinstallationprocess.TherootdirectoryC:\canbereplaced
withtheactualnameofyourdisk.
Eachprojectshouldbelocatedwithinaspecificdirectoryundertheabovelocation,withonlyone
projectwithinagivendirectory.
Thenameofaproject’sdirectoryshouldreflectthenameoftheproject(application).Forexample,
fromElmo’ssetofCprogramsexamples:“C_ReadDigitalInput”(seescreensnapshotbelow).Note
thatthenameoftheproject’sdirectoryrespectsthefollowingguidelines:
•Itreflectstheproject/applicationcontents.
•Ithasnospaces.
•Ifitconsistsoffewwords,eachwordstartswithaCapitalletterforeasyreading.
•Finally,forconvenienceonly,Elmoaddsaprefixtotheproject’sname(inthiscase:“C_”)toforce
thelistoftheprojectstoappearinagivenorderwithinWindowsexplorer.Thisisdoneinorder
toorganizeourbuilt‐inexamplesinadesiredorderforthereadersofthismanual.Youarenot
requiredtoaddthisprefix(seecustomer’sprojectWalkingRobotPrototypewithinthescreen
snapshotbelow).

Theabovethreeguidelinesfornamingproject’sdirectory,arealsoapplicablefornamingallofthe
project’sCandHfiles.Thenamemustreflectthecontentofthefile,includenospacesandeach
wordinthenameshouldstartwithacapitalletter,e.g.:ReadDigitalInput.c


G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐11

3.1.2. Project’s Files
EachprojectwillbebasedonamainCfile,respectingthefollowingguidelines:
•Itsnamewillbeidenticaltotheproject’sdirectoryname(withouttheprefix,ifused).For
example:ReadDigitalInput.c
•Itwillincludethemain()function,whichwillbethefirstfunctionwithinthefile.
Eachprojectwillalsoincludeamainheader(*.h)file,whichwillbealsonamedwiththenameofthe
project(e.g.ReadDigitalInput.h)andwillincludealldefinitionswhicharespecificfortheproject
(suchasconstants,functionsprototypes,etc.).
Inaddition,thedevelopercancreateadditionalcodeandheaderfiles,asmaybeneededtoproperly
organizethevariousCfunctions.Allfilesshouldbenamedusingtheabovefilenamingguidelines.
3.1.3. Project’s Description Files
Elmohighlyrecommendsthatanapplicationprogrammershouldaddsomefilestoaproject’s
directorythatexplaintheprojectgoals,tasks,methodsofimplementation,etc.Itcanbeasimple
readmefileorfilesthataremorecomplex(machinespecification,motionsequences,machine’sATP,
designreviewsfortheimplementation,etc.).Thisinformation,ifsuppliedwiththeoverallproject
codefiles(foranewmemberinthedevelopmentteam,and/orforElmo’sstaffforsupport,etc.)can
significantlyimproveprocessese.g.learning,supportfortheproject,etc.
Pleaserefertotheproject’sdescriptionfilesincludedwitheachofElmo’sexamples(locatedat
C:\GMAS\MyGMASCProjectsaspartoftheDevelopmentSoftwareinstallationprocess)forexamples
ofsuchfiles.
Projectsdirectory
ReadDigitalInputproject
WalkingRobotproject

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐12
3.2. Functions, Variables and Constants
Thenamingandusageoffunctions,variablesandconstantsshouldabidebythefollowingguidelines:
•Functionsshouldbenamedsimilarlytofiles.Forexample:MainTimer().
•Variablesshouldalsobenamedsimilarly,butshouldbeprecededwiththevariabletypeinlower
case,accordingtothetablebelow.Forexample:iSpeedcanbethenameofanintegervariable
holdingavalueofspeed.
TypePrefixExample
IntegeriiMotorSpeed
UnsignedintegeruiuiUpperLimit
LongllPosition
UnsignedlongululLimitPosition
ShortssAnalogInput
UnsignedshortususDigitalInputs
CharccErrorString
UnsignedcharucucASCIICode
EnumeeTargetPositions
StructststHalt
•Constantsshallbenamedusingthefollowingformat:MY_CONSTANT(allcapitals,“_”between
eachword).
•Globalvariablesareallowedandrecommendedforvariablesaccessedbymorethanone
function.TheyshouldbedefinedatthetopofaCfile(inmostcases,theproject’smainCfile).
TheGlobalvariable’snameshouldhaveanadditional“G”atitsprefix,e.g.glPosition,
gcErrorString.ThiswillindicatetotheprogrammerthatthevariableisGlobal.
3.3. C and Header Files
ThecodewithintheCfilesshouldrespectthefollowingguidelines:
•Themainproject’sCfileshouldstartwithsomecommentslinesdescribingtheapplication.
•Eachfunctionshouldbeprecededwithsomecommentslines,providingasmuchdetailsas
possibleaboutthefunction(whatitdoes,inputandoutputparameters,whowroteit,version,
etc.).
•Themain()functionshouldbethefirstfunctionwithintheproject’smainCfile.Itshouldbe
typicallydefinedas:Voidmain()
meaning,noargumentsareexpectedwhenexecutingtheprojectandnoreturnedvaluetothe
operatingsystemuponexitingtheapplication.
Incaseargumentsshouldbepassedtotheapplicationcodefromtheoperatingsystem,orifthe

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐13
applicationshouldreturnavaluetooperatingsystemuponexiting,pleaserefertotherelevant
exampleincludedwithintheexamplesdirectory(c:\GMAS\MyGMASCProjects).
•ACfileshould“include”onlytheheaderfilesnecessary.
•Thecodeshouldnotincludenumbers.Constantsshouldbedefinedwithintherelevantheader
fileandthevalueoftheconstantshouldbedefinedonlywithintheheaderfile.Forexample:
HOMING_SPEED.
•Thisincludesvalueslike“0”and“1”.DefineOKandNOT_OK(and/orsimilarly,likeTRUE,FALSE).
•Codeshouldbeverticallyalignedandproperlynested.
•UseTABS,notspacestoalignthecodevertically.
•Openingandclosingbrackets(“{“and“}”)shouldbeeachwritteninaseparateline.
•Comments(filesandfunctionstitles,in‐linecomments,endoflinecomments,etc.)shoulduse
theformat(orstyle)asshownwiththesamplecodeattheendofthischapter.
3.4. Wrapper functions
Wrapperfunctionsfilesarefilesthatholdasetoflogicallyrelatedfunctions(actually,alibraryof
functions).Eachfunctioniswrittento“hide”arelativelycomplexprocess/codewithasimple
interfacefortheprogrammer.AnexamplecanbeaWrapperFunctionsfilethatwillincludeasetof
functionsformotion.Itmaycontain,forexample,afunctionlikeMyMoveAbsolute(dSpeed,
dPosition).Thisfunctionhasaverysimpleinterface(canbeeasilyusedtocreateamotion,asallyou
needtoenterarevaluesforSpeedandPosition),butinternally,itwillusethelesssimplePLCopen
Motionfunction,includingparametersinitializations,validitychecks,etc.
WrapperFunctionshelptokeepthemaincodecleanerandmoreelegant.Whilereading(and
debugging/modifying)themaincode,onewouldliketoeasilyseetheimplementedmachine
sequence(programflow)andthiscanbedoneonlyifthedetailsofthecodearehiddenwithin
functioncalls.
Acalltoafunctionnamed“MMC_InitSystem(…)”willbemuchclearerthanplacingthedetailedcode
ofthesysteminitialization(axes,communicationetc.)onlinewithinthemaincode.Therefore,if
necessary,thedevelopercanperformin‐depthanalysisonthedetailedcodeinthewrapperfunction.
WrapperFunctionscanbeusedforvariousproposes:
•HidingComplexand/orNotImportantCodeSegments
•Hidingrepeatedsegmentsofcode
•Providingeasierinterfaces(“shortcuts”)forrepeatedcallstofunctions
3.4.1. Hiding Complex and/or Not Important Code Segments
Whenprogrammingacomplexsynchronizeddistributedsystem,theoverallcodewilltypically
includerelativelycomplex,longand“non‐interesting”segmentsofcode.Thesesegmentsgenerally
dealwiththedetailedimplementationofthesysteminitialization,management,errorhandling,
terminationetc.Thiscodeisnotnecessarilyrelatedtothemaingoaloftheproject–toperformthe
machinesequence.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐14
Ifthesesegmentsofcoderemainwithinthemaincode,themaincodewillbecometoocomplex,
blockingreasonablereadingandtrackingofwhatismostimportant;theimplementationofthe
machinesequencesandlogic.
WrapperFunctionscanbeusedtohidethesesegmentsofcode.SuchWrapperFunctionsare
suppliedbyElmosothatourexamplescanbereadandunderstoodmucheasier.
3.4.2. Hiding Repeated Segments of Code
Repeatedsegmentsofcode,evenifnotcomplex,andevenifimportanttounderstandtheprogram
flow(themachinesequences),canbehiddeninsideaWrapperFunctiontominimizethemaincode
length.
3.4.3. Providing Easier Interfaces
Someofthebuilt‐inG‐MASFunctionBlockfunctionshavecomplexinterfaces,i.e.afunctionwith
manyarguments,withsomeoftheseargumentsalsocomplexstructures.Thiscomplexityis
necessarytomaintaincompatibilitywithstandardslikePLCopenMotionandtoenablefulloperation
ofthefunction.
However,inmostsituations,andyourcasemaybeoneofthem,theapplicationdoesnotneedfull
operationoftheFunctionBlock,butonlyneedsasmallsubsetoftheFunctionBlockinterfaces.
Underthesecircumstances,theprogrammer(orElmowithinitsexamples)maydefineanew
functionthatwillhaveasimpleinterfacewiththeprogramandwillinternallyassumesomedefaults
fortheremainingfunctionsarguments.
Anexamplecanbeasimplemotionfunction(tobetypicallylocatedwithinaWrapperFunctionsfile
thatwillincludemanyfunctionsforsimplemotions),e.g.MoveAbs(iPosition).
Thisfunctionacceptsonlyoneargument,thedesiredposition,andcreatesamotiontothistarget
position,usingthefullmechanismofthePLCopenMotionFunctionBlocks.Itwillassumedefault
valuesfortheadditionallyneededarguments,likespeedandacceleration,orwillkeepthevalues
usedrecently–dependingontheactualcodingoftheMoveAbs()function(thisofcoursemustbe
clearlydocumentedfortheusersofthewrapperfunction).
Assumingthattheuserunderstandswhatarethedefaultactionstakenbythewrapperfunction,itis
mucheasiertocalltheMoveAbs()thanthestandardPLCopenMoveAbsolutefunction.
Anotherexamplemaybe:
intiEndMotionReason=MoveAbsWaitEndMotion(iPosition)
Thisisclearlyafunctiontocreatemotionandtowaittoitsend(whateveristhereason;reachingthe
target,limit,error,…).Thefunctionreturnsonlywhenthemotionends,returningthereasonforthe
endofmotion.

Ingeneral,WrapperFunctionsarelibrariesoffunctionsthatareaimedtosimplifythe
writingandthereadingofthemaincode–themachinesequences.


G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐15
ElmosuppliesasetofWrapperFunctionsfilesaspartofitssetofexamples.Youcandefineand
createyourownsetofWrapperFunctionsfiles(startingfromscratchorbasedononeofElmo’s
examples),assuitableforyourprojectsandstyleofwriting.
WrapperFunctionsfilesshouldfollowthefollowingguidelines:
•Elmo’ssuppliedWrapperFunctionsfilesshouldnotbemodified.Instead,ifmodificationsare
necessary,copythefiletoanewfileandmodifyit.
•EachWrapperFunctionsfileshouldincludeasetoffunctionsthatarelogicallyrelated.Each
functionshouldhaveasimpleuserinterface.
•EachWrapperFunctionsfileshouldbenamedtoreflectitscontents.Forexample:
SimplifiedSynchronizedMotions.c.
•EachWrapperFunctionsCfileshouldhaveaheaderfile(*.h),withthesamename.Theheader
filewillincludedefinitionsrelevanttotheWrapperFunctionsfile,aswellasprototypesforthe
wrapperfunctionsincludedwithinit.
•Thegeneral(notexamplespecific)WrapperFunctionsfilesthataresuppliedbyElmo,arelocated
undertheG:\GMAS\GMASCWrapperFunctionsFiles.
•AdditionalWrapperFunctionsfilesthataremorespecifictoagivenproject/applicationshouldbe
locatedwithintheprojectdirectory.
•IfaWrapperFunctionacquiresanumberofassumptions(defaultvalues,keepingprevious
values,etc.),theseassumptionsmustbeclearlydocumentedfortheuser.
•ItisstronglyrecommendedthataWrapperFunction(unlessitwaswrittentoaveryspecificand
fixedproject)willnotincludedefaultvaluesforparameters.Aneasymistakecanbe,for
example,toassumeavalueof100000(forexample)forasimplifiedmotionfunction.Thismay
workperfectlyforagivenexample,butwillnotbesuitableforafutureexample,whennoone
willrememberthisdefaultdecision.Othersolutionsarerecommended(forexample,toincludea
WrapperFunctionwithinthefilethatwillbeusedtoinitializeallthisdefaultvaluesfromthe
maincode).Somethinglike:
InitMotionsWrapper(iSpeed,iAcceleration,iDecelaration,iMode,iSmoothing,…)
ThentheprogrammercanfreelyuseMoveAbs(iPosition)etc.
3.5. Implementing machine sequences
Aprogramthathandlesmachinesequencesshouldanswerthefollowingrequirements:
•Capabletohandleanumberofsequencesinparallel.
Forexample,assumingthattheG‐MASshouldhandleamachinewiththreeaxes(e.g.X,YandZ)
togetherwithanAutomaticLoaderthatshouldloadandunloadtheobjectto/fromthemachine,
itselfconsistingof4axes.
Eachofthesesub‐assembliesshouldbecontrolledinparallel,havingsequencesthatare
independentwhilenecessarilysynchronized.
AUserApplicationattheG‐MASshouldbeabletoexecutebothsequences(themachineandthe
Loader)inparallel,andtosynchronizethem,whensynchronizationisrequired.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐16
•Capabletohandlebackgroundsystemprocessessuchasvalidationread,andhandlestatuses,
emergencies,etc.
Manytasksshouldbecontinuouslyormoreaccurately,periodically,handledbytheapplication.
Thesetasksshouldbeexecutedindependentlyofthemachinestatusand/ormodeofoperation.
•Capabletoalwaysbereadytoreceiveincomingcommunication(typically,fromtheHost)with
reasonableresponsetimeandmoreimportant,withpre‐definedlimitedresponsetime.
Theapplicationprogramshouldnotbetoobusy(intermsoftime)withanygiventask,and
shouldalwaysbeabletoobtainandproperlyrespondtoincomingcommunication.
•Determinism.
Theapplicationprogramshouldexecutethesamesequences,respondtoincomingmessages,
andcreatecommunicationstothedevicenetwork,inadeterminedway,withlittledelaysor
jittersandwithinapredefinedlimit.
•Maintainability.
Finally,butnotlessimportantistherequirementforeasydevelopmentandmaintenanceofthe
program.Theprogrammustbeorganizedinawaythatcomplexsequencescanbeeasilywritten,
controlled,andmaintained.
Therearenumerousmethodstowriteaprogramthatwillanswertheaboverequirements.For
example:multi‐taskingandinterrupts.
Elmohasanextensiveexperienceinthedevelopmentofuserapplications.Wehaveacquiredthis
experienceduringmanyyearsofcustomerssupportandduringin‐housedevelopmentofuser
applications.
Basedonthisexperience,wehaveconcludedthattheoptimalmethodtowriteprogramsfor
machinesequencesisastructurethatisbasedonStatesMachines.Thisprogrammingstructure
optimallyanswerstheaboverequirements.
WithaStatesMachinestructure,aprogramdoesnotneedMulti‐Tasking(acomplexstructurefor
mostprogrammers,andobviouslymostMotionControlengineers)andinmostcaseseveninterrupts
arenotrequired.AllthatisneededisanunderstandingofthebasicsofStatesMachine
programming.Thecodethenbecomesverysimpletodevelopandtomaintain.

AllprogramsexamplesprovidedbyElmoareimplementedusingStatesMachinestructure.Itis
stronglyrecommendedtousethisprogrammingstructure.ItwillenableeasieruseofElmo’s
examples,allowElmo’ssupportteamtoprovidebetterandfastersupport.Inaddition,itwillshorten
yourtime‐to‐marketandreduceyourdevelopmentriskssignificantly.

ThisisagoodpointtostartexplainingthedetailsofStatesMachineprogrammingstructure.The
explanationisnotsimple,andispresentedinasystematicprocedure.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐17
3.5.1. The main() program structure
Elmo’srecommendedstructureforthemain()functionofaG‐MASUserApplicationprogramis
presentedinFigure1:

Figure1:Main()programstructure
Themain()startswithacalltoMainInit(),afunctionthatperformsallprogramandsystem
initializations(moreonthislaterwithinthemanual’sexamples).Afterallinitializationsare
completed,theMachineSequences()functioniscalled.Thisfunctionintentionallystartsthe
executionofthemachinesequencesandmotions.Duringthemachineoperation,the
MachineSequences()functiondoesnotreturntothemain(),untiltheprogramrequeststoterminate
(dueto,e.g.errors,userrequesttoclose,etc.).Whenthemachineoperationiscomplete,the
MachineSequences()functionreturnstothemain(),whichcallstheMainClose()functiontoclose
everythingthatrequiresclosing,beforetheprogramterminates.
Thisisthemain()functionoftheprogram.Simpleandcleanaspossible.Nowweprogressintothe
MachineSequences()functiontofindtheimplementationofthemachinesequences,usingtheStates
Machinestructure.

G‐MAS–GoldMaestroSoftwareUser’sManual SoftwareUserManual
XXXXXXXXXXXX(0.01)

3‐18
3.5.2. The MachineSequences() Function
Figure2presentsElmo’srecommendedstructurefortheMachineSequences()function.

Pleasenotethatablockcoloredred,isasegmentofcodethatrequirestoexecuteasfastaspossible
andshouldnotincludeanyprocesswitharelativelylongexecutiontimeordelay.Thiswillbecome
especiallyrelevantasweinvestigatedeeperwithintheprogramstructure.Obviously,itshouldnot
includeanyendlesslooporanywaitingforasystemprocesstoend.Aredcoloredblockshould
includeasegmentofcodethatunconditionallyexecutesalimitedsizecode,withnodelaysorwaits.


MachineSequences()startswithacalltoMachineSequencesInit().Thisfunctioninitializesallvariables
asmayberequiredtoactivatetheMachineSequencesTimer()andtomanagetheStatesMachine
(refertoFigure2).
Immediatelyafter,MachineSequences()callstheEnableMainTimer(TIMER_CYCLE(Remember,the
format(CAPITAL_LETTERS)referstoaconstantdefinedbytheprogrammerintheheaderfile))to
starttheexecutionoftheMachineSequencesTimer()functionandtodefinethatitwillbe
automaticallyexecutedbytheOperatingSystem(OS)eachTIMER_CYCLEms.Asatypicalvaluefor
thesedescriptions,let’sassumeaTIMER_CYCLE=20ms.
Fromthispointon,theOSactivatestheMachineSequencesTimer()every20ms.Thistimerfunction
actuallyhandlesandmanagestheStatesMachine,asexplainedbelow.
TheMachineSequences()functionnowentersanendlesswhileloop,waitingforaglobalvariable
(giTerminate)toindicatethattheMachineSequencesTimer()isaskingtoterminatetheprogram.The
giTerminatevariablewillinitializetoFALSEwhentheMachineSequencesInit()functionstarts,andwill
optionallybesettoTRUE,whenandifneeded(possibleforaprogramtoneverterminate)bythe
MachineSequencesTimer()function.
Generallyspeaking,thisendlesswhileloopneedstodonothingexceptwaitforatermination
request.InordernottoloadtheCPUjustforrunning‐in‐loops‐doing‐nothing,aSleep(SLEEP_TIME)is
insertedintheloop.AtypicalvaluefortheSLEEP_TIMEis100ms,meaning(inourexample)thatthis
backgroundloopisactivatedapproximatelyeach5cyclesofthetimerfunction(whichisactivated
every20ms).
Notethatthetimermethodisanaccuratemethodtocreatecallstothetimerfunctioneachgiven
period.TheSleep()methodisnotaccuratebuttimingaccuracyisnotanissueforthisidleloop.
Finally,sincewehavehereabackgroundloopcodethatisactivatedperiodicallyinarelativelylow
rate,wecanuseittoperformsomelesstime‐criticalprocessesasmayberequiredbythe
application.Processes,thatyoumaynotwanttoincludeinthemainStatesMachinewhichis