Current and Correct Documentation of Syntax for Things and Items Needed

Where is the current and correct documentation for the file-based definition of Things and Items located? Much of the documentation here and on the SmartThings site is self-contradictory as well as being contradicted by Eclipse SmartHome Designer 0.8.0 and causing failure of the runtime.

This is truly a blocker. You can’t reasonably use Paper UI to define a modest system of 20 dimmers, 10 keypads, and a bridge because:

  • There are over 100 entities that need to be defined, which would take hours with a one-by-one UI (Close to 300 if the presets were available in the binding)

  • There is no way to set the unique ID for auto-generated entities in a human-readable fashion, making automation rules completely unreadable

  • Paper UI instances do not appear in Eclipse SmartHome Designer, so can’t be used in rules

While I have scripts to emit Things and Items based on a simple textual list of physical devices, use, and location, the fact that both the Designer and the run-time code fail with the syntax documented means that this isn’t just a “steep learning curve” but a guessing game as well.

The syntax for .things files is defined as follows (parts in <…> are required):

Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]

and continues to provide, as an example

Thing network:device:webcam "Webcam" @ "Living Room" [ hostname="192.168.0.2", timeout="5000", ... ]

Designer immediately flags the @ here as an error

I have also confirmed that use of the @ notation, at least with the Lutron binding, causes incorrect parsing of the line containing it, and then the remainder of the file is silently “skipped” with no warnings in the logs.

https://eclipse.org/smarthome/documentation/features/dsl.html does not provide a syntax for Thing definition, but gives an example

Thing yahooweather:weather:losangeles "Los Angeles" @ "home" [ location=2442047, unit="us", refresh=120 ]

which also fails syntax checks in Designer.

Interestingly, the second line is not flagged as an error, suggestive of the same parsing problem that impacts the runtime parsing of the files.

Beyond how to properly specify a description and/or location is resolved, this definition is in conflict with bindings, including at least the Lutron binding

That page gives the Thing examples for dimmers and keypads as

lutron:dimmer:theater (lutron:ipbridge:radiora2) [ integrationId=8, fadeOutTime=2 ] lutron:occupancysensor:theater (lutron:ipbridge:radiora2) [ integrationId=9 ] lutron:keypad:theater (lutron:ipbridge:radiora2) [ integrationId=10 ]

which is clearly in conflict with the definition at http://docs.openhab.org/configuration/things.html (which does not allow parenthetical reference to another thing). It is further in conflict with https://eclipse.org/smarthome/documentation/features/dsl.html states that

The DSL also supports the definition of bridges and contained things. The following configuration shows the definition of a hue bridge with two hue lamps:

