Hubitat is an event-driven system. In general, automations on Hubitat are performed using an app that acts on a device (the code behind a device is called a driver), where the device in Hubitat usually corresponds to some real-world device like a switch or thermostat. Devices may offer commands that can be executed on the device (e.g., to turn a switch off or set a thermostat to a certain setpoint). Devices generally also generate events, which are usually changes in state — for example, motion becoming active or a switch turning off.
Related to events are attributes, which have a value. These attributes generally represent the current state of a device and are visible under Current States on the device detail page. Any time the value of an attribute changes, an event is normally generated (though ultimately the driver controls whether one is created or not). The hub itself — rather than a device — also generates some events, like at sunrise, sunset, or when the hub mode changes.
In general, an app might subscribe to one or more of these events, then perform user-configured actions in response. For example, an app could listen for (subscribe to) a specific motion sensor to becoming active (i.e., an event). The app could then tell a switch to turn on (i.e., run a command on a device). This is the means by which apps create automations on Hubitat.
Some apps are used to help integrate devices to make setup and maintenance easier than a driver-only approach or handle communication between the some real-world service or device and the Hubitat device(s). These are sometimes called "integration apps." Built-in examples include the Hue Bridge Integration app and the Sonos Integration app. The focus here is mostly on typical, automation-oriented apps.
For an introduction to Hubitat app development, start with: App Development Overview, then move to Building a Simple App.
In general, a driver "translates" information to and from Zigbee, Z-Wave, a LAN or cloud API, or whatever the underlying device protocol is into something standardized, so both users and apps can interact with devices without knowing specific, underlying details.
NOTE: Virtual drivers are different in that they generally simulate real device behavior without an underlying real device. As a developer, they can be useful as a way to test apps without needing a "real" device (or real device events).
An important concept for driver (and app) development is capabilities, which specify a set of commands and/or attributes that a driver that implements that capability should offer. Most drivers implement multiple capabilities, depending on the features of the device and its intended use.
For example, a driver that implements capability "Switch" must offer on() and off() commands. Additionally, it must have a switch attribute that reports either on or off as the value (generally expected to represent the actual device state), per the capability specification. Capabilities differ in what they require but generally correspond go real-world features that actual devices of that type generally offer. See Driver Capability List for a list of available capabilities and the commands and attributes they require.
For an introduction to Hubitat driver development, start with: Driver Development Overview.
Hubitat apps and drivers are written in Groovy and run inside the Hubitat Elevation app and driver execution environment. This environment is a sandbox that provides Hubitat-specific methods for convenience (see more in the other developer guides for apps, drivers, and common methods) and security.
As part of this model, there are some restrictions. You cannot:
println() or sleep()However, the sandbox generally provides a way to do anything you need to do in an app or driver (e.g., use log.debug and similar methods instead of println).
You do not need to be a Groovy expert to create apps or drivers on Hubitat, though experience with Groovy, Java, or a similar language may be helpful. Hubitat uses Groovy 2.4. Official Groovy 2.4 documentation can be found at: http://docs.groovy-lang.org/docs/groovy-2.4.21/html/documentation/. Other resources are also available online or in print (but be aware of what version they assume, as different Groovy versions may not offer some features found in other versions).
There are also many Hubitat app and driver examples; see the app and driver developer docs and HubitatPublic repository for more). The rest of the developer documentation also includes examples and tutorials for app and driver development.
Some Groovy points that may be worth noting for developers familiar with other languages:
log.debug "My log message"
return keyword is optional; the last statement in a method will be used as the return value (if the method is not void)GString type that allows interpolation of values, available to strings inside double quotes (no need to concatenate):String name = "John"
// This will print "My name is John" to Logs:
log.debug "My name is ${name}"
it) and return a value. They can be passed as parameters to methods and are particularly useful with many Groovy collection methods. For example:def myList = [1,2,3]
log.debug myList.any { it == 1 } // returns true
myMotionSensors.any { it.currentValue("motion") == "active" }
To get started developing apps, start with:
Or for drivers: