ICT Protege

Pierre Kil edited this page Jan 19, 2017 · 13 revisions
Clone this wiki locally

Introduction

Integrated Control Technology (ICT) is the developer of the Protege Suite - an enterprise level integrated access control, intrusion and building automation system. The system can be easily tailored for operation in a single site right through to multi-national corporations.

NOTE: ICT Protege is only available with OpenRemote Designer 2.1_

OpenRemote is able to control doors, areas, outputs, variables, and bypass inputs on the Protege Controller. It can also monitor the current status of all of the above, along with receiving events generated by the controller.

Designer Overview

The Designer needs to be configured in two places for the ICT Protege integration. The Protege controller's IP address, encryption settings, and other settings are edited within the Designer Configuration section. Commands are created by selecting the ICT Protege protocol from the new command drop-down box.

Global Configuration

The Global Configuration contains all of the options for communicating with the Protege Controller. It is located on the Building Modeler page of the designer (the house icon). At the bottom of the page click the Config for Controller button and select ict_protege.

Address

This is the IP address and Port number of the Protege controller. It is in the format IP:Port (for example, 192.168.1.2:9189).

Encryption Type

Match this to the Protege controllers service settings.

Encryption Key

Match this to the Protege controllers service settings.

Monitoring Pin

This is an optional PIN number used for monitoring events and the status of records without having to be logged in as a user. If left blank, this feature will be disabled. For security, it is important that the user does not have an access level and therefore cannot control the system. However, in a situation where the network is considered to be highly secure and the OpenRemote controller files cannot be accessed, this can be set to an actual user. In this case the user would not have to worry about logging in or out in order to control their system. Please note that this value is stored on the OpenRemote designer server and therefore is subject to the security of their system. If the above functionality is desired, it may be preferable to leave this field empty and edit the controller's "..\webapps\controllercontroller.xml" file after download.

ICT Protege - ICT_Configuration

Devices

Devices are used to group commands and sensors. They can be created from the Building Modeler page of the designer (The house icon).

Creating a new device
  1. Select the New button at the top of the page and click New Device
  2. Enter the name of the device (for example Protege WX).
  3. Set the Vendor to ICT.
  4. Set the Model to WX, GX or SE.
  5. Clicking next will present you with the options to add commands and other features.
Adding Commands
  1. Click New | New Command (or the Add Command button if you are creating a new device).
  2. Enter the name of the command, which should be a short description of what this command does (for example, Unlock Front Door).
  3. Set the Protocol to ICT Protege.
  4. The commands available are described below in the Commands section.
  5. The record index refers to the record ID of the item the command is controlling. If using a WX with the ACPUseDisplayOrder option enabled, the index is the records position in the list. Otherwise it is the database ID of the record. A more detailed description of this is in the Setting up the Protege Controller | Configure the Controller section of this document.
  6. The Record Value is dependent on the command. It is either Door, Area, Output, Input, Variable or a number.

If you forget which value should go in the record index or value box, simply enter an invalid value (for example a "?") and on the right side a red "!" will appear. Hovering this will show you the options you are allowed to use.

ICT Protege - Record_Value_Hint

Commands

Control Commands

Door

Door commands allow the locking, unlocking and latch unlocking of doors.
Record Index: The Record ID of the door.
Record Value: Not used.

  • Door Lock
  • Door Unlock
  • Door Latch
Area

Area commands allow the arming and disarming of areas. This includes the normal and 24hr partitions of the area. Areas can also be force, stay or instant armed.
Record Index: The Record ID of the area.
Record Value: Not used.

  • Area Disarm
  • Area Disarm 24hr
  • Area Disarm All (Disarms both the normal and 24hr partitions)
  • Area Arm
  • Area Force Arm
  • Area Stay Arm
  • Area Instant Arm
Output

Output commands can turn outputs on or off and also turn them on for a set amount of time.
Record Index: The Record ID of the output.
Record Value: If the Output On Timed option is selected, set this to the time to activate the output for.

  • Output Off
  • Output On
  • Output On Timed
Input

