Add documentation for the rule and action to get thing status. #463

kceiw · 2017-07-30T05:47:08Z

I enabled to listen to thing status in the rule and also add a new action to get thing status in the script, in this pull request: eclipse-archived/smarthome#3001
This pull request is to add the documentation.

ThomDietrich · 2017-07-31T09:22:57Z

Hey @kceiw, thanks for both additions.

Could you please break down your text to one sentence per line. Also please be aware, that Kramdown demands empty lines around block elements. You need to add empty lines on front of your example code fences.

@kaikreuzer could you also take a look?

ThomDietrich · 2017-07-31T09:26:48Z

addons/actions.md

@@ -95,6 +95,26 @@ The Timer object supports the following methods:
 * `hasTerminated`: returns true if the code has run and completed
 * `reschedule(AbstractInstant instant)`: reschedules the timer to execute at the new time. If the Timer has terminated this method does nothing.

+### Thing Status Action
+
+`getThingStatusInfo(String thingUid)`: Gets ThingStatusInfo of the given thing identified by thingUid and returns the result as ThingStatusInfo


Explaining getThingStatusInfo with "Gets ThingStatusInfo" doesn't do much good 😃 I caught myself looking at the example below to understand what this section is all about. Maybe you could condense this sentence and the following paragraph.

note that we usually write thingUID.

ThomDietrich · 2017-07-31T09:28:20Z

addons/actions.md

+} else {
+    logError("ThingStatus", "The thing isn't online.")
+}
+```


Nice comprehendible example. Did you want to say "isn't online" instead of "is offline"?

Yes. I intend to say "isn't online". It can be "offline" or "not in the system".

ThomDietrich · 2017-07-31T09:31:37Z

configuration/rules-dsl.md

+```
+
+The ThingUid is the identifier assigned by OpenHAB to the thing you add. You can find it from
+PaperUI. For example, one of my z-wave device is assigned "zwave:device:c5155aa4:node14".


*openHAB

You can find it from PaperUI.

This sentence is a bit vague. You can also get it by looking at the Karaf remote console.

one of my z-wave device is assigned

There is no "I" in documentation. 😜

ThomDietrich · 2017-07-31T09:32:56Z

configuration/rules-dsl.md

+PaperUI. For example, one of my z-wave device is assigned "zwave:device:c5155aa4:node14".
+
+> Note: You need to use quote around ThingUid. The parser will not recognize the whole text
+> correctly without quotes.


Why not simply show it in the syntax listing then?

Clarify it. It's not necessary if thingUID doesn't contain ':'.

But a thingUID always contains ':'...

It's true that a thingUID always contains ':' right now. I would rather view that as an implementation detail which is subject to change. So I changed the note in a way that it doesn't need to be changed even if thingUID schema is changed. I believe that hardly happens. It doesn't hurt to put such a note, I believe.

I can assure you that Thing UIDs will contain colons for at least the next 30 years ;-)

ThomDietrich · 2017-07-31T09:34:00Z

configuration/rules-dsl.md

+> correctly without quotes.
+
+The status used in the trigger and the script is a string (no quotes). You can find all the
+possible values from [Thing Status]({{base}}/concepts/things.html).


This reference should additionally be found in the first sentence of this section.

kaikreuzer · 2017-08-05T20:19:43Z

addons/actions.md

@@ -95,6 +95,26 @@ The Timer object supports the following methods:
 * `hasTerminated`: returns true if the code has run and completed
 * `reschedule(AbstractInstant instant)`: reschedules the timer to execute at the new time. If the Timer has terminated this method does nothing.

+### Thing Status Action
+
+`getThingStatusInfo(String thingUid)`: Gets ThingStatusInfo of the given thing identified by thingUid and returns the result as ThingStatusInfo


note that we usually write thingUID.

kaikreuzer · 2017-08-05T20:21:12Z

configuration/rules-dsl.md

