Skip to content

HubitatController

HubitatController is the interface to Hubitat Elevation home automation controllers. Setup for Hubitat is a little more involved than some of the other controllers, because it involves installing add-on applications to enable their API.

Tip

If you have another integration that is already using Maker API, you will need to install another instance of Maker API for Reactor's use exclusively. This will not disrupt your other integration(s). When you create the new Maker API instance, you can give it a name that is distinct so you know it used by Reactor (e.g. "Maker API for Reactor")

  1. Open the Hubitat user interface in a browser locally;
  2. Go to the "Apps" section.
  3. Create a Maker API instance by clicking the "Add Built-in App" button, typing "Maker" in the search box, and clicking "Maker API". This will open a detail dialog for the new instance.
  4. Assign the new instance a name that lets you easily discern that it's for Reactor (see Tip above).
  5. Turn on "Allow Access via Local IP Address". It is not necessary to turn on "Allow Access via Remote / Cloud" (and it is recommended that you leave it off).
  6. Leave "Create new access token" selected (unless you know what you are doing and you want to reuse an existing token).
  7. Click on "Select device" and choose all devices (or only those devices you want available in Reactor).
  8. Turn on "Include location events to be sent by POST", and if you use modes or HSM, turn on the "Allow control of" switches for those as well.
  9. Turn on "Allow control of modes" and "Allow control of HSM".
  10. You're almost finished. Before you leave this page, right-click the "Get All Devices" link under the *Local URLs" heading and choose "Copy link location..." (or your browser's nearest equivalent). You will be pasting this into your reactor.yaml configuration file in a future step.
  11. Click the "Done" button at the bottom of the page to create your new instance. You can get back to these settings any time (and you may need to when you add devices) by going to Apps in the left navigation and then clicking the instance name.
  12. Open reactor.yaml (in the config subdirectory) in your text/code editor and find the Hubitat entry. Go to the source key under config in this section, and paste the entire URL copied from two steps ago (remove the default/placeholder URL). Make sure the URL is surrounded in double-quotes (see example below).
  13. Go up to the enabled key for this controller and change the value to true (no quotes around the value).
  14. Save the configuration file.

Your configuration for Hubitat should now look something like this:

controllers:
  # ...other controller configuration not shown for clarity

- id: hubitat
  enabled: true
  implementation: HubtitatController
  name: Hubitat
  config:
    source: "http://192.168.0.3/apps/api/166/devices?access_token=4b840f3e-0000-4c1d-0000-357242c2d272"

You may now restart Reactor. Refresh any browser windows open to the Reactor UI, and go to the Entities list. You should see your Hubitat devices listed.

You Must Publish New Devices

Remember, any time you add a device to Hubitat, if you want to see it in Reactor, you need to add your new device(s) to the "allowed" list in the Maker API instance, or Reactor will not be able to see it/them.

Hubitat with Hub Login Security Enabled

Hubitat's Hub Login Security causes its event notification WebSocket connections to issue no events or data at all until a login to the hub is performed (this is presumably a security feature, but it's a pretty weak one at best). If you have Hub Login Security enabled, you will notice that Reactor frequently reconnects to your hub (visible in log messages about every six minutes by default) and is slow to detect device changes. This is particularly seen after a hub reboot, where there is a gap in time between the hub starting up and your first login to it.

The following solutions are available:

  1. Set the username and password fields in the controller's config section of reactor.yaml. The HubitatController will do its own login and thus enable the WebSocket API to function as needed.
  2. Turn off "Hub Login Security" in your hub settings.
  3. Don't let the HubitatController use the WebSocket API and have it use the old "POST URL" mechanism. This can be done by adding use_posturl: true to the controller's config section of reactor.yaml. This is the least desirable of the three solutions as it has been shown to be less reliable than using the WebSocket API, but it's a trade-off between security and performance/reliability.

Polling

Legacy Z-Wave devices that don't support "instant status" or a similar workaround (due to patents in effect at the time) need to be polled periodically, as their manual manipulation is not immediately reported to the hub. HE provides an app called Z-Wave Poller for this purpose, but it is widely reported to be troublesome and not work as expected/desired. HubitatController has a polling feature that functions as a replacement for this app.

To configure polling, all you need to do is add poll_entities to your configuration as shown below:

    config:
      source: "http://192.168.0.3/apps/api/166/devices?access_token=4b840f3e-0000-4c1d-0000-357242c2d272"
      poll_frequency: 60000  # poll a device at most every 60000ms (60 seconds)
      poll_entities:
        - id: 110  # Hallway Light
          interval: 300  # 300 seconds = 5 minutes
        - id: 15  # Basement Light
          interval: 900  # 900 seconds = 15 minutes

Each element of poll_entities needs to contain id with the device ID to be polled, and interval with the polling interval in seconds.

