Napco Gemini HomeSeer Plug-in

Release notes and Legal notices

Napco Gemini Support Forum

Overview

This plug-in adds support for the Napco Gemini security panel.  It allows HomeSeer to receive configuration information (zones/areas), real-time status updates (events/keypad status messages) and to control certain functions of the panel.  It adds many new triggers and several new actions to HomeSeer.

System Requirements

Napco Security Panel

GEM-P3200*, GEM-P9600, GEMX-255

Original Napco panels. *older P3200 (hardware v11) reportedly work with GEM-AUTOMATION but newer (hardware 20+) do not

GEMC-32, GEMC96, GEMC-128, GEMC-255

Newer Napco panels expected to work with this plug-in.

This plug-in was developed and tested with a GEM-P9600 panel and GEM-AUTOMATION v40c


Napco GEM-AUTOMATION

This is the EPROM firmware upgrade that allows two-way communication with a Napco Security Panel.  This upgrade package may include the Napco PCIMINI for direct serial communication but it is recommended to use the GEM-RS232 discussed next.

This plug-in was developed and tested with GEM-AUTOMATION version v40c


Napco GEM-RS232 (recommended option)

Napco PCI-MINI (alternate option)

This is a panel mounted serial interface that provides signal and ground isolation between the HomeSeer PC and the Napco Security Panel. It is recommend to use this over the PCI-MINI direct serial connection option.

GEM-RS232 can be connected directly to a standard traditional serial port or can be used with a serial to USB adapter.  Note that serial to USB adapters may introduce noise into the communication slowing down the process as retries are necessary.

This plug-in was developed and tested using the GEM-RS232 serial interface and a serial to USB adapter by VSCOM (FTDI driver 7/12/13 v2.8.30.0)


Napco RM3008

This is a remote relay board module designed to work with the original Napco GEM series panels.

Napco GEMC-RM3008

This is a remote relay board module designed to work with the newer Napco GEMC series panels.

This plug-in supports the commands necessary to turn on/off relays assuming they are correctly configured with the Napco panel.  This plug-in was not tested with this relay board option.


NOTE!  This plug-in does not provide Napco Panel programming capability.  Tools like Napco Quickloader for Windows  or keypad programming techniques must still be used separately to pre-configure the Napco panel before connecting to HomeSeer via this plug-in.  This is in line with previous Napco Gemini support under HomeSeer 1 and 2.

Plug-in Web-Based Configuration

This section details the plug-in configuration options

Initial Startup

After using the HomeSeer updater to install the plug-in, a few settings are required before communication with the panel can commence.  The main HomeSeer dialog window may show error(s) similar to:

1/11/2014 6:08:27 AM ~!~Napco Gemini Error~!~No MASTER CODE defined.  Use config page to enter. Be sure to SAVE when done.
or
1/11/2014 6:09:11 AM ~!~Napco Gemini Error~!~No serial port defined.  Use config page to enter. Be sure to SAVE when done.

The PLUG-INS -> Manage web page may also show plug-in interface status warnings like:

WARNING: No MASTER CODE defined. Use config page to enter. Be sure to SAVE when done.
or
WARNING: No serial port defined. Use config page to enter. Be sure to SAVE when done.

Access the Napco Gemini plug-in configuration via the menus.

PLUG-INS -> Napco Gemini -> Napco Gemini Config

Napco Gemini Web-Based Config

Panel -> Max Zones

First, consider the number of zones the panel supports but more importantly the highest zone number actually configured and in use.   Set the Max Zones to at least the highest configured and used zone number.  The default is 32 but many panels support up to 96, 128 or 255.  Setting Max Zones only as high as the highest configured and used zone number will speed up panel communications.

Panel -> Master Code

Next, it is necessary to enter the Master Code for your panel.  This should be a 6-digit all numeric entry and can usually be found on a sticker inside the panel over the cover to the EPROM.  Note that the master code will likely have changed from the original factory code to a new one when the GEM-AUTOMATION upgrade was installed.  The Master Code will display in the config page in clear text but it will be encrypted before storing to the INI file.

Panel -> Serial Port

Finally, it is necessary to enter the Serial Port that the panel is connected to.  This can be done with the full name like COM4 or abbreviated just to the numeric digit 4 (COM will be added)

Panel  Communications

Once the Max Zones, Master Code and Serial Port have been entered, an initial connection to the panel will be made.  This will take a minute!  The web page will display a “please wait” type message while the panel communication is occurring.  When complete, an updated list of zones will be displayed on the web config page.  Assuming these required values were saved, on future startups the plug-in will obtain this same status information automatically at HomeSeer start.

 The time it takes to communicate with the panel is directly related to the number of zones defined by the Max Zones setting.  Regardless of how many zones are actually available or how many are actually configured in use in the panel, commands will be issued to see the status of each zone from 1 to Max Zones.

Napco Gemini Config Showing Zones

Timing -> Command Timeout:

