UltraCID3 HSPI User’s
Guide
A HomeSeer HS3 plug-in to store and retrieve
caller ID data
Copyright © 2014
[email protected]
Revised 12/21/2014
This document contains proprietary and copyrighted information and may not be copied, reproduced,
translated, or reduced to any electronic medium without prior consent, in writing, from
[email protected].
Table of Contents
Introduction .................................................................................................................................................. 4
Intended Audience .................................................................................................................................... 4
UltraCID3 HSPI Overview .............................................................................................................................. 4
How It Works ............................................................................................................................................ 4
Features .................................................................................................................................................... 4
Requirements............................................................................................................................................ 4
UltraCID3 HSPI Installation ........................................................................................................................... 4
Downloading and Installing the HomeSeer Plug-in .................................................................................. 4
UltraCID3 HSPI Setup .................................................................................................................................... 5
Initial Setup Checklist ................................................................................................................................ 5
Screenshots: .............................................................................................................................................. 5
UltraCID3 HSPI Configuration ....................................................................................................................... 6
Web Page Layout ...................................................................................................................................... 6
UltraCID3 HSPI Options ............................................................................................................................. 7
Screenshot ............................................................................................................................................ 8
UltraCID3 HSPI Caller Log .............................................................................................................................. 8
Screenshot ................................................................................................................................................ 9
UltraCID3 HSPI Caller Details ........................................................................................................................ 9
Modifying Caller Details ............................................................................................................................ 9
Deleting Caller Details ............................................................................................................................... 9
Screenshot .......................................................................................................................................... 10
UltraCID3 HSPI Plug-in Devices ............................................................................................................... 10
Modem Device ........................................................................................................................................ 10
Phone Extension Device .......................................................................................................................... 10
Last Caller Name Device.......................................................................................................................... 10
Last Caller Number Device ...................................................................................................................... 10
Last Caller Attribute ................................................................................................................................ 10
Last Caller Rings ...................................................................................................................................... 10
UltraCID3 HSPI Triggers............................................................................................................................... 11
2
UltraCID3 Incoming Caller ....................................................................................................................... 11
Screenshot .......................................................................................................................................... 11
UltraCID3 OnRing .................................................................................................................................... 11
UltraCID3 Local Handset ......................................................................................................................... 11
Screenshot .......................................................................................................................................... 12
UltraCID3 Phone Extension ..................................................................................................................... 12
Screenshot .......................................................................................................................................... 12
UltraCID3 HSPI Trigger Actions ................................................................................................................... 12
UltraCID3 Drop Caller.............................................................................................................................. 12
UltraCID3 HSPI Trigger Conditions .............................................................................................................. 13
UltraCID3 HSPI Replacement Variables ...................................................................................................... 13
UltraCID3 HSPI Speak Examples .................................................................................................................. 13
Screenshot .......................................................................................................................................... 14
UltraCID3 HSPI E-mail Notification Examples ............................................................................................. 14
Screenshot .......................................................................................................................................... 15
UltraCID3 HSPI API Reference ..................................................................................................................... 15
3
Introduction
UltraCID3 is a HomeSeer3 plug-in that allows you to use HomeSeer and an inexpensive USB or PCI
modem to log callers to an underlying database. The plug-in also supports triggering HomeSeer
events based on the name, number or attributes of a received call.
Intended Audience
This document is intended for the HomeSeer user that has chosen to install and configure the UltraCID3
HomeSeer Plug-in.
UltraCID3 HSPI Overview
How It Works



UltraCID3 listens for incoming caller ID (caller identification, CID) messages from your PCI or USB
modem and inserts the data into an underlying database.
HomeSeer events can be written to trigger based on the name, number or attributes of a
received call.
Access to the underlying database is provided via built in web pages and a plug-in API.
Features




Supports HomeSeer triggers based on caller ID events.
Logs all calls and associated caller ID information to an underlying database.
Error Try/Catch logic to ensure plug-in doesn't fail with an unhandled exception.
Multiple threading allows UltraCID3 to process caller ID events without disrupting the
performance of HomeSeer.
Requirements


