Ultra1wire3 HSPI User's Guide

Ultra1Wire3 HSPI User’s Guide A HomeSeer HS3 plug-in to monitor temperature and humidity in your home

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 Ultra1Wire3 HSPI Overview ...... 4 How It Works ...... 4 Features ...... 4 Example Usage ...... 5 Requirements ...... 5 Ultra1Wire3 HSPI Installation ...... 5 Downloading and Installing the HomeSeer Plug-in ...... 5 Ultra1Wire3 HSPI Configuration ...... 5 Web Page Layout ...... 5 Ultra1Wire3 HSPI Setup ...... 6 Initial Setup Checklist ...... 6 Midon Design TEMP08 ...... 7 EDS HA7E ...... 7 EDS HA7Net ...... 7 EDS OWServer ...... 7 MeshNet Controller ...... 7 Ultra1Wire3 HSPI Options...... 8 Ultra1Wire3 HSPI Devices ...... 9 Manually Adding a New 1-Wire Adapter ...... 9 Modifying a 1-Wire Adapter ...... 9 Deleting a 1-Wire Adapter ...... 9 Adding 1-Wire Environmental Sensors ...... 10 HA7E, HA7Net, OW-Server, MeshNet Controller Host Adapters ...... 10 TEMP08 Host Adapter ...... 10 Adding Other 1-Wire Devices to the TEMP08...... 10 Modifying a 1-Wire Environmental Sensors ...... 10 Deleting a 1-Wire Environmental Sensors ...... 11

Ultra1Wire3 HSPI Charting...... 11 Ultra1Wire3 HSPI Triggers ...... 12 Device Value Trigger ...... 12 Ultra1Wire3 HSPI Trigger Actions ...... 12 Ultra1Wire3 HSPI Trigger Conditions ...... 13 1-Wire Network Description ...... 13 Linear 1-Wire Network Topology ...... 13 Example 1-Wire Linear Network ...... 14 Star 1-Wire Network Topology ...... 14 Example 1-Wire Star Network ...... 15 Supported 1-Wire Host Adapters ...... 15 Supported 1-Wire Devices ...... 16 Temperature Sensors ...... 16 Temperature/Humidity Sensors ...... 16 Counters ...... 16 Switches/Light Sensors ...... 16 Embedded Data Systems Environmental Sensors ...... 16 Embedded Data Systems Wireless Environmental Sensors...... 16 Ultra1Wire3 HSPI API Reference...... 17

Introduction Ultra1Wire3 is the next generation HomeSeer plug-in that makes tracking temperature and humidity in your home easy. By using the Embedded Data Systems Intelligent 1-Wire Interface Adapters and/or the Midon Design TEMP08 Serial One Wire Interface, this plug-in automatically creates and maintains a HomeSeer device for each 1-Wire environmental sensor detected. In addition, the temperature, humidity, barometric pressure and counter values for each 1-Wire sensor are inserted into an underlying database for graphing purposes.

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

Ultra1Wire3 HSPI Overview

How It Works

 The plug-in connects to any of the supported 1-Wire Host Adapters and obtains a list of supported 1-wire devices.  When using the HA7Net or OW-Server 1-Wire host adapters, the plug-in checks the value of each connected digital environmental sensor then updates the HomeSeer device and inserts temperature, humidity, barometric pressure and counter readings into the database.  When using the HA7E 1-Wire host adapter, the plug-in checks the value of each connected digital environmental temperature sensor then updates the HomeSeer device and inserts temperature readings into the database.  When using the TEMP08 host adapter, the plug-in reads the output of all connected devices then updates the HomeSeer device and inserts temperature, humidity, barometric pressure and counter readings into the database.

