Description for Channels within a .things file

Setup, Configuration and Use Beginners
1
  • Platform information:
    • Hardware: RPi4
    • OS: Raspbian with docker
    • Java Runtime Environment: OpenJDK 64-Bit Server VM (build 17.0.7+7-Debian-1deb11u1, mixed mode, sharing)
    • openHAB version: openhab/openhab:4.0.2-debian
  • Issue of the topic: Is there a way to add a description to Channels defined in .things file. In the PaperUI there is a field “Description” below the “Label”, but can’t find any documentation on how to fill in that field.

This is the current format i use for an MQTT channel, but there is only room for an Label and no description.

Type number : channel_id "Label" [ prop="value" ]

I tried the following without success:

Type number : channel_id "Label" "Description" [ prop="value" ]

Type number : channel_id "Label" @ "Description" [ prop="value" ]
  • Please post configurations (if applicable):
Bridge mqtt:broker:broker1 "MQTT Broker" @ "SomePlace"  [
    lwtQos=0,
    publickeypin="true",
    clientid="xxxxxxxxx",
    keepAlive=60,
    hostnameValidated="true",
    birthRetain="true",
    certificatepin="true",
    shutdownRetain="true",
    protocol="TCP",
    qos=0,
    reconnectTime=60000,
    mqttVersion="V3",
    host="localhost",
    port=1883,
    lwtRetain="true",
    enableDiscovery="false"
]

Thing mqtt:topic:ebusd "MQTT for ebus" (mqtt:broker:broker1) @ "BoilerRoom" [
    availabilityTopic="ebusd/global/signal",
    payloadAvailable="true",
    payloadNotAvailable="false"
] {
    Channels:

    Type number : ebusd_b7v_z1RoomTemp "ebusd/b7v/z1RoomTemp" [ description="The ground floor room temperature in degrees celcius." stateTopic="ebusd/b7v/z1RoomTemp", transformationPattern="JSONPATH:$.tempv.value", unit="°C", min=15, max=25, step=1]
}
  • If logs where generated please post these here using code fences:
2

Welcome! You have the right idea in the posted configuration file, but you’re missing a comma between the celcius." and stateTopic words in the actual definition.

By the way, when I need to figure out what identifier to use for a file-based configuration, I open a similar Thing in MainUI, and click on the Code tab - that shows me exactly what I need to use to set a specific config field.

3

Wow, thats a quick response. The use of the Code tab can help me very much in the future.

As for the description field, i corrected the missing comma, but still the description is not visible within the UI.

New thing code:

Thing mqtt:topic:ebusd "MQTT for ebus" (mqtt:broker:broker1) @ "BoilerRoom" [
    availabilityTopic="ebusd/global/signal",
    payloadAvailable="true",
    payloadNotAvailable="false"
] {
    Channels:

    Type number : ebusd_b7v_z1RoomTemp "ebusd/b7v/z1RoomTemp" [ description="The ground floor room temperature in degrees celcius.", stateTopic="ebusd/b7v/z1RoomTemp", transformationPattern="JSONPATH:$.tempv.value", unit="°C", min=15, max=25, step=1]
}

The configured description between the brackets does not fill the description field in the UI.

ebus_roomtemp
ebus_roomtemp738×646 33.9 KB

Result in code tab

UID: mqtt:topic:ebusd
label: MQTT for ebus
thingTypeUID: mqtt:topic
configuration:
  payloadNotAvailable: "false"
  availabilityTopic: ebusd/global/signal
  payloadAvailable: "true"
bridgeUID: mqtt:broker:broker1
location: BoilerRoom
channels:
  - id: ebusd_b7v_z1RoomTemp
    channelTypeUID: mqtt:number
    label: ebusd/b7v/z1RoomTemp
    description: null    <-- I want to have this description field filled
    configuration:
      retained: false
      postCommand: false
      unit: °C
      min: 15
      formatBeforePublish: "%s"
      max: 25
      step: 1
      stateTopic: ebusd/b7v/z1RoomTemp
      transformationPattern: JSONPATH:$.tempv.value

Since the description field is part of the base Channel (independent of the Channel type) i thought the description should come somewhere before the brackets, but the cannot find the right notation for it.

4

This is either not supported at all through .things files or it’s missing from the Things configuration docs. The @ is used to set the location, not the description (note that the location property of the Thing has limited utility.

If you do figure this out, at a minimum please file an issue so it can be added to the docs: How to file an Issue or, if it’s a simple change even you could contribute to the docs. There’s a link at the bottom of the page to a page that will walk you through the steps necessary to create a PR to suggest the change.

Unfortunately I’ve long since given up on file based configs because fighting with the syntax isn’t a problem through managed Things.

An interesting idea just occurred to me. It is possible to create rules in JSON format (same format you see when you query for a rule in the REST API). I wonder if Items and Things can be defined in JSON too.

5

I think i found the definition for the .things file in the source code (Thing.xtext) and it seems the description field is not present and therefore not supported.

ModelChannel:
	(((channelKind= ('State' | 'Trigger'))? type=ModelItemType) | 'Type' channelType=UID_SEGMENT) ':' id=CHANNEL_ID
    (label=STRING)?
	('['
		properties+=ModelProperty? (',' properties+=ModelProperty)*
	']')?
;

Having configuration files in JSON or YAML (like the code tab) would also work for me and would improve editor support by a lot, but since i’m not a Java developer its not something i can contribute.

6

I already know you can do rules in JSON files placed in the automation folder. But you can’t have newlines in JSON so the actual code part is pretty miserable to work with. But that wouldn’t be the case for Things and Items. If you can use .json files the same as rules maybe that would be an option.

There is the beginnings of work to support the same YAML that you see in the code tab in MainUI but it’s probably quite a ways away.

Personally, I got fed up with fighting syntax errors here on the forum and in my own setup. I made an exception to my rule by even replying here. I’ve found that any time saved by using a text editor is more than dwarfed by fighting missing commas here and a lowercase letter used where a capital is required there that I’ve abandoned their use and helping others use them. I want to solve home automation problems, not parse weird text files for a missing comma.