Groovy: What does "getLinkText(device)" do?

🚧 Developers Coding Questions
#1

I'm modifying a driver that has this code in it (life360) and I have no idea where this method comes from:

I'm also very new to using groovy so I'm not sure what parts of the language are built-in and what parts are Hubitat specific.. where do devs look to figure these references out?

    // *** Presence ***
    def linkText = getLinkText(device)
    def handlerName = ( memberPresence == "present" ) ? "arrived" : "left"
    def descriptionText = "Life360 member " + linkText + " has " + handlerName
    if(logEnable) log.debug "linkText = $linkText, descriptionText = $descriptionText, handlerName = $handlerName, memberPresence = $memberPresence"
    def results = [
          name: "presence",
          value: memberPresence,
          linkText: linkText,
          descriptionText: descriptionText,
          handlerName: handlerName
    ]
    sendEvent (results)
    state.presence = memberPresence
#2

In the driver you are modifying it is commented out: hubitat-drivers/life360_driver.groovy at master · jpage4500/hubitat-drivers · GitHub

I'm not sure where it comes from.

#3

Ok thanks.. so you're saying getLinkText() isn't something that's built-in at all but defined in another class/import?

That's what I was trying to figure out.. I didn't see it but I'll look for it now that I know it's not built-in somehow

#4

This is not something I would use on Hubitat, though I just tested and it apparently exists. It just returns the display name of the passed device, i.e., the displayName property, which was once called linkText on SmartThings but deprecated long ago (but apparently something people kept copying into new DTHs and even Hubitat drivers, where it is likely included for compatibility). I would use device.displayName instead.

To answer this:

I suppose the Groovy stuff you'll just have to know or learn, but Hubitat-specific methods are all in the developer documentation:

Most commonly, you'll want to look at either the Driver (in your case) or App (if you were writing an app) methods docs, or Common Methods for things that are available to both/either.

3 Likes
#5

Still wishing this documentation could be complete, without the TODO sections in Driver, App, Zwave and ZigBee.

1 Like
#6

thanks - that helps explain things! I'm going to use device.displayName for future reference so it'll make sense later on.

#7