Homeseer 3 or greater.
Modem that supports caller identification (CID).
UltraCID3 HSPI Installation
Downloading and Installing the HomeSeer Plug-in
1. From your HomeSeer web page, select PLUG-INS > Manage.
2. Click the + icon next to Additional Interfaces to expand the list of available HomSeer3 plug-ins.
3. Click the + icon next to the “Telephone,Text and Email Integration” category, then click the
checkbox next to the UltraCID3 plug-in package to mark the plug-in for installation.
4. Under “Pending Updates/Installs”, click the Download and Install button.
4
5. Once the installer finishes, find the UltraCID3 plug-in under Installed Plug-Ins, then enable it.
UltraCID3 HSPI Setup
Before you begin to configure the UltraCID3 plug-in, you’ll need to make sure you test connectivity to
your modem to be sure it is working properly.
Initial Setup Checklist
1. Modem Installation – Refer to the Modem Install Guide and User Manual on how to install the
modem.
2. Enable Caller ID – Using a serial program like PuTTY, connect to the serial port of your modem,
and then enable caller ID output by copy and pasting the following commands.
Note: Download PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
a.
b.
c.
d.
ATZ <enter>
AT+VCID=1 <enter>
AT+FCLASS=8 <enter>
AT-STE=7 <enter>
Screenshots:
5
3. Confirm Extension Notifications – Lift up a phone extension in your home to confirm you see
output containing the characters P (indicating off hook) and p (indicating on hook).
4. Confirm Handset Notifications – Lift the handset connected to your modem to confirm you see
output containing the characters H (indicating off hook) and h (indicating on hook). PCI modems
support handset notifications by connecting a phone to the handset jack on the modem. Most
USB modems do not support handset notification as there is only one phone connection to the
modem.
5. Confirm Caller ID Output – Call your home number and confirm you see caller ID output
containing DATE =, TIME =, NMBR = and NAME = lines.
UltraCID3 HSPI Configuration
Web Page Layout
The UltraCID3 plug-in has four web pages that provide access the available features of the plug-in.
6
The available web pages are as follows:
1. Status – Displays the plug-in, modem and database status.
2. Options – Displays and allows you to change the options associated with the plug-in.
3. Caller Log – Provide the ability to quickly filter and display the caller logs stored in the database
tables.
4. Caller Details – Allows you to view the caller details and to modify the caller alias and other
caller attributes (announce caller, block caller, etc).
UltraCID3 HSPI Options
All options are set from the Options web page. The following options are supported:
1. Serial Com Port – Specifies the serial port number used to connect your caller ID modem. The
default is disabled.
2. Modem Initialization – Specifies the modem initialization commands used to set up caller ID
logging. You can override the default settings if your modem requires other initialization
commands.
3. Drop Caller - Specifies the modem commands to drop a caller. You can override the default
settings if your modem requires other commands to terminate a call.
4. Use Number Block Mask – Specifies the regular expression to use to block incoming calls based
on the caller ID number.
5. Use Name Block Mask – Specifies the regular expression to use to block incoming calls based on
the caller ID name.
6. Add Announce Attribute – If set to Yes, this option will automatically add the announce caller
attribute to new callers.
7. Caller Number Query URL – Enter the URL that will be used when looking up a caller. Use
$nmbr for the number variable.
8. 9 Digit Format – Specifies the format of a 9 digit number.
7
9. 10 Digit Format – Specifies the format of a 10 digit number.
10. 11 Digit Format - Specifies the format of an 11 digit number.
11. Authorized User Roles – The HomeSeer users authorized to access the web page. This option
does not override the default HomeSeer web server settings.
12. Debug Mode – If set to Yes, the plug-in will write verbose logging to the HomeSeer log file.
Screenshot
UltraCID3 HSPI Caller Log
The Caller Log web page displays a list of recent callers for the past 30 days. You can display callers
older than 30 days by clicking the Caller Log Search arrow, then click the From: textbox to display a
calendar. You can also easily search results by simply typing text in the search box.
8
Screenshot
UltraCID3 HSPI Caller Details
The Caller Details web page allows you to display information on the callers and edit the display name,
caller notes and caller attributes.
Modifying Caller Details
1.
2.
3.
4.
Click on the UltraCID3 > Caller Details tab.
Find caller you want to edit, and then click the Edit link.
Edit the values as needed, then press the Update button.
To cancel the changes, simply click the X icon in the upper right corner.
Deleting Caller Details
1.
2.
3.
4.
Click on the UltraCID3 > Caller Details tab.
Find the caller you want to delete, and then click the Delete link.
Confirm you want to delete the Caller by clicking the Delete button.
To cancel, simply click the X icon in the upper right corner.
9
Screenshot
UltraCID3 HSPI Plug-in Devices
Modem Device
This HomeSeer device allows you to enable or disable the caller ID monitoring. If you need to open or
close the modem port for any reason, simply click the Open or Close button from the HomeSeer Status
web page.
Phone Extension Device
This HomeSeer device displays the status of the phone extensions (on hook, off hook).
Last Caller Name Device
This HomeSeer device displays the name of the last caller.
Last Caller Number Device
This HomeSeer device displays the number of the last caller.
Last Caller Attribute
This HomeSeer device displays the selected attributes for the last caller.
Last Caller Rings
This HomeSeer device displays the number of rings for the last caller.
10
UltraCID3 HSPI Triggers
UltraCID3 Incoming Caller
This option allows you to trigger a HomeSeer event based on an incoming call. The following plug-in
specific triggers are supported:
1. Any Caller – triggers on any caller with CID data.
2. First Time Caller – Triggers when the plug-in detects a caller that is not already in the database.
3. Announce Caller – Triggers when a call is received and the caller has the “Announce” attribute
set.
4. Block Caller – Triggers when a call is received and the caller has the “Block” attribute set.
5. Business Caller – Triggers when a call is received and the caller has the “Business” attribute set.
6. Family Caller - Triggers when a call is received and the caller has the “Family” attribute set.
7. Friends Caller - Triggers when a call is received and the caller has the “Friends” attribute set.
8. Telemarketer Caller - Triggers when a call is received and the caller has the “Telemarketer”
attribute set.
9. Caller Number [Caller Name] – Triggers when a call is received from the specified caller.
Screenshot
UltraCID3 OnRing
This option allows you to trigger a HomeSeer event on a particular ring.
UltraCID3 Local Handset
This allows you to trigger a HomeSeer event whenever the local handset is picked up. The following
plug-in specific triggers are supported:
1. On-Hook – Triggers when the local handset goes on-hook
2. Off-Hook – Triggers when the local handset goes off-hook.
11
Screenshot
UltraCID3 Phone Extension
This allows you to trigger a HomeSeer event whenever an extension is picked up. The following plug-in
specific triggers are supported:
1. On-Hook – Triggers when an extension goes on-hook.
2. Off-Hook – Triggers when an extension goes off-hook.
Screenshot
UltraCID3 HSPI Trigger Actions
UltraCID3 Drop Caller
This action answers the phone after the caller ID information is available (usually after 1 ring) then
disconnects the call.
12
UltraCID3 HSPI Trigger Conditions
To be determined
UltraCID3 HSPI Replacement Variables
You can use any of the supported HomeSeer replacement variables in the Speak and E-mail notification
examples below (see the Using Replacement Variables in the HomeSeer documentation for a complete
list of replacement variables).
The following replacement variables can be used in the Speak and E-mail notification examples.
$$DTA:UltraCID3-Name:
Replaced with the caller name
$$DTA:UltraCID3-Nmbr:
Replaced with the caller number
$$DTA:UltraCID3-Attr:
Replaced with the list of the caller attributes
$$DTA:UltraCID3-Ring:
Replaced with the number of rings
UltraCID3 HSPI Speak Examples
You can use the HomeSeer to speak the caller information when a new incoming call is detected. Simply
create a new HomeSeer event with an “UltraCID3 : Incoming Call” trigger, then select “Announce
Caller”. See UltraCID3 Incoming Caller for a complete list of the supported incoming call triggers.
For the Event Action, select “Speak”, then enter the announce text you want to speak. As an example,
enter “Incoming call from $$DTA:UltraCID3-Name:”. This will cause HomeSeer to replace
$$DTA:UltraCID3-Name: with the name of the last caller.
Please Note: If you want to speak different text for first time callers, then set New Caller Options > Add
Announce Attribute to False, then create another event and select “First Time Caller” as the event action.
13
Screenshot
UltraCID3 HSPI E-mail Notification Examples
You can use the HomeSeer to send an e-mail notification that includes the caller information when a
new incoming call is detected. Simply create a new HomeSeer event with an “UltraCID3 : Incoming Call”
trigger, then select “Announce Caller”. See UltraCID3 Incoming Caller for a complete list of the
supported incoming call triggers.
For the Event Action, select “Send an Email”, then enter the notification text you want to include in the
message body. As an example, enter:
You received a new incoming call from
$$DTA:UltraCID3-Name:
$$DTA:UltraCID3-Nmbr:
on $date $time
14
Screenshot
UltraCID3 HSPI API Reference
To be determined
15