Features

 Multiple threading allows 1-Wire readings to take place without disrupting the performance of HomeSeer.  Automatically discovers and builds HomeSeer devices for each supported 1-Wire environmental sensor.  Logs all temperature, humidity, counter and barometric pressure readings to an underlying database.  Temperature, humidity, counter and barometric pressure charts are created using AMCharts http://www.amcharts.com/.  Ability to trigger HomeSeer3 events based on 1-Wire device sensor readings.

 Error Try/Catch logic to ensure plug-in doesn't fail with an unhandled exception.

Example Usage  Use Ultra1Wire3 to generate an e-mail notification whenever an environmental sensor exceeds a set threshold.  Use Ultra1Wire3 to monitor installed temperature sensor in your child’s room and receive e- mail notification using a HomeSeer event when the temperature exceeds a set threshold.  Use Ultra1Wire3 to monitor installed humidity sensor in your basement and receive e-mail notification using a HomeSeer event when the humidity exceeds a set threshold.  Use Ultra1Wire3 with installed indoor and outdoor temperature and humidity sensors to receive notifications using a HomeSeer event when it’s more efficient to open your windows instead of turning on your air conditioner.  Use Ultra1Wire3 along with installed temperature sensor to monitor the ambient temperature of an enclosed media cabinet.

Requirements  Homeseer 3.0 or greater.  One or more 1-Wire Host Adapters (HA7E, HA7Net, OW-Server, MeshNet Controller, TEMP08).  One or more 1-Wire environmental sensors. Please see Supported 1-Wire Host Adapters in this document for a complete list of supported sensors.

Ultra1Wire3 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 “Analog & Digital Input/Output Device Support” category, then click the checkbox next to the Ultra1Wire3 plug-in package to mark the plug-in for installation. 4. Under “Pending Updates/Installs”, click the Download and Install button. 5. Once the installer finishes, find the Ultra1Wire3 plug-in under Installed Plug-Ins, then enable it.

Ultra1Wire3 HSPI Configuration

Web Page Layout The Ulta1Wire plug-in has four web pages that provide access the available features of the plug-in.

The available web pages are as follows:

1. Status – Displays the plug-in status and database statistics. 2. Options – Displays and allows you to change the options associated with the plug-in. 3. Devices – Displays an at-a-glance status of all temperature sensors. 4. Charts – Allows you to chart one or more temperature, humidity, counter or barometric pressure sensors over time.

Ultra1Wire3 HSPI Setup Before you begin to configure the Ultra1Wire3 plug-in, you’ll need to compile a list of 1Wire device adapters that you want to connect to the plug-in. For the HA7E and TEMP08, you’ll need to determine the communications port you used to connect to your computer. For the HA7Net, OWServer and the MeshNet Controller, the plug-in should be able to automatically discover them on your network.

Initial Setup Checklist You will need the following information to complete the setup of your 1-Wire setup:

□ Confirm your computer can connect to your 1-Wire adapter.

□ Write down the 1-Wire interface name, type and how your computer connects to the 1-Wire interface.

□ Write down the 1-Wire sensor addresses and note where each sensor is installed in your home. If you have never mapped your sensor addresses to a location, then you may need to unplug a sensor one at a time to determine which address is no longer displayed using the 1-Wire interface adapter search feature.

Midon Design TEMP08 1. Using your favorite serial terminal program (e.g. PuTTY Tel), make a connection to your TEMP08.

2. At the > prompt, type TMP to read the list of 1-Wire sensors.

3. If you see the list of sensors, then the TEMP08 is properly configured for use with the plug-in. Please note the communications port number you used as you’ll need this to manually define the 1-Wire adapter within the PLUG-INS > Ultra1Wire3 > Ultra1Wire3 > Devices web page.

EDS HA7E 1. Using your favorite serial terminal program (e.g. PuTTY Tel), make a connection to your HA7E.

2. Once connected, type “F10” to obtain the first connected temperature sensor. Keep typing lowercase f to obtain a list of the remaining connected temperature sensors. If the address list does not change, then you have reached the end of the address list.

