==============================================================================
  _____                            _          ______  ___   ___  
 | ____|_ __   ___ _ __ __ _  __ _| |_  ___  |__  / |/ _ \ / _ \ 
 |  _| | '_ \ / _ \ '__/ _` |/ _` | __|/ _ \   / /| | | | | | | |
 | |___| | | |  __/ | | (_| | (_| | |_|  __/  / /_| | |_| | |_| |
 |_____|_| |_|\___|_|  \__, |\__,_|\__|\___| /____|_|\___/ \___/ 
                       |___/                                     

  ____  _____    _    ____  __  __ _____ 
 |  _ \| ____|  / \  |  _ \|  \/  | ____|
 | |_) |  _|   / _ \ | | | | |\/| |  _|  
 |  _ <| |___ / ___ \| |_| | |  | | |___ 
 |_| \_\_____/_/   \_\____/|_|  |_|_____|

ENERGATE Z100 HOME AUTOMATION DRIVER README

==============================================================================
------------------------------------------------------------------------------
==============================================================================

LICENSE
=======

Copyright (c) 2009-2010 Digi International Inc., All Rights Reserved

This software contains proprietary and confidential information of Digi
International Inc.  By accepting transfer of this copy, Recipient agrees
to retain this software in confidence, to prevent disclosure to others,
and to make no use of this software other than that for which it was
delivered.  This is an published copyrighted work of Digi International
Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly
prohibited.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to
restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in
Technical Data and Computer Software clause at DFARS 252.227-7031 or
subparagraphs (c)(1) and (2) of the Commercial Computer Software -
Restricted Rights at 48 CFR 52.227-19, as applicable.

Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343

Contents
========
1. ABOUT
2. REQUIREMENTS
3. FEATURES
4. INSTALLATION
5. TROUBLESHOOTING
6. REFERENCE DOCUMENTATION

ABOUT
=====

The Z100HA thermostat driver makes Energate Z100 thermostats
interoperable with the ZigBee Cluster Library Thermostat and Fan
Control clusters when accessed through a Digi gateway. This makes
Energate Z100 thermostats compatible with Digi's Energy Daytrader
iPhone app.

REQUIREMENTS
============

The Z100HA driver has been tested with the following devices:

 Gateway Requirements
.--------------------.
1) SE Framework v1.3.0 or 1.3.1
2) Gateway radio firmware version 0x3123
3) Gateway firmware version 2.10.0.3

 Energate Z100 Requirements
.--------------------------.
1) Software version 1.8.6
2) Hardware version 1.3
3) ZigBee Firmware Version 1.3.221

FEATURES
========

The Z100HA thermostat driver adds support for reading, writing and discovering
the following attributes:

 Supported Attributes
.--------------------.

1)  Thermostat Cluster (0x0201)
    a. Local temperature (0x0000)
    b. Heating set point (0x0011)
    c. Cooling set point (0x0012)
    d. Control sequence of operation (0x001b)
    e. System mode (0x001c)

2)  Fan Control Cluster (0x0202)
    a. Fan Mode (0x0000)
    b. Fan Mode Sequence (0x0001)


INSTALLATION
============

Option 1: Python Installation Script (requires python 2.4+)/Windows executable
Option 2: Manual Installation
Option 3: Advanced Installation

 Python Installation Script
.--------------------------.

The Z100HA package provides two installer scripts: install.py and
\dist\install.exe. The install.py script may be run on any system with python
2.4+. The install.exe may only be run on windows machines.

Usage:

./install.py
.\dist\install.exe

usage: %prog [options] idigi_url idigi_username idigi_password gateway_id

idigi_url        The iDigi instance associated with the gateway where the
		 Z100HA driver will be installed.

idigi_username   The username of the iDigi user who owns the gateway where the
                 Z100HA driver will be installed.
idigi_password   The password for idigi_username.
gateway_id       The last six digits of the MAC address of the gateway where
		 the driver will be installed.

 Manual Installation
.-------------------.

1) Upload Z100HA.zip to the gateway using iDigi.
    a. Login to iDigi using your iDigi username and password.
    b. Open the devices page by clicking the device link on the left-hand menu.
    c. Double click on the target gateway. A device properties tab will open.
    d. Under the device properties tab click `Python`.
    e. Click the upload file icon (file icon with an up arrow).
    f. Select HAZ100.zip from the installation directory.
    g. Click OK.
2) Configure the gateway.
    a. Open the web services console by clicking the `Web Services Console`
       link on the left-hand menu.
    b. Next to HTTP Method click the `POST` option.
    c. Paste the following XML into the text box, replacing {{GATEWAY_ID}}
       with the last six digits of the gateway's mac address (usually present
       on the bottom of the gateway).

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
<sci_request version="1.0">
  <send_message>
    <targets>
      <device id="00000000-00000000-00409DFF-FF%s" />
    </targets>
    <rci_request version="1.1">
      <do_command target="RPC_request">
        <add_path synchronous="true">
          <path_name type="string">WEB/python/Z100HA.zip"</path_name>
        </add_path>
	<add_module synchronous="true">
	  <module_name type="string">energate_virtual_thermostat</module_name>
	</add_module>
      </do_command>
    </rci_request>
  </send_message>