Input commands allow the control of the bypass state of an input. The bypass can be removed, added until next disarm or added permanently.
Record Index: The Record ID of the input.
Record Value: Not used.

  • Input Remove Bypass
  • Input Temporary Bypass
  • Input Permanent Bypass
Variable

Variable commands allow the value of a variable to be set.
Record Index: The Record ID of the variable.
Record Value: The value to set the variable to.

  • Variable Set

System Commands

System commands are used for monitoring or for logging into the Protege controller.

System Monitor Record

This command is used with sensors in order to view the real time status of a record.
Record Index: The Record ID of the record to monitor.
Record Value: Select from Door, Area, Output, Input or Variable. (Please note that OpenRemote fields are case sensitive and that these values must be entered as shown here).

System Request Events

This command asks for events to be sent from the controller to the OpenRemote app. These are saved to a file on the OpenRemote controller and are used to populate sensors on the event sensor page. See the Events Screen configuration guide for more information.
Record Index: Not used.
Record Value: Not used.

Send Login

This sends the current PIN number to the controller and attempts to login. If the PIN is incorrect it will be cleared. This also logs out the current user.
Record Index: Not used.
Record Value: Not used.

Clear Login

Clears the current PIN and also logs out from the controller.
Record Index: Not used.
Record Value: Not used.

Pin Digit

Sends a PIN digit to the OpenRemote controller, which will be forwarded to the Protege controller when a Send Login command is sent.
Record Index: Not used.
Record Value: The PIN digit to send (0-9).

System Status Monitoring Commands

Status monitoring commands are used to check the state of various parts of the system. These do not have a Record Index or a Record Value.
Record Index: Not used.
Record Value: Not used.

Monitor Login Status

Checks if the user is currently logged in to the protege controller. This should be shown on every page that sends commands if possible, as commands sent while not logged in will be ignored by the Protege controller.
States: User, Monitoring, Logged Out

Monitor Connection Status

Checks if the connection between the OpenRemote controller and the Protege controller is live. Commands sent while disconnected will be queued until the connection is re-established.
States: Connected, Disconnected

Monitor Queued Commands

Returns the number of commands currently waiting to be sent to the Protege controller. This is mainly for debugging purposes.
States: 0-100

Configuration Guides

These guides provide simple instructions to get the most out of the OpenRemote - Protege integration. If this is the first time setting up the Protege commands on your OpenRemote account, you will need to add the commands in each section. These steps assume that you have already created a Device and a Panel.
All custom state items must match the capitilisation as shown in this document.

System Status

The system status sensors are used on every page to inform the user of the current state of the OpenRemote controller.

Connection Status Sensor

This sensor provides information about the network connection between the OpenRemote controller and the Protege controller. Note that this does not notify you if the OpenRemote app loses connection, as this is handled by the app itself.

Connection Status Command
  1. Click on the Building Modeler icon and open the Device tab.
  2. Click New | New Command
  3. Enter Connection Status in the Name field.
  4. Select ICT Protege in the Protocol drop down box.
  5. Select Monitor Connection Status from the Command drop down box.
  6. Click Submit.

ICT Protege - Command_Connection_Status

Connection Status Sensor
  1. Click New | New Sensor
  2. Enter Connection Status Sensor in the Name field.
  3. Select the Connection Status command in the Command window.
  4. Set the Type to Custom.
  5. Add a custom state item for Connected.
  6. Add a custom state item for Disconnected.

ICT Protege - Sensor_Connection_Status

Login Status Sensor

This sensor provides information on whether a user is logged into the Protege controller. Users must be logged in to control the system.

Login Status Command
  1. Click on the Building Modeler icon and open the Device tab.
  2. Click New | New Command
  3. Enter Login Status in the Name field.
  4. Select ICT Protege in the Protocol drop down box.
  5. Select Monitor Login Status from the Command drop down box.
  6. Click Submit.

ICT Protege - Command_Login_Status

Login Status Sensor
  1. Click New | New Sensor
  2. Enter Login Status Sensor in the Name field.
  3. Select the Login Status command in the Command window.
  4. Set the Type to Custom.
  5. Add a custom state item for User.
  6. Add a custom state item for Monitoring.
  7. Add a custom state item for Logged out.