3. If the command above returns an address, then the HA7E is properly configured for use with the plug-in. Please note the communications port number you used as you’ll need this to manually define the 1-Wire adapter within the PLUG-INS > Ultra1Wire3 > Ultra1Wire3 > Devices web page.

EDS HA7Net 1. Make a connection to your EDS HA7Net device using http://ipaddress/1Wire/Search.html. Replace ipaddress with the IP address of your HA7Net 1-Wire interface.

2. The HA7Net Search web page should display a list of 1-Wire sensors connected to your HA7Net. Please remember to write down the 1-Wire sensor addresses and note where each sensor is installed in your home.

EDS OWServer 1. Make a connection to your EDS OWServer device using http://ipaddress/details.xml. Replace ipaddress with the IP address of your OWServer 1-Wire interface.

2. The OWServer details web page should display a list of 1-Wire sensors connected to your OWServer. Please remember to write down the 1-Wire sensor addresses and note where each sensor is installed in your home.

MeshNet Controller 1. Make a connection to your EDS MeshNet Controller device using http://ipaddress/details.xml. Replace ipaddress with the IP address of your EDS MeshNet Controller interface.

2. The EDS MeshNet Controller details web page should display a list of 1-Wire sensors. Please remember to write down the 1-Wire sensor addresses and note where each sensor is installed in your home.

Ultra1Wire3 HSPI Options All options are set from the Options web page.

The following options are supported:

1. HA7Net Discovery – If enabled, the plug-in will send an auto-discovery packet out each enabled network interface in an attempt to find connected HA7Net devices. The default is enabled. 2. OWServer Discovery – If enabled, the plug-in will send an auto-discovery packet out each enabled network interface in an attempt to find connected OW-Server devices. The default is enabled. The OWServer Discover option includes the EDS MeshNet Controllers. 3. Delay Between Checks – The number of minutes to pause between checks. The default is 1 minute. 4. Attempts – The number of times to try reading the 1-wire sensor. The default is 1 time. 5. On No Report – Specifies what action to take when a temperature/humidity devices does not respond. The default action is to insert the previous reading into the database. 6. Unit Type – The format used to display temperatures and barometric pressure from the 1-wire sensors. The default format is U.S customary units. 7. Display Degree Units – If set to Yes, the degree unit (e.g. F or C) will be displayed on the HomeSeer status web page. 8. Display Degree Image – If set to Yes, a degree icon will be displayed on the HomeSeer status web page. 9. Authorized User Roles – The HomeSeer users authorized to access the web page. This option does not override the default HomeSeer web server settings. 10. Logging Level – Select the level of application debug.

Ultra1Wire3 HSPI Devices The Ultra1Wire3 HSPI Devices web page allows you manually add a 1-Wire adapter to the plug-in.

Manually Adding a New 1-Wire Adapter 1. Click on the PLUG-INS > Ultra1Wire3 > Ultra1Wire3 > Devices tab. 2. Click the New button near the upper left corner of the web page. 3. Complete the following form fields: a. Device Serial: Enter a unique identifier for the device. If you are going to use a serial connection, simply duplicate the contents of the Connection Address into this field. b. Device Name: Enter a unique name for your 1-Wire adapter. c. Device Type: Select from one of the supported 1-Wire adapters from the Device Type dropdown list. d. Connection Type: Select either Ethernet or Serial. e. Connection Address: If you are using a network connection, enter the IP address and port number using the format ipaddress:port (e.g. 192.168.1.10:80). If you are using a Serial connection, use the format COMx where x is the port number (e.g. COM1). 4. Click the Create button to add the 1-Wire Adapter. 5. To cancel, simply click the X icon in the upper right corner.

Please note: The plug-in checks for manually added 1-Wire adapters once per minute.

Modifying a 1-Wire Adapter 1. Click on the PLUG-INS > Ultra1Wire3 > Ultra1Wire3 > Devices tab. 2. Find the 1-Wire adapter you want to edit, and then click the Edit link. 3. Edit the fields that you want to change, then click the Update button. 4. To cancel the changes, simply click the X icon in the upper right corner.

