Allegiant Satellite SDK

12 Pages·2005·0.16 MB·English

SFT-INTSRV - Allegiant Satellite SDK
User Guide
EN Allegiant Satellite
SDK Version 1.00
Allegiant Satellite SDK| User Guide| Contents EN|2
Table of Contents
1.0 UNPACKING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.1 Parts List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.3 Features Provided by the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.4 Allegiant Matrix Switcher Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.5 Recommended PC Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.6 Supported Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.7 SDK Library File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.8 SDK Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.9 SDK Redistribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
2.0 ALLEGIANTSDKDEPLOYMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
2.1 System Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
2.2 System Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
3.0 USING THE ALLEGIANT SDK IN A CLIENT APPLICATION . . . . . . . . . . . . . . . . . . . . . . . .7
3.1 Communications Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
3.2 Selecting the Parser Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
3.3 Starting the Allegiant Command Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
3.4 Stopping the Allegiant Command Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
3.5 Handling Camera Switching Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
3.6 Processing PTZ Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
3.7 Translating Continuous PTZ Operations to their Indefinite Equivalents . . . . . . . . . . . . . . . . . . . . .9
3.8 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
3.9 Connecting to Multiple LTC 8780 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
3.10 SDK Version Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
3.11 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide| Unpacking EN|3
1.0 UNPACKING selecting video and control of PTZ devices on the
Allegiant monitors. This type of solution improves the
Verify that all parts shown in the Parts List have been
return of investment on existing capital assets, removes
included. If any items are missing, notify your Bosch
the need for training, and reduces the risk for adopting
Security Systems Sales or Customer Service Representative.
new technology by incrementally adding to the system.
1.1 Parts List
The SDK is compatible with all models of the
Although the SFT-INTSRV software package includes
Allegiant Series switchers. In addition to video
several components, only the following items are
switching commands and PTZ control, auxiliaries and
applicable to the Allegiant Satellite SDK software: prepositions are also supported.
Qty Item The SDK is supplied with five (5) sample applications.
1 Allegiant Satellite SDK User Guide (this book) Three (3) use C++ to demonstrate incorporating the
1 "SFT-INTSRV" CD-ROM containing Allegiant Satellite SDK SDK in a Console, ATL, and MFC application. In
software files
addition, samples using Visual Basic®, and
1 RS-232 interface cable (Bosch Security Systems Part Microsoft’s® .NET Framework are included.
#S1385)
1 Software License Agreement
1.3 Features Provided by the SDK
1.2 Description • Seamlessly Integrate 3rd Party Analog or Digital
CCTV Systems with Bosch Allegiant Series
The Allegiant Satellite Software Development Kit
Matrix Switchers
(SDK) is a fully supported set of libraries,
• Supports Video Switching and PTZ Commands,
documentation, and samples targeted at PC-based
Including Aux and Preposition Functions
application software that is used to control 3rd party
• Translates Continuous PTZ Commands to their
CCTV matrix systems or manage IP-based digital
Indefinite Equivalents for Bandwidth Reduction
video networks.
• Supports Allegiant LTC 8100 thru LTC 8900
Since the SDK can be used to create customized
Series Matrix Switchers
solutions for unique, specific problems, customers
• Integrate with applications developed using
looking to integrate an Allegiant matrix system with
C/C++, Visual Basic®, and .NET
products offered by other manufacturers is readily
accomplished. For the thousands of existing Allegiant
1.4 Allegiant Matrix Switcher Compatibility
customers, it also provides a bridge to integrate or
The Allegiant Satellite SDK software is compatible
expand their systems with IP-based products gradually
with any Alllegiant Series system that supports Satellite
rather than a total and instantaneous replacement.
configuration. Minimum Allegiant CPU firmware
When operating in an Allegiant satellite system
required to support Satellite configurations is version
configuration, an Allegiant master generates switching
4.0 or later (i.e., units manufactured after 1991).
and PTZ data that is typically used to control a remote
Allegiant satellite matrix. Using the SDK, the video
1.5 Recommended PC Platform
switching commands and PTZ data from the master
system are converted into an ActiveX interface method • Microsoft Windows® compatible PC, Intel®
allowing developers to easily translate this information Pentium® 2.8 GHz or greater
into formats used to control other original equipment • Operating Systems
manufacturer’s (OEM) systems. The SDK also • Windows 2000 (Service Pack 3 or later)
supports an ability to translate repetitive type Allegiant • Windows XP Professional
PTZ commands to their indefinite equivalents, • 512 Mb RAM
resulting in reduced interface traffic and lower • 50 Mb Fixed Drive space
bandwidth demands when controlling IP-based • CD-ROM Drive
networks. • Ports required (Minimum)
• 1 Serial port for external interface
The level of integration available with the SDK results
communications
in a robust interface that provides transparent
• Additional serial ports required if
operation to the existing Allegiant operators. Operators
multiple systems are being interfaced
continue to use their existing CCTV keyboards for
• SVGA display or compatible display
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide| Unpacking EN|4
1.6 Supported Containers 1.8.2 Installing the .NET Example
The .NET examples requires for the correct version
The Allegiant Satellite SDK is designed to support
of Microsoft’s® .NET framework installed on the host
the following ActiveX Client containers.
machine prior to running it, this sample was built
• ActiveX containers developed with using MS Visual Studio .NET 2003 and the
Microsoft Visual C++ 6.0 .NET Framework version 1.1.
• Microsoft Visual Studio .NET applications
The framework can be downloaded from Microsoft’s
• Microsoft Visual Basic
website using the following link;
1.7 SDK Library File Descriptions http://msdn.microsoft.com/netframework/downloads/u
The SDK contents are described below, with respect to pdates/default.aspx
SDK installation folder.
Folder Filename(s) Description 1.9 SDK Redistribution
Documentation Allegiant_UG_F01U008398.PDF This document To redistribute the Allegiant Satellite SDK along with a
client application, the rules noted below must be
Documentation Allegiant Satellite SDK Interface Documents the
Definition.chm classes and followed.
interfaces of the
1. Only the LTC8780_CommandParser.dll may be
SDK
redistributed, and copyright notices may not be
Examples/ATL Multiple Source and executable files Source Code
Examples/C++ and runnable removed or altered
Examples/DOTNET samples
Examples/MFC illustrating the 2. The LTC8780_CommandParser.dll redistributed
Examples/Visual Basic integration of to end-user PCs must be copied to the
the SDK in the
<common files>\Bosch Security Systems folder.
indicated
environments The <common files> value is located in the
LTC8780_Command LTC8780_CommandParser.dll The SDK DLL registry at:
Parser DLL LTC8780_CommandParser.tlb compiled in
Release mode
key: HKEY_LOCAL_MACHINE \
and .tlb (type
library) file. This SOFTWARE \ Microsoft \ Windows \
DLL must be
CurrentVersion
registered for
use by a client
(see Installation value: CommonFilesDir
Section 3.0)
3. Existing copies of LTC8780_CommandParser.dll
LTC8780_Command LTC8780_CommandParser.dll The SDK DLL
Parser DLL/Debug compiled in should only be overwritten if their version
Debug mode
numbers are lower than those of the copies
(will provide
being redistributed.
TRACE
messages for
4. The LTC8780_CommandParser.dll must be
debugging
purposes) registered such as running the following
command at the command prompt in the same
1.8 SDK Software Installation directory where the DLL is located;
1.8.1 SDK Installation
The SDK contents described above can be copied regsvr32 LTC8780_CommandParser.dll
from the distribution media and copied to any location
If the above rules are not followed, applications that
on the software developers hard disk.
use the SDK may not function properly.
Register the LTC8780_CommandParser.dll using the
command "regsvr32 LTC8780_CommandParser.dll",
from a command prompt.
For installation of the redistributable components on
an end-user’s PC, refer to SDK Redistribution Section.
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide | Allegiant SDK Deployment EN|5
2.0 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)
RS-23C2O IDNE OUT CODER SIN-232 OUT ON LTC 8780 Satellite
Address Decoder
RS-232 Interface
PC
IAllegiantParser LTC8780_CommandParser.dll
e
Control thnd Parser atad DRSO dataSatellite Cdraotsaspoint
e to mma
ac o
nterf80 C
ent iC87
CliLT 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.
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide| Allegiant SDK Deployment EN|6
2.2 System Settings DIP Switch Number Recommended Function
Switch Setting
S101 1 (BAUD) ON RS-232 Baud Rate
2.2.1 Configuring the Allegiant Master Satellite
of 38400
System 2 (BAUD) ON
The SDK is designed to work with an Allegiant
3 (CODE DIST) OFF Biphase input to
matrix/controller setup in a satellite configuration. It Biphase output
requires an Allegiant matrix/switcher, an LTC 8780
4 (ADDR FUNCT) OFF CCL Address Select
Data Converter Unit and a PC work station.
S102 1 (RCVR DRVR) ON Enable transmission
Familiarity with the Allegiant Matrix Switch control of R/D messages
system, Windows-based software, and a general 2 (XPOINT) OFF Disable transmission
Crosspoint
knowledge of networking is required.
messages
Refer to the Allegiant Instruction Manual for 3 (CCL) ON Enable transmission
of CCL messages
configuring the Allegiant system to operate as a
‘master’ system in an Allegiant Satellite configuration. 4 (MATCH) ON Set to OFF to
disable CCL
Allegiant manuals are available for download from the
message addresses
Bosch website: www.boschsecurity.com checking
S103 1 – 4 (ADDR (See Table 2) Address or Block
2.2.2 Configuring the LTC 8780 Data Converter Unit
LOW) Select Low Order
• The LTC 8780 Data Converter is required to Bits (Must be set to
Satellite Address)
convert Allegiant Satellite commands into a
S104 1 – 4 (ADDR (See Table 2) Address or Block
format that matches the software settings.
HIGH) select high order bits
• Connect the LTC 8780 CODE IN connector to (Must be set to
Satellite Address)
the biphase port of the Allegiant.
S105 1 (MODEM CMD) OFF Not applicable
• Refer to the LTC 8780 manual for biphase
connections, which can be found on the Bosch 2 (ORIGINATE) OFF Modem command +
ATA
website: www.boschsecurity.com.
3 (CHECK CTS) ON Check CTS before
• The LTC 8780 is connected to the PC’s COM
transmitting data
port using a Bosch S1385 or Industry standard
4 OFF Not used
Null modem RS-232 data cable.
Table 1: DIP Switch Settings
• 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.
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide| Using the Allegiant SDK in a Client Application EN|7
Address DIP Switches CCL Address The below sections explain programming tasks
Select
relevant to creating an application using the Allegiant
S104 S103
SDK. Use the below in conjunction with the supplied
4 3 2 1 4 3 2 1
sample applications.
OFF OFF OFF OFF OFF OFF OFF OFF 1
3.1 Communications Configuration
OFF OFF OFF OFF OFF OFF OFF ON 2 The communication configuration of the LTC 8780
Command Parser must match the hardware settings of
OFF OFF OFF OFF OFF OFF ON OFF 3
the LTC 8780 or the parser will not be able to receive
and decode the incoming commands. The configuration
OFF OFF OFF OFF OFF OFF ON OFF 4
items are exposed as properties of the parser component.
OFF OFF OFF OFF OFF OFF OFF OFF 5
3.1.1 Configuring the RS-232 Serial Port
The baud rate, RS-232 handshaking mode and COM
OFF OFF OFF OFF OFF OFF OFF ON 6
port name must match the settings in the LTC 8780.
The following properties can be used to apply the
OFF OFF OFF OFF OFF ON ON OFF 7
settings;
OFF OFF OFF OFF OFF ON ON ON 8 Using the IAllegiant interface, which is exposed by the
AllegiantParser coclass set the following properties;
X X X X X X X X (continue
series) PortName(…) -RS-232 PC port that is
connected to code converter
ON ON ON ON ON ON ON OFF 255
BaudRate(…) -Baud rate setting using
ON ON ON ON ON ON ON ON 256
jumpers S101 on the Data
converter
Table 2: CCL Address Select
HandShake(…) -Handshake mode as set
2.2.3 Using the LTC 8780 Data Converter Unit with using jumper S105 on the
Address Matching Enabled Data converter
The Data Converter unit can be configured to either
Once configured the serial port can be opened
forward all CCL commands that are received from the
and closed using the OpenCOMM(…) and
Master Allegiant system or only forward commands
CloseCOMM(…) methods on the IAllegiantParser
that match the Address of the Data Converter unit.
interface.
Switch #4 on dip switch S101 enables the Address
function and Switch #4 on dip switch S102 enables
3.1.2 Select Address Matching
Address matching, the format of CCL messages will
The Command Parser exposes a property
vary based on how your configure the dip switches.
UseMessageHeader(…) on the IAllegiantParser
interface which needs to be set to true when
3.0 USING THE ALLEGIANT SDK Address matching is disabled and false otherwise
IN A CLIENT APPLICATION (see Section 2.2.2, Configuring the LTC 8780 Data
Converter Unit).
Refer to the Allegiant Satellite SDK Interface
Definition for details about the interfaces and the 3.2 Selecting the Parser Mode
object model of the SDK. 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.
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide| Using the Allegiant SDK in a Client Application EN|8
Each property is of type PARSER_MODE that takes 3.3 Starting the Allegiant Command
either a bitmap or one of the following values: Parser
Once all the communication settings have been applied,
PARSER_MODE_PROCESS - process all commands (per the above) call the StartParser(…) method from the
and forward using interface methods IAllegiantParser interface supplying at least one callback
interface pointer (IOSRDCommand, ISateliteCommand
PARSER_MODE_USE_RAW_METHOD - semi or IcrossPointInfo). This method is asynchronous and
process the command and forward using raw method will return once the parser has been started. Incoming
that includes device address. In addition, this mode can messages will be pushed to the appropriate callbacks as
be combined as a bitmap to set exceptions for commands they arrive on the wire.
that still need to be forwarded to the appropriate interface
methods. 3.4 Stopping the Allegiant Command
Parser
PARSER_MODE_RAW - no processing required just The command parser can be stopped at any moment by
forward all commands to the raw interface invoking the Stop(…) method.
The following code snippet displays how to set the parser 3.5 Handling Camera Switching
mode; Commands
// set the parser mode to send raw OSRD
The camera switching commands are periodically sent
// commands but supply the logical camera
to the ISateliteCommand interface through the
// number and the message //payload, use
SetCameraOnLogicalMonitor(…) method, using the
// interface methods to deliver Aux and
interface supplied by the client application as an
// Prepos commands
argument to StartParser(…).
pIAllegtParser- 3.6 Processing PTZ Commands
>put_ParserModeOSRD(PARSER_MODE_USE_RAW_METH
PTZ commands are forwarded to the IOSRDCommand
OD|PROCESS_AUX_PREPOS);
interface of the Client, using the interface supplied by the
client application as an argument to StartParser(…). Based
// set the parser mode to send raw Satellite
on the ParserModeOSRD property setting the commands
// commands but supply the logical camera
will either be decomposed and forwarded to interface
// number and the message
methods or they will be sent to one of the raw methods.
// payload
When the ParserModeOSRD is set to
pIAllegParser->put_ParserModeSatellite
USE_RAW_METHOD all commands will be channeled
(PARSER_MODE_USE_RAW_METHOD);
to the PutRawOSRDCommand(…) method. The second
parameter (arrRawCommand) contains the raw PTZ
// set the parser mode to process all
payload that can be decoded by an Autodome Camera
// Crosspoint commands and deliver them
hence it is probably the most efficient way for the client
// to interface methods
application to transparently transmit PTZ commands.
pIAllegParser>put_ParserModeCrosspoin
(PARSER_MODE_PROCESS);
// kick off the parser
pIAllegParser->StartParser
(m_pIOSRDCommand, m_pISateliteCommand,
m_pICrosspointCommand);
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide | Using the Allegiant SDK in a Client Application EN|9
3.7 Translating Continuous PTZ 3.9 Connecting to Multiple LTC 8780
Operations to their Indefinite Units
Equivalents For each LTC 8780 unit that the client application wishes
The motion of the AutoDome camera may be jittery to connect to, one instance of the AllegiantParser object
when continuous PTZ operations are used. This is due to must be created and each unit needs a unique serial port.
network latencies that slow down the transmission of For example, if the client wants to connect three (3) Data
packets. Furthermore much more bandwidth is consumed converters then three (3) AllegiantParser objects instances
when sending out repetitive commands. The command and three (3) serial ports will be required. In addition, the
parser can be instructed to convert continuous PTZ client application may need separate callback objects so
operations to their indefinite equivalents, in this mode the that they can determine what parser instance fired the
Application will only receive two commands, one to start callback.
the indefinite PTZ operation and a last one to cancel the
last PTZ operation. When using variable speed PTZ 3.10 SDK Version Information
commands, the client application will only get speed The LTC8780_CommandParser.dll version information
updates. can be retrieved by using Windows Explorer, simply
right click on the file, select propertiesand go to the
The EnableRepetitiveCommands(…) properties of Versiontab.
interface IAllegiantParser enables the PTZ command
translation when set to false. 3.11 Limitations
The below have not been implemented, and are included
3.8 Error Handling in the Allegiant Satellite SDK Interface Definition
Every interface method returns an HRESULT. When document for reference only:
an error condition occurs, the low order bytes of the • IMonitor interface
HRESULT will contain the error code. Once this value • ICrossPointInfo interface
has been extracted, it will map to one of the values in • IAllegiant::ParserTrigger() method
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";
}
}
Bosch Security Systems | 21 March 2005
Allegiant Satellite SDK| User Guide| EN|10
Bosch Security Systems | 21 March 2005