SFT-INTSRV - Allegiant Satellite SDK. User Guide Allegiant Satellite SDK Version 1.00

Transcription

1 SFT-INTSRV - Allegiant Satellite SDK EN User Guide Allegiant Satellite SDK Version 1.00

2 Allegiant Satellite SDK User Guide Contents EN 2 Table of Contents 1.0 UNPACKING Parts List Description Features Provided by the SDK Allegiant Matrix Switcher Compatibility Recommended PC Platform Supported Containers SDK Library File Descriptions SDK Software Installation SDK Redistribution ALLEGIANT SDK DEPLOYMENT System Diagram System Settings USING THE ALLEGIANT SDK IN A CLIENT APPLICATION Communications Configuration Selecting the Parser Mode Starting the Allegiant Command Parser Stopping the Allegiant Command Parser Handling Camera Switching Commands Processing PTZ Commands Translating Continuous PTZ Operations to their Indefinite Equivalents Error Handling Connecting to Multiple LTC 8780 Units SDK Version Information Limitations

3 Allegiant Satellite SDK User Guide Unpacking EN UNPACKING Verify that all parts shown in the Parts List have been included. If any items are missing, notify your Bosch Security Systems Sales or Customer Service Representative. 1.1 Parts List Although the SFT-INTSRV software package includes several components, only the following items are applicable to the Allegiant Satellite SDK software: Qty Item 1 Allegiant Satellite SDK User Guide (this book) 1 "SFT-INTSRV" CD-ROM containing Allegiant Satellite SDK software files 1 RS-232 interface cable (Bosch Security Systems Part #S1385) 1 Software License Agreement 1.2 Description The Allegiant Satellite Software Development Kit (SDK) is a fully supported set of libraries, documentation, and samples targeted at PC-based application software that is used to control 3rd party CCTV matrix systems or manage IP-based digital video networks. Since the SDK can be used to create customized solutions for unique, specific problems, customers looking to integrate an Allegiant matrix system with products offered by other manufacturers is readily accomplished. For the thousands of existing Allegiant customers, it also provides a bridge to integrate or expand their systems with IP-based products gradually rather than a total and instantaneous replacement. When operating in an Allegiant satellite system configuration, an Allegiant master generates switching and PTZ data that is typically used to control a remote Allegiant satellite matrix. Using the SDK, the video switching commands and PTZ data from the master system are converted into an ActiveX interface method allowing developers to easily translate this information into formats used to control other original equipment manufacturer s (OEM) systems. The SDK also supports an ability to translate repetitive type Allegiant PTZ commands to their indefinite equivalents, resulting in reduced interface traffic and lower bandwidth demands when controlling IP-based networks. The level of integration available with the SDK results in a robust interface that provides transparent operation to the existing Allegiant operators. Operators continue to use their existing CCTV keyboards for selecting video and control of PTZ devices on the Allegiant monitors. This type of solution improves the return of investment on existing capital assets, removes the need for training, and reduces the risk for adopting new technology by incrementally adding to the system. The SDK is compatible with all models of the Allegiant Series switchers. In addition to video switching commands and PTZ control, auxiliaries and prepositions are also supported. The SDK is supplied with five (5) sample applications. Three (3) use C++ to demonstrate incorporating the SDK in a Console, ATL, and MFC application. In addition, samples using Visual Basic, and Microsoft s.net Framework are included. 1.3 Features Provided by the SDK Seamlessly Integrate 3rd Party Analog or Digital CCTV Systems with Bosch Allegiant Series Matrix Switchers Supports Video Switching and PTZ Commands, Including Aux and Preposition Functions Translates Continuous PTZ Commands to their Indefinite Equivalents for Bandwidth Reduction Supports Allegiant LTC 8100 thru LTC 8900 Series Matrix Switchers Integrate with applications developed using C/C++, Visual Basic, and.net 1.4 Allegiant Matrix Switcher Compatibility The Allegiant Satellite SDK software is compatible with any Alllegiant Series system that supports Satellite configuration. Minimum Allegiant CPU firmware required to support Satellite configurations is version 4.0 or later (i.e., units manufactured after 1991). 1.5 Recommended PC Platform Microsoft Windows compatible PC, Intel Pentium 2.8 GHz or greater Operating Systems Windows 2000 (Service Pack 3 or later) Windows XP Professional 512 Mb RAM 50 Mb Fixed Drive space CD-ROM Drive Ports required (Minimum) 1 Serial port for external interface communications Additional serial ports required if multiple systems are being interfaced SVGA display or compatible display

4 Allegiant Satellite SDK User Guide Unpacking EN Supported Containers The Allegiant Satellite SDK is designed to support the following ActiveX Client containers. ActiveX containers developed with Microsoft Visual C Microsoft Visual Studio.NET applications Microsoft Visual Basic 1.7 SDK Library File Descriptions The SDK contents are described below, with respect to SDK installation folder. Folder Filename(s) Description Documentation Allegiant_UG_F01U PDF This document Documentation Allegiant Satellite SDK Interface Definition.chm Examples/ATL Multiple Source and executable files Examples/C++ Examples/DOTNET Examples/MFC Examples/Visual Basic LTC8780_Command Parser DLL LTC8780_Command Parser DLL/Debug LTC8780_CommandParser.dll LTC8780_CommandParser.tlb LTC8780_CommandParser.dll Documents the classes and interfaces of the SDK Source Code and runnable samples illustrating the integration of the SDK in the indicated environments The SDK DLL compiled in Release mode and.tlb (type library) file. This DLL must be registered for use by a client (see Installation Section 3.0) The SDK DLL compiled in Debug mode (will provide TRACE messages for debugging purposes) 1.8 SDK Software Installation SDK Installation The SDK contents described above can be copied from the distribution media and copied to any location on the software developers hard disk. Register the LTC8780_CommandParser.dll using the command "regsvr32 LTC8780_CommandParser.dll", from a command prompt Installing the.net Example The.NET examples requires for the correct version of Microsoft s.net framework installed on the host machine prior to running it, this sample was built using MS Visual Studio.NET 2003 and the.net Framework version 1.1. The framework can be downloaded from Microsoft s website using the following link; pdates/default.aspx 1.9 SDK Redistribution To redistribute the Allegiant Satellite SDK along with a client application, the rules noted below must be followed. 1. Only the LTC8780_CommandParser.dll may be redistributed, and copyright notices may not be removed or altered 2. The LTC8780_CommandParser.dll redistributed to end-user PCs must be copied to the <common files>\bosch Security Systems folder. The <common files> value is located in the registry at: key: HKEY_LOCAL_MACHINE \ SOFTWARE \ Microsoft \ Windows \ CurrentVersion value: CommonFilesDir 3. Existing copies of LTC8780_CommandParser.dll should only be overwritten if their version numbers are lower than those of the copies being redistributed. 4. The LTC8780_CommandParser.dll must be registered such as running the following command at the command prompt in the same directory where the DLL is located; regsvr32 LTC8780_CommandParser.dll If the above rules are not followed, applications that use the SDK may not function properly. For installation of the redistributable components on an end-user s PC, refer to SDK Redistribution Section.

5 RS-232 IN CODE OUT CODE IN RS-232 OUT ON Allegiant Satellite SDK User Guide Allegiant SDK Deployment EN ALLEGIANT SDK DEPLOYMENT 2.1 System Diagram Allegiant "Master" System ALLEGIANT Video Matrix BOSCH Biphase Code Containing: P/T/Z commands Satellite commands Crosspoint data (optional) Alarm data (optional) LTC 8780 Satellite Address Decoder RS-232 Interface IAllegiantParser LTC8780_CommandParser.dll PC Client interface to Control the LTC8780 Command Parser OSRD data Satellite data Crosspoint data IOSRDCommand ISatelliteCommand ICrosspointInfo Client Application Figure 1: System Diagram The client application controls the LTC 8780 Command Parser using the exposed IAllegiantParser COM interface. The client application implements the three interfaces shown, and passes them to the LTC 8780 Command Parser, to use in returning data to the client. Specifics relating to the uses of the interfaces are provided in Section 3, Using the Allegiant SDK and are illustrated by examining the source code provided with the example applications provided as part of this SDK.

6 Allegiant Satellite SDK User Guide Allegiant SDK Deployment EN System Settings Configuring the Allegiant Master Satellite System The SDK is designed to work with an Allegiant matrix/controller setup in a satellite configuration. It requires an Allegiant matrix/switcher, an LTC 8780 Data Converter Unit and a PC work station. Familiarity with the Allegiant Matrix Switch control system, Windows-based software, and a general knowledge of networking is required. Refer to the Allegiant Instruction Manual for configuring the Allegiant system to operate as a master system in an Allegiant Satellite configuration. Allegiant manuals are available for download from the Bosch website: Configuring the LTC 8780 Data Converter Unit The LTC 8780 Data Converter is required to convert Allegiant Satellite commands into a format that matches the software settings. Connect the LTC 8780 CODE IN connector to the biphase port of the Allegiant. Refer to the LTC 8780 manual for biphase connections, which can be found on the Bosch website: The LTC 8780 is connected to the PC s COM port using a Bosch S1385 or Industry standard Null modem RS-232 data cable. The data rate of the RS-232 interface should be set to 38.4 kbs Hardware handshaking should be enabled See Table 1 and Table 2 below for DIP Switch settings. DIP Switch Switch Number Recommended Table 1: DIP Switch Settings Setting Function S101 1 (BAUD) ON RS-232 Baud Rate 2 (BAUD) ON of (CODE DIST) OFF Biphase input to Biphase output 4 (ADDR FUNCT) OFF CCL Address Select S102 1 (RCVR DRVR) ON Enable transmission of R/D messages S103 S104 2 (XPOINT) OFF Disable transmission Crosspoint messages 3 (CCL) ON Enable transmission of CCL messages 4 (MATCH) ON Set to OFF to disable CCL message addresses checking 1 4 (ADDR LOW) 1 4 (ADDR HIGH) (See Table 2) (See Table 2) Address or Block Select Low Order Bits (Must be set to Satellite Address) Address or Block select high order bits (Must be set to Satellite Address) S105 1 (MODEM CMD) OFF Not applicable 2 (ORIGINATE) OFF Modem command + ATA 3 (CHECK CTS) ON Check CTS before transmitting data 4 OFF Not used

7 Allegiant Satellite SDK User Guide Using the Allegiant SDK in a Client Application EN 7 Address DIP Switches S104 Table 2: CCL Address Select S OFF OFF OFF OFF OFF OFF OFF OFF 1 OFF OFF OFF OFF OFF OFF OFF ON 2 OFF OFF OFF OFF OFF OFF ON OFF 3 OFF OFF OFF OFF OFF OFF ON OFF 4 OFF OFF OFF OFF OFF OFF OFF OFF 5 OFF OFF OFF OFF OFF OFF OFF ON 6 OFF OFF OFF OFF OFF ON ON OFF 7 OFF OFF OFF OFF OFF ON ON ON 8 CCL Address Select X X X X X X X X (continue series) ON ON ON ON ON ON ON OFF 255 ON ON ON ON ON ON ON ON Using the LTC 8780 Data Converter Unit with Address Matching Enabled The Data Converter unit can be configured to either forward all CCL commands that are received from the Master Allegiant system or only forward commands that match the Address of the Data Converter unit. Switch #4 on dip switch S101 enables the Address function and Switch #4 on dip switch S102 enables Address matching, the format of CCL messages will vary based on how your configure the dip switches. 3.0 USING THE ALLEGIANT SDK IN A CLIENT APPLICATION Refer to the Allegiant Satellite SDK Interface Definition for details about the interfaces and the object model of the SDK. The below sections explain programming tasks relevant to creating an application using the Allegiant SDK. Use the below in conjunction with the supplied sample applications. 3.1 Communications Configuration The communication configuration of the LTC 8780 Command Parser must match the hardware settings of the LTC 8780 or the parser will not be able to receive and decode the incoming commands. The configuration items are exposed as properties of the parser component Configuring the RS-232 Serial Port The baud rate, RS-232 handshaking mode and COM port name must match the settings in the LTC The following properties can be used to apply the settings; Using the IAllegiant interface, which is exposed by the AllegiantParser coclass set the following properties; PortName( ) BaudRate( ) -RS-232 PC port that is connected to code converter -Baud rate setting using jumpers S101 on the Data converter HandShake( ) -Handshake mode as set using jumper S105 on the Data converter Once configured the serial port can be opened and closed using the OpenCOMM( ) and CloseCOMM( ) methods on the IAllegiantParser interface Select Address Matching The Command Parser exposes a property UseMessageHeader( ) on the IAllegiantParser interface which needs to be set to true when Address matching is disabled and false otherwise (see Section 2.2.2, Configuring the LTC 8780 Data Converter Unit). 3.2 Selecting the Parser Mode The command parser supports three independent modes, ParserModeOSRD( ) for OSRD commands, ParserModeSatellite( ) for Satellite commands and ParserModeCrosspoint( ) for crosspoint commands, all these properties are members of the IAllegiantParser interface.

8 Allegiant Satellite SDK User Guide Using the Allegiant SDK in a Client Application EN 8 Each property is of type PARSER_MODE that takes either a bitmap or one of the following values: PARSER_MODE_PROCESS - process all commands and forward using interface methods PARSER_MODE_USE_RAW_METHOD - semi process the command and forward using raw method that includes device address. In addition, this mode can be combined as a bitmap to set exceptions for commands that still need to be forwarded to the appropriate interface methods. PARSER_MODE_RAW - no processing required just forward all commands to the raw interface The following code snippet displays how to set the parser mode; // set the parser mode to send raw OSRD // commands but supply the logical camera // number and the message //payload, use // interface methods to deliver Aux and // Prepos commands piallegtparser- >put_parsermodeosrd(parser_mode_use_raw_meth OD PROCESS_AUX_PREPOS); // set the parser mode to send raw Satellite // commands but supply the logical camera // number and the message // payload piallegparser->put_parsermodesatellite (PARSER_MODE_USE_RAW_METHOD); // set the parser mode to process all // Crosspoint commands and deliver them // to interface methods 3.3 Starting the Allegiant Command Parser Once all the communication settings have been applied, (per the above) call the StartParser( ) method from the IAllegiantParser interface supplying at least one callback interface pointer (IOSRDCommand, ISateliteCommand or IcrossPointInfo). This method is asynchronous and will return once the parser has been started. Incoming messages will be pushed to the appropriate callbacks as they arrive on the wire. 3.4 Stopping the Allegiant Command Parser The command parser can be stopped at any moment by invoking the Stop( ) method. 3.5 Handling Camera Switching Commands The camera switching commands are periodically sent to the ISateliteCommand interface through the SetCameraOnLogicalMonitor( ) method, using the interface supplied by the client application as an argument to StartParser( ). 3.6 Processing PTZ Commands PTZ commands are forwarded to the IOSRDCommand interface of the Client, using the interface supplied by the client application as an argument to StartParser( ). Based on the ParserModeOSRD property setting the commands will either be decomposed and forwarded to interface methods or they will be sent to one of the raw methods. When the ParserModeOSRD is set to USE_RAW_METHOD all commands will be channeled to the PutRawOSRDCommand( ) method. The second parameter (arrrawcommand) contains the raw PTZ payload that can be decoded by an Autodome Camera hence it is probably the most efficient way for the client application to transparently transmit PTZ commands. piallegparser>put_parsermodecrosspoin (PARSER_MODE_PROCESS); // kick off the parser piallegparser->startparser (m_piosrdcommand, m_pisatelitecommand, m_picrosspointcommand);

9 Allegiant Satellite SDK User Guide Using the Allegiant SDK in a Client Application EN Translating Continuous PTZ Operations to their Indefinite Equivalents The motion of the AutoDome camera may be jittery when continuous PTZ operations are used. This is due to network latencies that slow down the transmission of packets. Furthermore much more bandwidth is consumed when sending out repetitive commands. The command parser can be instructed to convert continuous PTZ operations to their indefinite equivalents, in this mode the Application will only receive two commands, one to start the indefinite PTZ operation and a last one to cancel the last PTZ operation. When using variable speed PTZ commands, the client application will only get speed updates. The EnableRepetitiveCommands( ) properties of interface IAllegiantParser enables the PTZ command translation when set to false. 3.8 Error Handling Every interface method returns an HRESULT. When an error condition occurs, the low order bytes of the HRESULT will contain the error code. Once this value has been extracted, it will map to one of the values in PARSER_ERROR enum. The following code snippet displays how to extract the error code:;.. HRESULT hr = S_OK; //attempt to open the serial port hr = piallegiantparser- >OpenCOMM(_bstr_t("COM1")); // check the return value if (FAILED(hr)) { PARSER_ERROR eerror = (PARSER_ERROR)HRESULT_CODE(hr); if(parser_error_port_open_failed == eerror) { std::cout << "Failed to open the specified Communication port"; } } 3.9 Connecting to Multiple LTC 8780 Units For each LTC 8780 unit that the client application wishes to connect to, one instance of the AllegiantParser object must be created and each unit needs a unique serial port. For example, if the client wants to connect three (3) Data converters then three (3) AllegiantParser objects instances and three (3) serial ports will be required. In addition, the client application may need separate callback objects so that they can determine what parser instance fired the callback SDK Version Information The LTC8780_CommandParser.dll version information can be retrieved by using Windows Explorer, simply right click on the file, select properties and go to the Version tab Limitations The below have not been implemented, and are included in the Allegiant Satellite SDK Interface Definition document for reference only: IMonitor interface ICrossPointInfo interface IAllegiant::ParserTrigger() method

10 Allegiant Satellite SDK User Guide EN 10

11 Allegiant Satellite SDK User Guide EN 11

12 Americas Bosch Security Systems 130 Perinton Parkway Fairport, New York, 14450, USA Phone: +1 (585) Europe, Middle East, Africa Bosch Security Systems B.V. P.O. Box JB Eindhoven, The Netherlands Phone: +31 (0) Fax: +31 (0) Asia-Pacific Bosch Security Systems Pte Ltd 38C Jalan Pemimpin Singapore Phone: Fax: Bosch Security Systems GmbH F01U Updated March 21, 2005 Data subject to change without notice. Intel and Pentium are registered trademarks of Intel. Windows is a registered trademark of Microsoft Corporation. Allegiant is registered by Bosch Security Systems, Inc. in the US Patent Trademark Office.