Blockly Reference

openHAB Blockly Reference

openHAB specific Blockly language block reference

Blocks available as of version 3.2.0.M4 (release date: 7 Oct. 2021)
image of openHAB specific block catagories

GetItemState

Table of Contents

Introduction

One of the core feature that OpenHAB provides is writing rules to allow specific behaviour with the home automation system. The usual way of developing rules is by coding them like described in the Textual Rules section. However, this art programming may become intimidating early on and shy away away people with few or almost no experience in programming. Therefore openHAB also provides a graphical way of writing rules which allows to put together rules in a rather visual way (even though some programming background may still help).

The basic idea behind the visual paradigm and representation within openHAB is based on the Google Blockly Support which has been integrated and which provides the basic blocks for programming like

  • Logic-Blocks for comparison
  • Loop-Blocks for repeatable actions
  • Math-Blocks for calculations
  • Text-Blocks for Text/String manipulations
  • List-Blocks for iterating over and manipulation collections
  • Color-Blocks for easy handling of color settings
  • Variables to store / retrieve values
  • and functions to provide reusable block functionality

All of the above provide general functionality that is not specific to openHAB itself. If you want to learn more about how to use them, search for the many blockly tutorials that are available.
However, to leverage the full capabilities of the home automation specific blocks have been provided that are tailored for easy access of openHAB’s capabilities. The following will provide a detailed description of these specific blocks and provides examples on how to use them. Note that some of the blocks (like voice, streaming or notifications) need some specific setup within openHAB - in these case links to the respective documentation is given. It should also be mentioned that each of the blocks does have a context sensitive menu which appears upon a right click.

It is highly recommended to click on help which will then link you to the functionality which the block provides.

Getting Started

  • (todo) describe how to create a blockly rule
  • describe how to use logging via frontail (OH:9001)

Items and Things

Items and Things are the major entities of openHAB (see Concepts | openHAB) to control and monitor the home. These can be accessed with the blocks in the “Items & Things” section.

Overview of the Items and Things category

The most common task is to either retrieve the state (like ON/OFF or a temperature) from an item or change the value of the item. In some case access of the whole thing is even required. Therefore openHAB blockly provides two blocks that allow the access or the thing

image

Note that they always used in conjunction with another block as the block on its own would not have an effect. One example could be to retrieve the state of an item for a condition or to change the value of an item to switch on a light. For example to switch on the “Living Room Light” when the “Main Switch” is pressed then you could you the item-block like so

Item

Block image:

Item

Function: Retrieves a specific Item or Group for use in other item related functions

Notes:

  1. Clicking ‘MyItem’ displays a list of Items to pick from

Get Item

Block image:

GetItem

Function: Gets an Item for use in other item related functions

Notes:

  1. Clicking ‘MyItem’ displays a list of Items to pick from

Get Members of Group

Block image:

Getmember

Function: Gets the members of a group

Notes:

  1. A valid group must be used

Get State of Item

Block image:

GetItemState

Function: Get the current state of an Item or Group

Notes:

Get Name of Item

Block image:

GetItemName

Function: Get the current name, label, state, catagory, tags, groups, or type of an Item ItemOptions

Notes:

Send Command

Block image:

SendCommand

Function: Sends a command or posts an update to an Item or Group

Sendoptions

Notes:

  1. valid input is like Items eg. ON or OFF for a switch
  2. Clicking ‘MyItem’ displays a list of Items to pick from

Timers and Delays

image of Timers and Delays catagory

TimersAndDelays

Thread Sleep

Block image:

ThreadSleep

Function: Suspends execution of the rule for a given period of time

Notes:

  1. unit of time (ms) is milliseconds
  2. 1000 ms = 1 second
  3. a number may be directly entered into pink box

After period of time Do With Timer

Block image:

AfterTimeDoWithTimer

Function: Schedule a task to be performed at a specified period in the future

Notes:

  1. a number may be directly entered into gray box

Options for time

Time Options

After period of time Do With Timer With Reschedule

Block image:

AfterTimeDoWithTimerWithRetrigger

Function: Schedule a task to be performed at a specified period in the future with the ability to reschedule, cancel or ignore the timer in the event the timer is retriggered

Options for Reschedule

Reschedule Options

Notes:

  1. a number may be directly entered into gray box
  2. If reschedule is selected, the timer will restart if the timer is retriggered
  3. If cancel is selected, retriggering the timer will cancel it
  4. If do nothing is selected, retriggering the timer will be ignored

Cancel Timer

Block image:

CancelTimer

Function: Cancels a named timer

Notes:

Timer is Active

Block image:

TimerIsActive

Function: Determines if a named timer is active

Notes:

  1. For use in conditional

Timer is Running

Block image:

TimerIsRunning

Function: Determines if a named timer is running

Notes:

  1. For use in conditional

Voice and Multimedia

image of Voice and Multimedia catagory

VoiceandMultimedia

Play Audio

Block image:

PlayAudio

Function: Plays an audio file on an audio sink

Notes:

  1. audio file must reside in userfiles/openhab/sounds
  2. specify an available audio sink
image of default options:

PlayOptions

Play Audio with Volume

Block image:

