HiQnet Third Party Programmers Quick‐Start Guide EveryHiQnetmessageconsistsofaHiQnetHeaderandaPayload.Allnumeric
fieldsaresentoverthewirein“network‐byte‐order,”ie.Big‐Endian.
HiQnet Header Structure Thestructureoftheheaderisasfollows:
VERSION
1byte
HEADERLENGTH
1byte
MESSAGELENGTH
4bytes
SOURCEADDRESS
6bytes
DESTINATIONADDRESS
6bytes
MESSAGEID
2bytes
FLAGS
2bytes
HOPCOUNT
1byte
SEQUENCENUMBER
2bytes
AdditionalVariableHeader
0ormore bytes
TheVersionNumberindicatestherevisionnumberoftheentireprotocol;itis
notusedfordifferentiatingbetweenrevisionsofindividualmessages.Thevalue
isalways“2”.
TheHeaderLengthisthesizeinbytesoftheentiremessageheader,including
anyadditionaloptionalvariable‐lengthheader.
TheMessageLengthisthesizeinbytesoftheentiremessage‐fromthe
‘Version’fieldthroughtothelastbyteofthepayload.
TheSourceAddressspecifieswherethemessagehascomefrom.
TheDestinationAddressspecifieswherethemessageistobedelivered.
TheMessageIDindicatesthemethodthatthedestinationnodemustperform.If
thereisapayload,itisusuallyspecifictothetypeofmethodindicatedbythe
MessageID.
TheFlagsdenotewhatkindsofoptionsareactivewhensetto‘1’andare
allocatedinthefollowingmanner:
Bit 15:
Bit 14:
Bit 13:
Bit 12:
Bit 11:
Bit 10
Bit 9:
Bit 8:
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Reserved
Bit 7:
Bit 6:
Bit 5:
Bit 4:
Bit 3:
Bit 2:
Information
Bit 1:
Bit 0:
Reserved
Reserved)
Guaranteed
Reserved
Error
(header
extension
follows)
Reserved
Reserved
HopCountvalueis5.
SequenceNumberisfordebugging.Itmaybezero,oritsvaluemaybe
incrementedwitheverymessagesentstartingfrom1.
2
HiQnet Header for the Discovery Message VERSION
HEADERLENGTH
MESSAGELENGTH
SOURCEADDRESS
1byte
1byte
4bytes
2
25
72
6bytes
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6bytes
MESSAGEID
2bytes
0x0
FLAGS
2bytes
0x0020 (guaranteedbitset)
HOPCOUNT
1byte
5
SEQUENCENUMBER
2bytes
0
TheMessageLengthof72bytesincludesthecontentsoftheDiscoveryPayload
Structurebelow.
Discovery Payload Structure NODE
2bytes
COST
1byte
SERIALNUMBERLENGTH 2bytes
SERIALNUMBER
16 bytes
MAXMESSAGESIZE
4byte
KEEPALIVEPERIOD
2byte
NETWORKID
1byte
MACADDRESS
6byte
DHCP
1byte
IPADDRESS
4byte
SUBNETMASK
4byte
GATEWAY
4byte
TheNODEaddressisthesourceHiQnetaddressofthedeviceorapp.Itsvalueis
1through65534.Zeroand65535arereserved.
COSTisalways1whenusingEthernet.
SERIALNUMBERLENGTHisalways“16”.
SERIALNUMBERuniquelyidentifiestheNodeindicatedbytheSourceAddress.
ItislargeenoughtocontainaUUID.Often,adevicewillhavethefirst10bytesbe
zeroandthelast6bytesbetheMACaddress.
3
TheMAXMESSAGESIZEspecifiesthemaximumsizeofaHiQnetmessagethat
thedevice(orapp)iscapableofreceiving.Appstypicallyadvertise1,048,576in
thisfield.
KEEPALIVEPERIODisinmilliseconds.Itistypically10,000(tenseconds).
NETWORKIDisalways1forEthernet.
MACADDRESSistheMACaddressoftheconnectingclient.
DHCPissetto1whentheclientisusingaDHCPserver.Itissetto0toindicate
staticIPaddress.
IPADDRESSistheIPaddressofthedeviceorapp,whichwillbeusedbythe
desktoconnectbackwiththisclientuponreceivingthediscoverymessage.
SUBNETMASKisusedtodetermineifdevicesandappsareinthesamesubnet.
GATEWAYisoptional.Use0.0.0.0for“nogateway.”
4
Discovery Payload Example NODE
COST
SERIALNO.LENGTH
SERIALNUMBER
2bytes
1
1byte
1
2bytes
16
0x00
0x00 0x17 0x24 0x82 0x3a
0xf2
Bytes
Bytes11‐16(6‐byteMACAddress)
16bytes
1thru10
MAXMESSAGESIZE
KEEPALIVEPERIOD
NETWORKID
MACADDRESS
DHCP
IPADDRESS
SUBNETMASK
GATEWAY
4bytes
2bytes
1byte
6bytes
1byte
4bytes
4bytes
4bytes
1048576 (1024*1024)
10000
1
0x000x170x240x820x3a0xf2
1
0x0a0x010x130x0d(10.1.19.13)
0xff 0xff 0x000x00(255.255.0.0)
0x000x000x000x00(0.0.0.0)
Connecting to the device from your app ThedevicewillbelisteningonTCPport3804.CreateaTCPsocketandconnect
toport3804onthedevice’sIPaddress.
SendaDiscoverymessageasthefirstmessage.Thedevicewillreplywitha
DiscoverymessagewiththeInfobitsetto1intheFlags.Thisletsyouknowthat
thedevicehasrecognizedyourappandcancommunicate.
KeepAlive message TokeeptheTCPconnectionalive,sendthesameDiscoveryMessageperiodically,
withtheflag’sInfoandGuaranteedbitssetto1.Sotheflagsfieldwouldbe
0x0024.TheperiodictimeintervalthedevicerequestedisadvertisedinitsDisco
message.Itistypicallytenseconds.SendingtheDiscoveryMessageeveryfive
secondsisalwayssafe.
Enabling Normal Session‐less Communication Afterestablishingaconnectionwiththeclient,somedevicesorappswillsenda
HiQnetHelloMessagetoyourapp.MessageIDforthismessageis0x08andit
isusedtoopenasessionbetweentwoHiQnetnodes.Infobitintheheaderof
thismessagewillnotbesetwhichmeansthatthisisaRequestmessageand
deviceisexpectingareplyforthismessage.Yourappshouldthenreplywithan
errorheadertorefusesessions.Thennormalsession‐lesscommunicationcan
occur.
5
Example HiQnet Header for the Hello Session Request Message VERSION
HEADERLENGTH
MESSAGELENGTH
1byte
1byte
4bytes
SOURCEADDRESS
6bytes
2
25
29
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6bytes
MESSAGEID
FLAGS
HOPCOUNT
SEQUENCENUMBER
2bytes
2bytes
1byte
2bytes
0x8
0 (or0x20)
5
0
Payload for the Hello Message From Device SESSIONNUMBER
2bytes
1‐65535
FLAGMASK
2bytes
0x01FF
SESSIONNUMBERinthepayloadisarandomnumber,whichthedevicewillbe
expectingintheHiQnetHeadersunlesstheclientrefusessessionswithanError
Headerresponse.
Example HiQnet Error Header Response to Hello Message VERSION
HEADERLENGTH
MESSAGELENGTH
1byte
1byte
4bytes
SOURCEADDRESS
6bytes
2
29
29
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6bytes
MESSAGEID
FLAGS
HOPCOUNT
SEQUENCENUMBER
ERRORLENGTH
ERRORMESSAGE
2bytes
2bytes
1byte
2bytes
2bytes
2bytes
0x8
0x002c (Guar,Error,Info)
5
0
2
0x000x00
6
Setting a Parameter on the Device Ifaclientwantstochangesomeparameteronthedeviceithastosenda
MultiParamSetmessage,whichhastheMessageIDof0x0100.
HiQnet Header for the MultiParamSet Message VERSION
HEADERLENGTH
MESSAGELENGTH
SOURCEADDRESS
1byte
1byte
4bytes
2
25
34 (dependsonpayload)
6bytes
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6bytes
MESSAGEID
FLAGS
HOPCOUNT
SEQUENCENUMBER
2bytes
2bytes
1byte
2bytes
0x0100
0x0020(Guar)
5
0
Payload for the MultiParamSet Message NUMBEROFParameters 2bytes
1
PARAMETERID
2 bytes
1
DATATYPE
1byte
4
VALUE
4 bytes
1
NUMBEROFPARAMETERScanbegreaterthanoneifrequestingmorethanone
parameterinthesamemessage.“PARAMETERID”through“VALUE”willrepeat
“NUMBEROFPARAMETERS”times.
PARAMETERIDuniquelyidentifiestheparameterwithinanObject.
7
DATATYPEisdefinedinthetablebelow.Inthisexampleitwas4,whichmeans
LONG.HowmanybytesVALUEtakesupdependsontheDATATYPE.
Name
‘C’Declaration Range
Bytes DATATYPE
Enumeration
BYTE
Char
‐128to127
1
0
UBYTE
unsignedchar
0to255
1
1
WORD
Short
‐32768to32767
2
2
UWORD
unsignedshort
0to65535
2
3
LONG
long
4
4
ULONG
FLOAT32
FLOAT64
unsignedlong
float
double
‐2,147,483,648to
2,147,483,647
0to4,294,967,926
AsIEEE‐754
AsIEEE‐754
4
4
8
5
6
7
VALUEtakesupthenumberofbytesasdeterminedbyTYPE.
Receiving a Parameter from the Device TheMultParamSetmessageisalsousedtoreceiveParametersfromaDevice.
TheInfobitintheflagsfieldmayormaynotbeset.Forexample,aSoundcraft
devicewillnotsettheInfobitbutaCrowndevicewill.Ifanappisreceiving
MultiParamSet’sfromaDevice,theycontainthecurrentvaluesofParametersin
theDevice.ItdoesnotmeantheDeviceistryingto“set”parametersintheapp,
whichwouldmakenosense.
OnewaytogettheDevicetosendaMultiParamSettoanappisfortheappto
sendaMultiParamGettothedevice.
8
HiQnet Header for the MultiParamGet Message VERSION
HEADERLENGTH
MESSAGELENGTH
1byte
1byte
4bytes
SOURCEADDRESS
6bytes
2
25
29
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6bytes
MESSAGEID
FLAGS
HOPCOUNT
SEQUENCENUMBER
2bytes
2bytes
1byte
2bytes
0x103
0x0020(Guar)
5
0
Payload for the MultiParamGet Message PARAMETERCOUNT
2bytes
1
PARAMETERID
2bytes
1
FortheaboveexampletheMultiParamGetisaskingforoneParameterfromthe
device,parameterID1livingonVirtualDevice0,Object0.
PARAMETERCOUNTisthenumberofparametersthatliveinthissameobject
thatarebeingrequested.
PARAMETERIDwillrepeat“PARAMETERCOUNT”times.
TheresponsetoaMultiParamGetisaMultiParamSetasmentionedabove.Ifan
errorheadercomesbackinstead,thentheparameterdoesnotexistonthe
device.
9
Subscribing to a value change on the device TheotherwaytogetthedevicetosendMultiParamSetmessagesisfortheappto
sendtheParamSubscribeAlltothedevice.ThemessageIDis0x113.
SupposetheproductXMLforSoundcraft’sSiExpression2issomethinglike
shownbelow.ThensubscribingtotheObjectwithObjectAddress2willnotify
theclientofchangestoanyofthefourstatevariablesintheObject:theOn
ButtonstatesandtheFaderlevelvaluesforLRandMono.
Anytimeoneoftheseparameterschange,thedevicewillimmediatelysenda
MultiParamSettotheappwiththenewcurrentvalue.
<?xml version="1.0"?>
<Product ClassID="909" ClassName="Si Expression 2">
<VirtualDevices>
<VirtualDevice Index="1" Name="Public VD Si Expression 2">
<Objects>
<Object ClassID="402" Name="Main masters" Address="2">
<StateVars>
<StateVar ClassID="2404" Name="Main LR Master On" DataType="4" ID="1" />
<StateVar ClassID="2404" Name="Main Mono Master On" DataType="4" ID="2" />
<StateVar ClassID="2403" Name="Main LR Master Level" DataType="4" ID="3" />
<StateVar ClassID="2403" Name="Main Mono Master Level" DataType="4" ID="4" />
</StateVars>
</Object>
</Objects>
</VirtualDevice>
</VirtualDevices>
</Product>
10
HiQnet Header for the SubscribeAll Message From Client VERSION
HEADERLENGTH
MESSAGELENGTH
1byte
1byte
4bytes
SOURCEADDRESS
2
25
36
6bytes
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0x01000002
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6bytes
MESSAGEID
2bytes
0x113
FLAGS
2bytes
0x0020(Guar)
HOPCOUNT
1byte
5
SEQUENCENUMBER
2bytes
0
HowisthevalueofVD‐OBJECTcalculatedas0x01000002(decimal
16777218)?
VD‐OBJECTisa4bytevaluewhichhas1st(mostsignificant)bytecorresponding
totheVirtualDeviceandremaining(leastsignificant)3bytescorrespondingto
theObjectaddress:
VD,1byte
Object,3bytes
0x01
0x000002
…aspertheexampleintheXMLabove,wheretheVirtualDeviceindexis1and
theObjectaddressis2.
Thebinaryrepresentationofabove4bytesis
00000001000000000000000000000010
whichisequalto16777218indecimal.
Payload for the SubscribeAll Message From Client NODEID
VD‐OBJECT
ChangeType
SensorRate
InitialUpdate
2bytes
4bytes
1byte
2bytes
2bytes
1‐65534
0x01000002
5
50
1
11
ChangeTypeisabitfieldfornewerdevices,andanenumeratednumberfor
olderdevices.Itspurposeistotellthedevicewhichkindofparameterstheclient
appwantstosubscribeto.
Forolderdevices,thevalueofChangeTypeis:
enumChangeType
{
AllParametersAndAttributes=0,
NonSensorParametersAndAttributes=1,
SensorParameters=2
}
Fornewerdevices,thevalueofChangeTypeis:
Bitfield:
Bit0:Non‐SensorSVs
Bit1:SensorSVs
Bit2:Attributes
Bit3‐7:notused(zero)
ThevalueforSoundcraftconsolesisalways5,whichmeanswearesubscribing
toNon‐SensorSV’sandAttributes(bitszeroandtwoareset).
Olderdevicesincludethoseby:
 AKG
 dbx
 JBL
 SomeolderCrownamplifiers
