CommunicationsProtocol

ME218CSpring2016

TableofContents:

Section1:Definition
s
Section2:CommunicationsOverview
Section3:HardwareRequirements
Section4:PacketStructure
4.1XBeeAPIPacketStructure:
4.2PacketTypes:
4.3PairRequestPacket:
4.4EncryptionKeyPacket:
4.5ControlPacket:
4.6StatusPacket:
Section5:EncryptionProtocol
Section6:CommunicationStateCharts
Section7:SampleCommunicationsSequences

Section1:Definitions

Term

Definition

LOBBYIST

Aremotecontrolledhovercraftcapableofmovingforward/backward,left/right
andoptionallyperformingadigitallycontrolledspecialaction.

PAC

AcontrollercapableofinterfacingwithanyoftheLOBBYISTs.Requiredinputs
are:pairingaction,fwd/back,left/rightanddigitalspecialaction.

pairingaction

Acommandinputthat,whenperformed,willinitiateapairingsequence
betweenthePACandtheLOBBYIST.

Section2:CommunicationsOverview
Thisdocumentdescribestheprotocoltobeusedforcommunicationbetweenremotecontrolled
hovercraft(LOBBYIST)anditscontroller(PAC).Onthedayoftheprojectpresentation,atournament
willtakeplace.Ineachround(lasting218seconds),twoteamsofthreewillcompeteagainsteach
other(redteamandblueteam).EachteamwillgetthreerandomPACs,andtherewillbeatotalof
fourLOBBYISTsonthefield.EachLOBBYISTmustbeabletointerfacewithanyofthePACs.A
successfulpairingwillallowaPACtocontroltheLOBBYISTfor45secondsoruntiltheconnectiongets
interrupted.ThetaskoftheLOBBYISTsistoherdlawmakers(pingpongballs)intorevolvingdoors
(goals)toscorepoints.Thearenawillhavetworeversers,platesthatwilltemporarilyconverttheir
respectivegoalsintothegoalofoppositecolor.

ThecommunicationbetweenPACsandLOBBYISTswillbecarriedoutusingXBeeradiomodules
workinginAPImode.ThemaximumfrequencyofexchangesbetweenaPACanditsLOBBYISTwillbe
5Hz.ThiswillneedtobeenforcedbythePACusingitstimerstodisablerequestsfor20msaftereach
transmittedpacket.InordertotakecontrolofaLOBBYIST,thePACwillsendapairingrequesttoit.
TheLOBBYISTwillthenrespondwithastatuspacketacknowledgingthepairing.Afterasuccessful
pairing,a32bytekeywillbesenttotheLOBBYISTbythePAC.Fromthenon,thePACwillsendcontrol
packetstotheLOBBYIST,withrollingencryption.Everycommandmustbeacknowledgedbythe
LOBBYISTthroughtheuseofastatuspacket.Followinga1secondlackoftransmissions,orafter45
secondsaftertheinitialpairing,thePACandtheLOBBYISTwillunpairfromeachotherandgointothe
freestate.ApairedLOBBYISTwillignoreanyincomingpairingrequests.

Section3:HardwareRequirements
Inordertoimplementtheradiocommunicationdescribedinthisdocument,thefollowingminimum
hardwarerequirementsarenecessary:
AllteamswilluseXBeeradiomodules(Zigbee)toimplementradiocommunicationbetween
PACandLOBBYIST.
BoththeLOBBYISTandPACwillcarryoneofthesemodulesonboard.Eachradiomodulewill
haveanaddressassociatedwithit(2180through218B)and(2080through208B).Eachrobot
willalsohaveanIDnumberassignedusingahardwareattachment.
ThecommunicationbetweenanymicrocontrollerandtheXBeeradiomoduleshouldtake
placeviaasynchronousserialcommunicationonly.(UART)
TheasynchronousserialcommunicationbetweenanyonboardmicrocontrollerandanyXbee
boardwilltakeplaceatafixedbitrateof9600.
ThePACandLOBBYISTcantransmitatamaximumrateof5Hzeach.Thatincludesfailed
transmissions.Italsomeansthataresponsecanoccurfasterthan200msafteramessageis
received.