PlayAudiowithVol

Function: Plays an audio file on an audio sink at a set volume

Notes:

  1. audio file must reside in userfiles/openhab/sounds
  2. specify an available audio sink

Play Stream

Block image:

PlayStream

Function: Starts an stream playing on an audio sink

Notes:

  1. specify an available audio sink

Stop Stream

Block image:

StopStream

Function: Stops a playing stream on the specified audio sink

Notes:

Say

Block image:

Say

Function: Provides text to speech

Notes:

Notifications

image of Notifications catagory

Notifications

Send Notification Email

Block image:

SendNotificationEmail

Function: Sends a notification to an email address

Notes:

  1. Provide valid email address

Send Notification to All Devices

Block image:

SendNotificationAllDevices

Function: Sends a notification to all devices

Notes:

SendNotificationOptions

Send Notification to Log Only

Block image:

SendNotificationtoLog

Function: Sends a notification to the log

Notes:

Value Storage

image of Value Storage catagory

Value Storage

Store Value

Block image:

StoreValue

Function: Stores a value in a keyed pair for use in the future

Notes:

  1. Provide a unique key name

Get Stored Value

Block image:

GetStoredValue

Function: Retrieves a stored value in a keyed pair

Notes:

  1. Provide previously named key

Logging and Output

image of Logging and Output catagory

Logging and Output

Log Statement

Block image:

GetItemState

Function: Sends a entry to the openHAB log file

Notes: Drop down list for log statement severity Levels:

  1. error
  2. warn
  3. info
  4. debug
  5. trace

LogLevel

11 Likes

reserved

1 Like

If you like I can make this a wiki so others can edit it. Though in practice few will and they will just post comments anyway.

Looks good so far!

Yes please Rich
I think at least Stefan will want to add stuff

Done.

1 Like

I definitely will engage :partying_face:

Thanks, @rlkoshak

1 Like

Can you share the URL to the wiki?

It is the first post here…

:rofl: I wasn’t aware that I can edit the post. Thanks #dummyme

As it was turned into a wiki post, you can :wink:

I started contributing and I wonder if the images should have an internal or external link, so we can later integrate this page into the official openhab documentation?

No idea …
@Confectrician ??

All the image links will need to be reworked no matter what you choose so I wouldn’t worry about it until it’s time to move them over to the docs. It would help though to save off the images somewhere with reasonable names because the images will need to be checked in along with the text as part of the PR. But the way the image tags work in the docs you’ll have to rework the links anyway so don’t worry too much about setting up something external for this post to host the images.

Ok, thanks for the info. Not really a good process unfortunately and not really temping to put many images in :wink: ( I will do anyway). Can we not push this page earlier to GitHub and then work on it there?

If you want you can create a WIP PR and work on it there.

However you’ll also have to run a separate service to build the pages so you can preview them as you write which involves a bit more work in the long run.

I’ve never tried to collaborate with more than one author on the same PR though so I don’t know how easy that is to do.

And you will pretty much cut off any chance of contributions or suggestions from the target audience. If they are coding in Blockly, they are almost certainly not going to be reviewing and contributing to a PR in progress on Github.

In my experience, the little bit of work at the end managing the images is less than the extra work required and some of the draw backs in terms of contributions and exposure to make it worth writing the first draft here on the forum and then moving them over.

I checked the Rules | openHAB in the repo which is at openhab-docs/rules-dsl.md at main · openhab/openhab-docs · GitHub and turns out to be a Markdown file, isn’t it? And it seems to have the picture referenced to the relative folder images. So it should be easy to clone the repo and write the md-file locally and see how it looks with an MD-Viewer. Does it come out quite differently after running the build or would that be worth trying?

Another question: Is there the possibility to have sub pages? I feel that the documentation will become quite comprehensive and long and would actually profit from being broken down in separate pages but I seems that openHAB Docs only has one level of page hierarchy, does it?

Yes but…

All the external references (such as for images or links to other pages) is not MD as far as I’m aware. There are some other small quirks that you probably won’t run into.

That never worked for me well enough to rely on it.

That’s a discussion for @Confectrician as the keeper of the overall structure of the docs for what is the best way. You can have subpages. Look at the UI Guide’s Component Reference page (which I believe is automatically built from the actual widgets and not from the MD files, but that would still work. Or you can have a sequence of pages similar to the Getting Started Tutorial which are all at the same level but grouped together on the left hand side.

I could see a single page with a generic “here is how to create a rule with Blockly” with a reference table that has links to a separate page, or parts of a separate page with the detailed info for that block.

As far as i know deeper hierarchies should be possible, but we only allow one level hierarchy in the sidebar navigation, so it does not get to overgrown.

2 Likes

So we could have a main page that would link down to the sub pages (which are not shown in the menu to the left), right?

Yes, this would be the current behavior.

We could for sure check, if we can define something different for blockly.
This should be a fair amount of research.
@ysc do you have something in mind about the navigation setting we configured in vuepress?

We can add a blockly section for testing purposes at any time.
Changes will only be available for the snapshot docs anyway until the next release of openHAB is published.
So we can’t destroy that much while testing things out. :slight_smile:

1 Like