Newerdevicesincludethoseby:
 BSSAudio
 NewerCrownamplifiers
 Soundcraft
Whenindoubt,trythebit‐fieldversionofChangeTypefirst.
SensorRateisthevalueinmillisecondswhichissenttogettheupdatesofthe
parametersataperiodicinterval.50isatypicalvalue.Sensorparametersare
thingsthatchangeperiodically,suchasmetersandLED’s.Soundcraftconsoles
donothavesensorparametersbutallotherdevicesdo.
InitialUpdateiszeroorone.Zeromeansjustsetupthesubscription.One
meanssetupthesubscriptionandimmediatelysendallthecurrentvaluesofthe
subscribedparameters.Oneisthetypicalvaluehere.
12
MultiParamSubscribe MultiParamSubscribe,MessageID0x010F,isusedtosubscribetoindividual
parametersratherthanwholeobjects.Theexamplebelowshowssubscribingto
justacoupleoftheparametersintheXMLexampleabove.Wewillsubscribeto
justthe“MasterLevel”parameters.
VERSION
1byte
2
HEADERLENGTH
1byte
25
MESSAGELENGTH
4bytes
59
SOURCEADDRESS
6bytes
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0x01000002
4Bytes
VD‐OBJECT
DESTINATION
ADDRESS
6bytes
MESSAGEID
2bytes
0x010F
FLAGS
2bytes
0x0020
HOPCOUNT
1byte
5
SEQUENCENUMBER 2bytes
0
Payload…
NoofSubscriptions
2bytes
2
PublisherParamID
2bytes
3
SubscriptionType
1byte
0
SubscriberAddress
6bytes
(sameasSourceAddress)
SubscriberParamID
2bytes
3
Reserved
1byte
0– Reserved
Reserved
2bytes
0– Reserved
SensorRate
2bytes
50 (ignoredfornon‐sensors)
PublisherParamID
2bytes
4
SubscriptionType
1byte
0
SubscriberAddress
6bytes
(sameasSourceAddress)
SubscriberParamID
2bytes
4
Reserved
1byte
0– Reserved
Reserved
2bytes
0‐ Reserved
SensorRate
2bytes
50 (ignoredfornon‐sensors)
NoofSubscriptionsisthenumberofparametersthatwillfollow.Publisher
ParamIDthroughSensorRatewillrepeatNoofSubscriptionstimes.
PublisherParamIDistheparameterIDtosubscribe.Inthisexampleweare
referringto"MainLRMasterLevel",ID=3,andinthesecondsubscription,"Main
MonoMasterLevel",ID=4.
SubscriptionTypeisalwayszero.
13
SubscriberAddressisthesameastheSourceAddress.
SubscriberParamIDisthesameasthePublisherParamID.
SensorRateisformetersorLEDsandistypically50milliseconds.The
MultiParamSubscribemessageisagoodwaytosubscribetojusttheindividual
sensorparametersyouwant.
Receiving Subscription Data at the Client WhetheryouuseSubscribeAllorMultiParamSubscribe,datawillcomeback
fromthedeviceintheformofMultiParamSet’s.Non‐sensorparameters,suchas
faders,willarriveonthesameTCPconnectionusedfortheoriginalsubscribe
message.Sensorparameters,suchasmeters,willarriveonUDPport3804as
UDPframes.SoifyousubscribetoanysensorSV’s,youwillneedtobindaUDP
sockettoport3804and“ReceiveFrom”theUDPsockettogetthe
MultiParamSet’s.
Goodbye WhenaclientwantstodisconnectwiththedeskithastosendaGoodbye
messagetothedesksothatthedeskwillcloseitscurrentsessionwiththeclient.
ThemessageIDassociatedwiththisGoodbyemessageis0x7.Goodbyecancels
allsubscriptions.ClosetheTCPconnectionaftersendingGoodbye.Thereisno
responsetoGoodbye.ThedevicewillNOTsendaGoodbyewiththeInfobitset
intheflagsfield.
HiQnet Header for the Goodbye Message From Client VERSION
HEADERLENGTH
MESSAGELENGTH
1BYTE
1BYTE
4BYTE
SOURCEADDRESS
6BYTE
2
25
27
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
1‐65534
2Bytes
NODE
0
4Bytes
VD‐OBJECT
DESTINATIONADDRESS
6BYTE
MESSAGEID
FLAGS
HOPCOUNT
SEQUENCENUMBER
2BYTE
2BYTE
1BYTE
2BYTE
0x7
0x0020
5
0
14
Payload for the Goodbye Message From Client NODEID
2BYTE
12345
Device Objects and Parameters DeviceshaveanObject,Parameter,andAttributetreestructure.RunAudio
ArchitectorSystemArchitectandviewthetreestructureofadevicebydragging
anofflinedeviceofthetypeyouareinterestedinontotheVenueandusingthe
explorer.Forexample:
ByexpandingtheVenueExplorer,wecanseethatifwewanttosubscribetothe
“GainReductiondB”parameter,wewoulduseaDESTINATIONADDRESSof
0x0001forthe“Node”(orwhateverthenodeaddressisforthisdevice)and
0x03000100fortheVD‐OBJECTportion.That’sbecausethe“Audio”Virtual
DeviceisatID[3],andthe“P1”Objectisat[0.1.0].Then,forthePublisher
ParamIDwewoulduse9,since“GainReduction”isParameterID[9].
Bydouble‐clickingonthe“GainReduction”parameter,wegetawindow
describingtheAttributesthatbelongtothisparameter.Attributesaremetadata
thathavenamesandvalues.The“Min”attributeis‐80dbandthe“Max”attribute
is+40db,whichmeansthatthe“GainReduction”parameterisguaranteedto
haveavaluesomewhereinbetween‐80dband+40db(inclusive).
Note,the“GainReduction”parameterisameter(Sensor=True),so
MultiParamSet’sfromthedevicewillarriveperiodically(every50ms)onUDP
port3804attheclientapp.
15
MultiParamSubscribe example Fora4‐channelCrownDCiSeriesamplifier,saytheappsubscribestothe
Channel1AnalogInputFader.
WeseetheHiQnetNodeAddressis1,theVirtualDeviceis0,theCh1Analog
InputObjectAddressis1.8.1,andtheFaderParameterIDis3.Soa
MultiSVSubscribefromourappatHiQnetNodeAddress51wouldlooklikethis:
02190000002B003300000000000100010801010F002005000000
0100030000010001080100030000000000
AfastwaytogeneratestringslikethisistouseAudioArchitect’sThird‐party
Controllertool.Youcandragtheparametersyouwantontotheform,and
generateHiQnetmessagestringsforSet,Subscribe,andUnsubscribe.
Formoreinformationandmoremessages,seetheHiQnetThirdParty
Programmer’sGuideandtheGuidetoSoundcraft’sHiQnetConnectivity
documents.
16