SIERRA VIDEO SYSTEMS SP-14 API Protocol User’s Manual
This manual details the protocol used to remotely control your television broadcast image processor. Where pseudo code can clarify the protocol, it has been included. If you have any queries relating to this or any other product supplied by Kramer visit our Web site www.kramerelectronics.com . For technical support e-mail info@kramerel.com COPYRIGHT This document and the software described within it are copyrighted with all rights reserved.
Contents 1 2 Introduction .................................................................................................................... 1 Communication Ports ...................................................................................................... 1 2.1 RS232 ...................................................................................................................... 1 2.2 Ethernet .................................................................................................
1 Introduction This manual details the protocol used to remotely control your SP-14 image processor, where pseudo code clarifies the protocol that has been included. 2 Communication Ports The AV API protocol provides remote control functionality of units via RS232 and Ethernet. 2.1 RS232 The RS232 port is a 9-pin female connector. It is a three wire connection: RX, TX and ground. The unit has the following serial port settings: baud rate parity data bits stop bits 9600 none 8 1 2.
avPar_chCurr_pipSizeXY avPar_outputDisplay avPar_outputGammaMode avPar_pictureFormat 50 ms * 300 ms 250 ms 150 ms * This parameter has proved to be particularly troublesome and unpredictable with regard to the delay. It is recommended that special attention be paid and err on the side of caution. 3 API Functions All communications to the unit have fixed request packet size of 16 bytes. There are different reply packets for the class of function.
The fun, paramID, attribute and value values are numeric values (with the exception of set string) using Base 64 (see 3.4 Base 64 Encoding) and must be fully padded. Base 64 is used as a compromise between compressing numeric values whilst still using user readable characters. 3.2.1.1 Function The function identifier specifies the action or request to be performed.
Reserved Reserved Reserved Reserved Reserved avPar_pan avPar_tilt avPar_zoomX avPar_zoomY avPar_panZoomTiltReset Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved avPar_audioDelay avPar_inVideo avPar_factoryReset avPar_aspectRatioWidth avPar_aspectRatioHeight avPar_CCScorrection avPar_CUEcorrection avPar_ICPcorrection avPar_temporalNRLevel avPar_MPEGNREnable avPar_MPEGNRLevel avPar_movieMode avPar_blackLevel Reserved avPar_inAudio Reserved avPar_chTPG_select avPar_chSVGA_1_audio avPar_
avPar_chCVBS_1_button 88 AAABY avPar_chCVBS_2_button 89 AABZ avPar_chSDI_1_button avPar_chSVGA_1_reset avPar_chDVI_1_reset avPar_chHDMI_1_reset avPar_chSVid_1_reset Reserved avPar_chComp_1_reset Reserved avPar_chTPG_reset avPar_chCVBS_1_reset avPar_chCVBS_2_reset avPar_chSDI_1_reset 90 91 92 93 94 95 96 97 98 99 100 101 AABa AABb AABc AABd AABe AABf AABg AABh AABi AABj AABk AABl avPar_chComp_1_format Reserved 102 103 AABm AABn avPar_colorSpaceIn avPar_chHDMI_1_480i avPar_chHDMI_1_480p avPar_chHD
Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved avPar_infoFWVersion avPar_infoOutResolution avPar_infoOutFrameRate avPar_infoInResolution avPar_infoInFrameRate avPar_infoInHFreq avPar_infoOutHFreq avPar_infoGenlock avPar_infoGenlockSource avPar_infoIPAddrSource avPar_infoDHCPStatus avPar_infoMACAddress avPar_infoIPAddress avPar_infoSubnetMask avPar_infoGatewayIP 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
Reserved Reserved Reserved Reserved Reserved Reserved avPar_outputProcMode Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved avPar_colorNoSync avPar_preset1Load avPar_preset2Load avPar_preset3Load avPar_preset4Load avPar_preset1Reset avPar_preset2Reset avPar_preset3Reset avPar_preset4Reset Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved avPar_dhcpEnable avPar_staticIP avPar_subnetMask 192 193 194 195 196 197 198 199 200 201 202 203 20
Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved avPar_infoBTVersion Reserved avPar_LegacyMode avPar_unsharpmask Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved Reserved avPar_VTFilterStrength avPar_VTFilterRecursive Reserved Reserved Reserved Reserved Reserved Reserved Reserved 247 248 249 250 251 252 253 254 255 256 257 258 259 260 26
avPar_lumaGain avPar_R_Y_Gain avPar_B_Y_Gain avPar_lumaOffset avPar_R_Y_Offset avPar_B_Y_Offset avPar_audioChannelSwap01 avPar_audioChannelSwap23 avPar_audioChannelSwap45 avPar_audioChannelSwap67 avPar_refVertOffset avPar_refHorizOffset Reserved 300 301 302 303 304 305 306 307 308 309 310 311 312 AAEs AAEt AAEu AAEv AAEw AAEx AAEy AAEz AAE0 AAE1 AAE2 AAE3 AAE4 avPar_blueCheck 313 AAE5 avPar_safeAreaMarkers 314 AAE6 avPar_powerConfig avPar_infoPowerStatus1 avPar_infoPowerStatus2 315 316 317 AAE7 A
avPar_memcFrcExclusionZoneRBorder avPar_memcFrcExclusionZoneTBorder avPar_memcFrcExclusionZoneBBorder avPar_memcFrcExclusionZoneSBorder Reserved avPar_memcAdvancedParam1 avPar_memcAdvancedParam2 avPar_memcAdvancedParam3 avPar_memcAdvancedParam4 avPar_memcAdvancedParam5 avPar_memcAdvancedParam6 avPar_memcAdvancedParam7 avPar_memcAdvancedParam8 avPar_memcAdvancedParam9 avPar_memcAdvancedParam10 Reserved Reserved avPar_outputTimeCodeEnable avPar_TimeCodeOffset avPar_dropframeModeEnable avPar_TimeCodeSrcSel avP
3.2.1.3 Attribute The attribute identifier specifies the attribute of the parameter this action or request is related to. Identifier avParamAttr_avail avParamAttr_availValue avParamAttr_min avParamAttr_max avParamAttr_value avParamAttr_e2value Value 0 1 2 3 4 5 Base 64 AA AB AC AD AE AF Description Availability of the parameter. Availability of the specific parameter value. Minimum valid parameter value. Maximum valid parameter value. Parameter value (live). Parameter value (persistent).
3.2.2.2 Success Reply Packet with return value For a function that returns a numeric value the reply packet of a successful call will look like this: 1 ‘O’ 2 ‘K’ 3 ‘:’ 4 5 6 7 value 8 9 Where value is the requested value represented in base 64. 3.2.2.3 Success Reply Packet with string returned For a function that returns a string the reply packet of a successful call will look like this: 1 ‘O’ 2 ‘K’ 3 ‘:’ 4 …n ASCII characters … The string length will vary.
3.2.3 Query The query function provides information about the functions implemented for each parameter. There are two type of query function: single query and a query all functions. The single query will return true (1) or false (0) indicating if the function for the specified function, attribute, parameter combination is implemented. The query all will return a value where the binary digits indicate where specific functions/attribute combination as been implemented.
3.2.4 Get The get function is used to obtain a number of attribute of the specified parameter. The parameter request packet takes the following format: 1 2 3 4 5 6 7 8 9 10 ‘A’ ‘P’ ‘B’ paramID attribute Where ‘A’, ‘P’, ‘B’ paramID attribute value 11 12 13 value 14 15 16 ‘A’ are literal ASCII characters. is the parameter identifier. (see 3.2.1.2 Parameter Identifier) is the attribute identifier. (see 3.2.1.3 Attribute) is a value.
The parameter request packet takes the following format: 1 2 3 4 5 6 7 8 9 10 ‘A’ ‘P’ ‘C’ paramID attribute Where ‘A’, ‘P’, ‘C’ paramID attribute value 11 12 13 value 14 15 16 ‘A’ are literal ASCII characters. is the parameter identifier. (see 3.2.1.2 Parameter Identifier) is the attribute identifier. (see 3.2.1.3 Attribute) is a value. Only the avParamAttr_value and avParamAttr_e2value attributes may be set and these must be use together.
3.2.7 Set String The set string function is used to set a string, however it is restricted to six ASCII characters. Only a few parameters implement this function. The parameter request packet takes the following format: 1 2 3 4 5 6 7 8 9 10 ‘A’ ‘P’ ‘E’ paramID attribute Where ‘A’, ‘P’, ‘E’ paramID attribute value 11 12 13 Value 14 15 16 ‘A’ are literal ASCII characters. is the parameter identifier. (see 3.2.1.2 Parameter Identifier) is the attribute identifier. (see 3.2.1.3 Attribute) is a value.
3.3 Guidelines for AV API Usage The AV API was designed to be a generalised interface to control units and as such provides access to a number of different parameter types. This is reflected in the functions that are implemented for the various parameters. It is advisable to follow these guidelines when implementing any user interface for controlling units. 3.3.1 Query Function The purpose of query function is to ascertain which functions are available to a parameter.
used to convert the numeric value into a string and hides the numbers from the user. Note that the get string function may return a different string for a particular value on separate occasions. 3.3.5.3.1 Example scenario To demonstrate how all the functions are interrelated and work together, the following sections present pseudo code showing how the API is intended to be used and is used within our own user interface software both in firmware and on a PC. 3.3.5.3.
end if if succ then succ = get(paramID => avPar_contrast, attribute => avParamAttr_e2value, value => val); end if if succ then if (qfuncs and avQueryFunc_get_availValue) > 0 then valAvail = val; succ = get(paramID => avPar_contrast, attribute => avParamAttr_availValue, value => valAvail); else valAvail = TRUE; end if end if if succ then if (qfuncs and avQueryFunc_gets) > 0 then succ = gets(paramID => avPar_contrast, attribute => avParamAttr_value, value => val, returned string => st); else st = convertToStr
if valAvail then succ = set(paramID => avPar_contrast, attribute => avParamAttr_value, value => newval); if succ then oldval = newval; -- update old value end if else -- value not available: do not set indicate on UI that value is not available end if else newval = oldval; -- revert change end if if succ then if (qfuncs and avQueryFunc_gets) > 0 then succ = gets(paramID => avPar_contrast, attribute => avParamAttr_value, value => val, returned string => st); else st = convertToString(val); end if display st
3.4 Base 64 Encoding Base 64 is used as a compromise between compressing numeric values whilst still using human readable ASCII characters. Base 64 is used by various internet protocols. Base 64 is defined in “RFC 3548 The Base16, Base32, and Base64 Data Encodings July 2003” and is available on the internet at http://www.faqs.org/rfcs/rfc3548.html.
Base 10 Base 16 Base 64 0 0x000 AAAAAA 1 0x001 AAAAAB 2 0x002 AAAAAC 3 0x003 AAAAAD 4 0x004 AAAAAE 5 0x005 AAAAAF 6 0x006 AAAAAG 7 0x007 AAAAAH 8 0x008 AAAAAI 9 0x009 AAAAAJ 10 0x00A AAAAAK 11 0x00B AAAAAL 12 0x00C AAAAAM 13 0x00D AAAAAN 14 0x00E AAAAAO 15 0x00F AAAAAP 16 0x010 AAAAAQ 17 0x011 AAAAAR 18 0x012 AAAAAS 19 0x013 AAAAAT 20 0x014 AAAAAU 21 0x015 AAAAAV 22 0x016 AAAAAW 23 0x017 AAAAAX 24 0x018 AAAAAY 25 0x019 AAAAAZ 2
146 0x092 AAAACS 195 0x0C3 AAAADD 244 0x0F4 AAAAD0 147 0x093 AAAACT 196 0x0C4 AAAADE 245 0x0F5 AAAAD1 148 0x094 AAAACU 197 0x0C5 AAAADF 246 0x0F6 AAAAD2 149 0x095 AAAACV 198 0x0C6 AAAADG 247 0x0F7 AAAAD3 150 0x096 AAAACW 199 0x0C7 AAAADH 248 0x0F8 AAAAD4 152 0x098 AAAACY 200 0x0C8 AAAADI 249 0x0F9 AAAAD5 151 0x097 AAAACX 201 0x0C9 AAAADJ 250 0x0FA AAAAD6 153 0x099 AAAACZ 202 0x0CA AAAADK 251 0x0FB AAAAD7 154 0x09A AAAACa 203 0x0CB
293 0x125 AAAAEl 342 0x156 AAAAFW 391 0x187 AAAAGH 294 0x126 AAAAEm 343 0x157 AAAAFX 392 0x188 AAAAGI 295 0x127 AAAAEn 344 0x158 AAAAFY 393 0x189 AAAAGJ 296 0x128 AAAAEo 345 0x159 AAAAFZ 394 0x18A AAAAGK 297 0x129 AAAAEp 346 0x15A AAAAFa 395 0x18B AAAAGL 298 0x12A AAAAEq 347 0x15B AAAAFb 396 0x18C AAAAGM 299 0x12B AAAAEr 348 0x15C AAAAFc 398 0x18E AAAAGO 300 0x12C AAAAEs 349 0x15D AAAAFd 397 0x18D AAAAGN 301 0x12D AAAAEt 350 0x15E
440 0x1B8 AAAAG4 461 0x1CD AAAAHN 482 0x1E2 AAAAHi 441 0x1B9 AAAAG5 462 0x1CE AAAAHO 483 0x1E3 AAAAHj 442 0x1BA AAAAG6 463 0x1CF AAAAHP 484 0x1E4 AAAAHk 443 0x1BB AAAAG7 464 0x1D0 AAAAHQ 485 0x1E5 AAAAHl 444 0x1BC AAAAG8 465 0x1D1 AAAAHR 486 0x1E6 AAAAHm 445 0x1BD AAAAG9 466 0x1D2 AAAAHS 487 0x1E7 AAAAHn 446 0x1BE AAAAG+ 467 0x1D3 AAAAHT 488 0x1E8 AAAAHo 447 0x1BF AAAAG/ 468 0x1D4 AAAAHU 489 0x1E9 AAAAHp 448 0x1C0 AAAAHA 469 0x1D5
