This has now been merged into the main docs (should be available sometime in the next day or so after the next build). Thanks for all comments and edits! I’m closing this thread now.
rlkoshak
This Wiki topic’s goal is to serve as a working document, in order to provide an up-to-date tutorial for OH3 aimed at new users and novices. Everyone is welcome and encouraged to edit it, when we’re satisfied it will make its way to the official docs. You may reply for the specific purpose of improving the article are allowed, but please, this is NOT a support thread: if you’re stuck while reading this and are simply seeking support please open another thread. Thanks!
Note: this is more of a showcase than a tutorial, but I thought it would be a nice way to wrap up the tutorial with a real example of what you can achieve with openHAB and try to give some inspiration to the reader. It’s one of examples I come up with when I’m asked about what openHAB can do. Credit where it’s due, it’s only a version of Washing Machine State Machine updated for OH3!
Prerequisites:
- a regular washing machine without connected capabilities
- a connected wall plug that’s able to report the power consumption - in this example, we’ll use a Z-Wave FGWP102 Metered Wall Plug Switch
- a connected lightbulb - in this example, a Philips Hue one
Scenario: you want to “smarten” your washing machine and make it so that you’re notified when it has finished its cycle, for instance by flashing a light bulb in another room.
This is what your model could look like:
We have Equipment representing the washing machine, the wall plug it’s attached to (as a sub-Equipment), and a Measurement point for reporting the power consumption.
This item is linked to the channel of the metered wall plug so that it’s updated in real-time.
We first need to figure out when we can consider the washing machine is done, based on the evolution of that metric - openHAB’s UI Analyzer can help us do that.
Click on Analyze to open it and try to find a previous typical laundry cycle. Open the controls by clicking on the button in the bottom toolbar and change settings as needed, as well as the chart period with the controls on the top-right corner, until you get a good view like this:
What we can conclude from it, is that while the washing machine is running, the power consumption never gets under 2 W; when it finally does, that would mean that the cycle is finished. We therefore want to detect when the reported power changes from over 2 watts to below 2 watts and react to it.
Close the Analyzer, and take a note of the name of the item (here FGWP102WallPlug_Power).
Back to the Model, let’s examine the “Kitchen Table Light” equipment in the kitchen:
According to the documentation of the hue binding, the light bulb defines an “alert” channel, which will make the light bulb flash when we send certain commands (SELECT, LSELECT or NONE). we have therefore added a Point item and linked it to that channel. Pushing the default widget for it opens a list of command options provided by the binding; we can try selecting “Long Alert”: the light will flash for a couple of seconds - that’s what we want.
Let’s create a rule to make these 2 items work together. Click on Rules on the sidebar.
Create a new rule using the “+” button. Change the name and ID.
Save (with Ctrl-S on the Save button in the title bar), then open the Rule again.
We want to trigger the rule when the state of FGWP102WallPlug_Power changes: click on Add Trigger, select “when an item state changes” and pick the item.
Here, we cannot use the “Previous State” and “State” of the trigger because it requires exact states and we don’t actually know what they’ll be, so we have to make the rule run whenever the state changes and try to implement the logic somewhere else.
We’ll do it in a script action.Click Add Action and choose “execute a given script”.
You’re given the choice of the language you want to use for your script, ECMAScript (i.e. JavaScript) or the openHAB domain-specific language uses for rules (Rule DSL). Let’s choose ECMAScript.
Click on the Edit script button, this will open a code editor.
Type the following code:
var threshold = new QuantityType("2 W")
if (newState < threshold && oldState >= threshold) {
events.sendCommand('HueKitchen_Alert', 'LSELECT');
}
Here are some explanations:
- The trigger will define some variables for you:
oldStateandnewStateyou can use to get the previous and current states; - By checking the logs you noticed that since the item has a Unit of Measurement, the states will not actually be numbers but instead strings in the format
23.6 W. We therefore need to create a QuantityType using the same general units to perform the comparison. So we create a newthresholdvariable which is of typeW. - Once we have a value we can compare to the two states, we can send use the
events.sendCommandmethod made available to the script to send the LSELECT command to theHueKitchen_Alertitem - but only when the previous parsed state was >=2 and the current one is < 2.
Close the code editor, and save the rule. You should now see the lights flashing when the power drawn from the washing machine drops below 2 W from above that threshold!
Previous → Your first rule