Section4:PacketStructure
4.1XBeeAPIPacketStructure:
ThefigurebelowprovidesreferenceforthestructureoftheXBeeTXpacket.Allthepacketsdescribed
throughoutsection4arecontainedwithintheRFDatasectionofthetransmission.

Note:theFrameIDbytehasnoimpactonthecommunicationsbetweenthePACandtheLOBBYIST.It
isonlyusedtoidentifywhichoutgoingpacketanXBeestatusmessagerefersto.Itsrequiredthatthe
LOBBYISTreceivesaconfirmationofreceiptfromthePACsXBeebeforerotatingtheitsencryption
key.Forthat,theFrameIDhastobeusedbutthisdocumentdoesnotimposeanyimplementation
details.

4.2RFDataStructure:

4.3PacketTypes:

Packettype

Direction

Header

Encrypted

Contents[First

Byte

LastByte]

REQ_PAIR

PL

0x00

[PAIR_DATA]

ENCR_KEY

PL

0x01

[ENC_KEY0][ENC_KEY1]..[ENC_KEY31]

CTRL

PL

0x02

[CTRL0][CTRL1][CTRL2][CHKSM]

STATUS

LP

0x03

[PAIR][ACKDATA]

LetterPreferstoPACandLto
Lobbyist

4.4PairRequestPacket:
Broadcast(destinedforspecifichovercraftusingtheIDnumber)

Packetlength:Header+1databyte

Purpose:
ThepairrequestpacketisbroadcastfromaPACseekingtopairwithanunpairedLobbyist.The
Lobbyistaddressisstoredinbits0through6ofthePAIR_DATAbyteandthecolorisstoredinbit7.

Byte0:[HEADER]
REQ_PAIR=0x00
5


Byte1:[PAIR_DATA]
ThePAIR_DATAbyteisusedbythePACtoindicatewhichLobbyistnumber(LBY)itwantstopairwith.

PAIR_DATA
COLOR

NUM6

NUM5

NUM4

NUM3

NUM2

NUM1

NUM0

Bits<60>:TheaddressnumberofaLobbyistforplayinginthegame.
Whilegradingorgame,onlybits1and0willbeusedasuptofourlobbyistswillbe
present.Bits2to6shouldbecleared.Thetransmittednumbershouldrepresentthe
LOBBYISTnumberminusone.
Fordebugging,theusershouldprogramtheirLOBBYISTsnumbertobeequaltotheir
classteamnumber+3.
Bit7:COLORThecolorselector.
Ifset,assignstheLOBBYISTtotheblueteam.OtherwisetheLOBBYISTwillbered.

4.5EncryptionKeyPacket:
Directed,unencrypted,PACtopairedLobbyist

Packetlength:Header+32databytes

Purpose:
The32byteencryptionkey,startingwithENC_KEY0.Eachbyteisarandomnumbergeneratedbythe
PACeverytimepairingisperformed.

Byte0:[HEADER]
ENCR_KEY=0x01

Byte1:[ENC_KEY]
Thisisthe32byteencryptionkey,sentfromthezeroindexbyteuptothe31stbyte.Thisisarandom
numbergeneratedbythePAC.Oncepaired,allofthecontrolpacketdatasentfromthePACtothe
Lobbyist(includingtheheaderbyte)areencryptedusingthiskey,untiltheendoftheperiodof
control.

ENC_KEY0ENC_KEY3132byteencryptionkey
KEYBIT7

KEYBIT6

KEYBIT5

KEYBIT4

KEYBIT3

N.B.:SendENC_KEY0first.

KEYBIT2

KEYBIT1

KEYBIT0

NOTE:
Fortesting,itmaybehelpfultouseanencoderkeyofallFFs.Thisway,theencrypteddata
willjustbecomplemented.

4.6ControlPacket:
Directed,encrypted

Packetlength:Header+4databytes

Purpose:
TheCTRLbytesaresentfromthePACtotheLOBBYISTandareusedtocontrolthemotionofthe
LOBBYIST,aswellasanyspecialactionstheLOBBYISTmighttake.Notethatallthebytesinthecontrol
packet(includingthepacketheader)areencryptedwiththerollingkey.

Byte0:[HEADER]
CTRL=0x02

