Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Hubitat=====
{{:supported_hardware:hubitat_hero.jpg?400 |}}
(v1.2) The [[https://hubitat.com/|Hubitat]] is a ZWave and ZigBee hub that can be connected to XTension via the new Hubitat plugin. This plugin is currently in beta and you should not convert your entire Z-Wave network to one as it is not feature complete as of this writing. It offers a choice for ZWave connectivity in XTension beyond the older Vera units that we will continue to support. As of this moment both the plugin as well as the support for local connectivity in the Hubitat itself are under construction and so features and functions may continue to be added or removed as the protocols develop. Note that currently the plugin is not as feature complete as the Vera plugin and given that I don't know what will get added to the Hubitat protocols or when it may never be. Switching between the 2 devices cannot yet be done as a simple conversion from one plugin to the other. See more info below. 


====Hubitat Setup:====
Follow the standard initial Hubitat setup. A cloud connection is not required for XTension to talk to the Hubitat, all communications are done over the local network and so it is necessary that the Hubitat and the XTension be on the same local network subnet. If you have a more complex networking setup and need to specify the local address that it should tell the Hubitat to send push updates to please let me know and I can prioritize that to be added in a future plugin version.

===Install the MakerAPI Plugin on the Hubitat:===

The XTension plugin connects to the "MakerAPI" plugin on the Hubitat. This can be installed on the Hubitat by visiting it's built in web server which should be available at http://hubitat.local on your internal network. Visit the the "Apps" link in the vertical menu on the left hand of the screen and then click the "Add Built-In App" button on the upper right hand of the page. A list of official hubitat plugins will be displayed. Use the search field or just scroll down to find and select the "MakerAPI" plugin. There are several settings that need to be setup on this page as well as some information that you'll need when we setup XTension in the next step. First give the plugin instance a name that makes it clear that this is the interface to XTension when looking at the Apps list. It is possible you may need multiple instances of the MakerAPI plugin for other devices so to keep them straight you should change the Maker API Label field from the default of "Maker API" to something like "XTension Maker API" or similar.

===Select Units To Share:===
Scroll down until you find a header called "Allow Endpoint to Control These Devices" and click on the widget below it called "Select Devices." Here you can click the "Toggle All On/Off" button to allow all the units assigned to your hubitat to be shared or individually select the devices you want to share. **If you add new devices to the hub you must return to this page and check the device in this list before it will appear in XTension** there is no way to tell it ahead of time to share everything that you add later. If you wish the location, mode or security units also sent to XTension you will need to turn on the switches for "Include location events to be sent by POST", "Allow control of modes" and "Allow control of HSM."

===Find the API ID and Access Token:===
To connect to the Hubitat XTension will need to know two pieces of information, the API ID and the access_token of the MakerAPI plugin. You can find these towards the bottom of the MakerAPI configuration page. There will be some example URL's at the bottom of this page that look something like this:

<code>
Get Device Info (replace [Device ID] with actual subscribed device id
http://192.168.0.100/apps/api/67/devices/[Device ID]?access_token=29af4932-6fde-4277-9235-f24bfb5a338f
</code>

in this case the API ID is the "67" in the link and the Access Token is the long string of numbers and dashes at the end after the "access_token=" portion. Your API ID and access token will be different from the example above. Keep this page open as you will need to cut and paste those values into XTension in the next step.

====XTension Settings:====
{{:supported_hardware:hubitat_settings.png?600 |}}
In XTension visit the Interface List Window and click the **New Interface** button in the toolbar. Give the interface a descriptive name and select "Hubitat" from the **Device** popup. The rest of the window will populate with the info the plugin needs to connect to your hubitat.

If you have only a single Hubitat on your network you can leave the defaults for **Address** as "hubitat.local" under normal circumstances the port should be left as "80."

If you are running multiple Hubitat's on the network then you will need to provide them with Static IP addresses so you know which one XTension is connecting to. There is no interface to this inside the Hubitat itself so you will need to visit the configuration of your router and create a DHCP reservation for the 2 devices, then restart them to make sure they pick up the new address if you changed it from what they were using at the time. Then enter that into the address field. 

If you have setup local access security on the Hubitat check the "Send Authentication" checkbox and enter the user and password. **NOTE:** as of this beta version sending passwords is not implemented. If this is something you need sooner please let me know and I will move it up the list of items yet to implement. It will be available before the plugin is promoted out of beta.

Enter the API ID and Access Token from the URL's in the MakerAPI setup screen into the next section.

The **Scan For New Devices Now** button will be enabled if the plugin interface is running and will perform a deep database scan when you click it. If you add new devices to the MakerAPI sharing list you can make them show up in XTension immediately by clicking that button. A deep scan is run every 5 minutes, this button runs it on demand.

Click the Save button to save the Hubitat plugin instance in XTension. You can then enable the plugin in the Interfaces list window.

====Using The Hubitat Plugin:====

Once the plugin is enabled any Units you have selected to share on the MakerAPI setup screen will be created for you in XTension. If the devices have multiple sensor endpoints such as Motion, Temperature, Power Usage etc these will be given separate units from the master device unit. Each sensor endpoint will get it's own Unit in XTension to store and graph that data. If a sensor has enumerated labels such as "active/inactive" or "open/closed" those will be automatically added to the new Unit as an [[xtension_manual:advancedlabel|Advanced Label]] Once the Unit is created if you wish to have other labels displayed for the values you can edit this label in the Edit Unit window. These values are only set when the Unit is created and will not overwrite any changes you make after that point. 


Lights, Switches and outlets should all behave as expected in XTension. Including full color support for color and color temperature capable devices.

For switches that support Central Scene actions on click and double click please use the same handler in the Unit's On Script as you did with the Vera. Specifically create an on centralScene( theButton, theGesture) handler like:

<code>
on centralScene( theButton, theGesture)
    
    write log (thisUnit) & " central Scene for button " & theButton & " with gesture of " & theGesture

end centralScene
</code>

to capture the holding and releasing of a switch create an "on hold" and "on release" handler such as:

<code>
on hold( theButton)
    write log (thisUnit) & " button " & theButton & " is being held"
end hold

on release( theButton)
    write log (thisUnit) & " button " & theButton & " was released"
end release
</code>


**Note:** as of this beta version there is not yet an "insert" toolbar menu item to insert a default handler for these actions. That will be added before the release.

**NOTE:** Unlike the Vera it seems that the Hubitat only supports single and double clicks. Devices that support multiple clicks beyond that do not share that data with XTension yet. When this becomes available in the Hubitat API I will make sure it works properly with XTension.

**Device Notifications:** If the device supports a notification such as the flashing light on some switches and you define that in the Hubitat that notification will show up as a separate unit in XTension that will allow you to turn on and off the notification display by turning on and off the unit.

====Things That Are Not Implemented Yet:====
Multiple taps on a central scene switch beyond single and double tap are not sent by the Hubitat. If you make use of the triple or more click capability of some switches that is not currently working. This is a limitation in the Hubitat and so I cannot say when or if it will be addressed but since I use that functionality I will certainly be pushing for it from them. It does appear that the Hubitat itself supports more taps than just the double tap it is just a matter of them making this information available to the MakerAPI protocol and then I can support it as well.

Devices with more than the 2 buttons on a regular paddle switch do appear to be working. The third "config" button on the Innovelli switches does come in as a tap on button 3. (though no double tap is supported on it) So I expect that central scene controllers with multiple buttons will also work normally but I have not yet tested this. At least they should work normally for single and double taps, more than that are probably not supported yet given the above limitation.

Virtual units may not be controllable from XTension yet but they will send their value and state changes to XTension. I'm not sure yet why some appear to work normally and others do not but will get this sorted out for the release.

Sensor type devices that should be controllable, for example door locks or garage door controllers may not be controllable yet from XTension. If you have a device like this that does not work properly please drop me a note and we can gather some data to help make this work properly.

As of this moment it does not appear that setting of device firmware data is supported by the Hubitat protocol. So things like setting the LED display colors on the Innovelli or Home Seer switches is not yet possible. I hope to either have this sorted out or to have a feature request in to the Hubitat folks to implement it as soon as possible but since it is up to them on their side I cannot guarantee when or if this will ever work properly. It is something I make a lot of use through the Vera and so I will be pushing hard to find a way to make this work. It does appear that the hub itself supports setting this information. It is just a matter of bringing it out to the MakerAPI protocol so that we can do it remotely.

The support for location events, control of modes and control of the "HSM" or security features of the Hubitat are completely untested as of this first beta. If you are using these things and they do not work as expected please drop me a note and we can collect some more data to make it easier for me to properly implement them on our side.

Since this is a new Hub and a new plugin and I have not built a large system with it yet there will almost certainly be other issues and limitations with specific devices and I cannot yet speak about those. Overall it appears the Hubitat has very good support for the more standard ZWave and ZigBee devices. Please visit their support community to verify that any other more exotic devices you might use are supported and working before you dive in. 

The Hubitat and it's MakerAPI protocol are moving targets as of this moment, new firmware updates may break things, or fix things or add or remove features. I do not have control of that but will of course do everything I can to keep up with the latest upcoming changes. There may be frustrations ahead but by doing some integration of this device you will definitely help get it as reliable and feature complete as it is possible to be.

====Converting from the Vera:====
I know there is great interest among some folks to have an alternative to the Vera for ZWave control. As of this moment I do not recommend just transferring your entire network to the Hubitat. There is too much to do yet though if you were to begin transferring individual units, especially unusual or special ones that will help me to make sure all those are as well supported as possible given the evolving state of the Hubitat communications protocol. 

Indeed, even if you wanted to you cannot simply transfer the network from another controller to the Hubitat. This feature seems to be missing from their feature list and instead they recommend removing the devices from the old controller and adding them to the Hubitat one at a time. This would be a HUGE job for some folks with larger networks and so I hope they will relent and work on the bulk transfer as an important feature for people switching to their hub. 

Please make your desire for this to them via feature requests or posts on their community support boards!

====Potential Issues:====
  * I cannot currently get my Hubitat to recognize some older ZWave 1 switches. They can be added only as a “Device” and are not controllable. Changing the device type in the Hubitat to a generic dimmer or switch does show the rest of the controls but they cannot be successfully controlled.
  * As of this moment only click and double click and click and hold appear to be able to captured to the central scene handler. Many switches support more than that. This appears to be a limitation in the MakerAPI as of this writing.
  * The enumerations for things like Thermostat Modes are different than the Vera. To avoid confusion you should script them via the newer [[dictionary:unitinformation:enumeratedvalue|Enumerated Value]] capabilities of XTension so that you can do things like:
<code AppleScript>
set value of “Thermostat Mode Unit” to “cool”
</code>

====History:====
  * The Hubitat plugin was first added as a beta version in XTension v9.4.35 in January of 2021
  * Thermostats are working as of XTension version 9.4.36 plugin version 1.1
  * Ceiling Fan control is working as of XTension version 9.4.37 plugin version 1.2
Mac Home Automation

User Tools

Site Tools

Page Tools