Deleting a 1-Wire Adapter 1. Click on the PLUG-INS > Ultra1Wire3 > Ultra1Wire3 > Devices tab.

2. Find the 1-Wire adapter you want to delete, and then click the Delete link. 3. Confirm you want to delete the 1-Wire Adapter by pressing the Delete button. 4. To cancel, simply click the X icon in the upper right corner.

Adding 1-Wire Environmental Sensors

HA7E, HA7Net, OW-Server, MeshNet Controller Host Adapters Simply connect your 1-wire environmental sensors and the plug-in will automatically discover each supported sensor and will build an associated HomeSeer device.

Note: Follow the instructions in the HA7E, HA7Net, OW-Server or MeshNet Controller user’s guide to be sure your sensors are discovered by the host adapter.

TEMP08 Host Adapter Simply connect your 1-wire temperature sensors and the plug-in will automatically discover each supported sensor and will build an associated HomeSeer device.

Note: Follow the instructions in the TEMP08 user’s guide to be sure your sensors are discovered by the host adapter.

Adding Other 1-Wire Devices to the TEMP08 The TEMP08 host adapter supports a wide range of 1-wire devices. At this time, the Ultra1Wire3 HSPI will create a HomeSeer device for the following 1-wire devices:

1. Temperature 2. Humidity 3. Barometer 4. Counter 5. Switch 6. Rain 7. Lightning

Modifying a 1-Wire Environmental Sensors You can define the sub-type of certain 1-Wire sensors to indicate if they are lightning sensors, rain gauges, water meters or light sensors.

1. From the HomeSeer device management web page, click the device name, then select the Ultra1Wire3 tab.

2. Select the Sensor Subtype from the dropdown list.

3. Enter the resolution for the Sensor type, then click the Save button.

Deleting a 1-Wire Environmental Sensors You can delete an Ultra1Wire3 sensor the same we you delete any other HomeSeer device. From the HomeSeer device management web page, click the device name, then click the Delete button.

Please Note: A HomeSeer device will be recreated if the 1-wire sensor remains connected to the 1-wire host adapter.

Ultra1Wire3 HSPI Charting You can chart your environmental sensors over time from the Charts web page. Simply select the chart type (temperature, humidity, counter or barometric pressure), the chart type, the duration, the ending date and time, then click the Build Chart button.

The underlying database will be queried based on your selections and a chart will be displayed.

Ultra1Wire3 HSPI Triggers At this time, the Ultra1Wire3 HSPI does not provide additional triggers. However, you can use the HomeSeer device value triggers for 1-wire sensors.

Device Value Trigger Ultra1Wire3 HSPI uses the HomeSeer device value to keep track of the current reading of the 1-wire sensors. Simply create a trigger that uses the built in device value triggers.

Ultra1Wire3 HSPI Trigger Actions This plug-in does not have any HomeSeer actions defined.

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

1-Wire Network Description A 1-Wire network consists of a master device connected to one or more branches via category 5 twisted pair copper wire. In some cases, your 1-Wire network may need 5V power applied by the master device in order to successfully communicate to the slave devices on the 1-Wire network.

For additional information on 1-Wire Networks, please refer to the Dallas Semiconductor application note #148 available at http://DalSemi.com/.

Linear 1-Wire Network Topology The Linear 1-Wire network topology is generally the most reliable. It consists of a single category 5 cable run with the 1-Wire sensors connected using short stubs or branches of less than 3m.

Linear 1-Wire Network Topology

1-wire Master Category 5 Wire

Example 1-Wire Linear Network A Typical 1-Wire Linear Network

1-Wire Network (Category 5 Copper Wire)

Lightning Detector

Temperature Temperature Wall Wall Wall Sensors Sensors Mounted Mounted Mounted Sensors Sensors Sensors