Byte1:[CTRL0]
All8bitsoftheCTRL0byteareusedtocreateonesignedinteger,whichspecifiestheforwardand
backwardspeedoftheLOBBYIST.WhentheCTRL0byteisapositivevalue,theLOBBYISTwillmove
forward.Conversely,whentheCTRL0byteisanegativevalue,theLOBBYISTwillmovebackward.
WhentheCTRL0bytehasavalueof0,theLOBBYIST'spropulsionshouldbeoff.Thisbytecanstorea
signedintegerranginginvaluefrom128,whichrepresentsreversalatfullspeed,to+127,which
representsfullspeedforward.

CTRL0AnalogForward/BackwardControl
FB7

FB6

FB5

FB4

FB3

FB2

FB1

FB0

Bits<7:0>Signed8bitinteger

Byte2:[CTRL1]
All8bitsoftheCTRL1byteareusedtocreateonesignedinteger,whichspecifiesthedirectional
controlfortheLOBBYIST.WhentheCTRL1byteisapositivevalue,theLOBBYISTwillturntotheright.
Conversely,whentheCTRL1byteisanegativevalue,theLOBBYISTwillturnleft.WhentheCTRL1byte
hasavalueof0,theLOBBYISTshouldnotturnineitherdirection.Thisbytecanstoreasignedinteger
ranginginvaluefrom128,whichrepresentsturningleftatthefastestspeedpossible,to+127,which
representsturningrightatthefastestspeedpossible.

CTRL1AnalogLeft/RightControl
LR7

LR6

LR5

LR4

LR3

Bits<7:0>Signed8bitinteger
7

LR2

LR1

LR0

Byte3:[CTRL2]
TheCTRL2byteisusedtospecifyanyspecialactionsaLOBBYISTcantake.Theseactionsinclude
braking,purposelyunpairingwiththePAC,andanyotheroptionalspecialactionsdesignatedatthe
discretionofeachteam*.
*Note:Teamswhousebits27shouldbeawarethatotherPACsmaynotbeabletocontrolthese
specialactionsbecausetheywillnothaveuserinputmodesavailabletocontrolthem.

CTRL2SpecialActions
SA5

SA4

SA3

SA2

SA1

SA0

UNPR

BRK

Bits<7:2>Specialactions(7to3optional,SA0mustbeavailableineveryPAC)*
1=Activatespecialaction
0=Deactivatespecialaction
Bit1Unpairing
1=Unpair
0=RemainPaired
Bit0Brake
1=Applybrake
0=Disengagebrake

*Unimplementedspecialactionbitsshouldbecleared.

Byte4:[CHKSM]
CHKSMisusedasanerrorcheckingmeasuretoensurethedecryptionprocessremainsinsync.Every
timeacontrolpacketissentbythePAC,controlbytes0,1,2,and3shouldbesummedtogetherand
theresultshouldbeplacedinCHKSM(i.e.byte4ofthecontrolpacketdata).Oncethecontrolpacket
hasbeenreceivedbytheLOBBYIST,thepacketshouldbedecryptedandtheLOBBYISTshoulds+um
bytes0,1,2,and3.Iftheresultofthissummationdoesnotmatchthevaluesentinbyte4,anerror
occurredandthedecryptionprocessshouldbetreatedasbeingoutofsync.Ifthisisthecase,the
statuspacketshouldbeupdatedsuchthatthePairingbitinSTATUSisclearedandtheDecryption
FailurebitinSTATUSisset.

CHKSMDecryptionErrorChecking
CHKSM7

CHKSM6

CHKSM5

CHKSM4

CHKSM3

CHKSM2

CHKSM1

Bits<7:0>Unsigned8bitinteger

4.7StatusPacket:
Directed,semiencrypted(databyte1unencrypted,databyte2encrypted)

CHKSM0

 Packetlength:Header+2databytes

Purpose:
TheSTATUSpacketissentfromtheLOBBYISTtothePACandisusedtoletthePACknowitis
connectedtotheLOBBYIST.Thereceiptofthepacketisalsoasignalthatthesentcommandhasbeen
acknowledged.IfthepacketsenttotheLOBBYISTwasnotencrypted(eitheraPairRequestoran
EncryptionKey),thentheDEC_ERRbitisclear.TheSTATUSpacketalsocontainsACKDATA,theCTRL
Datachecksumbyte(encrypted)previouslyreceived,totellthePACwhichinstructionisbeing
acknowledged.

