Ultramon HSPI User S Guide

UltraMon HSPI User’s Guide A HomeSeer HS2 plug-in to monitor network connected devices

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 UltraMon HSPI Overview...... 4 How It Works...... 4 Features...... 4 Requirements...... 5 Default Options...... 5 UltraMon HSPI Installation...... 5 Downloading the HomeSeer Plug-in...... 5 Enabling the HomeSeer Plug-in...... 6 UltraMon HSPI Configuration...... 6 Web Page Layout...... 6 UltraMon HSPI Options...... 7 Adding Monitored Devices...... 8 Modifying a Monitored Devices...... 10 Deleting a Monitored Device...... 11 UltraMon HSPI Triggers...... 11 Device Status Trigger...... 11 Device Value Trigger...... 11 UltraMon HSPI Trigger Actions...... 12 UltraMon Device Action...... 12 UltraMon HSPI Trigger Conditions...... 12 UltraMon HSPI API Reference...... 12 ResetDeviceStatistics Function...... 12 Example...... 12 DoWOL Function...... 12 Example...... 12 DoWOLByName Function...... 12 Example...... 12

2 DoShutdown Function...... 13 Example...... 13 DoShutdownByName Function...... 13 Example...... 13 GetMonitoredDevices Function...... 13 Example...... 13 GetMonitoredIPAddresses Function...... 14 Example...... 14 GetIPSubnets Function...... 14 Example...... 14

3 Introduction UltraMon is a HomeSeer HS2 plug-in that allows you to monitor devices on your home network. Multiple threading allows device monitoring to take place without disrupting the performance of HomeSeer. UltraMon supports the ability to send a Wake on LAN (WOL) packet to turn on PC's that support WOL and to shutdown a networked PC using PsShutdown or the UltraMon Shudown Service installed on a Windows PC.

Intended Audience This document is intended for the HomeSeer user that has chosen to install and configure the UltraMon HomeSeer Plug-in.

UltraMon HSPI Overview

How It Works  At regular intervals, the plug-in obtains a list of devices owned by the plug-in, then sends either an ICMP ping or connects to the TCP port to determine the device status. The plug-in updates the HomeSeer device depending on the up/down status of the device.

o For ICMP ping monitoring, the device string can be updated to contain a more verbose status.

o For TCP port monitoring, the device string indicates the TCP port number being monitored.

o The device status can also be updated depending on the up/down status of the device. This option may be useful when creating events that trigger off the device status.

 The plug-in monitors selected IP subnets for new devices and allows you to easily create a HomeSeer device for hosts found on the network. A HomeSeer trigger can also be created to alert you when a new device is discovered on your network.

Features  Provides the ability to monitor the status of the devices on your network using ICMP ping.

 Discovers all network devices on selected /24 subnets.

 Provides the ability to monitor the status of a service running on a device using a TCP port connection test.

 A "Discovered" devices web page allowing you to easily create a HomeSeer device for hosts on your network.

 HomeSeer trigger for new IP addresses discovered on monitored subnets.

4  Support alias (HomeSeer device name different than hostname or fully qualified domain name).

 All pre-defined device types have an associated image (e.g. camera, laptop, iPhone, router, Xbox, etc).

 Ability to wake up a computer via WOL packet.

 Ability to shutdown, reboot, log off, sleep, hibernate local networked computers using PsShutdown (by Windows Sysinternals) or using the UltraMon Shutdown windows service (available via separate download).

 Multiple threading allows device monitoring to take place without disrupting the performance of HomeSeer. Requirements  Homeseer 2.2.066 or greater

Default Options  Device monitoring is enabled.

 Five minutes delay between checks intervals.

 Ping device 2 times before marking a device unreachable.

 Device monitoring begins 60 seconds after HomeSeer starts.

 Ping timeout of 1 second.

 Flag device failed after 5 consecutive failures.

UltraMon 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 UltraMon, the click the checkbox to mark the plug-in for installation.

3. Click the Next button to begin downloading the UltraMon plug-in package.

5 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 UltraMon plug-in, and then select Save to enable the plug-in.

4. The UltraMon plug-in is now enabled. Click the UltraMon button to view the plug-in status, setup, devices and discovered devices.

UltraMon HSPI Configuration

Web Page Layout The Ultramon 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 status and monitored device statistics.

2. Options – Displays and allows you to change the options associated with the plug-in.

3. Device Types – Allows you to create custom UltraMon device types.

4. Devices – Displays an at-a-glance status of all UltraMon devices created by either the Add Device button or selecting discovered devices from the Discovered web page.

5. Discovered – Displays all discovered devices on your network. The monitored subnets are created the first time you start the plug-in and can be changed or disabled from the Options web page.

6. UPnP Devices – Displays all discovered UPnP devices on your network.

UltraMon HSPI Options All options are set from the Options web page. The following options are supported:

1. Delay Between Checks – The number of minutes to pause between checks.

2. Attempts – The number of times to try sending an ICMP ping to a device.

3. Marked Failed After – The number of consecutive failures before flagging the device offline.

