TinyFrameisasimplelibraryforbuildingandparsingdataframestobesentoveraserialinterface(e.g.UART,telnet,socket).Thecodeiswrittentobuildwith--std=gnu99andmostlycompatiblewith--std=gnu89.
Thelibraryprovidesahighlevelinterfaceforpassingmessagesbetweenthetwopeers.Multi-messagesessions,responselisteners,checksums,timeoutsareallhandledbythelibrary.
TinyFrameissuitableforawiderangeofapplications,includinginter-microcontrollercommunication,asaprotocolforFTDI-basedPCapplicationsorformessagingthroughUDPpackets.
Thelibraryletsyouregisterlisteners(callbackfunctions)towaitfor(1)anyframe,(2)aparticularframeType,or(3)aspecificmessageID.Thishigh-levelAPIisgeneralenoughtoimplementmostcommunicationpatterns.
TinyFrameisre-entrantandsupportscreatingmultipleinstanceswiththelimitationthattheirstructure(fieldsizesandchecksumtype)isthesame.Thereisasupportforaddingmulti-threadedaccesstoasharedinstanceusingamutex.
TinyFramealsocomeswith(optional)helperfunctionsforbuildingandparsingmessagepayloads,thoseareprovidedintheutils/folder.
PortsTinyFramehasbeenportedtomutiplelanguages:
ThereferenceCimplementationisinthisrepoPythonport-MightyPork/PonyFrameRustport-cpsdqs/tinyframe-rsJavaScriptport-cpsdqs/tinyframe-jsPleasenotemostoftheportsareexperimentalandmayexhibitvariousbugsormissingfeatures.Testersarewelcome:)
FunctionaloverviewThebasicfunctionalityofTinyFrameisexplainedhere.Forparticlars,suchastheAPIfunctions,it'srecommendedtoreadthedoccommentsintheheaderfile.
StructureofaframeEachframeconsistsofaheaderandapayload.Bothpartscanbeprotectedbyachecksum,ensuringaframewithamalformedheader(e.g.withacorruptedlengthfield)oracorruptedpayloadisrejected.
TheframeheadercontainsaframeIDandamessagetype.FrameIDisincrementedwitheachnewmessage.ThehighestbitoftheIDfieldisfixedto1and0forthetwopeers,avoidingaconflict.
FrameIDcanbere-usedinaresponsetotiethetwomessagestogether.Valuesofthetypefieldareuserdefined.
Allfieldsintheframehaveaconfigurablesize.Bychangingafieldintheconfigfile,suchasTF_LEN_BYTES(1,2or4),thelibraryseamlesslyswitchesbetweenuint8_t,uint16_tanduint32_tforallfunctionsworkingwiththefield.
,-----+-----+-----+------+------------+----+-------------,|SOF|ID|LEN|TYPE|HEAD_CKSUM|DATA|DATA_CKSUM||0-1|1-4|1-4|1-4|0-4|...|0-4|<-size(bytes)'-----+-----+-----+------+------------+----+-------------'SOF.........startofframe,usually0x01(optional,configurable)ID.........theframeID(MSbisthepeerbit)LEN.........numberofdatabytesintheframeTYPE........messagetype(usedtorunTypeListeners,pickanyvaluesyoulike)HEAD_CKSUM..headerchecksumDATA........LENbytesofdataDATA_CKSUM..datachecksum(leftoutifLENis0)MessagelistenersTinyFrameisbasedontheconceptofmessagelisteners.AlistenerisacallbackfunctionwaitingforaparticularmessageTypeorIDtobereceived.
Thereare3listenertypes,intheorderofprecedence:
IDlisteners-waitingforaresponseTypelisteners-waitingforamessageofthegivenTypefieldGenericlisteners-fallbackIDlistenerscanberegisteredautomaticallywhensendingamessage.Alllistenerscanalsoberegisteredandremovedmanually.
IDlistenersareusedtoreceivetheresponsetoarequest.WhenregisterignanIDlistener,it'spossibletoattachcustomuserdatatoitthatwillbemadeavailabletothelistenercallback.Thisdata(void*)canbeanykindofapplicationcontextvariable.
IDlistenerscanbeassignedatimeout.Whenalistenerexpires,beforeit'sremoved,thecallbackisfiredwithNULLpayloaddatainordertolettheuserfree()anyattacheduserdata.ThishappensonlyiftheuserdataisnotNULL.
ListenercallbacksreturnvaluesoftheTF_Resultenum:
TF_CLOSE-messageaccepted,removethelistenerTF_STAY-messageaccepted,stayregisteredTF_RENEW-sameasTF_STAY,buttheIDlistener'stimeoutisrenewedTF_NEXT-messageNOTaccepted,keepthelistenerandpassthemessagetothenextlistenercapableofhandlingit.Databuffers,multi-partframesTinyFrameusestwodatabuffers:asmalltransmitbufferandalargerreceivebuffer.Thetransmitbufferisusedtopreparebytestosend,eitherallatonce,orinacircularfashionifthebufferisnotlargeenough.Thebuffermustonlycontaintheentireframeheader,soe.g.32bytesshouldbesufficientforshortmessages.
Usingthe*_Multipart()sendingfunctions,it'sfurtherpossibletosplittheframeheaderandpayloadtomultiplefunctioncalls,allowingtheapplciationtoe.g.generatethepayloadon-the-fly.
Incontrasttothetransmitbuffer,thereceivebuffermustbelargeenoughtocontainanentireframe.Thisisbecausethefinalchecksummustbeverifiedbeforetheframeishandled.
Ifframeslargerthanthepossiblereceivebuffersizearerequired(e.g.inembeddedsystemswithsmallRAM),it'srecommendedtoimplementamulti-messagetransportmechanismatahigherlevelandsendthedatainchunks.
UsageHintsAllTinyFramefunctions,typedefsandmacrosstartwiththeTF_prefix.BothpeersmustincludethelibrarywiththesameconfigparametersSeeTF_Integration.example.candTF_Config.example.cforreferencehowtoconfigureandintegratethelibrary.DONOTmodifythelibraryfiles,ifpossible.Thismakesiteasytoupgrade.StartbycallingTF_Init()withTF_MASTERorTF_SLAVEastheargument.Thiscreatesahandle.UseTF_InitStatic()toavoidtheuseofmalloc().Ifmultipleinstancesareused,youcantagthemusingthetf.userdata/tf.usertagfield.ImplementTF_WriteImpl()-declaredatthebottomoftheheaderfileasextern.ThisfunctionisusedbyTF_Send()andotherstowritebytestoyourUART(orotherphysicallayer).Aframecanbesentinit'sentirety,orinmultipleparts,dependingonitssize.UseTF_AcceptChar(tf,byte)togivereaddatatoTF.TF_Accept(tf,bytes,count)willacceptmulitplebytes.Ifyouwishtousetimeouts,periodicallycallTF_Tick().Thecallingperioddeterminesthelengthof1tick.Thisisusedtotime-outtheparserincaseitgetsstuckinabadstate(suchasreceivingapartialframe)andcanalsotime-outIDlisteners.BindTypeorGenericlistenersusingTF_AddTypeListener()orTF_AddGenericListener().SendamessageusingTF_Send(),TF_Query(),TF_SendSimple(),TF_QuerySimple().Queryfunctionstakealistenercallback(functionpointer)thatwillbeaddedasanIDlistenerandwaitforaresponse.Usethe*_Multipart()variantoftheabovesendingfunctionsforpayloadsgeneratedinmultiplefunctioncalls.ThepayloadissentafterwardsbycallingTF_Multipart_Payload()andtheframeisclosedbyTF_Multipart_Close().Ifcustomchecksumimplementationisneeded,selectTF_CKSUM_CUSTOM8,16or32andimplementthethreechecksumfunctions.Toreplytoamessage(whenyourlistenergetscalled),useTF_Respond()withthemsgobjectyoureceived,replacingthedatapointer(andlen)witharesponse.AtanytimeyoucanmanuallyresetthemessageparserusingTF_ResetParser().Itcanalsoberesetautomaticallyafteratimeoutconfiguredintheconfigfile.GotchastolookoutforIfanyuserdataisattachedtoanIDlistenerwithatimeout,whenthelistenertimesout,itwillbecalledwithNULLmsg->datatolettheuserfreetheuserdata.Thereforeit'sneededtocheckmsg->databeforeproceedingtohandlethemessage.Ifamulti-partframeisbeingsent,theTxpartofthelibraryislockedtopreventconcurrentaccess.Theframemustbefullysentandclosedbeforeattemptingtosendanythingelse.Ifmultiplethreadsareused,don'tforgettoimplementthemutexcallbackstoavoidconcurrentaccesstotheTxfunctions.Thedefaultimplementationisnotentirelythreadsafe,asitcan'trelyonplatform-specificresourceslikemutexesoratomicaccess.SetTF_USE_MUTEXto1intheconfigfile.ExamplesYou'llfindvariousexamplesinthedemo/folder.Eachexamplehasit'sownMakefile,readittoseewhatoptionsareavailable.
ThedemosarewrittenforLinux,someusingsocketsandclone()forbackgroundprocessing.TheytrytosimulaterealTinyFramebehaviorinanembeddedsystemwithasynchronousRxandTx.Ifyoucan'trunthedemos,thesourcefilesarestillgoodasexamples.
评论