Parsing Zigbee "messages"

🚧 Developers Coding Questions
1

I am looking to understand the "event" as it applies to Zigbee parsing. In the below code (a typical structure from one of the code guru's here) I'm missing the meaning/need for the event code lines.

My understanding of an "event" is; an event occurs whenever something is written to the database (maybe oversimplified).

In the below parse method there are two lines that I'm lost on:

  1. def event = zigbee.getEvent(description) --> If we just received a zigbee message, why must we we have to get an "event" based on the zigbee message? And what would it be?

  2. sendEvent(event) -->
    so we:

  • received a zigbee message
  • got some related event
  • then we have to send this event to ?? somewhere
def parse(String description) {
	if (logEnable) log.debug "description is $description"
    Map map = [:]
	def event = zigbee.getEvent(description)
	if (event) {
        if (txtEnable) log.debug "parsed zigbee event = '${event}"
		sendEvent(event)
	}

Thanks
John

2

All that comes into parse() is the "raw" description string. You need to parse this message to figure out what it contains. In many cases, this would correspond to an event you want to generate (e.g., a switch turning on or off). The zigbee.getEvent() method is a sort of "shortcut" you can use to generate an event object from this data if the device uses standard clusters and attributes and this is one that this method knows about. For simple devices like switches, it very well could.

An alternative approach you'll see in some drivers is using zigbee.parseDescriptionAsMap() instead. Then you can inspect the (keys and) values in the resulting map object yourself and build/generate events as needed. This is the approach Hubitat developers normally use themselves, as far as I know, with zigbee.getEvent() likely just being around for ST compatibility (though certainly usable if it works for the messages your device sends).

The previous steps really just created an event object; now you need to pass it to the platform to actually create/generate the event itself. Calling sendEvent() is one way you can do that (returning an event object itself, whether created from the first method above or manually with createEvent(), which just makes the object but doesn't "send" it, is another, though also something I don't think most Hubitat drivers do).

This document (and ones it links to) explains more about the above and demonstrates the typical methods used by Hubitat drivers:

2 Likes
3

Thank you. I had read the "building a Zigbee Driver" more than a few times, I even read the smarthings docs (I downloaded as they were changing).

So my error was assuming the message was the result of an event. But your explanation shows me the message comes directly from the device. Much clearer now.

I'll have to investigate more what the created object contains to better understand the ramifications of creating or not the object event.

4

We don't use createEvent internally since it doesn't support every capability.
The patterns that we use generally follow the form shown in this driver:

1 Like