| layout | documentation |
|---|---|
| title | Rules Blockly |
[[toc]]
openHAB provides a visual programming editor based on Blockly by Google. It enables the creation of automation rules by dragging and dropping graphical blocks instead of writing textual code. It is ideal for those with little to no programming experience, yet powerful enough to perform most advanced automations with openHAB.
Check out the 
Quick Intro to Blockly Rules.
Please visit Getting started with Blockly to learn the basics of using Blockly.
Three YouTube tutorials have been made available via the openHAB YouTube channel:
- Episode 1
- Introduction
- Quick Intro Blockly Rules
- Debugging Rules with openHAB Developer Tools to watch Item-Status
- Creating a Blockly Rule
- Overview of the Blockly Sections
- Logging
- Working with Items
- Working with Text-Blocks
- Sending Commands
- Using Color-Blocks and HSB-Conversion
- Waiting in Rules
- Various Help Documentation available in openHAB Blockly
- Blockly as an ECMA-Script code generator
- Loops in Blockly
- Playing sounds on audio sinks
- Using Text-to-speach easily with blocks
- Streaming Music
- Episode 2
- Episode 3
- Datetimes and Cron-Triggers
- Copy-Of, Datetime-Now with Math-Operations
- Datetime - Temporal Units
- Date comparison
- Creating Datetimes and other datetime blocks
- Convert item states to Datetimes
- Send Notifications to the openHAB mobile app
- Using Ephemeris information
- Using Persistence data
- Wrap up and short overview on basic blocks
- Basic: Logic, Loops, Variables overview
- Basic: Math
- Basic: Text
- Basic: Lists, Colors
- openHAB Blocks Wrap up
- Global Value Storage
- Run & Process blocks, transform
- Inline Scripts
- Outro
The toolbox contains the building blocks of a Blockly program. The following categories are available in the toolbox:
These include general functionalities to perform various operations such as loops, comparison and text manipulation. Additionally, more than 50 special blocks are provided for performing openHAB related tasks.
The following sections provide detailed descriptions of the openHAB-specific blocks and provide examples on how to use them.
Also view Overview of the Blockly Sections
| Section | Description |
|---|---|
| Items & Things | Control and monitor the status of Items and Things in the smart home. |
| Timers & Delays | Execute something in the future. |
| Voice & Multimedia | Play audio and synthesize speech. |
| Units of Measurement | Operations with numeric quantity and unit conversions. |
| Dates & Times | Information, operations, and conversions of Date and Time. |
| Ephemeris | Calendar functionality to determine holidays. |
| Notifications | Send notifications using the openHAB cloud. |
| Persistence | Access historical data. |
| Value Storage | Variable storage that is kept after the rule has run, so it can be reused when the rule is run again later in stateful way. |
| Run & Process | Call other scripts, access rule context, and perform data transformations. |
| Logging | Write to the system logs for debugging purposes. |
| Extensions to Standard Blocks | Additions to complement the standard blocks. |
The core openHAB are meant to cover most of the functionality that is needed to write rules. However, there might be functionality that is not available (yet). These can be provided by the community.
A good explanation on how to write custom blocks can be found at How to write openHAB Blockly Libraries
All published custom blocks can be found at Published Blockly Libraries and can be directly downloaded within your openHAB installation in the Settings -> Automation section
Even though you may not notice it directly, the blocks are automatically converted into code that can run on the openHAB server. The generated code can be viewed when clicking the button 
on the lower right corner of the Blockly editor.
Please watch the video Blockly as an ECMA-Script code generator for a live demo.
Blockly generates JavaScript (ECMAScript) code, which exists in two different major implementations and versions:
- The older NashornJS, a.k.a. ECMAScript 5.1, released in 2011
- The newer GraalJS, currently supporting the ECMAScript 2022 version, released in 2022
The ECMAScript version that is used by Blockly in openHAB 3 is ECMAScript 5.1, a.k.a. Nashorn JS which was a part of Java until Java 14.
As openHAB 4 is based on Java 17, the old ECMAScript 5.1 is no longer available by default in the JVM and must be installed as a separate add-on. A replacement for the NashornJS is GraalJS ("the holy grail"), which is currently running ECMAScript 2022 and therefore supports all modern JavaScript features, like arrow functions. This is now the default JavaScript engine for Blockly in openHAB 4.
GraalJS is already available in openHAB 3 when the JS Scripting Addon is installed.
::: tip
Please convert your old rules as quickly as possible because only with GraalJS you can leverage the openHAB JavaScript library (openhab-js) in Blockly.
Using this library you can not only create much simpler code, it also allows new functionalities that are not available with NashornJS.
Note that some blocks are only available with the openhab-js library on GraalJS.
:::
From a technical perspective a rule internally holds a MIME-type that tells openHAB how the generated JavaScript language has to be interpreted.
The default MIME-type application/javascript in openHAB 3 runs the rule with NashornJS, while this same MIME-type will run the Blocky rule with GraalJS in openHAB 4.
As a result when running an unconverted openHAB 3 Blocky rule on openHAB 4, openHAB 4 will run a rule that was meant for NashornJS with GraalJS, and it will fail.
There is the choice to
- Convert each rule to GraalJS, or
- Keep them as NashornJS
Either way, some work on each rule needs to be done.
- Make sure the JS Scripting Addon is installed.
- Open each Blockly rule in openHAB 4 and save it - that's it!
- After all scripts of all rules have been converted to GraalJS, uninstall the
JavaScript Scripting (Nashorn)addon to save memory.
- If you still want to run the Blockly rules that were created in openHAB 3 for the time being without changing them (see above), you have to install the JavaScript Scripting (Nashorn) Addon which provides backwards compatibility until you have converted all rules.
- Open each Blockly rule or go to the Code TAB or Search for type: application/javascript;
- Replace it by
application/javascript;version=ECMAScript-5.1. Open the Blockly rule, find the following symbol and click on it.
Choose the old version of JavaScript and then save the rule.
- After the installation of the Addon, both the old rules created in openHAB 3 and the new rules created in openHAB 4 can run on openHAB 4 at the same time.
- Note that this allows you to mix rules that run with NashornJS and some that run with GraalJS (see above).