This setting controls how long the plug-in will wait after sending a command to receive back the expected reply.  A default of 5 seconds has been chosen as that aligns with the documented time that the panel will wait after receiving a command before it times out and goes back to non-command mode.  This setting is important to the retry processing that the plug-in does with the panel.  Setting this value too high may make it appear that the panel is sluggish or non-responsive during communication failure retry loops.  Unless specifically troubleshooting an issue, the default of 5 is recommended.

Timing -> Max Retry:

The Max Retry setting controls all the retry loop logic within the plug-in.  When a command times out, a retry will be issue.  If the serial communication is noisy, several retries may be needed.  The default setting of 4 was chosen based on development experience working with a somewhat noisy USB-to-serial adapter.   Unless specifically troubleshooting an issue, the default of 4 is recommended.

Logging

Logging Options -> Log Incoming Status Messages?

This setting control whether the plug-in will log all incoming status messages.  NOTE! This can be quite a volume of messages.  The default for this setting is on but it is expected that most users will eventually turn this off during routine operation.

Logging Options -> Log Outgoing Commands?

This setting control whether the plug-in will log all outgoing commands issued to the panel.  This option does not generate quite as much logging traffic as the incoming above, however, it does generate enough.  The default for this setting is on but it is expected that most users will eventually turn this off during routine operation.

Logging Options -> Log Debug Information?

This setting increases the amount of logging that the plug-in does and can be quite verbose!  If this option is turned on, it is suggested that it only be done for short periods of active review and then be turned back off.  The default is off. NOTE! In addition to logging to the HomeSeer log, this will log all plug-in output to NapcoDebug.log on disk.  This file is plain text readable and may be useful for troubleshooting and support.  It can be found in the HomeSeer installation directory under Logs.

Example: C:\Program Files (x86)\HomeSeer HS3\Logs\NapcoDebug.log

Keypad Display

The plug-in provides a web-based keypad status display that simulates the Napco keypads often physically installed with the panel.  This section of the config controls options related to the web-based status display.

Keypad Display Options -> Show Zone Status Icons?

This controls whether the built-in icons are shown on the keypad display zones.  If unchecked, only the zone status string will display.

Keypad Display Options -> Arm Button?

This controls whether the Arm Area button is shown on the keypad display.

Keypad Display Options -> Disarm Button?

This controls whether the Disarm Area button is shown on the keypad display.

Keypad Display Options -> Bypass  Buttons?

This controls whether the Bypass Zone button is shown with each zone in the area.

Keypad Display Options -> Relay Controls?

This controls whether the Relay On/Off and Relay Number textbox are shown.

Keypad Display Options -> Keypad Refresh

This controls the built in timer on the web-based keypad status page.  Every X seconds the simulated keypad display(s) are updated with the latest information received from the panel via the real-time keypad status update messages.  This doesn't generate any panel command traffic.  It has no bearing on the timeliness of panel status updates or panel operations.  It only controls how often the plug-in updates the simulated keypad status page from the latest information the plug-in has.

Panel Zones

Once panel communication has been established, the list of zones found and synchronized with HomeSeer is displayed on the web config page.

Panel Zones -> Name

Each zone is shown with the name as configured in the panel.  It is important to note that while it is possible to change the HomeSeer device name for a zone, it does not alter how it is configured in the panel.  It also does not change how the plug-in remembers the name of the zone.  The zone name as determined to be configured in the panel is stored within each HomeSeer device that represents a zone as “plug-in extra data” (PED).  This allows the plug-in to continue to know the zone by the name configured in the panel which is important when restarting and synchronizing the zone information. 

Panel Zones -> Number

This is the zone number defined in the panel

Panel Zones -> Area

This is the area number that the zone is associated with in the panel

Panel Zones -> Log incoming?

This checkbox controls whether that particular zones incoming status messages from the panel can be logged.  This works together with the overall Log Incoming option.  By default all zones have their log incoming checked.  It is generally more useful to turn on or off overall incoming logging than to do it per zone.  However, this per zone option allows for eliminating incoming logging on zones that may be particularly active.

Panel Zones -> Bypass on arm?

This option exists to instruct the plug-in to automatically issue a bypass command for a zone before completing a request to arm the area associated with a zone.

HomeSeer related device info

This section is for reference only.  It shows the relevant HomeSeer device information for the zone.  This is a convenient place to see if there’s a different Panel Name vs. HomeSeer device name configured.  Other useful information like Loc (a.k.a. Room), Loc2 (a.k.a. Floor) Address and Code can also be referenced here.

HomeSeer Devices

After startup and successful configuration and panel communication, the plug-in will synchronize the information it obtains from the panel with any existing HomeSeer devices.  It will add device definitions to HomeSeer that are missing and remove device definitions from HomeSeer that do not match those configured in the panel (e.g. if a zone is renamed in the panel or area associations are changed)

HomeSeer Napco Device List

Napco Panel Status (root parent status device)

At startup, the plug-in will enumerate all HomeSeer devices until it finds those associated with it and then will look for the parent device.  There is only ever one parent device and it represents the entire panel status.