+You can listen on status updates or on status changes (an update might leave the status unchanged).
+You can decide whether you want to catch only a specific status or any.
+Here is the syntax for all these cases (parts in square brackets are optional):
+```java


please add an empty line above the code section

kaikreuzer · 2017-08-05T20:22:39Z

configuration/rules-dsl.md

+You can decide whether you want to catch only a specific status or any.
+Here is the syntax for all these cases (parts in square brackets are optional):
+```java
+Thing <ThingUid> received update [<status>]


Change to thingUID, similar to above.

kaikreuzer · 2017-08-05T20:24:11Z

configuration/rules-dsl.md

+PaperUI. For example, one of my z-wave device is assigned "zwave:device:c5155aa4:node14".
+
+> Note: You need to use quote around ThingUid. The parser will not recognize the whole text
+> correctly without quotes.


kceiw · 2017-08-10T05:10:53Z

Thanks for the feedback. I'll improve my pull request.

kceiw · 2017-08-10T05:48:20Z

I update the pull request. Please review this again. Let me know if I still miss anything.
Thanks.

ThomDietrich · 2017-08-19T20:11:55Z

addons/actions.md

@@ -95,6 +95,29 @@ The Timer object supports the following methods:
 * `hasTerminated`: returns true if the code has run and completed
 * `reschedule(AbstractInstant instant)`: reschedules the timer to execute at the new time. If the Timer has terminated this method does nothing.

+### Thing Status Action
+
+`getThingStatusInfo(String thingUID)`: Gets status information of the given thing identified by thingUID


"thingUID."

ThomDietrich

Hey @kceiw, thanks for the improvements. Sorry for the slight delay ( 🌤 🏖 🏄 ), I got another set of comments for you :)

ThomDietrich · 2017-08-19T20:12:23Z

addons/actions.md

+
+`getThingStatusInfo(String thingUID)`: Gets status information of the given thing identified by thingUID
+
+The result is of type ThingStatusInfo.


I'd prefer the word in code fences or as a link as well.

ThomDietrich · 2017-08-19T20:13:05Z

addons/actions.md

+For example:
+
+```java
+var statusInfo = getThingStatusInfo("zwave:device:c5155aa4:node2")


In the example above you referred to this variable as as "thingStatusInfo".

ThomDietrich · 2017-08-19T20:15:04Z

configuration/rules-dsl.md

@@ -178,6 +179,27 @@ then
 end
 ```

+### Thing Triggers
+
+You can listen on status updates or on status changes (an update might leave the status unchanged).


"listen for" or "trigger on"

ThomDietrich · 2017-08-19T20:17:06Z

configuration/rules-dsl.md

+For example, one z-wave device can be "zwave:device:c5155aa4:node14".
+
+> Note: You need to use quote around thingUID if it contains special characters such as ':'.
+> The parser will not recognize the whole text correctly without quotes.


@kaikreuzer makes sense for things defined via config files, my things do not have : in their name and would naturally work without quotes.

ThomDietrich · 2017-08-19T20:20:43Z

configuration/rules-dsl.md

+And refer to [Thing Status Action]({{base}}/addons/actions.html) to find how to get thing status in the script.
+In the trigger, thingUID is the identifier assigned by openHAB to the thing you add.
+You can find it from PaperUI or from Karaf remote console.
+For example, one z-wave device can be "zwave:device:c5155aa4:node14".


The last three sentences are only interesting of the user had these things autodiscovered. Could you make them their own paragraph and begin with "The thingUID is the identifier assigned to the Thing, manually in your configuration or automatically during auto discovery...."?

kceiw · 2017-08-26T22:14:24Z

Thanks @ThomDietrich. I updated the pull request according to your new comments.

ThomDietrich · 2017-08-27T09:35:09Z

Wonderful. Thanks for the addition!

One last thing I've missed so far: You need to sign off your PR please: https://github.com/openhab/openhab-docs/blob/gh-pages/CONTRIBUTING.md#sign-your-work

ThomDietrich · 2017-08-30T12:06:30Z

Hey @kceiw, to clarify: Normally you need to sing-off every commit but as an exception it's acceptable to sign-off in the PR description. Please do so and we are ready to merge.

