Object Model / API Description

Hi There,

first of all: Thanks for OpenHAB, I really like it!

I haven’t seen an API Description for the different Items I have in Openhab. Is there a guide to the functions and properties available in the language and the different objects?

I use OpenHAB mostly with Homematic Items and also with the weatherbinding.

This is a rule I created. My question is: How would I know the properties of a Homematic Rollershutter? Just to see the possibilities. (in this example, I want to send the command only, when the state of the rollershutter is >0 or something.) But how would I know the exact property name? Or even the language syntax. Is it Java Script? :slight_smile: confused

Number   Rain          "Regen [%.2f mm/h]"   {weather="locationId=home, type=precipitation, property=rain"}
Rollershutter Shutter_Bedroom  "Schlafzimmer Dachluke [%d %%]" <rollershutter> (gShutter, gBedroom) { channel="homematic:HM-LC-Bl1PBU-FM:3014F711A0001F98A9AABA5D:OEQ2338407:1#LEVEL" } 


var Number rain

rule "Luke zu bei Regen"
when
    Item Rain received update 
then
    logInfo("Luke zu", "Rule Triggered {}", Rain)
    if (Rain.state() > 0.06) {
        Shutter_Bedroom.sendCommand(0)
    }
end

Uhm okay, the syntax is obviously Xtend, didn’t see that right away. So Obviously I need to look here http://www.eclipse.org/xtend/documentation/index.html for the syntax description…

But what about the description of (for example) the Number or the Rollershutter Object?

You can create an item manually & then “GET” it through the API to figure that out :wink: That is what I did below.

For example, here is a (redacted) Number item.

{
  "link": "https://[server]/rest/items/cpu_load",
  "state": "4.3",
  "stateDescription": {
    "pattern": "%.1f %%",
    "readOnly": true,
    "options": []
  },
  "editable": false,
  "type": "Number",
  "name": "cpu_load",
  "label": "CPU Load",
  "tags": [],
  "groupNames": [
    "system_info"
  ]
}

thanks @Bruce_Osborne !

Just found out how easy that is by installing the Rest Documentation from the “Misc” section of the Add-Ons and then accessing it through the dashboard:

1 Like

That is exactly what I did. My example is in a text file. That is likely why it is marked as not editable.

Okay. Now I know how to see the properties of an Item. Seems the “sendCommand()” explicitly sets the state property.

There’s also the Rest call to give me all items. Now. Where would I look for the documentation of a collection / list that contains all items? In what namespace would I find this?

Next: I want to cycle through all items of group “gFritzBox” to check if the Contacts are “online” or “offline”. So instead of using the item names in the rule I’d like to select the items based on their group…

You mean the chart here?

ALL Rollershutter Items have the same properties. One of the main purposes of Items is to model your home automation independent of the devices and technologies in use. A Homatic Rollershutter Item is identical to a Zwave Rollershutter Item.

I’m not sure that actually answers the OP’s question. I think he asking what methods are available on the Rollershutter Item which would not be reflected in the REST API.

All Items have a standard set of functions/properties you can call from Rules. See https://www.openhab.org/docs/configuration/rules-dsl.html#manipulating-item-states for how to specifically access, update, command and use Item’s states in a Rule.

There are other methods available to pull historical data from persistence, check/change Group membership, access members for a Group Item, and the like. They are all in the docs.

It is a custom Domain Specific Language based on Xtend. You can find info about the syntax here and here.

You appear to be a coder. You might be happier using JSR223 and coding Rules in Jython, JavaScript (Nashorn) or Groovy. Here is the version of your Rule in Jython using the Helper Library.

from core.rules import rule
from core.triggers import when

@rule("Luke zu bei Regen")
@when("Item Rain received update")
def luke(event):
    log.info("Rule triggered {}".format(items["Rain"]))
    if items["Rain"] > DecimalType(0.06): events.sendCommand("Shutter_Bedroom", 0)

For the purposes of Rules, the only difference is the type of MyItem.state. For a Number the type will be DecimalType (which itself is of type Number). Rollershutter is of type PercentType (also of type Number). Both Items have the same properties and methods.