The panel status device will show the various states of the panel and its relationship with HomeSeer.

There are several command buttons to control the panel state.

Area Devices (1 to 8)

Napco panels support from one to eight areas to partition the zones.  The plug-in will create a HomeSeer device for each area number that it finds configured in the panel.  A configured area means that at least one zone is set as belonging to that area number. 

The panel status device will show the state of the area it represents in the panel to HomeSeer.

The area device also maintains some additional PED related to the icons, LEDs and status display lines that exist on the physical keypads and that are communicated to the plug-in via real-time area status updates from the panel.  This PED is used during the web status refreshes to show the current state of the area graphically inside HomeSeer.

There are two command buttons associated with an area. 

Zone Devices

Depending on the Napco panel used, zones may be from 1 to 32/96/128/255.  At startup, or during changes to the MasterCode, Serial Port or Max Zones config, or during a Napco Panel Status Refresh command, zone configuration will be requested from the panel from 1 to the Max Zones setting.  Each zone has a unique zone number, a name and an area defined in the panel.  This information is used to create a HomeSeer device that keeps track of the status of a zone.

Zones can have one of several status values.

There is only one active control for a zone and that is to Bypass it manually.  This allows for a temporary one-time bypassing of a zone.  Once the area is armed and then disarmed, the zone will revert back to a regular (non-bypassed) state.  To continually bypass a zone when HomeSeer is used to arm the area, set the config option to bypass that zone.

Like the other devices, PED is used to keep track of various settings on the zone.  Attributes like whether the zone is open, armed, bypassed, requested to be bypassed (from config), requested to be logged (from config) are all maintained in PED.

Plug-in Web-Based Status

Once everything is configured and running, it is useful to view the status of the overall panel and areas via the online web-based status page.  This page creates a virtual Napco Gemini keypad similar to the physical keypads used with the panel. Use the menus to access this.

PLUG-INS -> Napco Gemini -> Napco Gemini Status

Napco Gemini Web-Based Status

Napco Gemini Web Status Keypads

Each area is represented with a separate tab to keep the status simple and uncluttered.  The icons, LEDs and display lines for the area are all near the top of the keypad display.  These are arranged to approximate their physical keypad counterparts.   Controls for arming and disarming that specific area are in the middle. 

Below the keypad is a listing of all the zones associated to that area.  Each zone is shown with:

Finally at the bottom is a set of controls to turn on/off an arbitrary relays.  These relay controls are not area specific and appear at the bottom of each area tab.  They all can issue commands for any relay numbers.

Scripting Interface

The scripting interface for the Napco Gemini plug-in is limited due to concerns about the sensitive nature of alarm systems. Full status and all control functions are only available via the HomeSeer GUI and Web Interface.

The plug-in, can be accessed by HomeSeer scripts using the HomeSeerAPI.PluginAccess(hs, "Napco Gemini", "") object. It provides two properties, “LastSecurityEvent” and “LastCommonSecurityEvent” These allow scripts to react to panel event notifications with specific information available depending on the event.

There are two very basic example scripts provided with this plug-in. Look in the HomeSeer scripts directory for NapcoGemini_LastCommonSecurityEvent.vb and NapcoGemini_LastSecurityEvent.vb.

HomeSeer Interface HomeSeerAPI.PluginAccess(hs, "Napco Gemini", "")
PROPERTY: LastCommonSecurityEvent

This property provides the most recent common event status. Common events are those whose state is tracked by the plug-in. This list specifically includes zone open/closed/bypassed, area armed/disarmed or the last alarm issued by the panel. One other status included here is the Keypad Ambush. While not specifically tracked by the plug-in, it is included in this property.

PROPERTY: LastSecurityEvent This property latches on to each and every event issued by the panel. It will often be set to the latest keypad update event like "Keypad Green LED On" which is not often that useful.

The table below provides detail on the fields that may be set in in the properties above.

EventNumber This is the number for the event assigned by the Napco panel. Typically this should be in the range 0-255 (&H0 to &HFF)
EventName This is the name associated to the event number above. The plug-in has an array of event number/names which are documented by Napco.
Parameter1 The is the raw first Integer parameter for this event provided by the panel. For many events this is the area number. Any other use has not been documented by Napco. This is provided for completeness only.
Parameter2

The is the raw second Integer parameter for this event provided by the panel. For many events this is the zone number. There are a few events where this represents a user number defined in the panel. See UserNumber below. Any other use has not been documented by Napco. This is provided for completeness only.

AreaNumber For those Napco events that require an area, Parameter 1 above was used to lookup the area from the plug-in internal data and this is the area number.
ZoneNumber For those Napco events that require a zone, Parameter 2 above was used to lookup the zone from the plug-in internal data and this is the zone number.
ZoneName For those Napco events that require a zone, Parameter 2 above was used to lookup the zone from the plug-in internal data and this is the zone name.
UserNumber Some events like AreaArmed, AreaDisarmed or Keypad Ambush also include a Napco panel user number via Parameter 2. This is that number.