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?
- Apparently ony defined for Item Name
- 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> ]