Improve documentation wrt to support for checking receivedCommand in Rule Builder

[jlaur]

I just uncovered a bug in one of my rules that I migrated from DSL to JavaScript some time ago.

The setup is something like this:

Item:

Switch TestTimer_Switch { expire="15m,command=OFF" }

The DSL rule:

rule "Test Timer DSL"
when
    Item TestTimer_Switch received command OFF
then
    logInfo("Test Timer", "Received command OFF")
end

And the part of a rule restarting the timer:

        items.TestTimer_Switch.postUpdate("OFF");
        items.TestTimer_Switch.sendCommand("ON");

Now, the rule having the bug which was driving me crazy:

rules.when()
    .item("TestTimer_Switch").receivedCommand("OFF")
    .then(event => {
        console.log("Received command OFF");
    })
    .build("Test Timer JS");

And the bugfixed version:

rules.when()
    .item("TestTimer_Switch").receivedCommand()
    .then(event => {
        if (event.receivedCommand == "OFF") {
            console.log("Received command OFF");
        }
    })
    .build("Test Timer Cmd JS");

The real rule has multiple triggers, so actually had to check the item as well:

        if (event.itemName == "OfficeTvSocketIdle" && event.receivedCommand != "OFF") {
            return;
        }

After reading the documentation, the mistake in my migration from DSL to JavaScript became obvious, but nevertheless, I'm wondering if it would make sense - and is feasible - to support providing the command in the Rule Builder Trigger? I.e. so that it would be possible to use .receivedCommand("OFF") (as an example).

Your Environment

• openHAB version used: 4.2.2
• openhab-js version used: 5.3.1

[florian-h05]

You can use .receivedCommand().toOn(), .receivedCommand().toOff() and .receivedCommand().to(command), though "received command to ..." sounds a bit awkward.

Seems like we need to improve the docs to make that more clear.

[jlaur]

You can use .receivedCommand().toOn(), .receivedCommand().toOff() and .receivedCommand().to(command), though "received command to ..." sounds a bit awkward.

Thanks, I totally missed that.

Seems like we need to improve the docs to make that more clear.

To be honest, if this is the list that should be made more clear, I still don't fully understand how to read it. I get it now that to(state), toOn() and toOff() can be used on both changed() and receivedCommand(). But they appear at the same level in this list, is that intentional? I guess item('foo').toOn().changed() doesn't make sense?

[florian-h05]

I think those docs need some enhancements, TBH I haven't worked much on them, they are from the time before I maintained this library.
Currently I guess the best way to learn what is possible is by looking at the IntelliSense powered by the type definitions.

[florian-h05]

Better with #411?

[jlaur]

Better with #411?

Yes, perfect! 👍 Thanks.