Byte0:[HEADER]
STATUS=0x03

Byte1:[PAIR]
Bit0inthePAIRbyteisusedtoshowwhethertheLOBBYISTispairedtoaPACornot.

R/W0

R/W0

R/W0

R/W0

R/W0

R/W0

DEC_ERR

PAIR

Bit<7:2>:Unimplementedread/writeaszero
Bit1:Decryptionerrorbit
1=Decryptionfailureoccurred
0=Decryptionsuccessfulornotapplicable

Bit0:Pairingbit
1=PACandLOBBYISTarepaired
0=PACandLOBBYISTareunpaired

Byte2:[ACKDATA]
TheACKDATAbytebeingsentbacktothePACcontainstheencryptedCHKSMbyteoftheCTRLdata
previouslysenttothelobbyistthathasbeenacknowledgedbyit.IfthePACfailstoreceivethe
STATUSdatabytesfromthelobbyistwithin100ms,itshallresendthepreviouscontrolbytesequence
tothelobbyist.However,iftheacknowledgeisreceivedbeforethe100mstimeout,thePACcan
checktheACKDATAtoconfirmthereceiveofitspastCTRLdataandcannowpreparetosendnew
CTRLdata.

ACKDATA
7

ACKDATA
6

ACKDATA
5

ACKDATA
4

ACKDATA
3

Bits<7:0>Unsigned8bitinteger

ACKDATA
2

ACKDATA
1

ACKDATA
0

Section5:EncryptionProtocol
Purpose:
TopreventdesynchronizationbetweenthePACandtheLOBBYIST

Howto:

TheencryptionprotocolconsistsofanXORcipherwitha32bytekeysequencerandomlygenerated
bythePAC.TheXORcipherisimplementedbyperformingabitwiseXORoperationonthetransmitted
datapacket,usingthecurrentencryptionbyteastheoperand.Thekeyshouldbegeneratedevery
timeanewpairingprocessisinitiatedbetweenalobbyistandthePAC.Postpairing,everybyteofthe
datapacketsentbythePACtothelobbyistwillbeencryptedusingthecurrentbyteofthekey.Note
thedatapacketconsistsonlyoftheRFDATApartoftheXBeepacket.Thatincludesallthebytesofthe
controlpacketdefinedinsection4.Thekeywillcontinuerotatingbetweentransmissionswiththe
indexincrementingwitheachbyteofdatatransmitted.

ToensurethatthePACisalwaysinsynchronizationwiththeLOBBYIST,anadditionalchecksumbyte
willberequiredtobetransmittedattheendofeachcontrolpacket.Thechecksumbyteisdefinedas
thesumoftheheaderandcontentbytesinthecontrolpacketbeforeencryption.Thechecksumbyte
willbetreatedlikeanormaldatabytei.eitwillbeencryptedwiththecontinuingkeyindexbefore
beingtransmittedaspartofthedataframe.

AttheLobbyist,theadditionalchecksumbyte(lastbyte)ofthecontrolpacketisdecryptedand
comparedwiththesumofalltheotherdecryptedbytesofthecontrolpackettoestablishthe
legitimacyofthedatareceived.

Ifthedecryptedchecksummatchedthesumofthedecryptedbytesofthecontrolpacket,thepacket
receivedisconfirmedaslegitimateandthepairbitcontinuestobesetintheSTATUSbytethatissent
back.Ifthedecryptedchecksumdoesnotmatchthesum,thedecryptionerrorbitissetinthe
STATUS.Inaddition,theLobbyistwillclearthepairbitintheSTATUSbyteandunpairwiththePAC.In
thiscase,thePACandtheLOBBYISTwillhavetoreestablishpairingwithafreshkeysequenceto
resumecommunication.

10

Section6:CommunicationStateCharts

11


NotestothePACstatediagram:
ifnoACKisreceivedaftersendingacommand,thePACcanresendthesamemessageafter200ms
andkeeptryinguntilthe1stimerexpires.However,untilitgetsanACK,it
cannot
rotatethekey.

Section7:SampleCommunicationsSequences

Interaction

Pairingattempt
(LOBBYISTunavailable
topair)

PAC

LOBBYIST

Transmits
RequesttoPair
(broadcast,
unencrypted)withnumberoftargeted
LOBBYIST