4. Ping Timeout – The number of seconds to wait for a ping response.

5. Update Device String – Updates the HomeSeer device string with the results.

6. Update Device Status – Updates the HomeSeer device status (on/off) based on ping results.

7. Monitored Subnets – A list of /24 IP subnets to monitor.

8. Send Email – Send an email when non-monitored hosts are discovered on the network.

9. Email To – Email address used to send the email notification to.

10. Email From – Email sender address used to send the email notifications. This email address must be valid.

11. Email Subject – Default email subject for the non-monitored IP address on network notifications.

7 12. Email Body - Default email template for the non-monitored IP address on network notifications.

13. WOL UDP Port – UDP Port used to send the WOL packet to.

14. Shutdown Program – Select either UltraMonShutdown or PsShutdown, and then click the Save Options button. If you select UltraMonShutdown, then a download link will be provided so you can install the Windows Service on your Windows computers.

15. PsShutdown Path – Specifies the location of the PsShutdown application used to shutdown computers on your network.

16. Shutdown Username – The username used to authenticate to a remote system.

17. Shutdown Password – The password used to authenticate to a remote system. The password is stored encrypted within the hspi_ultramon.ini file.

18. Shutdown Message – The message displayed to logged-on users when a shutdown countdown commences.

19. Display Message For – Display shutdown message for the specified number of seconds before the shutdown. Selecting 0 disables the message dialog.

20. Connection Timeout – Specifies the number of seconds to wait for the Shutdown program to return a result before giving up.

21. Countdown Display – Specifies the countdown in seconds until the shutdown.

22. Allow Shutdown Abort– Allow the shutdown to be aborted by the interactive user.

23. Force Exit– Forces all running applications to exit during the shutdown instead of giving them a chance to gracefully save their data.

24. Authorized User Roles – The HomeSeer users authorized to access the web page. This option does not override the default HomeSeer web server settings.

25. Register Link – If set to Yes, the UltraMon button will be displayed on all web pages.

26. Debug Mode – If set to Yes, the plug-in will write verbose logging to the HomeSeer log file.

Adding Monitored Devices You can manually add a monitored from the UltraMon – Devices web page.

8 1. From the UltraMon - Devices web page, click the Add Device button.

2. From the UltraMon – Device web page, enter the Device Name, Hostname or IP Address, select the device type, and then select the Device Monitoring type.

3. For ICMP Ping monitoring, enter the Device MAC, then indicate the HomeSeer buttons you want created. The device MAC address is optional and is only needed if the device supports WOL.

9 4. For TCP Port monitoring, enter the TCP port number, then enter a short description for the TCP port (e.g. HTTP Web Service), then indicate if you want the Browser button created.

You can also automatically add ICMP Ping monitored devices from the UltraMon – Discovered web page. This method allows you to quickly add all your devices in one step. You can customize them after they get created.

1. Access the list of discovered devices from the UltraMon – Discovered web page.

2. Click each device you want to create, then click the Save button.

10 3. Once the web page refreshes, the checkboxes will be checked and disabled and the status will show the devices were created successfully.

Modifying a Monitored Devices You can modify an UltraMon monitored device the same way you modify any other HomeSeer device. Simply click on the device name from the HomeSeer device page, and then change the device properties as needed. UltraMon takes advantage of a new feature of HomeSeer 2 that allows the plug-in to display the device properties along with the typical HomeSeer device properties.

11 Deleting a Monitored Device You can delete an UltraMon monitored device the same we you delete any other HomeSeer device. From the HomeSeer device web page, click the device name, then from the HomeSeer modify device web page, click the Delete button.

UltraMon HSPI Triggers You can create HomeSeer events using device status or value triggers. In addition, you can create an event which triggers when the plug-in detects a new host on your network (e.g. UltraMon Host Discovery).

Device Status Trigger UltraMon HSPI can keep the device status updated (on or off) based on the current monitored device state. In order to use a Device Status Trigger, you need to have “Update Device Status” set to Yes in order for this event to work as expected.

1. Create a new HomeSeer event, and then select Device Status Change as the trigger.

2. Select your UltraMon device, and then set the status to “Change to On” or “Change To Off” as needed.

Device Value Trigger UltraMon HSPI uses the HomeSeer device value to keep track of the state of the monitored device. The device status displayed depends on the current value of the Device Value.

The following device values are valid:

 Online - Device value of 2 (2 or more consecutive ping successes)

 Recovered - Device value of 1 (1 consecutive ping successes)

 Unknown - Device value of 0 (newly created device or device values reset)

 Troubled - Device value of -1 (1 consecutive failure)

 Troubled x 2 - Device value of -2 (2 consecutive failures)

 Offline - Device value of -6 (6 or more consecutive failures)

12 UltraMon HSPI Trigger Actions

UltraMon Device Action This is a generic plug-in action that allows you to define actions to take on a monitored device.

 Send WOL – Allows you to send a WOL packet to the device.

 Shutdown – Allows you to send a shutdown action to the device.

Note: Additional actions may be added in future releases.

UltraMon HSPI Trigger Conditions This plug-in does not have any HomeSeer trigger conditions defined.