</sci_request>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
       
    d. Click the send link at the top of the screen.
    e. Wait 10 seconds.
    f. Clear the text box.
    g. Paste the following XML into the text box, replacing {{GATEWAY ID}}
       with the last six digits of the gateway's mac address (usually present
       on the bottom of the gateway).

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
<sci_request version="1.0">
  <send_message>
    <targets>
      <device id="00000000-00000000-00409DFF-FF{{GATEWAY ID}}" />
    </targets>
    <rci_request version="1.1">
      <do_command target="RPC_request">
	<add_endpoint synchronous="true">
	  <endpoint_class type="string">
	    EnergateVirtualHAThermostatEndpoint
	  </endpoint_class>
	  <endpoint_id>0x12</endpoint_id>
	</add_endpoint>
      </do_command>
    </rci_request>
  </send_message>
</sci_request>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    
    h. Click the send link at the top of the screen.    

 Advanced Installation
.---------------------.

More advanced installers may create their own scripts for updating a gateway
with the Z100 Home Automation driver. The iDigi platform supports web interface
calls. All web service calls for installing the Z100 Home Automation driver
target the url `http://{{your idigi instance url}}/ws/sci` and use the HTTP
POST method. The iDigi web services are authenticated using basic http
authentication with the credentials associated with the iDigi account that
owns the target gateway.

1) Upload Z100HA.zip to the target gateway using the following sci request
   where
   {{GATEWAY ID}} is the last 6 digits of the target gateway's mac address and
   {{BASE 64 ENCODED DATA}} is the Z100HA.zip file bytes encoded using base 64
   encoding.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
<sci_request version="1.0">
  <send_message>
    <targets>
      <device id="00000000-00000000-00409DFF-FF%s"/>
    </targets>
    <rci_request version="1.1">
      <do_command target="file_system">
        <put_file name="/WEB/python/Z100HA.zip">
          <data>%s</data>
        </put_file>
      </do_command>
    </rci_request>
  </send_message>
</sci_request>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

2) Configure the target gateway.
   a. Send an sci request with the XML from Manual Install 1e.
   b. Wait 10 seconds.
   a. Send an sci request with the XML from Manual Install 1g.


TROUBLESHOOTING
===============

This section describes what to do once the installation has been complete
if the Z100 doesn't function as expected. This could mean:

1) The Z100 does not function properly in the Energy Day Trader mobile app. 
   a. The Z100 does not show up a thermostat device.
   b. The Day Trader application does not display the current temperature, 
      current setpoints, ... etc. of the Z100.
   c. The Day Trader application does not allow modification of the current 
      temperature, current setpoints, ... etc. of the Z100.
2) The Thermostat Cluster and/or Fan Control cluster attributes of the Z100
   are not present in the iDigi Energy APIs.

 Resolving issues with the Energy Day Trader Application
.-------------------------------------------------------.

Problems using the Z100 with the Energy Day Trader Application might be 
solved using the following suggestions.

1) An issue with the internet connection may be causing the problem.

Solution: Make sure the device running the Energy Day Trader Mobile app is 
          connected to the internet.

2) The list of devices in the Energy Day Trader is being cached, so updates
   to the Z100 aren't being propogated to the device.

Solution: Clear the device cache. In the device list portion of the 
          application, push the refresh button at the bottom of screen.

3) The Z100 driver installation did not complete successfully. To verify
   that this is the issue, click on the Z100 device in the device list
   on the Energy Day Trader Application. Click the `identify` button in the
   bottom center of the screen. 
   a. If the [![INSERT COLOR OF LIGHT]!] light on the top of the Z100 turns 
      on, then it is likely that the Z100 driver installation did not 
      complete successfully. 

      Continue to `further troubleshooting`. 

   b. If the light does not turn on, some other problem exists. 
      Contact Digi support.

 Further troubleshooting
.-----------------------.

It is possible that these problems are the result of an unsuccessful or
incomplete installation of the Z100HA driver.

1) If you followed the manual or advanced installations, make sure that each
   step was followed closely.
2) Attempt rebooting the gateway by holding down the reset button on the side
   of the gateway for 3 seconds. Wait 3 minutes. If this does not resolve the
   issues continue to step 3.
3) In the networks section of iDigi, right click on the gateway the Z100HA 
   driver was installed on. Select `Rediscover (clear cache)` and wait for
   the discovery process to complete.
4) If none of steps 1-3 solved the problem, contact Digi support.

RELATED DOCUMENTATION
=====================

 Digi Products
.-------------.

1) iDigi User's guide
   <http://ftp1.digi.com/support/documentation/90001150_b.pdf>
2) iDigi Web services programming guide
   <http://ftp1.digi.com/support/documentation/90002008_a.pdf>

 Xbee Protocol
.-------------.

1) ZigBee Protocol Specification
   <http://www.zigbee.org/Markets/ZigBeeSmartEnergy/Specification.aspx>
2) ZigBee Cluster Library Specification
   <http://www.zigbee.org/Products/ZigBeeClusterLibraryDownload.aspx>
3) ZigBee Home Automation Public Application Profile
   <http://zigbee.org/Markets/ZigBeeHomeAutomation/download.aspx>