These will be filled out over time (and likely auto-generated, so I'm hesitant to do much with them manually now). But most are easily figured out in the meantime by looking at the method name and parameter names (like setLocationMode()), by examining the driver and app examples linked to in the documentation, or are rarely used and also likely there for similar reasons to the above. Is there anything in particular you are having problems with in the meantime?

#8

semi-related.. this block of code was also something that I was hoping to find documentation for

I've seen several examples of sendEvent() in drivers but this is the first time I've seen a JSON block called results which obviously sets the device presence state. But, aside from just believing it works it'd be nice to know what it does

#9

This is documented here:

https://docs2.hubitat.com/developer/driver/driver-object#sendevent

That is also a bad example, again likely ported ST code (linkText and handlerName do not do anything). This is a Groovy Map, not JSON, though Groovy does make it easy to convert between the two.

(There is also a little Groovy trick where a Map parameter can be treated like named parameters instead, accounting for the slightly different syntax you see in your example versus this one, but the general idea--and key/parameter names--are the same, and this is not Hubitat-specific.)

1 Like
#10

RE: sendEvent

Ok, this one I figured out myself.. partly just not understanding groovy language fully

But, I see the sendEvent() method documented here

I don't see what linkText or descriptionText are used for.. do they just create additional attributes for this driver?

#11

Again, linkText is not used on Hubitat (and was likely deprecated on ST long before Hubitat existed...probably people just copying DTH code into DTH after DTH and eventually Hubitat drivers without understanding what it was doing).

The descriptionText property here sets the same property on the event. Apps can use this (it's the %text% variable set by a Rule Machine trigger if you use that in your actions), and it's also displayed on the "Events" page for the device (accessible from the button at the top of the device detail page). There usually isn't too much exciting going on there, often just text "(Device name) (attribute name) is (value)," but it can be nice to set.

#12

This year? Soon? Should I stop asking?

Having to grep thru examples elsewhere to find something defeats the purpose of documentation in the first place. I'm STILL using the old ST documentation from an archive site to figure things out from time to time. Its super frustrating when documentation is incomplete.

Zwave is nearly empty.

This is one of my biggest wish-list items for Hubitat's developer ecosystem. I compare to ST's Edge documentation on their new environment. Its extremely rich.

1 Like
#13

Perfect - thanks for all the help!

I'm simplifying the original code from 1st post into this and will make sure it works:

    def descriptionText = device.displayName + " has " + ( memberPresence == "present" ) ? "arrived" : "left"
    sendEvent (name: "presence", value: memberPresence, descriptionText: descriptionText)

Mostly I'm just trying to understand how it all works so I can support apps/drivers in the future

1 Like
#14

You've been here long enough to know that specific timelines are rarely provided. :slight_smile:

Z-Wave Object, maybe, but what are you looking for that isn't available somewhere? (Really trying to figure this out for prioritizing what people seem to want more of, not trying to be difficult.) The Z-Wave Classes document is entirely documented, for example. There is also a new document you may not have seen on how to get started actually building a Z-Wave driver (probably not helpful for you if you've already done this, but certainly something that has been asked for):

There are also relatively new documents on virtual drivers, building an app, and a basic overview of both environments — all of which, like the above, arose out of a true need people noted on how to get help getting started and actually doing things (which is more likely to be prioritized at this point. but I don't disagree that it would indeed be to have complete descriptions of all methods, objects, etc.).

1 Like
#15

These are extremely valuable and I realize they take up a ton of time and resources to create (screenshots, coming up with a comprehensive sequence of instructions, etc). So I'm not arguing for having reference material above those.

My point is that sometimes you just need the reference. Searching thru a "My First Zwave Driver" type primer to find the details you're needing isn't always obvious. I wouldn't be writing my first driver so understanding the overall structure isn't something I need.

My points on reference would be:

  • Its the documented standard for which HE expects and assumes. Sure the examples can back those up but often there are no explainations or details included, just the method in use. You'd have to figure out how its being used to gleam information from it.
  • It often clarifies what was a holdover for ST compatibility.
  • Its usually quicker to find than searching thru HOW TO or example code.

One thing that would help in the Zwave object documentation case is to have a link back to your Building a Zwave Driver page. "For more information, see Building A Zwave Driver.". I had no idea that page existed. The more cross linkage the better.

#16

BTW please don't take my replies as a personal attack. I'm just asking if its possible to get the reference material more fleshed out for an improved developer experience and explaining my reasons for why i've needed it in the past. It feels wrong that the ST Groovy reference seems more complete. :slight_smile: I also have no idea if you're an employee, contractor or just a volunteer who offered to help out with documentation. Your bio just says enthusiast and you don't have an employee badge next to your name so I assume volunteer.

1 Like
#17

I've worked for a company that did work for Samsung in the past.. they've got a TON of resources ($$$) so this doesn't seem like a fair comparison. They had whole teams of people just working on documentation.

I've also worked for Wink in the past and they had a great product and great support.. even a public API. But, they also ran out of money because there just wasn't enough revenue to sustain them as they really just sold a Hub and didn't (until the end) charge any kind of monthly fees.

Anyway, that's my perspective on all of this.. I'm just happy Hubitat provides as much as it does but it's the community support like this that's main reason it's able to support so many different devices.

What I think would be nice and could be a win-win for Hubitat is if they could find a way to open up the documentation to allow some of the community to edit (and maybe they already do). Same with some of their apps/drivers -- just take advantage of all of the community support for fixing some of the minor things that they don't always have time to get to. I'm not saying that'd be easy either -- but there's probably a lot of people here that would be willing to help out too

2 Likes

Download the Hubitat app