Thing 0210 bulb1 [ lightId="1" ]
Thing 0210 bulb2 [ lightId="2" ]

}```

Within the curly brackets things can be defined, that should be members of the bridge. For the contained thing only the thing type ID and thing ID must be defined (e.g. 0210 bulb1). So the syntax is Thing []. The resulting UID of the thing is hue:0210:mybridge:bulb1.Bridges that are defined somewhere else can also be referenced in the DSL:

Thing hue:0210:mybridge:bulb (hue:bridge:mybridge) [lightId="3"]

The referenced bridge is specified in the parentheses. Please notice that the UID of the thing also contains the bridge ID as third segment. For the contained notation of things the UID will be inherited and the bridge ID is automatically taken as part of the resulting thing UID.

This show a four-component reference (with no indication of what 0210 indicates or if bulb1 and bulb2 are “free” identifiers, or fixed parts of the definition of the bridge), that is inconsistent with the Lutron notation, as well as the syntax definition from the openHAB2 documentation.

That the Thing keyword is optional is missing from the OpenHAB versions of the documentation, as is the ability to define Channels along with an instance of a Thing.

Past this, there is even a basic level of syntactical information missing. Crucial details like

  • Permissible character set
    • Apparently ony defined for Item Name
      • “letters, numbers” in which character set? US ASCII? ISO Latin 1? UTF-8?
  • Limits on length
  • Which identifiers are in what namespace (to understand uniqueness constraints)

Until I can get Things working properly, I can’t comment on Items much, but the situation there isn’t much better. Right from the start, from http://docs.openhab.org/configuration/items.html

itemtype itemname ["labeltext"] [<iconname>] [(group1, group2, ...)] [["tag1", "tag2", ...]] [{bindingconfig}]

where the angle brackets in <iconname> are apparently part of the syntax, being completely inconsistent with the notation used immediately prior for Things,

The syntax for .things files is defined as follows (parts in <..> are required):

Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]

1 Like

From my limited experience here, I would start by saying that you should assume that the Designer will not be 100% correct. It often flags things which are actually syntactically correct and will run fine. Designer really lacks purpose for items, but shines with rules and being able to keep track of it all. At the least you should use designer for rule syntax checks, at the most you could use it to manage your sitemap too. Much more and I don’t know that it has much purpose. Certainly not for me.

Have a read here for some similar points you raise.

I would also add that if you find errors/inconsistencies in the documents then you should create a pull request for the doc on github and submit your changes. I wrote the initial items document for OH2, based on the OH1 docs, and experience I had from my own systems. You are more than welcome to add/edit this if you feel that it might need more clarification in any particular areas. I have been meaning to clear up some of the information around icons as I see a number of posts about this still appearing here…

I absolutely agree that there is still work to be done on the documents to make them clearer. With your/our/everyones input on ways to fix them then it’ll get done.

1 Like

The format for Things are defined in the README for the binding the Thing is being created for. For example, here is the format for the Astro binding:

http://docs.openhab.org/addons/bindings/astro/readme.html#full-example

Some 2.x bindings do not (yet?) define how to write your own Things with the zwave binding being the largest one I can think of.

Also, note that 1.x version bindings do not use Things at all.

The format for Items is documented here:

http://docs.openhab.org/concepts/items.html

They don’t appear but they can be used. Just because Designer marks it with the red underline doesn’t mean OH will have a problem with it. This is a known problem with Designer right now (see below).

Keep in mind that Designer is currently stalled in development I believe due to lack of people to work on it. The 0.9 version of it is completely broken and a fix hasn’t been implemented. So the 0.8 version is the latest stable version and there have been some minor syntax changes made to the languages for which Designer is unaware.

That isn’t the case here since it is failing to run. I just wanted to level set you on what to expect from Designer right now.

I’m personally not sure what the @ notation is for or how it is used. It appears both in the ESH and OH docs so I suppose it is supported. I’ve never seen it so can’t comment. If it does what I think it does then I don’t think it is required. I also beleive, based on your experience, the @ notation is not supported by every 2.x binding.

When in doubt, use the examples provided in the Binding’s page as your guide.

It is not in conflict. The Yahoo binding is a different binding from the Lutron binding so it has different fields and slightly different format.

Things are where the abstraction layers built into OH meet the complexities of the real world. Every binding will have slightly different Things formats by necessity.

The stuff in () is a reference to a Bridge, not another Thing. That is the expected syntax as defined on the ESH docs. Clearly, we need to update the Thing’s docs (I thought the OH Things docs were generated from the ESH ones, do we have a build failure somewhere @ThomDietrich?). If there is a conflict it is that the Things doc doesn’t also document Bridges.

https://eclipse.org/smarthome/documentation/features/dsl.html#defining-things

The first keyword defines whether the entry is a bridge or a thing.

As described in the text further up on the on the ESH site:

https://eclipse.org/smarthome/documentation/features/dsl.html#defining-things

The next statement defines the UID of the thing which contains of the following three segments: binding id, thing type id, thing id. So the first two segments must match to thing type supported by a binding (e.g. yahooweather:weatheryahooweather), whereas the thing id can be freely defined.

So that coupled with the text you already quoted about how to define a Bridge:

  • 0210 = Thing Type
  • bulb1 = Thing ID

It clearly states Thing ID “can be freely defined.”

As to the four component in the first part of the ID. I think it is clear that more documentation is needed for how Bridges work. The way I read that four element example is instead of defining all of your Things inside the Bridge as was done in the first example, you can define your Bridge and Things separately and essentially add the Things to the Bridge using the paranthetical notation. In this case, the 2010:mybridge is the Thing Type. If I’m correct in my interpretation (I’ve never used a Bridge so could be very wrong) it is unfortunate they used the “:” as it makes it look like you have an extra element.

I could be wrong and would love for someone who uses Hue or other Bridged configurations to comment.

The Thing word is not optional AFIK. When defining a Thing you must use the Thing keyword. When defining a Bridge you must use the Bridge keyword. Nowhere do I see it implied nor do I see examples that imples the keyword is optional.

I would recommend starting with the examples on the Binding’s doc page and customizing them from there as a way forward.

Thanks for the pointer to the enumeration of Item types and the enum types for commands.

Unfortunately, the Lutron binding page is not anywhere near as complete as the Astro binding! It’s author has said that the “general” descriptions should be used. This kind of incomplete and inconsistent documentation takes what might be the most elegant model and implementation and makes it incredibly difficult to use.

For a variety of reasons, configuration has to be done manually. These include the well over 100 Things and Items that need to be defined for the dimmers and keypads in a small home, naming needing to be done in a way that the Item names are meaningful (so auto-generation is not a possibility), and that non-trivial Rules have to be defined textually.

If the binding were properly documented, it would have been much easier. I would suggest that bindings not be accepted into “production” unless they have a full and complete definition. Even once you are able to muddle through with a skeletal example, you then find out, for example, that the Dimmable light channel does not respond to INCREASE and DECREASE commands. It’s not clear at all if the keypads’ channels can be linked to Contact items instead of Switch items, and what the impact would be. Why would I consider Contact? Because it is a momentary button, not a toggle on the keypad.

It would be helpful if you could point me to the textual parser for the file configuration so that I can try determine what is “correct” syntax. Since file-based Things and Items can’t be modified in the UI, at least with persistence, properties such as “label” and “tags” need to be defined in the file.

My understanding of the notation from http://docs.openhab.org/configuration/things.html

The syntax for .things files is defined as follows (parts in <..> are required):

Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]

is just as it states, to be able to set the label and location for the Thing. Looking at HABmin, it indicates that there is a “location” field available.

(Note that the label below was created as a last-ditch effort with “${label}@${location}” being echoed by my shell script, in the hopes that the openHAB parser would split the string on the @ character.)

Similarly, Paper UI offers a “location” field:

This Thing is recognized as created:

2017-03-13 12:06:16.714 [ThingAddedEvent           ] - Thing 'lutron:dimmer:ui-created-dimmer-id' has been added.
2017-03-13 12:06:16.746 [hingStatusInfoChangedEvent] - 'lutron:dimmer:ui-created-dimmer-id' changed from UNINITIALIZED to INITIALIZING
2017-03-13 12:06:16.753 [hingStatusInfoChangedEvent] - 'lutron:dimmer:ui-created-dimmer-id' changed from INITIALIZING to ONLINE

and appears in the json as

/var/lib/openhab2/jsondb $ cat org.eclipse.smarthome.core.thing.Thing.json 
{
  "lutron:dimmer:ui-created-dimmer-id": {
    "class": "org.eclipse.smarthome.core.thing.internal.ThingImpl",
    "value": {
      "label": "UI Created Dimmer Name",
      "bridgeUID": {
        "segments": [
          "lutron",
          "ipbridge",
          "SmartBridgePro"
        ]
      },
      "channels": [
        {
          "acceptedItemType": "Dimmer",
          "kind": "STATE",
          "uid": {
            "segments": [
              "lutron",
              "dimmer",
              "ui-created-dimmer-id",
              "lightlevel"
            ]
          },
          "channelTypeUID": {
            "segments": [
              "lutron",
              "lightDimmer"
            ]
          },
          "configuration": {
            "properties": {}
          },
          "properties": {},
          "defaultTags": []
        }
      ],
      "configuration": {
        "properties": {
          "integrationId": 99
        }
      },
      "properties": {},
      "uid": {
        "segments": [
          "lutron",
          "dimmer",
          "ui-created-dimmer-id"
        ]
      },
      "thingTypeUID": {
        "segments": [
          "lutron",
          "dimmer"
        ]
      },
      "location": "ui-created-dimmer-location"
    }
  }

Note that the data is reflected for all three fields:

  • Thing ID: (bare key)
  • Name: label
  • Location: location

Since it is reflected in the data model, how can it be set through file-based configuration?

1 Like

https://eclipse.org/smarthome/documentation/features/dsl.html#shortcut

Note that this is generic “Textual Configuration” on the eclipse smarthome site, not a binding-specific page.

I agree and some movement towards that has been made. But:

  • many of the 2.0 bindings were accepted and included into the baseline before there even were a framework for the docs
  • there is a limited amount of resources the community has to review and accept new/updates to bindings and I suspect reviewing the docs is one place that gets short changed.

Please do file an Issue on github in the openhab2-addons repository to improve the docs for this binding.

Note that a Contact is intended to be used for binary sensors. If it is something you are sending commands to a Switch is what should be used.

Unfortunately, some bindings are not consistent on this fact, using Switches where a Contact is more appropriate. But I know of no instance where a Contact is used where a Switch is most appropriate.

Yes, and your point?

That site presents two example Thing definitions and then goes on to explain each part in turn.

I assume you would rather no example is given?

It will be somewhere in the ESH repo but I don’t know where nor do I know who the grammar is defined.

But I would point out that the Label and Location are optional fields and frankly only useful when using the administration UIs. These are not available to the end user interfaces nor are they available to rules or persistence.

I do have a question. Since you are planning on automatically creating all your Things and Items why not populate the JSON DB directly and skip the .things and .items files?

I don’t really care how I populate the Things and Items. While a line of configuration is somewhat easier to spew out than JSON, neither is all that difficult. Single-line configuration is easier to see diffs in git or the like, but if it is all programmatically generated, then I can always look at the single-line source files that drive the scripts.

As for defining rules, an IDE at least gives completion of Item names, which can be very helpful in not only speed of authoring, but accuracy as well. Since I want to be able to read my rules and only the Thing ID appears in the rules, a lot of information “needs” to appear there, so they become things like “pico_Bedroom_Entry_on” or “group_front_of_house_only” – many chances for missing or mistyping characters.

An IDE, be it in a stand-alone application or “web-based”, also should provide only the “acceptable” alternatives for things such as object methods and signatures, as well as indicate type of return values and call parameters. I’m used to includes/imports being generated automatically with eclipse, IntelliJ, and others. This especially when the language in play isn’t a well-known language. I’m not trusting Designer too much at this point, but that is the expectation when a project says it is based on eclipse and eclipse frameworks.

Trying to get everything configured using file-based approaches was also based on your own approach and suggestions in Eclipse Designer -- Unable to "see" any PaperUI-created things/items

Things do not appear in Rules. Items do. Items get linked to Things and everything else in OH works with Items.

So your names need to be clear for your Items. The Thing’s IDs can be as obscure as can be because you never deal with the directly in Rules, persistence, UIs, etc.

And the syntax for Items is much older, much better documented, and frankly much simpler (unless you are working with 1.x bindings in which case all that complicated binding by binding differences exist between the { } for Item definitions.

Designer does do <ctrl>-<tab> completion and <ctrl><space> introspection for Rules and I think sitemaps too. And it is fully aware of the full Items syntax (which hasn’t changed since at least 1.6). Where it has some problems are newer features added to Things definitions, new features added to Rules (e.g. Channel triggers), references to third-party Actions, and Items defines in the UIs instead of .items files. It marks these things as errors.

You should almost never have to include anything unless you plan on using stuff from java.utils or lambdas. I think I have two imports across ALL of my Rules files. All of the important stuff is already included for you.

Designer’s support for Things is much newer and not as robust. I’m not entirely certain it has been updated since the label @ location notation was added.

Thanks for the pointers.

You’re right, my wording mistake on Items vs. Things in rules.

Yes, I’ve already run into situations where I’ve apparently needed to import from java.lang.Math (max showed up as an error in my very early attempts at rules, as well as finding out that the Item state is a “proprietary” BD) and expect that I’ll end up using lambda expressions and closures where I can.

Still haven’t found the code that parses the flat-file format, but still looking.

Go to the GitHub page for eclipse/smarthome and use the following search string:
filename:.xtext

That query will find all the Xtext syntax specifications for Items, Rules, Things, etc.

1 Like

Perfect, thanks!!!

[openhab2-master/git]$ find . -iname '*.xtext'
./smarthome/bundles/model/org.eclipse.smarthome.model.item/src/org/eclipse/smarthome/model/Items.xtext
./smarthome/bundles/model/org.eclipse.smarthome.model.persistence/src/org/eclipse/smarthome/model/persistence/Persistence.xtext
./smarthome/bundles/model/org.eclipse.smarthome.model.rule/src/org/eclipse/smarthome/model/rule/Rules.xtext
./smarthome/bundles/model/org.eclipse.smarthome.model.script/src/org/eclipse/smarthome/model/script/Script.xtext
./smarthome/bundles/model/org.eclipse.smarthome.model.sitemap/src/org/eclipse/smarthome/model/Sitemap.xtext
./smarthome/bundles/model/org.eclipse.smarthome.model.thing/src/org/eclipse/smarthome/model/thing/Thing.xtext

There it is…

ModelThing:
        ('Thing')? (id=UID | thingTypeId=UID_SEGMENT thingId=UID_SEGMENT)
        (label=STRING)?
        ('(' bridgeUID = UID ')')?
        ('@' location=STRING)?
        ('['
                properties+=ModelProperty? (',' properties+=ModelProperty)*
        ']')?
        ('{'
                ('Channels:')?
                channels+=ModelChannel*
        '}')?
;

the @ "location" has to occur after the (bridgeUID)

(as is that the string Thing is optional)

1 Like

Happy to help. This stuff is complicated and it takes a bit to get the concepts straight.

Access to static methods and members uses “::” (e.g. Math::max(myNumber)). Why is it different? Who knows. You don’t have to import Math or anything else from java.lang.

I don’t understand.

I recommend looking at the Design Pattern postings. Coding in the Rules DSL is particularly challenging for programmers. The Rules DSL has a lot of features built into it that can make for some very terse and simple logic. However, if you try to code it as if it were an OO or procedural language it will fight you every step of the way and you will hate life.

As an example, see this example written by a C++ coder and my response with a much simpler approach:

Alternatively, if you don’t mind waiting (how long I don’t know) for the JSR233 binding to be upgraded to work with OH 2 you can code your rules in Jython, JavaScript, or Groovy if that is more your speed (I happen to appreciate the Rules DSL despite its many flaws).

But some rules of thumb for success with the Rules DSL:

  • avoid trying to create data structures, use Items and Group membership instead
  • avoid using named lambdas, combine Rules and use Separation of Behaviors and Group processing instead
  • take advantage of the resources OH provides (e.g. use Persistence rather than keeping timestamps, use Groups and Associated Items instead of Maps

Obviously these are all rules of thumb, not strict dictates. But I do treat the creation of data structures (which is awkward in the Rules DSL to put it nicely) and excessive use of named lambdas as code smells. There needs to be a good justification for using them.

It may not be that obvious. My understanding is that the actual base is Xtext (or maybe Xbase) with a custom grammar. There may not be actual code that you will find, at least not code that you will find useful. You may only find the grammars that these third party libraries use to define the langauge. Look for .xtext or .xbase files.

@jeffsf we are constantly trying to improve the documentation. The Things article is in fact only available since 7 days and an enhanced version is planned. Would you please add all your findings and everything else you commented on in the related Issue Tracker ticket!? That would be very helpful and will bring about the improvement you are asking for.

I am new to openhab and I can confirm that Things documentation is very bad.
came here by google looking for answers where does lined bridge part comes in in extended syntax with name.
this article helpt.

also:

is it possilbe to refference bridge for multiple things like this:

(mqtt:systemBroker:embedded-mqtt-broker) {
Thing …
Thing …
Thing…
}

?

This is partially because Things were never really meant to be defined in .things files and the developer of the MQTT 2 binding in particular believes they shouldn’t.

But if you search the forum for MQTT 2.4 or 2.5 there are many examples posted here and there.

I can’t comment on the specific syntax but the answer is yes, of course.

I see there are a lot of people here in discussion but nobody changed documentation for 2 years. Who has write access? Much more energy is used here in the discussion then what is needed to improve documentation.
Generaly flow is ok, not much chenges are needed. Just sometimes some piece of syntax is used without any interduction. At least there should be a link to a point where that part is explained.

For example now I’m trying to understand rules. Flow of article is ok but in Script section documentation just starts using variable MyItem without any explanation how is is declared. How do I declare variable out of Thing? Nowhere to be found in an article.

I got it. It uses variables from items files.
Only that one line is needed in doc!

Anyone can propose a change to the docs (i.e. submit a PR). At the bottom of every documentation page there is a link that will take you straight to the page and you can propose a change without even leaving your browser.

It’s not declared, at least not in the .rules file. It’s an Item. Items are an important concept in OH and they have their own page. In fact there are two pages dedicated to Items, one in the Concepts section and another in the Configuration section.

The Rules article assumes that you have read and understood the Concepts section of the Docs which introduces what Items and Things are.

This line still indicates that you don’t really understand what an Item is. It’s not a variable, at least not in the traditional sense of what a variable is. And .items files is not the only way to define an Item.

1 Like