See https://www.openhab.org/docs/concepts/items.html for further details.

The easiest way to get the full list of methods available on any Object in Rules DSL is to use VSCode with the openHAB extension. Then you can type MyItem. and a dialog with all the valid completions will pop up. Beyond that you can look at the source code for GenericItem. For the most part you will only care about state, sendCommand and postUpdate.

See https://www.openhab.org/docs/configuration/rules-dsl.html#manipulating-item-states. There are very important distinctions between sendCommand and postUpdate you need to understand.

There is no such thing in Rules DSL. You can get a dict of all Items and their current state in Jython Rules, called items.

Explain more what you are after because there are lots of ways to do this depending on what you are after, some of which don’t even require a Rule.

Get a count of all the OPEN contacts:

Group:Number gFritzBox

Set gFritxBox to OPEN if any member of the Group is OPEN

Group:Contact:OR(OPEN, CLOSED) gFritzBox

Trigger a Rule when any member of gFritzBox changes to OPEN

rule "something opened!"
when
    Member of gFritzBox changed to OPEN
then
    // do something
end

Jython version:

from core.rules import rule
from core.triggers import when

@rule("something opened")
@when("Member of gFritzBox changed to OPEN")
def opened(event):
    # do something

Do something with all OPEN members of gFritzBox when one of them changes to OPEN

rule "something opened!"
when
    Member of gFritzBox changed to OPEN
then
    gFritzBox.members.filter[ i | i.state == OPEN ].forEach[ i |
        // do something on each member that is OPEN
    ]
end

See Design Pattern: Working with Groups in Rules for further details.

from core.rules import rule
from core.triggers import when

@rule("something opened!")
@when("Member of gFritzBox changed to OPEN")
def opened(event):
    for i in filter(lambda i: i.state == OPEN, ir.getItem("gFritzBox").members):
        # do something

Check the group membership of an Item

    if(MyItem.getGroupNames.contains("MyGroup"){

Jython:

    if "MyGroup" in ir.getItem("MyItem").getGroupNames():

It is interesting the REST API has a list of thing-types but not item-types.

OP wasn’t asking for a list of Item Types. He was asking for a way to get a collection of all defined Items within a Rule. That isn’t possible in Rules DSL unless you create an All Group and methodically remember to add all of your Items to that Group.

The Item Types are fixed and are a part of the core so there really isn’t a need to have a REST API call to get that. Each binding can create their own Thing Type on-the-other-hand so having a REST API call for that makes sense.

@rlkoshak Thank you for that very interesting answer. I’ll definately look into that. You’re right, I was a programmer once :slight_smile:

Thank’s @Bruce_Osborne, too!!

1 Like

The easiest way to get the full list of methods available on any Object in Rules DSL is to use VSCode with the openHAB extension. Then you can type MyItem. and a dialog with all the valid completions will pop up.

Ah, yes, I tried that again tonight. At first it didn’t work (Same problem Reported in this issue here: https://github.com/eclipse/smarthome/issues/4831). But when opening the config folder from a mapped network drive instead of a UNC path, it worked!

Much better now :slight_smile:

Set gFritxBox to OPEN if any member of the Group is OPEN

Group:Contact:OR(OPEN, CLOSED) gFritzBox

Thanks, I think this is just what I needed. gFritzBox are a bunch of Contact Items using the TR064 Binding which does Presence Detection of MAC adresses of mobile devices connected to the WiFi network.

So i tried,

Group:Contact:OR(OPEN, CLOSED) gFritzBox

rule “Luke zu bei Regen”
when
Item Rain received update
then

logInfo("Luke zu", "Rule Triggered\n Rain: {}\n Luke: {}", Rain, Shutter_Bedroom)

if (Rain.state() > 0.06 && Shutter_Bedroom.state() > 0) {
    Shutter_Bedroom.sendCommand(0)
}

end

but get:

image

Probably just a Typo, but I don’t get the problem…you?

With this, I think I can solve my little use case pretty good with Rule DSL and without Jython, although it looks interesting, but time is limited :slight_smile:

Never mind. It’s actually the definition of the group and goes into fritzbox.items then!

1 Like