Ultralog User`s Guide - Automated Home Online

UltraLog HSPI User’s Guide
A HomeSeer HS2 plug-in to store and retrieve
HomeSeer and syslog events
Copyright © 2013
[email protected]
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
[email protected].
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 doesn't 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