Temperature Light Light Light Rain Gauge Probes Sensors Sensors Sensors

Star 1-Wire Network Topology The Star 1-Wire network topology is generally difficult to make reliable. It consists of a single category 5 cable run with the 1-Wire sensors connected using long branches often greater than 100 feet. Reflections from the end branches can cause data errors on the 1-Wire bus.

Star 1-Wire Network Topology

1-wire Master Category 5 Wire

Embedded Data Systems sells a 1-Wire wiring aid (JB6 1-Wire Junction Box) that solves the reliability issues associated with star 1-Wire networks by providing six 1-Wire branches, each with individual impedance matching components. The JB6 junction box is designed to simplify the installation of 1-Wire networks configured in a star / distributed star topology. Adding or removing a device to the 1-Wire bus is as simple as plugging it in to one of RJ12 jacks. In addition, the JB6 is designed with two RJ45 jacks that

14 are intended for connection to the main 1-Wire trunk. By providing two jacks, the 1-Wire trunk can be conveniently daisy chained from one JB6 to the next.

Example 1-Wire Star Network A Typical 1-Wire Star Network

1-Wire Network (Category 5 Copper Wire)

Temperature Probes

Temperature Temperature Sensors Sensors Wall Wall Wall Mounted Mounted Mounted Sensors Sensors Sensors

Lightning Light Light Light Rain Gauge Detector Barometric Sensors Sensors Sensors Pressure

Supported 1-Wire Host Adapters

1-Wire Adapter Temperature Humidity EDS Wired EDS Wireless Counters Switches Sensors Sensors Environmental Environmental Sensors Sensors

Midon TEMP08 Y Y N N Y Y*

EDS HA7E Y N N N N N

EDS HA7Net Y Y Y N Y Y*

EDS OW-Server Y Y Y N Y Y*

EDS MeshNet Controller N N N Y N N

* Read only

Supported 1-Wire Devices

Temperature Sensors  AAG 1-Wire Temperature Sensor TAI8520  iButtonLink T-Sense - Temperature Sensors  iButtonLink T-Probe - Temperature Sensors  iButtonLink MS-T - Temperature Sensors  1-Wire digital thermometers (DS18S20, DS18S20-PAR, DS1822, DS18B20 and DS1920)

Temperature/Humidity Sensors  AAG 1-Wire Humidity Module TAI8540D  Hobby Boards Humidity Sensor T3-R1-A  Midon 1-Wire Humidity Sensor MD3020E  iButtonLink MS-TH - Temperature and Humidity Sensor  1-Wire Humidity Sensors (DS2438)

Counters  Hobby Boards Dual Counter DC3-R1-A  Hobby Boards Lightning Detector LD4-R1-A  Hobby Boards Rain Gauge w/Counter RG1-R1-A  1-Wire Counters (DS2423)

Switches/Light Sensors  EDS D2Photo - Low Cost 1-Wire Light Monitor  iButtonLink MS-TL - Temperature and Light Level Sensor *Not compatible with the TEMP08

Embedded Data Systems Environmental Sensors  OW-ENV-T - Wall Mount Temperature Sensor  OW-ENV-TH - Temperature / Humidity Sensor  OW-ENV-THPL - Temperature / Humidity / Barometric Pressure & Light Sensor  OW-ENV-TL - Temperature / Light Sensor  OW-ENV-TP - Temperature / Barometric Pressure Sensor  OW-ENV-TR - Temperature Sensor with Relay

Embedded Data Systems Wireless Environmental Sensors  MN-ENV-T - Wall Mount Temperature Sensor  MN-ENV-TH - Temperature / Humidity Sensor  MN-ENV-THPL - Temperature / Humidity / Barometric Pressure & Light Sensor  MN-ENV-TL - Temperature / Light Sensor  MN-ENV-TP - Temperature / Barometric Pressure Sensor

Ultra1Wire3 HSPI API Reference To be determined