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.4.9) The [[https://hubitat.com/|Hubitat]] is a ZWave and ZigBee hub that can be connected to XTension via the new Hubitat plugin. It offers a choice for ZWave connectivity in XTension beyond the older Vera units that we will continue to support but that are no longer being produced. This is our best choice for ZWave support in XTension. These are very nice hubs with a good interface for XTension to use them as a ZWave interface.


====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. Earlier Hubitat OS versions did not support the setting of a static IP but more recent ones do.


>**You should give the Hubitat a static IP address either via the built in network settings or via a reserved DHCP address on your router. The local network lookup of “hubitat.local” can be very slow and cause noticeable delays in all communication and control.**

===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.

**NOTE: there is a problem that causes very slow performance when using the hubitat.local address. Later version of the Hubitat firmware have implemented the ability to set a static IP address and I recommend that you do this rather than rely on the local mDNS address. Then place the IP address into the Address field rather than the “hubitat.local” default. If you can’t set this through the hubitat interface a DHCP reservation in your router will work as well.**

If you have setup local access security on the Hubitat check the "Send Authentication" checkbox and enter the user and password.

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.

----

====Unit Naming Conventions:====
When XTension sees a new unit in the Hubitat it will automatically create a new unit for it with all the proper settings. It will also use the name you have given the unit in the Hubitat as it’s starting point. Once the unit is created the name of the unit is no longer important to the connection and you can change the name in XTension without changing it in the Hubitat. This can be useful if there are name length restrictions or if the naming convention you are using inside the hubitat would not be as useful as what you want to use in XTension.

-----

====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:** The default drivers in the hubitat may not support multi-clicks more than a double click. If you find a community driver that supports more that are not passed properly through to XTension please let me know and we can collect the information I need to properly support them.

**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.

===Scene Controllers:===
As of XTension 9.4.41 scene controllers and other devices with buttons or inputs should again behave properly. Wireless scene controllers will now create a single unit in XTension. It will not change state itself, but it will receive central scene events about which button was pressed and the number of clicks as available. Hold and release are handled the same as the examples above for switches.

-----
====Controlling Status LEDs:====
As of XTension 9.4.41 you can now control the status LED’s of the Home Seer WD200+ dimmers. Please see the [[supported_modules:hs-wd200|article about the WD200]] for more info and code examples.
-----

====Sending Device Specific commands:====

Many devices may have special commands that are not part of a normal Unit control, or that are just not implemented in this plugin yet. If that is the case you can use the **sendDeviceCommand** This is the same command that is used in the article above on controlling the status display on WD200 and other dimmers. This command allows you to send any command that you know the device supports regardless of the state of it’s support in XTension. It does require that the command be supported in the MakerAPI and the driver that the Hubitat is using.

Specific examples below but the general syntax for use requires that you know the command you’re trying to send. This can be found in the “Commands” portion of the Device control screen on the hubitat. It will have a big button for each command. If the command requires additional parameters then it will have fields for you to enter them. Those same parameters must be passed in the same order to the sendDeviceCommand command as additional parameters after the command name)

Since the Hubitat does not allow the low level setting of parameters in the device by number, you have to find the name of the command given to the parameter you wish to set by the driver as described anove.

<code>
tell xUnit “the name of the Unit” to sendDeviceCommand( “reboot”, ...(any number of additional path parameters needed by the command))
</code>

If you are running the command inside the Unit’s on or off script then you can leave off the tell xUnit portion and just use the sendDeviceCommand() without it.

Here are a couple of examples of using the command for real world devices. If you find a command for a device not listed here please let me know and I’ll add it as an example.

===HomeSeer Flex Sensor===
This device has the capability of producing a beep or alert sound. There is no standard Unit command to beep but you can use the sendDeviceCommand like this:

<code>
tell xUnit “name of HomeSeer Flex Sensor” to sendDeviceCommand( “beep”)
</code>

===Aeotec Home Energy Sensor===
This device has a command to reset the energy usage numbers which can be sent with the command:

<code>
tell xUnit “name of Home Energy Monitor unit” to sendDeviceCommand( “resetMeterAccumulation”)
</code>


-----
====Converting from the Vera:====
You cannot simply transfer your network from the Vera, or any other ZWave controller, and the Hubitat. They do not even attempt to support the transfer of the master controller as there are still so many holes in the implementation of most devices. No secure devices would transfer at all anyway by design. So the conversion process can be lengthy if you have many devices.

I would recommend removing devices from the Vera a few at a time, then re-linking them with the hubitat. In the MakerAPI app settings you’ll need to then select them for sharing. After that they will show up in XTension and new units will be created. You can then move the scripts over to the new units, delete the old Vera units and make sure the names are now the same as they were so that any scripts that access them will continue to do so without errors.

If you have the Units setup in any Views, events or web interfaces you will need to re-select them there too.

There is no reason to do an entire update at one time, except that you’ll be reducing the mesh qualities of the old network as you build up the new one. So I would do them in physical portions that might be routing through each other. This way the old device and the new devices will continue to be reachable on whichever interface they are connected to. XTension will happily control some through the vera and some through the Hubitat as you are converting.

You’ll find that it’s worth the effort as the Hubitat support, especially for things that were notoriously unreliable on the Vera such as door locks, work much better on the hubitat. They are sill in business as well and so their support continues to add new devices and improve the support of older devices. The way the interface to the hubitat allows you to write your own plugins, or cut and paste code fomr the community message boards on their site means that there is always going to be code available to support new devices, or less used features of special devices that aren’t supported by the built in drivers.

-----
====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.
  * Some older switches do not keep their state updated in the Hubitat and will report an incorrect value some time after you control them. I have written code into the plugin to get around this which fixes most but not all of the problems. If you find you have Units that continue to show that they are still on or still off after some time after they were controlled you can create a script that just sends a query to that unit. That will update it to the proper value. And use the on and off script of the Unit to execute that script a few minutes after the Unit has changed state or value. This will result in it being correct, but only some time after it was wrong for a bit. This is good enough for me in every circumstance I’ve found so far. I am able to look through my inside lights list and find any that were actually left on as opposed to having several units always report that they are on when they were turned off and are actually off.
  * 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>


-----
====Gathering Data For Unsupported Devices:====
If you have a device that is either not showing up at all or it showing no updates or the wrong updates please do the following to capture info about it. First I need a full database dump from your hubitat and the name of the device or it’s address so I can find the pertinent data in the potentially large database info. Please visit this link on your Hubitat, filling in your Access Token as described above in the initial setup:

<code>
http://hubitat.local/apps/api/<replace with your APP ID Number as above>/devices/*?access_token=<replace with your access token as above>
</code>

That will download some pages of JSON data into your browser, you can cut and paste it into an email to me or save it to a file and email me that if the data is too large.

Second I will need some of the push data that the hubitat sends when values change or are updated. In the Interface List window in XTension control click, or perform a contextual click on the hubitat interface you created there and select “Turn Debug Mode On” Now all the push information that is received will be written to the XTension log. Do whatever you need to in order to create some push updates from the Hubitat and then copy and paste those lines into an email to me as well. I’ll do whatever possible to support any devices that aren’t already handled properly.

-----
====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
  * Scene Controllers are working as of XTension 9.4.41
  * Valve devices, and other more unusual enumerated devices, are working as of XTension 9.5.2