UltraMon HSPI API Reference

ResetDeviceStatistics Function This function resets the statistics associated to each monitored device. The HomeSeer device will be reset back to an unknown status.

Example

Dim strResults As String = hs.plugin("ultramon").ResetDeviceStatistics() hs.WriteLog("Debug", strResults)

DoWOL Function This function allows you to send a wake on LAN (WOL) packet to a device that has been configured to support WOL. You must have already set the SupportsWOL HomeSeer device attribute and have entered a device MAC address from the HomeSeer device properties page.

Example

Dim strDeviceRef As String = "12345" Call hs.plugin("ultramon").DoWOL(strDeviceRef)

DoWOLByName Function This function allows you to send a wake on LAN (WOL) packet to a device that has been configured to support WOL. You must have already set the SupportsWOL HomeSeer device attribute and have entered a device MAC address from the HomeSeer device properties page.

Example

Dim strDeviceName As String = "DeviceLocation DeviceName" Call hs.plugin("ultramon").DoWOLByName(strDeviceName)

13 DoShutdown Function This function allows you to shutdown a PC using a command line application of your choosing. You must define the application path and application command line arguments from the UltraMon options web page.

Example "Suspend" Suspend the computer. "Hibernate Hibernate the computer. "Shutdown" Poweroff the computer "Lock" Lock the computer. "Logoff Logoff the console user. "Reboot" Reboot after shutdown.

Dim strDeviceRef As String = "12345" Call hs.plugin("ultramon").DoShutdown(strDeviceRef, "Shutdown")

DoShutdownByName Function This function allows you to shutdown a PC using a command line application of your choosing. You must define the application path and application command line arguments from the UltraMon options web page.

Example "Suspend" Suspend the computer. "Hibernate Hibernate the computer. "Shutdown" Poweroff the computer "Lock" Lock the computer. "Logoff Logoff the console user. "Reboot" Reboot after shutdown.

Dim strDeviceName As String = "DeviceLocation DeviceName" Call hs.plugin("ultramon").DoShutdownByName(strDeviceName, "Shutdown")

GetMonitoredDevices Function This function returns a hashtable of the monitored devices. The key is a unique HomeSeer device reference and the value is an object that contains the HomeSeer device code, device name, device type, device value, host ID, hostname, host IP address, supports WOL value, date last checked and the last ICMP ping result.

Example

Dim DeviceList As Hashtable = hspi.GetMonitoredDevices()

If DeviceList.Count = 0 Then ' ' No devices found ' Else ' ' Enumerate through the hashtable ' Dim MyEnum As IDictionaryEnumerator = DeviceList.GetEnumerator

While MyEnum.MoveNext

14 ' ' Get the host data ' Dim objHost As Object = DeviceList(MyEnum.Key)

Dim deviceCode As String = objHost.DevCode Dim deviceName As String = objHost.DevName Dim hostId As String = objHost.HostID Dim hostName As String = objHost.HostName Dim hostMACAddr As String = objHost.HostIPAddr Dim pingResult As String = objHost.Result

' ' Do something useful with the results ' End While End If

GetMonitoredIPAddresses Function This function returns a hashtable of all monitored devices on your network.

Example See GetIPSubnets Function example.

GetIPSubnets Function This function returns a sorted hashtable of all IP address associated with the monitored subnets. The key is a long that is identical to the dotted quad (example 192.168.1.1).

Example

Dim IPAddresses As Specialized.StringDictionary = hspi.GetMonitoredIPAddresses() Dim IPSubnets As SortedList = hspi.GetIPSubnets()

If IPSubnets.Count = 0 Then ' ' No monitored subents found ' Else ' ' Enumerate through the hashtable ' For Each IPSubnet As Long In IPSubnets.Keys

Dim IPHosts As SortedList = IPSubnets(IPSubnet)

' ' Convert long to IP address ' Dim strIPSubnet As String = "" Try strIPSubnet = New System.Net.IPAddress(IPSubnet).ToString Catch ex As Exception strIPSubnet = "0.0.0.0" End Try

15 ' Get an enumerator ' Dim MyEnum As IDictionaryEnumerator = IPHosts.GetEnumerator

While MyEnum.MoveNext ' ' Convert long to IP address ' Dim strIPAddress As String = "" Try strIPAddress = New System.Net.IPAddress(MyEnum.Key).ToString Catch ex As Exception strIPAddress = "0.0.0.0" End Try

If IPAddresses.ContainsKey(strIPAddress) = True Then ' ' This IP address has an assoicated HomeSeer device ' End If

' ' Get the host data ' Dim objHost As Object = IPHosts(MyEnum.Key)

If objHost.Result = "Success" Then ' ' Do something useful with hosts that are alive on the network ' Dim deviceCode As String = objHost.DevCode Dim deviceName As String = objHost.DevName Dim hostId As String = objHost.HostID Dim hostName As String = objHost.HostName Dim hostMACAddr As String = objHost.HostIPAddr Dim pingResult As String = objHost.Result

' ' Do something useful with the results ' End If End While Next End If