The change of the code is at eclipse-archived/smarthome#3001 After this commit, the end user can find the documentation about how to react to thing status change in the rule. Bug: openhab#517 Signed-off-by: Maoliang Huang <hellomao@outlook.com> Incorporate more pull request feedback.

kceiw · 2017-09-26T00:27:52Z

Hi @ThomDietrich
I've squashed my commits and addedthe sign-off to it.
At the same time, I created the issue #517 for this pull request and write it to the commit too.

ThomDietrich · 2017-09-26T10:06:48Z

Hey @kceiw I've resolved the conflict and we are ready to go. Thanks for your contribution!

ThomDietrich · 2017-09-26T10:13:26Z

GitHub tip: Next time write "Resolves #517" or "Closes #517" in our commit and Github will automatically do that upon merge ;)

ThomDietrich reviewed Jul 31, 2017

View reviewed changes

ThomDietrich requested changes Jul 31, 2017

View reviewed changes

kaikreuzer reviewed Aug 5, 2017

View reviewed changes

ThomDietrich reviewed Aug 19, 2017

View reviewed changes

ThomDietrich requested changes Aug 19, 2017

View reviewed changes

kceiw force-pushed the gh-pages branch from bcbcefd to 1ef45d5 Compare September 26, 2017 00:24

ThomDietrich approved these changes Sep 26, 2017

View reviewed changes

Merge branch 'gh-pages' into gh-pages

1415c48

ThomDietrich merged commit a080441 into openhab:gh-pages Sep 26, 2017

Confectrician added this to the 2.x.x milestone Nov 18, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for the rule and action to get thing status. #463

Add documentation for the rule and action to get thing status. #463

kceiw commented Jul 30, 2017

ThomDietrich commented Jul 31, 2017

ThomDietrich Jul 31, 2017 •

edited

kaikreuzer Aug 5, 2017

ThomDietrich Jul 31, 2017

kceiw Aug 10, 2017

ThomDietrich Jul 31, 2017

ThomDietrich Jul 31, 2017

kaikreuzer Aug 5, 2017

kceiw Aug 10, 2017

kaikreuzer Aug 10, 2017

kceiw Aug 11, 2017

kaikreuzer Aug 11, 2017

ThomDietrich Jul 31, 2017

kaikreuzer Aug 5, 2017

kaikreuzer Aug 5, 2017

kaikreuzer Aug 5, 2017

kaikreuzer Aug 5, 2017

kceiw commented Aug 10, 2017

kceiw commented Aug 10, 2017 •

edited

ThomDietrich Aug 19, 2017

ThomDietrich left a comment

ThomDietrich Aug 19, 2017

ThomDietrich Aug 19, 2017

ThomDietrich Aug 19, 2017

ThomDietrich Aug 19, 2017

ThomDietrich Aug 19, 2017

kceiw commented Aug 26, 2017 •

edited

ThomDietrich commented Aug 27, 2017 •

edited

ThomDietrich commented Aug 30, 2017

kceiw commented Sep 26, 2017

ThomDietrich commented Sep 26, 2017

ThomDietrich commented Sep 26, 2017


		`getThingStatusInfo(String thingUID)`: Gets status information of the given thing identified by thingUID

		The result is of type ThingStatusInfo.

Add documentation for the rule and action to get thing status. #463

Add documentation for the rule and action to get thing status. #463

Conversation

kceiw commented Jul 30, 2017

ThomDietrich commented Jul 31, 2017

ThomDietrich Jul 31, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kceiw commented Aug 10, 2017

kceiw commented Aug 10, 2017 • edited

Choose a reason for hiding this comment

ThomDietrich left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kceiw commented Aug 26, 2017 • edited

ThomDietrich commented Aug 27, 2017 • edited

ThomDietrich commented Aug 30, 2017

kceiw commented Sep 26, 2017

ThomDietrich commented Sep 26, 2017

ThomDietrich commented Sep 26, 2017

ThomDietrich Jul 31, 2017 •

edited

kceiw commented Aug 10, 2017 •

edited

kceiw commented Aug 26, 2017 •

edited

ThomDietrich commented Aug 27, 2017 •

edited