ICT Protege - Sensor_Login_Status

Using the Sensors

The sensors are shown in the top right hand corner of the example keypad screen below. The satellite dish is for the connection status and the ID card is for the login status.

  1. Open up the UI designer page.
  2. Select a screen.
  3. Add a new Image.
  4. Set the Sensor to your Connection State Sensor.
  5. Click the button beside Connected in the Sensor State box.
  6. Select an image.
  7. Click the button beside Disconnected in the Sensor State box.
  8. Select an image.

Repeat the above steps for the login status sensor.

Login Keypad

The login screen is essential to using the Protege system. It provides an extra layer of security to ensure that only authorized users can access the system.

ICT Protege - Example_Keypad

Keypad Commands

PIN Digits
  1. Click on the Building Modeler icon and open the Device tab.
  2. Click New | New Command
  3. Enter PIN 0 in the Name field.
  4. Select ICT Protege in the Protocol drop down box.
  5. Select PIN Digit from the Command drop down box.
  6. Enter 0 in the Record Value field.
  7. Click Submit and Continue. This will save the current command, but allow you to create another one using the same values.
  8. Change the Name to PIN 1 and the Record Value to 1, then click Submit and Continue.
  9. Repeat these steps for digits 2 through 9.

ICT Protege - Command_PIN_Digit

Send Login

This command sends the PIN to the Protege controller. 1. Create a new command with the Name Send Login. 2. Set the Command to Send Login. 3. Click submit.

ICT Protege - Command_Send_Login

Clear Login / Logout

The Clear Login command both resets the current PIN that the user has entered and logs out any current user. 1. Create a new command with the Name Clear Login (or Logout if you prefer). 2. Set the Command to Clear Login. 3. Click submit.

PIN Display Sensor

This sensor provides information to the user when they are entering their PIN number. It will show *'s when they press a digit and show a status after clicking send or clear.

PIN Display Command
  1. Click on the Building Modeler icon and open the Device tab.
  2. Click New | New Command
  3. Enter PIN Display in the Name field.
  4. Select ICT Protege in the Protocol drop down box.
  5. Select Monitor PIN Display from the Command drop down box.
  6. Click Submit.

ICT Protege - Command_PIN_Display

PIN Display Sensor
  1. Click New | New Sensor
  2. Enter PIN Display Sensor in the Name field.
  3. Select the PIN Display command in the Command window.
  4. Set the Type to Custom.
  5. Sensor_PIN_Display.png|align=center

Keypad Design

We will now use the designer to create a keypad. This can be easily customised to suit the user.

Layout
  1. Click on the UI Designer button.
  2. Click New | New Screen From Template.
  3. Enter Keypad in the name field.
  4. Click the Public radio button, and then search for ICT Protege.
  5. Select the Protege Keypad entry and click submit.
  6. You should now have a new screen with several buttons and labels. Templates can only be used to save the interface layout, so you will still need to assign the commands and sensors manually._

ICT Protege - New_Screen_From_Template

Setting Commands and Sensors
  1. Click on the Keypad screen.
  2. Click on button 1.
  3. On the right side of the screen, in the Button Properties window, click the Select button next to Command.
  4. Expand Devices | Device Name and select Pin 1. Click OK. Repeat these steps for the remaining PIN number buttons.
  5. Set the Clear button Command to Clear Login.
  6. Set the Enter button to Send Login.
  7. Click the PIN Status label and set the Sensor to PIN Display Sensor.
  8. Click the top right image and set the Sensor to Connection Status Sensor.
  9. Click the image to the left and set the Sensor to Login Status Sensor.

ICT Protege - Button_PIN

ICT Protege - Label_PIN_Sensor

Events Screen

The events screen is used to display a series of events from the Protege controller. A user must be logged in to receive events. The Monitoring PIN configuration field can be used in order to receive events without having to be logged in with an actual persons PIN number. Please see Monitoring PIN for more details.

  1. Create a single System Request Events command.
  2. Create several sensors, Event Sensor 1 to Event Sensor X.
    a. Set the command to the one created above.
    b. Set the type to custom. Do not add any mappings.
  3. Add several labels to the screen, making sure you add them from the top of the screen to the bottom.
  4. Set the top label's sensor to Event Sensor 1.
  5. Repeat with the rest of the labels, finishing with the bottom label as Event Sensor X.
    a. If events are not displayed in the correct order, check that you have the Event Sensors added to the labels in the order that the sensors were created. Events will be sorted by the ID number of the sensor, which is incremented in OpenRemote each time a new sensor is made.

