Where is the full API Documentation?

🚧 Developers
1

I'm writing an app and driver to do ongoing logging and charting purely locally, but am running into a lack of documentation.
For example, device.deleteCurrentState() was introduced around two years ago. But...

Where should I be looking?

2 Likes
2

Haven't seen it around but there isn't a lot to document outside of the full context:

device.deleteCurrentState(attributeName)

cc: @bertabcd1234

3

That's fair but...
Where do I even find that definition? Obviously I know about it now, and presumably there is a device.setState(), device.updateState() and device.readState(), but how do I find them? And what types can the attributes take?

Similarly, what (or where) is the canonical list of event calls? Is it possible to retrieve past device events?

1 Like
4

The formal documentation that exists is at Developer Documentation | Hubitat Documentation, the informal documentation is this community and its collective mind.

5 Likes
5

I couldn't find any reference to the above-mentioned (device.deleteCurrentState() ) methods in the formal documentation. Is it there, or is the hive-mind and pure luck the only approach to dowsing for APIs?

1 Like
6

I don’t know if there’s much luck about it.

Look at this instance. You couldn’t find something in the documentation. When you approached the community, you got an answer within a few hours. an hour.

A reasonable conclusion would be to approach the community for an answer when the docs are insufficient.

1 Like
7

If you can't find it with a quick search, I generally just post a quick question in the Developers category asking if anyone has done xxxxxxx - normally within in an hour I have enough options and suggestions that it takes me the most of the day to process and decide which way to proceed.

3 Likes
8

Uggah. Trouble is, I'm trying to do something that may not have been done before, and it's faster to read docs to find alternate approaches. But I guess these are the cards in the deck.

  • Is there a call to read the past events generated from a device?
  • Is there a size limit to the app state storage? At what point should I switch to files?
  • I would like to generate a custom dashboard tile from the app or a device, two-wide and with graphic content. What's a good way of going about it?
1 Like
9

You mention in your initial post on this topic that you're trying to do charting... are you aware that this was tried in the past and lead to problems? If you are, and you're going in a different direction, then: carry on. :slight_smile:

2 Likes
10

This addition was missed in the docs but has been added now. That being said, it is rare that you would need to do this in a real driver. Any attribute required by a capability the driver implements should always have a valid value, otherwise apps that depend on these values may behave unexpectedly. (Probably a good idea for custom attributes, too, but at least there are less likely to be conventions for those.)

For the other questions:

No, if you want to "set" or "update" the value of an attribute (i.e, something under "Current States" on the device detail page), you want to generate an event. The sendEvent() method is a common way to do this.

To read the value of an attribute, you can use currentValue("attributeName") (or equivalently the rarely-used currentState method), or the automatically generated currentAttributeName (where that is actually the name, e.g., currentSwitch) property.

Valid values depend on the particular attribute, either as defined by the capability or your custom attribute if that is what you're using.

Note that all the methods discussed so far refer to attributes/events, not the state object. I think this is what you mean, but some people do get confused with the similar names in the UI.

These are documented: Device Object | Hubitat Documentation. Specifically, look at the events() method.

But note that the user can set a number-based event limit on a device (you cannot as a developer), and by default I think you'll have something like 10 or 11 of the most recent stored. If you care about a specific event, you may want to have your app track it itself.

There is probably a theoretical limit, though I don't think I've ever seen anything come up in practical terms. If you're concerned, however, a file is probably better. It's just a bit more work to use since state is built-in and easy. The biggest issue with state is that it is loaded/de-seralized and re-seralized every time the app (or driver) code wakes and sleeps, so it will take longer as it gets larger.

Dashboard attribute tiles are limited to 1024 characters, though they might work for simple data. If you have a way to generate the image in your app, you could serve it via an OAuth endpoint. You might want to see how previous attempts at this, including Hubigraphs, did this; or how webCoRE does it now (either webCoRE Dashboard or the parts of Hubigraphs I think it absorbed).

Alternatively, lots of people will use an external system do to this kind of thing instead, e.g., feeding data to a database via Maker API and something running on another device/server and using a graph/chart solution with that data instead. (Search for Grafana here as one example.) While it can work, I'm not sure Hubitat Dashboard with an on-hub app or device is the best way to do this, personally.

5 Likes
11

Yes, I'm aware. And am going a different direction. :wink:

3 Likes