This page is part of archived documentation for openHAB 4.1. Go to the current stable version

# Before using blockly in openHAB

return to Blockly Reference

# Preface

Blocklies are an easy entry to the world of writing rules. However, after some times, you end up writing more and more complex rules, so more sooner than later you will encounter some challenges. This section intends to provide some hints to get started and how to deals with those challenges. Please read them carefully before asking questions in the forum.

# openHAB Configuration Files

Some openHAB blocks rely on particular configuration files found in the openHAB configuration folder. This folder is referred to as $OPENHAB_CONF in this page, and the location of this folder for your setup can be found via the UI: Help & About -> Technical Information -> Configuration folder.

  • via mounting the files shares from the server to your client-PC. In the main UI as an admin you can go to Help & About and will have the different folder locations under Technical information.
  • Use the share openHAB-conf when mounting it from Windows or MacOS

Link the openHAB share in Windows

  • Find you openHAB-Server via the network share functionality
  • User the share openHAB-conf to assign it to a network drive

Link the openHAB share in macOS

  • Finder -> Go -> Connect to Server

    • Enter the username and server name to connect to the openHAB Server

    macos-share-1

    • then choose the folder you want to mount

    macos-share-2

Finding it on Linux

  • Access the folder directly on the openHAB server at /etc/openhab

All methods reveal the following folders

  • html
  • icons
  • items
  • services
  • html
  • persistence
  • rules
  • scripts
  • sitemaps
  • sounds
  • things
  • transform

# Creating a blockly rule via the UI

Also view youtube Creating a Blockly Rule (opens new window)

  • go to Settings -> Rules
  • press plus on bottom right
  • enter a unique id and rule name for your new blockly rule
  • Under "When" click on "Add Trigger" to define a trigger for the rule (you may add multiple triggers which are perceived as any of those triggers may occurs which stands for an OR combination of the triggers)
    • choose a title for the rule
    • choose "item" (or something else) that should trigger the rule
    • select the item from your model and the click PICK on the upper right corner
    • choose "received a command", "was updated" or "changed"
  • Under "Then" click on "Add Action"
  • choose run-script-1
  • click on run-script-2 und you should now see this screen blockly-edit-screen
  • you can now click the toolbox-submenu to access all openHAB Blocks.
  • Drag and Drop the blocks to the white area
  • Press Ctrl-s (Windows) or Command-s (MacOS) to save your rule
  • Press Ctrl-r (Windows) or Command-r (MacOS) to directly run your rule with the trigger
  • Press Ctrl-d (Windows) or Command-d (MacOS) to disable / enable your rule. See the following video on youtube How to disable Rules (opens new window)
  • Click on showblock on the lower right of the bottom toolbar to see the generated code and will transition to showcode(click again to come back to the blocks).

More about the topic of code generation can be viewed at youtube Blockly as an ECMA-Script code generator (opens new window)

# Block context menu

It should also be mentioned that each of the blocks do have a context sensitive menu which appears upon a right click on the block itself.

blockly-context.png

# Cross-Rule-Copy/Paste

Sometimes you may want to copy some blocks from one rule to another. This is what Cross-Rule-Copy/Paste is for. Just mark the block(s) you want to copy, click on Cross-Rule-Copy and then in the destination rule open the context menu and click on Cross-Rule-Paste.

cross-rule-copy

Note that you cannot select several blocks at once but only one block to copy.

Copy multiple blocks

A way to copy multiple blocks at once is to copy a parent block, e.g. a loop block, that contains all the blocks you want to copy together. If you want to copy a number of connected blocks at once that do not have a parent block, there is nice trick to do that anyway: drag a function block into the workspace of the source rule, add the blocks to be copied into that function block, copy that function block and then paste it in the destination rule. Then in the destination rule just remove the function block that helped you to copy the inner blocks.

Copy and Paste in Action:

copy-and-paste-in-action

  • Duplicate: Clones the block
  • Add comment: Adds a comment to the block
  • Inline Inputs / External inputs: Switches between horizontal or vertical alignment of inputs

Inline: inline-inputs

External: external-inputs

  • Collapse (expand) block: Shrinks the block to get a better overview

Normal block view: expanded-block

Collapsed view:

collapsed-block

  • Disable (enable) block: Disables the block, so no code is generated and its functionality switched off
  • Delete: delete the blocks (this can be reverted via Command/Ctrl-Z)

# Searching the workspace

Sometimes blockly rules become pretty big, and it is hard to find particular blocks in the rule. Therefore, a search functionality has been provided by pressing Cmd/Ctrl-F which opens a small search window in the top right (just below the "save"-label). After pressing Enter all found blocks that contain the search term are marked in black.

blockly-search

# Zoom the workspace

The following controls allow the workspace to be zoomed:

workspace-zoom-controls

Pinching on a tablet or a touch bar also allows convenient zooming of the workspace.

# Use Frontail for viewing log files

During development the log-block is lot very often which writes information into the log files.

More on that topic can be viewed at youtube Logging (opens new window)

# Show an item status watch list besides the blockly rules

In the developer section there is the possibility to add a sidebar to the blockly rules development workspace that allows to watch live status of an item. View the chapter youtube Debugging Rules with openHAB Developer Tools to watch Item-Status (opens new window) for more information

# Return to Blockly Reference

return to Blockly Reference