Perimeter Patrol High Level Interface Programmers Guide
Contents
1. Zones 0 UpperAlarm Voltage Zones 0 LowerAlarmV oltage Zones 0 LowPowerLowerAlarmVo Itage Zones 0 LowPowerUpperAlarmVo Itage Zones 0 Name Zones 0 NetworkName Zones 0 NumLinePoints Zones 0 LinePointsX Zones 0 LinePointsX 0 Zones 0 LinePoints X 1 Zones 0 LinePoints Y Zones 0 LinePointsY 0 Zones 0 LinePointsY 1 Zones 0 Outputs Zones 0 Outputs 0 Zones 0 RelayControlEnable Zones 0 Relays JVA Technologies Pty Ltd 2012 Version October 2012 Uncontrolled if printed 0 5 1 8 My Zone ETH 161371 100 200 100 100 True False Appendix 1 Fields in the Configuration Data for this zone Raise an alarm if voltage rises above this value while the zone is armed at high power Raise an alarm if voltage drops below this value while the zone is armed at high power Raise an alarm if the voltage drops below this value while the zone is armed at low power Raise an alarm if the voltage rises above this value while the zone is armed at low power A user friendly name for the zone This value may not have been set by the administrator who configured the JVA Perimeter Patrol The network name PAE212 device that connects this zone to the Perimeter Patrol Server Applies only when ComMode ETHERNET Number of line points for this zone on the map Number of X coords for the line points on the map X coord for the line point X coord for the line point Number of Y coords for the line points2. JVA Perimeter Patrol High Level Interface Programmers Reference Guide Programmers reference guide to developing custom applications using JVA Perimeter Patrol HLI Version 5 1 Date October 2012 By Benjamin Boyle Your software system Perimeter Patrol Electric fences JVA Perimeter Patrol Introduction High Level Interface Table of Contents TOUCH ee ae en tne ee ene ee ee ee eee 2 del Reg iredreading and SGU siirteen inne e eaenseneoeannea tween OAE 2 A Eeee CC re E T AAT 3 TUNG SaN ae E E E A cece een A A E AE AN A E 4 2 1 Gontiguring Perimeter Patrols aa 4 2 1 1 Configuring Perimeter Patrol to accept HLI CONNECTIONS ccccseeeeeeeeeeeeeeeeees 4 2 1 2 Setup Perimeter Patrol users cccccccseccceeeceececeeccceecceueeceueecseecsueesseeeeeeessaeenaess 6 Uond He TALL GINO ROIS CL aerea E 7 3 1 The Interpreter object ccccccecccccceccceeeeceeeeeeeseeeeseeessueeseeeesaeeseueeseeeseeeseueeseeessneesaes 10 4 Using the HLI in your CUSTOM software ccccccseecceececeeeceseceeecceeseueeceessueessueeseeesseeess 11 4 1 Step 1 Adding the HLI to your development environment ccccseeeeceeeeeeeeeeeees 11 4 2 Step 2 Creating a HLITransportUser ObDje Ct ccc cceeeccneeeeceeeeseeeeeeeeeseeeeseeenees 11 4 3 Step 3 Implementing PP HLITransport IHLIClientTransportuUser 000086 13 4 4 Step 4 Sending commands to Perimeter Patrol
3. D3D4 4D4E A112 396BCD43665F Media State Media disconnected Connect ion specif ic DNS Suffix i JVA Technologies Pty Ltd 2012 Page 5 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Getting started High Level Interface 2 1 2 Setup Perimeter Patrol users Perimeter Patrol will not allow any HLI connection to receive information or receive commands unless the HLI connection provides a username and password that matches one those configured in Perimeter Patrol Your software will have to use these usernames and passwords to access Perimeter Patrol over the HLI You can hard code the usernames and passwords in your software system if you like but we recommend you require your users to type them in manually You can find out how to setup Perimeter Patrol users in the JVA Perimeter Patrol Configuration Manual Remember that there are three levels of security access permission 1 Users may view information a Accessible by your software via HLI 2 Supervisors may clear alarms and send commands a Accessible by your software via HLI 3 Administrators may configure the JVA Perimeter Patrol software a Not accessible to your software JVA Perimeter Patrol configuration must be done on the JVA Perimeter Patrol computer by an administrator Your HLI software will be given permissions according to the level of authentication it can provide JVA Technologies Pty Ltd 2012 Pag
4. an encrypted TCP IP connection The HLI component that we provide to your system programmers makes this easy Everything your programmers need to know is included in this document and the documents named in the Required reading and setup section below TCP IP connection Perimeter Patrol Electric fences 1 1 Required reading and setup This document assumes that you have already read and understood the following documentation e JVA Perimeter Patrol User Manual e JVA Perimeter Patrol Configuration Manual JVA Technologies Pty Ltd 2012 Page 2 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Introduction High Level Interface 1 2 Scope Read this document if you want to create custom software programs that connect to JVA Perimeter Patrol using the High Level Interface HLI If you want to connect two instances of Perimeter Patrol together in Server Client configuration please read section Connecting two instances of Perimeter Patrol in Server Client configuration using the HLI in the JVA Perimeter Patrol Configuration Manual 1 3 Contact details Position Name Email Author of this document Benjamin Boyle bboyle pakton com au Pakton Technologies CEO Paul Thompson aul pakton com au Pakton Technologies Kayleen Thompson sales pakton com au General Manager JVA Technologies Pty Ltd 2012 Page 3 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Ge
5. by devices such as electric fence energisers and monitors Alarms generated by devices such as electric fence energisers and monitors include those listed below You can find out more about them in the user manuals for each device This list is not guaranteed to be up to date as it is intended to be an example not an authoritative reference e Fence related alarms o Fence alarm there is a problem with the fence o Ground alarm there is a problem with the energiser s earth connection o Gate alarm one or more gates have been left open or jammed open for too long e Device related alarms o AC Fail alarm there is no mains power and the device is relying on its battery Low Battery alarm the device s battery is getting low Bad Battery alarm the device s battery is flat too old or has been damaged Tamper alarm the device s case has been opened by an unauthorized person o PCB Fault alarm the device needs repair JVA Perimeter Patrol reports the status of these alarms exactly as they are reported by the device generating them Alarms generated by devices can latch on which means they are not closed when the condition causing the alarm has been resolved Instead the devices wait for a user to acknowledge the alarm before they close the alarms Imagine for example that a gate has been left open for too long and one of the devices has generated a Gate alarm After the gate has been closed the condition causing
6. ccceeceeeeeeeeeeeeeeeeeeeeeeeeeeaaeees 21 44 1 Special comman Secese 22 4 4 2 Commands that apply to all electric fence ZONES ccceecccseeeeceeeeeeeeeeseeeseeeeens 22 4 4 3 Commands that apply to individual ZONES cccccseeeeeeeeeeeeeeeseeeeseeeeeseeeeeeeeees 22 4 4 4 Other COMMANAG cccccceeccceeececeeeeeeececeeeeseeeeeseeeessaeeeseusesseeeseeeesseeeeseeeesseeenas 23 4 5 Understanding the Alarms system ccccceccceeeeseeeceeeeceeeeseeeseeeseeeeseeeseueeseeesseeesanes 24 4 6 Understanding the Configuration Data structure cccccececcceeeeceeeeeeeeeeeeeseeesaeeesanes 26 4 7 Understanding the LiveData StrUCtUre ccccccccececeeeceeeeeeeceeeeseeeeeeeeseueeseeesaneesanes 26 5 Appendix 1 Fields in the Configuration Data cccccsscccsseeeeeeeeeseeeeseueeeseeeeseaeenseeeesaes 27 JVA Technologies Pty Ltd 2012 Page 1 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Introduction High Level Interface 1 Introduction JVA Perimeter Patrol a software system for monitoring and commanding JVA Security Electric Fence Devices is designed exclusively for JVA Technologies Pty Ltd by Pakton Technologies Pty Ltd of Brisbane Australia The JVA Perimeter Patrol High Level Interface HLI allows you to monitor and command JVA Security Electric Fence systems from within your own software systems Your software connects to the JVA Perimeter Patrol program over
7. ile Called whenever there is a change to the open alarms f summar i paras kA E gt A data table containing open alarm information serialized as an xml string lt param gt void PP HLITransport IHLIClientTransportUser OnOpenLopUpdated string openLog i interpreter OnOpenAlarmsUpdated openLog this SetOpenAlarms openLog this UpdateInterpreter Figure 14 Implementing the OnOpenLogUpdated function OnLogUpdated JVA Technologies Pty Ltd 2012 Page 18 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface This function is called by the HLI Transport object whenever JVA Perimeter Patrol adds a new log entry or modifies an existing log entry We keep things simple for you by sending the entire log contents every time The log is passed in as a string containing an XML serialized DataTable You most likely do not need to process the log data displaying it to the user will be sufficient for most use cases lt summary gt f Called whenever there is a new log entry or a log entry has been modified f lt summary gt lt param name loe gt The log data table serialized as an xml string lt param gt void PP HLITransport IHLIClLientTransportUser OnLogUpdated string log this SetLog log Figure 15 Implementing the OnLogUpdated function delegate void SetLogDelegate string log internal void SetLog
8. on the map Y coord for the line point Y coord for the line point Number of output relays this zone has False means the output is off no current can flow through it Indicates whether it is possible to toggle output relays for this zone Number of output relays this zone has Applies only to zones and zone monitors not to IO Boards Page 29 of 30 JVA Perimeter Patrol High Level Interface Zones 0 Relays 0 Zones 0 Relays 1 Zones 0 Relays 2 Zones 0 Relays 3 Zones 0 Relays 4 Zones 0 Sectors Zones 0 X Pos Zones 0 Y Pos JVA Technologies Pty Ltd 2012 Version October 2012 Uncontrolled if printed False False False False False Appendix 1 Fields in the Configuration Data False means the relay is off no current can flow through it Position of the zone label on the image map Measured in pixels from the left Position of the zone label on the image map Measured in pixels from the top Page 30 of 30
9. param gt f lt param name openLog gt Open alarms as a datatable serialized into xml lt param gt lt param name mapImage gt Map Image as a byte array lt param gt void PP HLITransport IHLiclientTransportuser OnSessionAccepted PP HLITransport ConfigDictionary config string log string openLog byte mapImage i interpreter 0nSessionAcceptance config log openLog mapImage this SetMapImage mapImage this SetConfig config this SetLog log this Set0penAlarms openLog Figure 11 Example implementation for OnSessionAccepted delegate void SetMapImageDelegate byte mapImage internal void SetMapImage byte mapImage if this InvokeRequired this Invoke new SetMapImageDelegate this SetMapImage mapImage else pIimage BackgroundImage new Bitmap new MemoryStream mapImage Figure 12 Displaying the Map Image JVA Technologies Pty Ltd 2012 Page 17 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface delegate void SetConftigDelegate PP HLITransport ConfigDictionary config internal void SetConfig PP HLITransport ContigDictionary config if this InvokeRequired i else i this Invoke new SetContigDelegate this SetConfig contig mnuControlOnSchedule Checked config GetBoolean ScheduledControlEnable monuArm4llHighPower Enabled mnuControlOnSchedule Checked mnuArm4l
10. software uses the HLITransport to communicate with the JVA Perimeter Patrol software Therefore it is considered to be a HLITransportUser Please create a class in your project that inherits the PP HLITransport IHLIClientTransportuUser interface When you inherit this interface and implement the functions it requires you give the HLI transport object a hook to pass information into your system or request information from your system JVA Technologies Pty Ltd 2012 Page 11 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface namespace PerimeterPatrolClientDemoProject public partial class DemoUI UserControl PP HLITransport IHLiclientTransportuser PP HLITransport IHLIClientTransport hli public DemoUI public void Shutdown lol Inherits lt summary gt f f This region of functions is used as hookaggj r the HLI transport layer to ca fff lt summary gt region IHLIClientTransportuUser string PP HLITransport IHLIClientTransportuser GetAuthenticationkey void PP HLITransport IHLIClientTransportUser OnConnection void PP HLITransport IHLIClientTransportuUser OnConnectionError Exception except void PP HLITransport IHLIClientTransportUser OnSessionAccepted PP HLITransport void PP HLITransport IHLIClientTransportuser OnLogUpdated string log void PP HLITransport IHLIClientTransportUser OnLiveData PP HLITransport
11. string log if this InvokeRequired i else i this Invoke new SetLogDelegate this SetLog log DataSet newData new DataSet StringReader sr new StringReader log newData ReadxXml sr XmlReadMode ReadSchema if dglog DataSource null i dgelLog DataSource newData Tables else i int save dgLog FirstDisplayedScrollingRowIndex DataTable dgLog DataSource Merge newData Tables deLog FirstDisplayedScrollingRowIndex save Figure 16 Deserializing the log file and displaying it in a DataGridView Note that the code shown also demonstrates how to merge new incoming data to a DataGridView without causing it to flicker OnLiveData The HLI Transport object will call your OnLiveData function every time it receives a Live Data update from the JVA Perimeter Patrol which is about once every second depending on your network connection speed To keep things simple for you the HLI Transport object passes the entire live data structure to you on every call JVA Technologies Pty Ltd 2012 Page 19 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface Please study the Interpreter object in the HLI Client Demo Project to understand how you should read the live data lt summary gt Called approximately once per second f Contains all the live data status values and alarms in the syst
12. was shut down 4 Configuration settings on the Perimeter Patrol server have been changed The client will be allowed to automatically reconnect and the modified configuration settings will be passed in the next Session Acceptance Message f f lt summary gt lt param name exception gt lt param gt void PP HLITransport IHLIClientTransportUser OnConnectionError Exception exception this ShowTransportLayerDisconnected exception null string Empty exception Message H Figure 10 Example implementation for OnConnection and OnConnectionError OnSessionAccepted The OnSessionAccepted function is called after a connection is established with the JVA Perimeter Patrol and your authentication key has been verified This function brings along some important information for your software system to use e The JVA Perimeter Patrol s configuration settings o AsaConfigDictionary object e The JVA Perimeter Patrol s log file o Asan XML serialized string containing a database table e The JVP Perimeter Patrol s open alarms o Asan XML serialized string containing a database table of the alarms e The JVA Perimeter Patrols map image o Asa byte array Remember to handle the function quickly so that the HLI Transport object can continue reading data from the TCP IP connection If you have any heavy processing of the data do it in a different thread Imagine the scenario where an administrator changes the configuration se
13. Configit void PP HLITransport IHLIClientTransportUser NotifyClient PP HLITransport Warnil System Net IPEndPoint PP HLITransport THLIClientTransportuUser GetIPEndPointFo ak endregion Figure 6 Create a class that inherits PP HLITransport IHLIClientTransportUser Now you are ready to create and dispose the HLITransport object First notice that to create the HLI Transport object you call a static function inside PP TransportLayer passing in an object that inherits the PP HLITransport IHLIClientTransportuUser Interface This is the object that will be used by the HLI Transport object as the hook it needs for posting and requesting data When you Start the object it will immediately begin attempting to connect to the JVA Perimeter Patrol software If it fails to connect it will simply keep on trying to connect over and over again If a connection is established and then fails it will continually attempt to reconnect There is no Stop function and an exception will be thrown if you attempt to call the Start function more than once Notice that we take special care to Dispose of the HLI Transport object when we are finished with it Its very important to Dispose it when you are finished with it because it needs to shut down all the threads that it had running JVA Technologies Pty Ltd 2012 Page 12 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interfa
14. Lii The key that will be used to encrypt communications between the Perimeter Patrol Server and client f The client must provide the correct key or the session will not be accepted dii lt summary gt ff lt returns gt The authentication key to use to encrypt messages between the f f Perimeter Patrol Server and Client lt returns gt string PP HLITransport IHLIClientTransportUser GetAuthenticationkey return abcd H Figure 8 Example implementation for GetAuthenticationKey GetIPEndPointForClientConnection The HLI Transport object will call this function to get the information it needs about how to connect to the JVA Perimeter Patrol software In the example code below have stored the server address as a string and use the System Net Dns object to convert it to a proper IP address object If you are in development and need to connect to localhost the string localhost will not work Use 127 0 0 1 instead Alternatively you can skip the Dns conversion and use System Net IPAddress Any This function will be called every time the HLI Transport object attempts to connect to the JVA Perimeter Patrol server which could be as often as once every second Make sure it is not a time consuming function JVA Technologies Pty Ltd 2012 Page 14 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface H lt summary gt f Calle
15. VA Technologies Pty Ltd 2012 Page 7 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI Demo Project High Level Interface This was done on purpose so that you can learn how to reference the dll file that is provided for you Right click on the PP HLITransport reference and choose Remove Now right click on References and choose Add Reference 43 System 43 System Core Resources iy app contig 4 MainForm cs 4 MainForm Designer cs EA MainForm resx eca PerimeterPatrolClientDemoProject csproj al PerimeterPatrolClientDemoProject sin PerimeterPatrolClientDermoProject suo 4 PerimeterPatrolDemoULcs 4 PerimeterPatrolDemoUL Designer cs a PerimeterPatrolDemoUlresx Program cs Now that you have added PP HLITransport dll as a reference to the project it should compile successfully Right click on PerimeterPatrolClientDemoProject and choose Rebuild ai Pie ey F Parimatar s roiClientDemoProject The project should compile successfully Now you need to setup the connection parameters so that it can connect to Perimeter Patrol Server Right click PerimeterPatrolUl cs and choose View Code JVA Technologies Pty Ltd 2012 Page 8 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI Demo Project High Level Interface app contig MainForm cs FE Perimeti 5 7 c Program FDS Open With View Code View D
16. adapter device Choose the address corresponding to the correct network adapter device ae C windows system32 cmd exe Microsoft Windows LUersion 6 1 7681 1 Copyright tc 2669 Microsoft Corporation ALL rights reserved Ci Users Benjamin Bowle gt ipconfig Windows IP Configuration Wireless LAN adapter Wireless Network Connection 2 Media State a a n n ew n Media disconnected Connection specific DAS Suffix Ethernet adapter Local Area Connection Media State a a o ao a a n ew n Media disconnected Connection specific DHS Suffix Wireless LAN adapter Wireless Network Connection Connection specific DAS Suffix Link local IPv6 Address IPu4 Address Eotn 40 49 0 39 665218 192 168 8 13 Capa p eo eo EF 192 168 090 222 Tunnel adapter isatap lt EB 717EB4 2BV73 47CE B130 SE9S3P2SD652F Media State a n we n Connection specific DNS Suffix Subnet Mask a a i i i i Default Gateway d t Media disconnected Tunnel adapter Local Area Connection 11 Connection specific DNS Suffix IPu6B Address 2 2 o Link local IPv6 Address Default Gateway 1 ow n z Tunnel adapter isatap 654338CA AAAF 4D76 B479 E2 ES BFEB6EEF gt B1 2629038 995c 22015 2eeb SFO iF FF2 S42 22c15 2eeb 3fS72fFF2415 oo Pe fo oo O G Media State a a a a Media disconnected Connect ion specif ic DNS Suffix Tunnel adapter isatap lt F 3C8H46
17. arry out the action requested There are a couple of synchronous functions made obvious by the _ block suffix on the function name These functions block execution until their results have been returned These functions throw an exception if the operation times out or there is some circumstance preventing the result of the command from being received JVA Technologies Pty Ltd 2012 Page 21 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface lf JVA Perimeter Patrol receives the command but is unable to carry out the requested action it will send a message to your software using the NotifyClient function that you have to implement for receiving these messages 4 4 1 Special commands ControlOnSchedule e When True tells JVA Perimeter Patrol to automatically arm and disarm the energiser zones according to the weekly schedule set up in the JVA Perimeter Patrol Server e When False tells JVA Perimeter Patrol to wait for user commands for arming and disarming the energiser zones The status of this parameter is contained in the JVA Perimeter Patrol s configuration settings When you change it JVA Perimeter Patrol will disconnect your software and all the other HLI Transport clients that are attached When your HLI Transport object automatically reconnects you will receive a new configuration settings containing the modified ControlOnSchedule parame
18. ce namespace PerimeterPatrolClientDemoProject public partial class DemoUI UserControl PP HLITransport IHLIclientTransportuser PP HLI Transport IHLIClientTransport hli public DemoUI InitializeComponent hli PP TransportLayer CreateHLIClientTransport thi hli Startt ae void Shutdown hli Dispose Bein nia S A Create and start the object Dispose the object Figure 7 Creating starting and disposing the HLI Transport object There are two more steps left for you to understand The next step Step 3 is about implementing all the functions required by PP HLITransport IHLICclientTransportUser so that the HLI Transport object can hook into your application to deliver information to your system or request information from your system Step 4 is about using the HLI Transport object to send commands to the JVA Perimeter Patrol 4 3 Step 3 Implementing PP HLITransport 1HLIClientTransportUser This section is about functions you have to implement in the object you create that inherits the PP HLITransport IHLIClientTransportUser interface Before we go ahead note the following important facts that all of these functions have in common 1 If your function throws an exception it will stop the worker threads in the HLI Transport object and the HLI Transport object will stop working Catch all your exceptions or make sure they do not throw exceptions 2 If your function takes a long time to exe
19. ct to the JVA Perimeter Patrol but it could also mean that the JVA Perimeter Patrol rejected your connection because your authentication key was incorrect lf the HLI Transport object is disconnected from the JVA Perimeter Patrol it will attempt to reconnect once every second It will call the OnConnectionError function after every single failed connection attempt The example implementation of these functions simply calls functions that make the User Interface tell the user it is not connected to JVA Perimeter Patrol Note that to do so ina thread safe manner the Ul methods ShowTransportLayerConnected and ShowTransportLayerDisconnected must use Invoke to prevent cross thread errors JVA Technologies Pty Ltd 2012 Page 15 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface f f lt summary gt This function is called whenever a connection is established with the Perimeter Patrol Server lt summary gt void PP HLITransport IHLIClientTransportUser QnConnection this ShowTransportLayerConnected lt summary gt f f Called whenever the connection to the Perimeter Patrol server is terminated f The connection can be terminated by the following circumstances f 1 A normal ethernet connection problem 2 The connection was refused by the Perimeter Patrol server due to incorrect authentication 3 The Perimeter Patrol server
20. cute it may prevent the HLI Transport object s worker threads from reading the underlying tcp ip socket connection and result in a connection loss Keep your functions very fast and simple 3 Your functions are called by worker threads that are not the same as the main thread your software is using Therefore you will have to make sure that your functions access your data structures in a thread safe manner and that you use Invoke to call methods in your UI GetAuthenticationKey JVA Technologies Pty Ltd 2012 Page 13 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface When you were setting up JVA Perimeter Patrol in the Getting Started section of this document you had to provide JVA Perimeter Patrol with an authentication key that your software would have to know before it would be allowed to connect to JVA Perimeter Patrol Normally you will store the authentication key in the configuration settings of your software project In the example code below cheated a little by simply hard coding an authentication key that matches the JVA Perimeter Patrol used for development and testing The HLI Transport object will call this function every time it tries to connect which could be as often as once every second if it is failing to connect Make sure it is not a time consuming function region IHLIClientTransportUser lt summary gt
21. d whenever making a connection to the Perimeter Patrol Server To connect to the server the client must know the address f IP Address and Port of the server lt summary gt lt returns gt An IPEndPoint object containing the address IP address and port f f of the Perimeter Patrol Server lt returns gt System Net IPEndPoint PP HLITransport IHLIClientTransportuser GetIPEndPointForClientConnection try string serverAddress Properties 5Settings Default ServerAddress System Net IPAddress ip System Net 0ns GetHostAddresses serverAddress int serverPort Properties Settings Default ServerPort return new System Net IPEndPoint ip serverPort catch this NotifyClient PP HLITransport WarningLevel Error Could not create an IPEndPoint for connecting to the Perimeter Patrol Server Please cheq return null Figure 9 Example implementation for GetIPEndPointForClientConnection OnConnection and OnConnectionError The HLI Transport object will call these functions to notify your software that it has connected to or disconnected from the JVA Perimeter Patrol software When OnConnection is called it means that you have connected to the JVA Perimeter Patrol but you have not been authenticated yet The JVA Perimeter Patrol will check your authentication key and will soon disconnect you if it is not correct When OnConnectionError is called it could mean that the HLI Transport layer was unable to conne
22. diagnose the alarm causes more easily JVA Perimeter Patrol also generates specialized alarms such as the following e Coms failure trouble communicating with the devices e Control Override devices have been disarmed either by someone not using your software or JVA Perimeter Patrol For example someone may have used a keypad to manually disarm a device Every alarm must be acknowledged by users regardless of whether the alarm condition still exists For example the voltage on a fence may temporarily drop below the acceptable level and an Under Voltage alarm will be opened If the voltage on the fence rises back up to an acceptable level the condition causing the alarm will no longer exist but Perimeter Patrol will hold the alarm open until a user has acknowledged it Summarizing JVA Perimeter Patrol alarms have a three stage lifecycle e Stage 1 Open o Alarm condition has been detected o Eg Fence voltage has fallen below the lower alarm level e Stage 2 OpenResolved o Alarm condition has been resolved but no user has acknowledged it yet o Eg Fence voltage has risen back up to acceptable levels o Even though the condition causing the alarm no longer exists JVA Perimeter Patrol is holding the alarm open until a user has acknowledged that the alarm had occurred e Stage 3 Closed o User has acknowledged that the alarm existed and written a note in the log explaining the situation sometimes there will be a situation whe
23. e 6 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI Demo Project High Level Interface 3 Using the HLI Demo Project Now that you have Perimeter Patrol setup and waiting to accept connections it s probably going to be easiest for you if you use the demo HLI project to make your first connection since all the work is done for you You need to have Visual Studio 2010 You can download it from htto download microsoft com download B 1 7 B17C731C 3161 45C0 AC16 56C81BAAF85C vs_premiumweb exe if you don t already have it on your computer Using the installation cd open the PerimeterPatrolClientDemoProject folder and copy it to a place your computer s hard disk In the place you have saved it double click PerimeterPatrolClientDemoProject sin a MainForm cs MainForm Designer cs t all files AA MainForm resx Name Documentation PerimeterPatrolClientDemoProject suo PerimeterPatrolIDemoUL cs c PerimeterPatrolDemoUL Designer cs 4 PerimeterPatrolIDemoULresx if JVA Perimeter Patrol 5 1 0 6389 msi PP HLITransport dll B setup exe c Program cs After the project loads you can click References in the Solution Explorer and you will see that there is a reference error DAEA DemoProject gt Ea Properties 4 l References lt 2 Microsoft oe 4 aie otal Core 42 System Data 42 System Data DataSetExtensions 42 System Deployment 42 System Drawing J
24. e Comment FullScreenPassword Password to exit full screen mode Administrators can set this parameter to stop people from exiting JVA Perimeter Patrol FullScreenRequiresPassword False Does JVA Perimeter Patrol require a password to exit full screen mode ScheduledControlEnable False Can JVA Perimeter Patrol automatically arm and disarm the zones according to the weekly control schedule Use the ControlOnSchedule command to set this value from your own software Zones 7 Number of zones that have been configured in JVA Perimeter Patrol Since there are seven zones the rest of the configuration dictionary will contain values for Zones 0 Zones 1 Zones 6 Zones 0 ArmStates 336 Number of arm states Is always 336 because that is the number of 30 minute periods in one week The ArmStates represent the weekly schedule that JVA Perimeter Patrol will use to automatically arm and disarm zones when the ScheduledControlEnable setting is True Zones 0 ArmStates 0 Disarm Represents the scheduled arm state for the first 30 minutes of the week starting at 12 00am on Sunday Zones 0 ArmStates 1 Disarm The second 30 minute block of the week Continues until Zones 0 ArmStates 335 Zones 0 Ch 0 Some energiser types can power more than one zone JVA Technologies Pty Ltd 2012 Page 27 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol High Level Interface Zones 0 ForceUselpAddress Zone
25. ed whenever the JVA Perimeter Patrol sends a message that you should display to your user Messages are usually related to authentication problems or when the JVA Perimeter Patrol is unable to complete the action that the user requested In the example code below the message is displayed by a popup message box window You may like to implement a more user friendly way to display messages to the users of your software system JVA Technologies Pty Ltd 2012 Page 20 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface f f lt summary gt f Called when there is a message that should be displayed to the user f f lt summary gt f lt param name warningLevel gt How important is the message lt param gt f lt param name message gt The message to display to the user lt param gt void PP HLITransport IHLIclientTransportuser NotifyClient PP HLITransport WarningLevel warningLevel string message this NotifyClient warningLevel message Figure 19 Implementing the NotifyClient function delegate void NotifyClientDelegate PP HLITransport WarningLevel warningLevel string message internal void NotifyClient PP HLITransport Warninglevel warningLevel string message if this InvokeRequired this Invoke new NotifyClientDelegate this NotifyClient warningLevel message else MessageBox Show message Figure 20 D
26. em ff lt summary gt j lt param name liveData gt A config dictionary containing all the live data status values and alarms lt param gt eit PP HLITransport IHLIClientTransportuser OnLiveData PP HLITransport ConfigDictionary liveData 1 interpreter OnLiveData liveData this SetLiveData liveData this UpdateInterpreter Figure 17 Implementing the OnLiveData function Note how the demo project sends the live data to the interpreter to have the live data placed in interpreted objects delegate void SetLiveDataDelegate PP HLITransport ContigDictionary liveData internal void SetLiveData PP HLITransport ContigDictionary liveData if this InvokeRequired i else i this Invoke new SetLiveDataDelegate this SetLiveData liveData DataTable newData new DataTable newData Columns Add Name newData Columns Add Value newData PrimaryKey new DataColumn newData Columns foreach KeyValuePair lt string PP HLITransport ContigValue gt kwp in liveData ToDictionary i newData Rows Add kvp Key kvp Value Value ToString if dgliveData DataSource null i f else i dgLiveData DataSource newData int save dgLiveData FirstDisplayedScrollingRowIndex DataTable dgLiveData DataSource Merge newData dgeLiveData FirstDisplayedScrollingRowIndex save Figure 18 Displaying LiveData in a DataGridView NotifyClient This function is call
27. esigner In the code window that opens modify the parameters shown below with the values needed to connect to Perimeter Patrol Server e Set the USER NAME and PASSWORD parameters to be the same as one of the user accounts setup in the Perimeter Patrol s configuration settings e Set the SERVER _ADDRESS parameter to the static IP address of the computer running Perimeter Patrol e Set the SERVER_PORT parameter to the same value as the TCP Listen Port that you specified in Perimeter Patrol s configuration e Set the AUTH KEY parameter to the same value as the Authentication Key that you specified in Perimeter Patrol s configuration public partial class PerimeterPatrolDemoUI UserControl i const string AUTH KEY 1234 const ae USER admin const E SERVER ADDRESS 192 168 0 26 Now press the F5 key to start the demo program When the program runs click Start to make it connect ameter Patrol High Level Interface Client Demo Start iew Arm iguration lf the programs connects and begins to display data then you know that you have the connection settings correct If not you will have to figure out what you need to change JVA Technologies Pty Ltd 2012 Page 9 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI Demo Project High Level Interface 3 1 The Interpreter object The Perimeter Patrol Demo HLI client project contains an Interp
28. figuration Data fields is to look at the code of the example Interpreter object and see how it reads the configuration settings to create objects that can be used in your code An appendix lists the data contained in the configuration data 4 7 Understanding the LiveData structure The Live Data structure is a ConfigDictionary of string keys and string values Look at the code in the Interpreter object to see how it maps incoming live data to the objects that it created from the configuration data Alarms There are a lot of named alarm values contained in this data in addition to arrays of open unresolved and open resolved alarms Do not use these values in your custom software They are present because they are used when two instances of Perimeter Patrol connect to each other You don t need them for your custom software Examine the code used in the Interpreter object in the HLI Client demo project and use the same methodology it uses for reporting alarms in your own custom software Voltages and Arm States Read the code in the Interpreter object in the HLI Client demo project to see how to get voltages and arm states of zones Use the same methodology in your own custom software JVA Technologies Pty Ltd 2012 Page 26 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Appendix 1 Fields in the Configuration Data High Level Interface 5 Appendix 1 Fields in the Configuration Data Key Example Valu
29. g to your Perimeter Patrol e Shut down and restart Perimeter Patrol as this is required for the new settings to take effect a High Level Interface LI JE er Disabled F HL Server Enabled Local TCP Listening Port 6000 Authentication Key fa 72cdf5 a352 46 1c 36b4 d987d2443210 Generate Maximum Concurrent Connections 3 Figure 1 Enabling HLI Server to accept HLI connections JVA Technologies Pty Ltd 2012 Page 4 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Getting started High Level Interface 2 1 1 1 Use a static fixed IP Address for Perimeter Patrol Ask your system administrator to configure your network router so that it assigns a static IP Address to the computer running Perimeter Patrol Your system administrator should be able to tell you the new IP Address but if he does not you will need to find out Here s how e On the computer s start menu click Start gt Run and enter cmd exe e lf that doesn t work enter C windows system32 cmd exe e If you don t have Run on your start menu you can find C windows system32 cmd exe in explorer and double click the file to start it e The window pictured below will open e Type ipconfig and press Enter e Write down the IPv4 address This is the IP Address that your client software needs to know e Sometimes your computer will have more than one IPv4 address if it has more than one network
30. isplaying the NotifyClient message to the user 4 4 Step 4 Sending commands to Perimeter Patrol This section contains all the commands that you can send to the JVA Perimeter Patrol All commands require the username and password of the currently logged in user This username and password must match the usernames and passwords set up in the Configuration Settings inside JVA Perimeter Patrol They are required for our second layer of authentication security and for logging purposes as well In this way we have given you the ability to run your software in display only mode with commanding disabled If you want to you can set up a system whereby when your software user needs to send a command they will be prompted to enter the higher level supervisor s username and password Most of the commands are asynchronous This means that the command is sent and the function continues without waiting for the command to be executed or any feedback about the command results Asynchronous functions return a boolean value They return true if the command was successfully sent to the JVA Perimeter Patrol or false if there was a problem sending the command For example an interrupted connection will result in the function returning false If the function returns false you can check the exception object to find out the error message The functions will still return true if the message reached JVA Perimeter Patrol even if JVA Perimeter Patrol was unable to c
31. llowPower Enabled mnuControlOnSchedule Checked mnuDisarmAll Enabled mnuControlOnSchedule Checked DataTable newData new DataTable newData Columns Add Name newData Columns Add Value newData Primarykey new DataColumn newData Columns foreach KeyValuePair lt string PP HLITransport ContigValue gt kvp in config ToDictionary i newData Rows Add kvp Key kvp Value Value ToString if dgConfig DataSource null i J else i deContig DataSource newData int save deContig FirstDisplayedScrollingRowIndex DataTable dgContig DataSource Merge newData deContig FirstDisplayedScrollingRowIndex save Figure 13 Displaying JVA Perimeter Patrol s configuration settings in a DataGridView Note that the code shown also demonstrates how to merge new incoming data to a DataGridView without causing it to flicker OnOpenLogUpdated This function is called whenever there is a change to the open alarms stored in Perimeter Patrol You will need to thoroughly understand the data that you receive in this function because it will be important that you are able to display the alarms properly The best way for you to learn how to interpret the alarm data is to read and understand the coding in the Interpreter object that is supplied with the demo project You can see in the code sample below that we send the new open alarm information to the interpreter object lt summary gt
32. meter Patrol Server receives this command and mutes the alarms you will notice a couple of changes in the data that it sends you a The openLog containing the open alarms will all have their muted fields set to a not null value and b the HasUnmutedAlarms value in live data will be false Your custom software s siren function should activate and deactivate according to the HasUnmutedAlarms value in Live Data so that it stays synchronized with the JVA Perimeter Patrol Server In this way any client can mute alarms and have the results duplicated not only in the server but also on all the other clients that are connected JVA Technologies Pty Ltd 2012 Page 23 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface 4 5 Understanding the Alarms system JVA Perimeter Patrol monitors the fence status and raises alarms whenever there is a condition on the fence or the security system that users should be aware of Some alarms are generated by devices such as electric energisers or monitors and sent to the JVA Perimeter Patrol Other more detailed alarms are generated by JVA Perimeter Patrol itself You will need to understand the differences between these alarms when you are writing software that interfaces with the JVA Perimeter Patrol because they have a slightly different life cycle and you will need to handle them differently Alarms generated
33. password int zoneId out Exception exception Disarm string username string password int zoneId out Exception exception ControlOnSchedule string username string password bool on out Exception exception Figure 21 List of commands that can be sent to the JVA Perimeter Patrol 4 4 4 Other commands ToggleOutputState Many of the zones including those belonging to energisers zone monitors and IO Boards have output relays You can toggle the output state of the relays with this command The zonelndex parameter identifies the zone and because each zone may have several output relays the outputIndex parameter identifies the output relay Close Alarms This command allows you to close resolved alarms See the Understanding the Alarms system section for more information about alarms ClearAlarmMemory This command allows you to close latching alarms that were generated by devices attached to JVA Perimeter Patrol Server The Understanding Alarms section will give you more information about the latching alarms RequestArchiveLog_block Requests an archived log for a given year and month in the past The archived log is returned inside an EventLogArchiveResult object which amongst other helpful information contains a string with the log DataTable serialized as an xml string Notice that this function is blocking MuteAlarms Commands JVA Perimeter Patrol Server to stop sounding sirens for the open alarms When JVA Peri
34. re the alarm cannot be resolved For example somebody might crash a car into an electric fence causing the fence voltage to drop below the lower alarm level It will take a day or more for an electric fence installation contractor to come and repair the fault In this case the user will not be able to close the alarm because the alarm is not resolved Users can only close alarms that are resolved When this is the case the user will want to switch off the alarm sirens strobe lights or any other systems are being used to alert people about the alarm JVA Perimeter Patrol allows users to Mute open alarms Muting alarms will switch off the sirens strobe lights etc but it will not close the alarm You can send a Mute command to Perimeter Patrol through the HLI JVA Technologies Pty Ltd 2012 Page 25 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface Your custom HLI Client software can also use the CloseAlarms command to close the alarms when a user has acknowledged them and entered a note to explain the circumstances causing the alarm 4 6 Understanding the Configuration Data structure JVA Perimeter Patrol sends its configuration settings to your software system when the HLI Transport object connects and is authenticated successfully The configuration settings are a ConfigDictionary of string keys and values The best way for you to understand the Con
35. reter class which is used to gather and make sense of the information received over the HLI connection This class has been written specifically for the purpose of helping you to understand how to interpret and use incoming HLI information in your own custom projects a WF PerimeterPatrolClientDemoProject p LE 4 W Interpreter wc Interpreter cs at OpenAlarm cs ac Zones cs RESOUICES app config MainForm cs 24 PerimeterPatrolDemoULcs ac Program cs Figure 3 The Interpreter object JVA Technologies Pty Ltd 2012 Page 10 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface 4 Using the HLI in your custom software 4 1 Step 1 Adding the HLI to your development environment 1 In your visual studio project add a reference to the PP HLITransport dll 2 This dll targets the Net Framework Version 4 Ensure your visual studio project targets the same Net Framework version 4 2 PerimeterPatrolClientDemoProject a Properties 4 o gt References SU Pe 413 System Core 43 System Data bt i a n i ni a Application N A Build Default namespace Build Events PerimeterPatrolClientDem Debu l J Target framework Resources WET Framework 4 Client Profile Figure 5 Referencing Net Framework version 4 It s not necessary to use the client profile 4 2 Step 2 Creating a HLITransportUser object Your
36. s 0 HostEnergiserType Zones 0 Inputs Zones 0 Ip Zones 0 Ip 0 Zones 0 Ip 1 Zones 0 Ip 2 Zones 0 Ip 3 Zones 0 Keypadid JVA Technologies Pty Ltd 2012 Version October 2012 Uncontrolled if printed False Z14 192 168 13 Appendix 1 Fields in the Configuration Data If this zone belongs to one of these energisers this parameter contains the index of the zone in the energiser Applies only when ComMode ETHERNET If true Perimeter Patrol has been configured to connect to the zone through a PAE212 ethernet adapter device using a Static IP Address If false Perimeter Patrol is connecting to the PAE212 ethernet adapter using its Network Name This information is helpful for you to know how to display information about the zone in your custom UI The type of energiser powering this zone The energiser type helps us know how many voltages will be measured how many relay outputs the zone has etc If this zone is an I OBoard or a zone monitor instead of an energiser zone this value will help you determine that How many inputs does this zone have Applies to IO Boards only If this value is non zero there will be extra fields representing the individual values of each input Eg Zones 0 Inputs 0 Number of items for the zone s IP address Is always equal to 4 Applies only when ComMode ETHERNET The keypad id of the device Page 28 of 30 JVA Perimeter Patrol High Level Interface
37. ter Therefore your User Interface display should reflect the state of the variable contained in the configuration settings 4 4 2 Commands that apply to all electric fence zones JVA Perimeter Patrol cannot obey these commands if ControlOnSchedule is enabled Therefore setup your user interface to disable these commands unless the user first disabled ControlOnSchedule e ArmAllHighPower e ArmAllLowPower e DisarmAll 4 4 3 Commands that apply to individual zones These commands require a zoneld parameter All the zones and their zoneld parameters are contained in the configuration settings that you receive in the OnSessionAccepted message after you first connect JVA Perimeter Patrol cannot obey these commands if ControlOnSchedule is switched on Therefore set up your user interface to disable these commands unless the user first switched ControlOnSchedule off e ArmHighPower e ArmLowPower e Disarm JVA Technologies Pty Ltd 2012 Page 22 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface ArmAl HighPower string username string password out Exception exception ArmAllLowPower string username string password out Exception exception DisarmAl string username string password out Exception exception ArmHighPower string username string password int zoneId out Exception exception ArmLowPower string username string
38. the alarm has been resolved However the device will hold the alarm open until it receives a ClearAlarmMemory command from a keypad or from JVA Perimeter Patrol Because JVA Perimeter Patrol reports alarms exactly as they are reported by the devices JVA Perimeter Patrol will also indicate these alarms until after they have been cleared in the devices Clearing the device s alarm memory is the purpose of the ClearAlarmMemory command that you will see in the High Level Interface documentation Without this command your software users will not be able to stop the devices from reporting resolved alarms The best way for you to know whether an open alarm was generated by a device is to use the code found in the Interpreter object for this purpose in the demo HLI client project JVA Technologies Pty Ltd 2012 Page 24 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface Alarms generated by JVA Perimeter Patrol In addition to reporting alarms generated by devices the JVA Perimeter Patrol generates its own alarms too Many of them look similar to the alarms generated by devices but they are often more informative For example while a device can only generate a general fence alarm the JVA Perimeter Patrol can create Under Voltage and Over Voltage alarms for each of three locations at which voltage is measured on each zone This extra information helps users to
39. tting started High Level Interface 2 Getting started This document assumes that you have a Security Electric Fence installation contractor who knows how to set up the electric fence systems as well as configure and command them using the JVA Perimeter Patrol software package To begin you will have an electric fence set up already or you will have a small testing rig in your office with a short section of fence and a number of JVA electric fence energisers or other devices You will have a computer with JVA Perimeter Patrol connected to the devices and you will have already sent commands to the devices from that computer 2 1 Configuring Perimeter Patrol Since you will be connecting to Perimeter Patrol with the HLI you need to configure it to accept the connections There are two small jobs you need to do e Configure Perimeter Patrol to accept HLI connections e Configure the user accounts in Perimeter Patrol 2 1 1 Configuring Perimeter Patrol to accept HLI connections e Click Setup gt System Configuration e Open the HLI Server tab e Choose HLI Server Enabled e Set the TCP Listening Port to a value between 1 000 and 10 000 e Seta value for the Authentication Key It doesn t matter what value you use for the Authentication Key during testing but you should use the Generate button to make a complicated key for your production sites because this key is like a password code that prevents unauthorized software from connectin
40. ttings on JVA Perimeter Patrol while your software is connected via the HLI Transport Of course JVA Perimeter Patrol will have to notify your software system about the configuration changes To do so JVA Perimeter Patrol will disconnect your HLI Transport object and allow it to automatically reconnect one second later After the reconnection is successful JVA Perimeter Patrol will send another OnSessionConnected message with the new configuration settings You can read the Understanding the Configuration Data Structure section Error Reference source not found to learn more about the JVA Perimeter Patrol configuration settings JVA Technologies Pty Ltd 2012 Page 16 of 30 Version October 2012 Uncontrolled if printed JVA Perimeter Patrol Using the HLI in your custom software High Level Interface f f lt summary gt f f Called after a connection has been established with the Perimeter Patrol server and the session has been authenticated successfully Note that whenever the Perimeter Patrol Server s configuration settings have been changed f f the client will be disconnected from the server This done so that when the client automatically reconnects to the server f f it will receive updated configuration settings f f lt summary gt lt param name contig gt Perimeter Patrol Server configuration settings lt param gt lt param name loge gt Contents of the log file as an xml string lt
Download Pdf Manuals
Related Search