ICT Protege - Example_Events_Screen

Protege Controller Setup

Please ensure that you are using WX firmware with an application version of 2.20.384 or later. To confirm this, please go to System | Firmware and click on the "Current Versions" text.

Configure the Controller

If using a WX controller, you will need to enter the following command into the Commands box under System | Settings:

ACPUseDisplayOrder true

This command means that all records will be referenced by their position in the list shown in the WX interface. For example, navigating to Programming | Doors and selecting the third door in the list will be referenced as record number 3. Without this command the door will be referenced by its database ID, which is how records are controlled on the GX and SE controllers.

Create the Service
  1. Go to Programming | Services.
  2. Add a new service.
  3. Set the service type to Automation and Control.
  4. Set the service mode to Start With Controller OS.
  5. On the general tab set up a TCP port that the service will run on. This port will need to be opened in firewalls and port forwarded if the Protege and OpenRemote controllers are on different networks.
  6. Set the encryption level to None.
  7. Set the Checksum Type to 8 Bit Sum.
  8. Enable the Ack Commands option.
  9. It is recommended to enable the User Logon Lock Out Timer If Incorrect PIN Is Supplied option for improved security.

OpenRemote Controller Setup

Download and setup OpenRemote as per the instructions at Getting Started.

Enable Apache Tomcat authentication

Enabling authentication on the Tomcat server is very important. This ensures that users must login to the OpenRemote controller when using the application. Without this feature, any web browser can be used to send a command to the ICT controller.

  1. Uncomment all items in the Security Configuration section of the web.xml file, located in \webapps\controller\WEB-INF.

  2. Add users to the user.xml file, located at \security.

    <?xml version='1.0' encoding='utf-8'?>

Enable Tomcat SSL

SSL is an imporant method to secure the connection between the OpenRemote application and controller. This is essential when using Tomcat authencication, and is highly recommended to prevent the interception of user PIN's. An in-depth guide can be found at Tomcat SSL Configuration. Below is a summary of the steps required to enable SSL for Tomcat.

Generate a keystore From the command line, enter the following. This assumes the JAVA_HOME environment variable has been set. For more information, please visit Installing the JDK Software and setting JAVA_HOME. Windows:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA

Unix:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

A specific folder can be defined by appending:

-keystore /path/to/my/keystore/

Along with a filename and .keystore file association. For example:

-keystore /path/to/my/keystore/tomcat.keystore

Edit server.xml Navigate to \conf and edit the server.xml file: Remove the comments around the SSL Coyote Connector line, as follows:

<!-- Define a SSL HTTP/1.1 Connector on port 8443... -->
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" 
               keyAlias="ORTomcat" keyPass="ORKeyChangeit"
               keystoreFile="${user.home}/.keystore" keystorePass="changeit"/>

Add the necessary keystore options, described below, and save the file.

  • keyAlias: Keystore alias defined when generated in the Generate a Keystore step.
  • keyPass: Password for the private key in the keystore, if different than keystore.
  • keystoreFile: Filepath location of the keystore created in the Generate a Keystore step.
  • keystorePass: Password for the keystore.

Optional: Changing the port number from the default Tomcat SSL port 8443 to the more widely used SSL port 443 can be done by modifying the server.xml file. Change the Connector, edited above, to port="443".
Also edit the other connector, shown below:

<Connector executor="HTTP-ThreadPool"
               port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="443" />

Templates

Below is a list of Templates that are available from ICT. To use these, click on New | New Screen From Template under the Panels section of the designer. They can all be found under the keyword "ICT".

ICT Keypad

This template contains a sample layout for the login screen.

ICT Resources

This templates contains all of the image resources on a single iPad screen. This is an easy way to import all of the ICT demo images into your project.

See Also