Ifalreadypaired,ignoresallbroadcast
messagesandmessagesdirectedtowards
otherLOBBYISTs

ReadytotransmitRequesttoPairafter
200ms

Pairingattempt
(LOBBYISTavailableto
pair)

Transmits
RequesttoPair
(broadcast,
unencrypted)withnumberoftargeted
LOBBYISTandteamcolor

12

IfLOBBYISTnumberinRequesttoPair
matchesownnumber:
IndicatessuccessfulpairingonDMC
Indicatesteamcolorspecifiedby
RequesttoPaironDMC
Starts45spairingtimer
Starts1stransmittimeouttimer
Activatesliftfan
Ignoresanyfurtherbroadcast

messages

Transmits
Status
(unencrypted,directed)
withpairingbitset

Generatesand
transmits
EncryptionKey
(unencrypted,directed)

topaired
LOBBYIST

Ifreceivedtransmissionisdirectedtothis
radio,saveskeylocally
Resets1stransmittimeouttimer

Transmits
Status
(unencrypted,directed)
withpairingbitset

ReadytostarttransmittingControl
packets

ReadytostartreceivingControlpackets

Encrypts
Control
packetwith
accordancewithsection5

Transmits
Control
packet(encrypted,
directed)topairedLOBBYIST

Controlsequence
(maximum5Hz)1

Incrementsencryptionkeyindexin
accordancewithsection5
ReadytostarttransmittingnextControl
packet

Ifreceivedtransmissionisdirectedtothis
radio:
DecryptsControlpacketwithlocally
savedencryptionkey
ValidatesControlpacketcontentsby
runningandcomparingControlpacket
checksum
Ifdecryptedchecksum
valid
:
Resets1stransmittimeouttimer
Implementscontrolcommands
Incrementsencryptionkeyindexin
accordancewithsection5
Transmits
Status
(unencrypted,directed)
withpairingbitset

ReadytostartreceivingnextControl
packet

Controlsequence
(decrypterror)

Encrypts
Control
packetwith32byte
encryptionkeyinaccordancewith
section5
Sends
Control
packet(encrypted,
directed)topairedLOBBYIST

Ifreceivedtransmissionisdirectedtothis
radio:
DecryptsControlpacketwithlocally

TheControlpackettransmitreceivesequencedependsonthePACradioreceivingaStatuspacketfromtheLOBBYISTradioto
acknowledgereceiptofeachControlpacket.DependingonthedelayrequiredforthePACtoreceiveacknowledgementfrom
theLOBBYIST,theeffectiveratemaybeslowerthan5Hz.

13

savedencryptionkeyinaccordance
withsection5
ValidatesControlpacketcontentsby
runningandcomparingControlpacket
checksum

ReadytotransmitRequesttoPair

Ifdecryptedchecksum
invalid
:
Deactivatesliftfan
IndicatesavailableforpairingonDMC
Disables45spairingtimer
Disables1stransmittimeouttimer
Transmits
Status
(unencrypted,directed)
withpairingbit
cleared
anddecrypterror
bitset

ReadytoreceiveRequesttoPair

If1stransmittimeouttimerexpires:
Deactivatesliftfan
IndicatesavailableforpairingonDMC
Disables45sDMCpairingtimer
Disables1stransmittimeouttimer

Communicationlink
lost(transmittimeout
timerexpired)

ReadytotransmitRequesttoPair

Transmits
Status
(unencrypted,directed)
withpairingbit
cleared

ReadytoreceiveRequesttoPair

If45spairingtimerexpires:
Deactivatesliftfan
IndicatesavailableforpairingonDMC
Disables45spairingtimer
Disables1stransmittimeouttimer

Pairingtimertimeout

ReadytotransmitRequesttoPair

Transmits
Status
(unencrypted,directed)
withpairingbit
cleared
ReadytoreceiveRequesttoPair

Sends
Control
packet(encrypted,
directed)topairedLOBBYISTwith
unpairbitset

ManualPACunpair

14

Deactivatesliftfan
IndicatesavailableforpairingonDMC
Disables45spairingtimer
Disables1stransmittimeouttimer

ReadytotransmitRequesttoPair

15

Transmits
Status
(unencrypted,directed)
withpairingbit
cleared
ReadytoreceiveRequesttoPair