To avoid creating too much Z-Wave traffic, the poller will only poll a device every poll_frequency milliseconds (default: 60000 = 60 secconds = 1 minute). This can be tuned down if you have a large number of devices to poll or devices that need to be polled frequently, but again, take care that you don't end up congesting your Z-Wave network with polling requests. Be realistic about your needs and the limitations of Z-Wave.

Other Configuration

The following other keys may appear in the config section, and perform their described function:

  • action_pace — (integer > 0) sets the minimum delay between actions sent to the hub (i.e. when a Reaction includes many); sending large numbers of requests can overwhelm the hub, it has been found, so this attempts to slow the pace to avoid this issue. The value must be an integer greater than 0, and the units are milliseconds; the default is 25.
  • warn_unresponsive — (boolean) Network latency, packet loss, and connection controls/restrictions can cause Hubitat's WebSocket events feed to stall, resulting in a loss of device updates. Reactor attempts to detect unresponsive feeds, and when it does, it closes its connections and opens new ones, logs that fact, and sends a alert notification (seen on the Status page). Set this configuration key to false to suppress the alert. Suppressing the alert does not change the detection/recovery behavior, and recovery events are still logged to the log file. If you are getting a large number of reconnections, that suggests poor network quality between the Reactor host and the hub.
  • probe_device — (optional, integer, Hubitat device number) sets the device number that the connection health probe should use. If not set, HubitatController selects a random device for each probe (less desirable). A virtual switch device is a good choice for this purpose, but any reliable device is adequate. Do not choose the Hub Information v3 (or later) driver as the probe device.
  • probe_action — (optional, string) the (Reactor) action to run against the probe device. By default, this is x_hubitat_Refresh.refresh. You may change the default action by specifying your own as the value here. If your action requires parameters, you may additionally specify an object containing key/value pairs for the parameters in probe_parameters. You should set these config values only if you really know what you are doing; failing to set these correctly may lead to random disconnects between HubitatController and your hub and cause reliability and performance issues in rules and entity states.

Don't use WiFi

Neither your Reactor host nor your hub(s) should be on WiFi connections. You need the reliability of a well-constructed hard-wired network for automation in production use.

Update Behavior and Cautions

When a Hubitat hub updates a device, it will send events one field/value at a time. For example, if the color is changed on an RGB light, there will be three events: one for the change to the red value, one for the change to the green value, and one for the change to the blue value. As a result, Reactor's entity for the device will, by default, undergo three updates, one for each event/updated value received. The effect of this, however, is that the color value on the entity may be incorrect until all three events have been processed. For example, if the current color of a device is (r, g, b) [0,255,0], and the color is changed to [255,0,255], the first event (change red) will cause the Reactor entity to show [255,255,0], the second (change green) will show [255,0,0], and the third will show [255,0,255], which is at last correct. There is no definitive way to tell how many events will be received for any given change, as that is dependent on the (Hubitat) capability, its attributes, and the value(s) from and to which they are being changed. Therefore, rules that rely on testing multiple related values on a single entity should therefore be carefully studied to ensure they do not react to intermediate conditions. This should, however, be a very rare need.

It is possible for Reactor to delay updating its entity when an event is received in anticipation of receiving additional events for the same entity. This behavior is not enabled by default, because enabling it dampens the responsiveness of the system. If you find you need the delay to make entity updates more atomic (a term often used to describe multiple steps that must be taken as a single action), you can set the delay_update key in your HubitatController config section to the number of milliseconds delay you want. There is no rule for choosing a delay — it depends entirely on your hub, devices and drivers, and is likely quite variable. That said, testing has shown that values under 25 are unlikely to be sufficiently long; larger values increase proportionally the risk that that brief device state transitions could be missed (that is, any event shorter than the delay could be missed — with a delay of 250ms, a virtual switch being turned on for 200ms and then off, for example, would be missed). The correct value is entirely dependent on your hub, your devices, your rules, etc. The value you choose may need to be re-evaluated if you add or remove hub devices, applications, and drivers. The author does not recommend using this delay (it's better to focus on your logic), but, you've been given the choice.

Limitations

  • x_hubitat_Variable.setVariable has two known limitations:
    1. Hubitat strings are limited to 1024 characters (or 255 for hub firmware earlier than 2.3.5.135). This is a hub limitation for which there is no workaround. Attempting to assign a longer string will result in the action being ignored (it is not truncated automatically). You can use a substitution expression of the form ${{ substr( str, 0, 1024 ) }} to ensure that your string does not exceed 1024 characters (this expression truncates the string).
    2. Strings set with this action may not contain commas. If commas appear in the string, the comma and everything after will be dropped. Testing has also shown that if there are multiple commas, the command may be ignored altogether. An expression of the form ${{ replace( str, ",", ";" ) }} can be used to substitute commas with another character (semicolon as shown). It is possible to use Rule Machine's API to form a URL to be used in an HTTP Request action that can set a string with embedded commas correctly, but this requires complex setup on HE and will not be documented here. Inquire on the Smarthome Community forums if you really want to try to use this approach.

Updated: 2023-Dec-27