v4 Documentation Preview

# Blockly Reference

# Introduction

"Built on Blockly"

openHAB provides a visual programming editor based on Blockly (opens new window) 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 youtube Quick Intro to Blockly Rules (opens new window).

# Getting Started

Please visit Getting started with Blockly to learn the basics of using Blockly.

# Blockly YouTube Tutorials

Three YouTube tutorials have been made available via the openHAB YouTube channel (opens new window):

# Blockly Toolbox

The toolbox contains the building blocks of a Blockly program. The following categories are available in the toolbox:

blockly-toolbox-1blockly-toolbox-2blockly-toolbox-3

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.

# openHAB Specific Blocks

The following sections provide detailed descriptions of the openHAB-specific blocks and provide examples on how to use them.

Also view youtube Overview of the Blockly Sections (opens new window)

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 (opens new window).
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.

# Community Provided 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 (opens new window)

All published custom blocks can be found at Published Blockly Libraries (opens new window) and can be directly downloaded within your openHAB installation in the Settings -> Automation section

# Blockly is a Code Generator

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 showcode on the lower right corner of the Blockly editor.

Please watch the video youtube Blockly as an ECMA-Script code generator (opens new window) for a live demo.

# openHAB 3 to openHAB 4 Migration

# Background

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 (opens new window) 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 (opens new window) is already available in openHAB 3 when the JS Scripting Addon (opens new window) 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 (opens new window) 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.

# Running openHAB 3 Blockly rules without migrating them right away

  • 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 (opens new window) 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.

javascript-dialog

Choose the old version of JavaScript and then save the rule.

choose-javascript

  • 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).

# Tutorials and other useful information

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)