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
© Copyright 2024