Writing a Device Driver

From Hubitat Apps
Jump to: navigation, search


Work in progress - initial edits are by Andrew Rowbottom who barely knows what he's doing

If possible copy an existing virtual driver.

Visit the Capabilities page https://docs.hubitat.com/index.php?title=Driver_Capability_List and decide which capabilities you are interested in implementing.

Lifetime[edit | edit source]

From some investigation it looks like the lifetime of a driver *instance* aka Java Object is very transitory, a simple "push" command from the MakerAPI (or Drivers Page) will create a Java instance of your driver class to execute the "push" command. If that method then calls runIn(1,delayedMethod) a NEW Java instance of the driver class will be created and the delayedMethod called on that instance.

This means that if you want to "preserve" a value for even just a millisecond across calls you cannot save it in an instance variable.

Sensors and Actuators[edit | edit source]

There are 2 "base" capabilities ..

  • "Sensor" which indicates that this device will report data that it got from somewhere
  • "Actuator" which is a device that does something

You're very unlikely to see a device from someone that only implements one or both of these. It is more useful to "tag" a device with other capabilities so that the apps can make decisions about how to display or control them .. e.g. a contact sensor, or a switch both have meaningful visual displays

In truth a device that doesn't implement another capability is something of an oddity, it doesn't integrate well into the Hubitat system because it doesn't really tell the Hub anything about itself.


Actuators[edit | edit source]

Actuators usually have commands and attributes .. commands because that's how you tell them to do something (which is what makes them Actuators) and usually (not always) Attributes so they can let the rest of the Hub know what the outcome of the last action was (e.g. Switches are on or off), useful for display and other purposes.

For actuators look at the "commands" section, you should implement methods matching the names.

For Example for a "momentary button" the docs say:

  Momentary
    Device Selector
  capability.momentary
    Driver Definition
  capability "Momentary"
   Attributes
  Commands
    push()

This tells us that it has "no state", but should implement a "push()" method

While a "Switch" looks like:

  Switch
   Device Selector
    capability.switch
   Driver Definition
    capability "Switch"
   Attributes
     switch - ENUM ["on", "off"]
   Commands
     off()
     on()

which tells is it should have an attribute named switch which can take on/off and it should have 2 "command" methods on() and off()

Sensors[edit | edit source]

You will see "Sensor" like capabilities without commands, so a ContactSensor doesn't control anything, it just reports on what is sees.

These are expected to get information from somewhere, somehow -- that's a more complex story.

Attributes, state, etc[edit | edit source]

What is the difference between an Attribute (aka "current state") and a "State Variable" - T.B.D.

Sending Events[edit | edit source]

Your driver should send events to update it's Attributes. Using sendEvent allows other parts of the Hub to know that the value of an attribute has changed, and perhaps act on it, the RuleMachine being an obvious example, though dashboards also want to know.

A simple sendEvent would look like:

   sendEvent(name: "switch", value: "off")
  • the name is the name of the Attribute
  • the value must be one of the defined "ENUM" values for the Attribute switch (since it is defined as an ENUM)

In most cases the attribute name is the same as the capability, but don't be fooled, it isn't always! For example the Beacon capability has a presence attribute, but takes ENUM ["not present", "present"], so you do need to take some care!

Commands[edit | edit source]

You probably need to implement commands, the ones you must implement are documented on the Capabilities page, you can implement others as you wish.

What other criteria must be fulfilled?[edit | edit source]

Many Capabilities (especially Actuator like ones) have BOTH Attributes and Commands.

This is because as well as doing something (commands) they (and other things like dashboards) often need to know what state they are in (on / off for switches).