UltraLog HSPI User s Guide A HomeSeer HS2 plug-in to store and retrieve HomeSeer and syslog events Copyright 2013 ultrajones@hotmail.com Revised 01/27/2013 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 ultrajones@hotmail.com.
Table of Contents Introduction... 4 Intended Audience... 4 UltraLog HSPI Overview... 4 How It Works... 4 Features... 4 Requirements... 5 UltraLog HSPI Installation... 5 Downloading the HomeSeer Plug-in... 5 Enabling the HomeSeer Plug-in... 5 UltraLog HSPI Configuration... 6 Web Page Layout... 6 UltraLog HSPI Options... 6 UltraLog HSPI Plug-in Devices... 7 Database Connection Device... 7 Syslog Logger Device... 8 UltraLog HSPI Triggers... 8 UltraLog Log Match... 8 Screenshot... 9 UltraLog Syslog Match... 9 Screenshot... 10 UltraLog Watchdog Trigger... 10 UltraLog HSPI Trigger Actions... 10 UltraLog HSPI Trigger Conditions... 10 UltraLog HSPI Regular Expression Captures... 10 Non-named Capture... 10 Example HomeSeer Event... 11 UltraLog HSPI API Reference... 13 DBStatus Function... 13 Example... 13 2
GetSyslogStatus Function... 13 Example... 13 GetHouseCode Function... 13 Example... 13 GetSyslogStatus Function... 13 Example... 13 ResetStatistics Function... 13 Example... 13 GetStatistics Function... 13 Example... 14 ExecuteSQL Function... 14 Example... 14 3
Introduction ULtraLog is a HomeSeer HS2 v2.2 plug-in that stores HomeSeer and syslog events to an underlying database in real-time. The built in web interface allows you to query the data making it easier to turn your home automation log data into useful information. Intended Audience This document is intended for the HomeSeer user that has chosen to install and configure the UltraLog HomeSeer Plug-in. UltraLog HSPI Overview How It Works UltraLog listens for HomeSeer and syslog events and inserts the data into an underlying database. Access to the underlying database is provided via built in web pages and a plug-in API. Features Multiple threading allows UltraLog to process HomeSeer and syslog events without disrupting the performance of HomeSeer. Supports HomeSeer triggers based on text or regular expression matches on HomeSeer log or syslog events. Ability to save and recall SQL queries. Logs all events to an OLEDB aware database. Currently supports Microsoft Access (database included), Microsoft SQL 2000 and Microsoft SQL 2005, MySQL and other ADO.Net database providers. Ability to specify custom connection strings. Ability to open and close database connections while plug-in is running. Debugging output to troubleshoot database connection issues. Ability to purge database records after a specified number of months. Error Try/Catch logic to ensure plug-in doesnt fail with an unhandled exception. If you are using an external database, the database watchdog logic will automatically reconnect if the database connection is lost. Web page is non-code behind ASP.Net to allow the user to easily customize the code and interface. UltraLog can insert device status and value changes to the underlying database. This feature and designed for users that need historical data associated with each HomeSeer device. 4
Requirements Homeseer 2.2.066 or greater UltraLog HSPI Installation Downloading the HomeSeer Plug-in 1. From your HomeSeer web page, select the Updater button. 2. Click the Next button until you find the entry for UltraLog, the click the checkbox to mark the plug-in for installation. 3. Click the Next button to begin downloading the UltraLog plug-in package. 4. Restart HomeSeer once you see the following message displayed: Enabling the HomeSeer Plug-in 1. From your HomeSeer web page, select the Setup button. 2. Select the Interfaces tab. 3. From the Built-in Interfaces section, click the Disabled button to enable the UltraLog plug-in, and then select Save to enable the plug-in. 5
4. The UltraLog plug-in is now enabled. Click the UltraLog button to view the plug-in Queries, Status, Options, Filters and SQL Editor. UltraLog HSPI Configuration Web Page Layout The UltraLog plug-in has five web pages that provide access the available features of the plug-in. The available web pages are as follows: 1. Queries Provides the ability to run previously created SQL queries using the SQL Editor or new SQL queries. 2. Status Displays the plug-in status and database statistics. 3. Options Displays and allows you to change the options associated with the plug-in. 4. Filters Provide the ability to quickly filter and display the data stored in the HomeSeer log or syslog database tables. 5. SQL Editor Allows you to create and store SQL queries to run via the Queries web page. UltraLog HSPI Options All options are set from the Options web page. The following options are supported: 1. Database Type Specify the database used to store HomeSeer log entries. The default is Microsoft Access. 2. Database Provider Specify the database provider. The default is the OleDb Database Provider. 6
3. Connection String The OleDb connection string used to connect to the underlying database. The default points to the included SQLite database. 4. Database Date Format The format used to insert dates into the database. The default is MM/dd/yyyy HH:mm:ss 5. Database Retention The number of months of data to keep before purging. The default is 12 months. 6. Database Purge Time The time of day when database purges are performed. The default is 23:45. 7. Compact Database When using the included Microsoft Access database, this option allows you to compact the database to free up space consumed by the database. This option will only be enabled if the database is offline. 8. Enable Syslog On Startup If set to Yes, this option will start the syslog server when the plug-in starts. The default is No. 9. Logging Severity The option specifies which log level severity you want to direct to the database. The logging severity will allow the selected level and higher events into the database. The default logging severity is Informational. 10. IP Address The IP address you want to bind to the syslog server. The default is an empty string which allows the syslog server to listen on all interfaces. 11. UDP Port Allows you to specify a custom syslog UDP port. The default is UDP port 514. 12. Sort Order Specifies the default sort order for filter queries. The default is ascending (ASC). 13. Records Per Page Specifies the number of records to display when performing filter queries. The default is 25. 14. Authorized User Roles The HomeSeer users authorized to access the web page. This option does not override the default HomeSeer web server settings. 15. Log Device Status Changes This option allow you to record all HomeSeer device status changes to the database. The default is No. 16. Log Device Value Changes This option allows you to record all HomeSeer device value changes to the database. The default is No. 17. Trigger Loop Protection This option allows you to disable the built in HomeSeer event loop protection. Trigger loop protection ignores duplicate event log entries that are used to trigger a HomeSeer event. 18. Register Link If set to Yes, the UltraLog button will be displayed on all web pages. 19. Debug Mode If set to Yes, the plug-in will write verbose logging to the HomeSeer log file. UltraLog HSPI Plug-in Devices Database Connection Device This HomeSeer device allows you to open or close the database connection. If you need to open or close the database for any reason, simply click the Open or Close button from the HomeSeer Status web page. 7
Syslog Logger Device This HomeSeer device allows you to enable or disable the syslog server. If you need to stop or start the syslog server for any reason, simply click the Enable or Disable button from the HomeSeer Status web page. UltraLog HSPI Triggers UltraLog Log Match This option allows you to trigger a HomeSeer event based on a text or regular expression match within a HomeSeer log event. The following plug-in specific triggers are supported: 1. Look In Log Specifies which part of the HomeSeer log event to search. a. Type Search the HomeSeer log type (e.g. Info, Warning, Error, etc). b. Message Search the HomeSeer message (e.g. Web Server Authorized login). 2. Match Type Specifies what type of string comparison to perform. a. Contains b. Starts With c. Ends With d. Regular Expression 3. Match Value Specifies the text string or regular expression used to trigger the HomeSeer event. 4. Notes Enter text to help you remember what the UltraLog Log Match trigger does. When the UltraLog Log Match triggers, the following HomeSeer variables are updated: 1. LogType Contents the HomeSeer log type. 2. LogMessage Contents the HomeSeer log message. If you specify named or parenthesized regular expression captures, then HomeSeer variables are automatically created based on your regular expression. See UltraLog HSPI Named Captures for more information. The plug-in has built in protection to prevent a trigger from creating an endless loop. 8
Screenshot UltraLog Syslog Match This option allows you to trigger a HomeSeer event based on a text or regular expression match within a syslog event. The following plug-in specific triggers are supported: 1. Look In Syslog Specifies which part of the syslog event to search. a. Hostname Search the syslog hostname or IP address. b. Message Tag Search the syslog tag. c. Message Content Searches the syslog message contents. 2. Match Type Specifies what type of string comparison to perform. a. Contains b. Starts With c. Ends With d. Regular Expression 3. Match Value Specifies the text string or regular expression used to trigger the HomeSeer event. 4. Notes Enter text to help you remember what the UltraLog Syslog Match trigger does. When the UltraLog Syslog Match triggers, the following HomeSeer variables are updated: 1. SyslogHostname The hostname that generated the syslog message. 2. SyslogMsgTag The tag portion of the syslog message. This is usually the name of the process that generated the syslog message. 3. SyslogMsgContent The syslog message contents. If you specify named or parenthesized regular expression captures, then HomeSeer variables are automatically created based on your regular expression. See UltraLog HSPI Named Captures for more information. The plug-in has built in protection to prevent a trigger from creating an endless loop. 9
Screenshot UltraLog Watchdog Trigger The UltraLog plug-in has a built in watchdog timer to ensure the plug-in is always connected to the underling database. The trigger can be used to trigger a HomeSeer event when connectivity to the database been lost or restored. Example Usage Receive a notification if the plug-in loses communication to the underlying database. Supported Events Database connection failure Database connection restore UltraLog HSPI Trigger Actions This plug-in does not have any HomeSeer actions defined. UltraLog HSPI Trigger Conditions This plug-in does not have any HomeSeer trigger conditions defined. UltraLog HSPI Regular Expression Captures If you specify named or parenthesized regular expression captures, then HomeSeer variables are automatically created based on your regular expression. Non-named Capture In the following example, the HomeSeer global variable 1 would contain the IP address and the variable 2 would contain the user name. 10
HomeSeer Log Line: Web Server authorized local login successful from: 127.0.0.1 User: default MatchValue Regular Expression: (\d+\.\d+\.\d+\.\d+) User: (.+) Named Capture In the following example, the HomeSeer global variable Hostname would contain the IP address and the variable User would contain the user name. HomeSeer Log Line: Web Server authorized local login successful from: 127.0.0.1 User: default MatchValue Regular Expression: (?Hostname\d+\.\d+\.\d+\.\d+) User: (?User.+) Example HomeSeer Event The following example demonstrates how logging into your HomeSeer web page causes the UltraLog plug-in to populate 2 global HomeSeer variables Hostname and User based on the regular expression specified below and allows you to access the variables via script. 1. From the Events web page, click Add Event. 2. From the Name tab, enter HomeSeer Web Access and unselect Disable Automatic Event Triggering. 3. From the Trigger tab, select UltraLog Log Match. In the Look in Log dropdown, select Message. In the Match Type dropdown, select Regular Expression. In the Match Value text box, enter: (?<Hostname>\d+\.\d+\.\d+\.\d+) User: (?<User>.+) Note: This regular expression contains 2 named captures Hostname and User. 11
4. From the Actions tab, select Run Script, then click the Switch to Advanced View. Enter a new script named called sandbox.vb, and then click the Open Script Window button. Enter the following script into the script text area, then click Save Script button, then the Update button, and then the Save button. Sub Main(ByVal parm As Object) Dim Hostname As String = GetHomeSeerVariable("Hostname") Dim User As String = GetHomeSeerVariable("User") hs.writelog("debug", String.Format("{0} logged in from {1}.", User, Hostname)) End Sub Function GetHomeSeerVariable(ByVal strvariablename As String) As String Dim strvariablevalue As String = String.Empty Try Dim objobject As Object = hs.getvar(strvariablename) If TypeOf objobject Is String Then strvariablevalue = CStr(objObject) End If objobject = Nothing Catch pex As Exception Ignore errors End Try Return strvariablevalue End Function 12
UltraLog HSPI API Reference DBStatus Function This function returns the current status of the underlying database. The function will return either Online or Offline. Example Dim strresults As String = hs.plugin("ultralog").getdbstatus() hs.writelog("debug", strresults) GetSyslogStatus Function This function returns the current status of the syslog server. The function will return either Enabled or Disabled. Example Dim strresults As String = hs.plugin("ultralog"). GetSyslogStatus() hs.writelog("debug", strresults) GetHouseCode Function This function returns the HomeSeer assigned house code. Example Dim strresults As String = hs.plugin("ultralog").gethousecode("basecode") hs.writelog("debug", strresults) GetSyslogStatus Function This function returns the HomeSeer assigned house code. Example Dim strresults As String = hs.plugin("ultralog"). GetSyslogStatus() hs.writelog("debug", strresults) ResetStatistics Function This function resets the database insert statistics. Example Dim strresults As String = hs.plugin("ultralog ").ResetStatistics() hs.writelog("debug", strresults) GetStatistics Function This function returns the counts associated with the various database actions. The following statistics are supported: 1. HSLoggerSuccess The number of successful HomeSeer events inserted into the database. 2. HSLoggerFailure The number of HomeSeer events that were not inserted into the database due to an error. 13
3. HSLoggerQueue The number of HomeSeer events waiting to be inserted into the database. This number should almost always be 0. 4. DeviceStatusSuccess The number of successful HomeSeer device status changes inserted into the database. 5. DeviceStatusFailure The number of HomeSeer device status changes that were not inserted into the database due to an error. 6. DeviceStatusQueue The number of HomeSeer device status changes waiting to be inserted into the database. This number should almost always be 0. 7. DeviceValueSuccess The number of successful HomeSeer device status changes inserted into the database. 8. DeviceValueFailure The number of HomeSeer device status changes that were not inserted into the database due to an error. 9. DeviceValueQueue The number of HomeSeer device status changes waiting to be inserted into the database. This number should almost always be 0. 10. SysLoggerSuccess The number of successful syslog events inserted into the database. 11. SysLoggerFailure The number of syslog events that were not inserted into the database due to an error. 12. SysLoggerQueue The number of syslog events waiting to be inserted into the database. This number should almost always be 0. Example Get a plug-in reference Dim hspi As Object = hs.plugin("ultralog") Check the number of pending events waiting to be processed Dim InQueue As Integer = hspi. GetStatistics("HSLoggerQueue") ExecuteSQL Function This function is used to get data from the underlying database using an SQL query and pages the results if the rows exceed pagesize. The return value is an ADO.Net DataTable. Note: This sample required you to modify the HomeSeer s settings.ini file. You must shtudown HomeSeer, then ensure the following line exists in the [settings] section: ScriptingReferences=System.Data;System.Data.dll,System.xml;System.xml.dll Example Get a plug-in reference Dim hspi As Object = hs.plugin("ultralog") Dim pagesize As Integer = 25 Dim pagecur As Integer = 1 The following are called by reference and are updated based on results Dim pagecount As Integer = 1 Dim recordcount As Integer = 0 14
Dim strsql = "SELECT * FROM tbllog WHERE Log_Type = UltraLog Info" Dim datatable As DataTable = hspi.executesql(strsql, recordcount, pagesize, pagecount, pagecur) Dim summary As String = String.Format("{0} pages, {1} total rows.", pagecount, recordcount) hs.writelog ("UltraLog Debug", summary) 15