Initial blockly reference contribution (#1755)

* [blockly docs] initial main page and first sub page (wip)

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

* [blockly-docs] add timers and delays section

* [blockly-docs] add all missing sections

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

* [blockly-docs] refactor structure, return blocks

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

* [blockly-docs] fix styling

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

* [blocky-docs] fix styling - one line per sentence

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

* Test temporary linter disabling

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* [blockly-docs] final style: suppress MD036

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

Co-authored-by: Jerome Luckenbach <github@luckenba.ch>

.vuepress/docs-sidebar.js

@@ -68,6 +68,7 @@ module.exports = [
       'configuration/items',
       'configuration/persistence',
       'configuration/rules-dsl',
+      ['configuration/blockly/', 'Blockly Rules'],
       'configuration/transformations',
       'configuration/actions',
       'configuration/iconsets/classic/',

.vuepress/process_main_docs.rb

@@ -92,6 +92,16 @@ def process_main_docs(docs_source_dir)
     puts " -> images"
     #FileUtils.cp_r("#{docs_source_dir}/configuration/images", "docs/configuration") // no images placed yet
 
+    puts ">>> Migrating the Blockly Tutorial section"
+
+    Dir.glob("#{docs_source_dir}/configuration/blockly/*.md") { |path|
+        file = File.basename(path)
+        puts " -> #{file}"
+        process_file("#{docs_source_dir}/configuration/blockly", file, "docs/configuration/blockly", "#{$docs_repo_root}/configuration/blockly/#{file}")
+    }
+    puts " -> images"
+    #FileUtils.cp_r("#{docs_source_dir}/configuration/images", "docs/configuration") // no images placed yet
+
     puts ">>> Migrating the UI section"
 
 

configuration/blockly/index.md

@@ -0,0 +1,160 @@
+---
+layout: documentation
+title: Rules Blockly
+---
+<!-- markdownlint-disable MD036 -->
+
+# Blockly Reference
+
+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]({{base}}/configuration/rules-dsl.html).
+However, this art of 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).
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-introduction}
+
+## Introduction
+
+The basic idea behind the visual paradigm and representation within openHAB is based on the [Google Blockly Support](https://developers.google.com/blockly) which has been integrated and which provides the basic blocks for programming like the ones on the left and the right side of the below images
+
+{: #blockly-toolbox}
+*Blockly toolbox*
+
+![blockly-toolbox-1](../images/blockly/blockly-toolbox-1.png)![blockly-toolbox-2](../images/blockly/blockly-toolbox-2.png)![blockly-toolbox-3](../images/blockly/blockly-toolbox-3.png)
+
+All of these 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 more than *50 specific blocks* have been provided that are tailored for easy access of openHAB's capabilities.
+
+This section provides a detailed description of the specific blocks and provides examples on how to use them. Note that some of the blocks (like voice, streaming or notifications) need some special setup within openHAB  - in these case links to the respective documentation is provided.
+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.
+
+**Block context menu**
+
+![blockly-context.png](../images/blockly/blockly-contextmenu.png)
+
+**Looking for help**
+
+A special mention should go towards the **Help** entry that links to a resource that is usually very helpful to understand the context of that particular block.
+Please read this information first before asking questions in the forum. *In case you ask for help please always post the respective code that is being generated.*
+
+## Before using blockly
+
+Please visit [Getting started with openHAB Blocklies](rules-blockly-before-using.html) before asking questions in the forum
+
+## Blocks
+
+### Items and Things
+
+*Items* and *Things* are the [major entities of openHAB](https://www.openhab.org/docs/concepts/) to control and monitor the home.
+
+[![Items and Things](../images/blockly/blockly-items-and-things-small.png "Items and Things")
+](rules-blockly-items-things.html)
+
+See [Items & Things](rules-blockly-items-things.html) section
+
+### Timers and Delays
+
+Timers and Delays are a little more complex but add important functionality to rules. Whilst the “Wait-For”-block is straightforward, the timer blocks should be well understood before being used - they may behave differently than expected.
+This chapter explains what these blocks do, sometimes displaying generated code to explain what is happening behind the scenes.
+
+[![Timers and Delays](../images/blockly/blockly-timers-and-delays-small.png "Items and Things")
+](rules-blockly-timers-and-delays.html)
+
+See [Timers and Delays](rules-blockly-timers-and-delays.html) section.
+
+### Date Handling
+
+Date blocks are used as input parameters for other blocks.
+At the moment some of these blocks are found in the ephemeris section, whilst others are found in the persistence section - they may be equally useful for both. These blocks are *typed* to assure correct connection to other blocks.
+
+[![Timers and Delays](../images/blockly/blockly-date-handling-ephemeris-small.png "Ephemeris Dates")
+](rules-blockly-date-handling.html) [![Timers and Delays](../images/blockly/blockly-date-handling-persistence-small.png "Persistence Dates")
+](rules-blockly-date-handling.html)
+
+See [Date Handling](rules-blockly-date-handling.html) section.
+
+### Ephemeris
+
+The ephemeris category provides blocks with calendar functionality. The blocks can be used to determine what type of day today is, or a number of days before or after today is.
+For example, a way to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc.
+
+[![Ephemeris](../images/blockly/blockly-ephemeris-small.png "Ephemeris")
+](rules-blockly-ephemeris.html)
+
+See [Ephemeris](rules-blockly-ephemeris.html) section.
+
+### Voice and Multimedia
+
+This section deals with *playing or streaming audio* to an audio sink e.g a speaker or *saying a text* via using any Text-to-Speech API (e.g. Google's API)
+
+[![Voice and Multimedia](../images/blockly/blockly-voice-and-multimedia-small.png "Voice and Multimedia")
+](rules-blockly-voice-and-multimedia.html)
+
+See [Voice and Multimedia](rules-blockly-voice-and-multimedia.html) section.
+
+### Notifications
+
+For use with your [openHAB cloud](https://www.openhab.org/addons/integrations/openhabcloud/) account, these blocks can be used to send notifications to relevant connected devices.
+Notifications can be used as push message to devices running the openHAB client.
+
+[![Notifications](../images/blockly/blockly-notifications-small.png "Notifications")
+](rules-blockly-notifications.html)
+
+See [Notifications](rules-blockly-notifications.html) section.
+
+### Persistence
+
+Persistence blocks enable access of historical data stored by the default persistence service.
+
+[![Persistence](../images/blockly/blockly-persistence-small.png "Persistence")
+](rules-blockly-persistence.html)
+
+See [Persistence](rules-blockly-persistence.html) section.
+
+### Value Storage
+
+These blocks enable storing information *for a rule* that is kept after the rule has run, so it can be reused when the rule is run again later in stateful way.
+
+[![Value Storage](../images/blockly/blockly-value-storage-small.png "Value Storage")
+](rules-blockly-value-storage.html)
+
+See [Value Storage](rules-blockly-value-storage.html) section.
+
+### Run & Process (Rules and Scripts)
+
+This section allows calling rules or other scripts, retrieving attributes provided by the rule context or transforming values via different conversion methods (e.g. map, regex, jsonpath)
+
+[![Run & Process](../images/blockly/blockly-value-storage-small.png "Value Storage")
+](rules-blockly-run-and-process.html)
+
+See [Run and Process](rules-blockly-run-and-process.html) section.
+
+### Logging
+
+This section allows calling rules or other scripts, retrieving attributes provided by the rule context or transforming values via different conversion methods (e.g. map, regex, jsonpath)
+
+[![Logging](../images/blockly/blockly-value-storage-small.png "Logging")
+](rules-blockly-logging.html)
+
+See [Logging](rules-blockly-logging.html) section.
+
+### openHAB Extensions to the Standard
+
+This section explains only the blocks that have been added to the standard blocks by openHAB
+
+[![openHAB Extensions to the standard](../images/blockly/blockly-colors-overview-small.png "openHAB Extensions to the Standard")
+](rules-blockly-standard-ext.html)[![openHAB Extensions to the standard](../images/blockly/blockly-lists-dictionary-overview-small.png "openHAB Extensions to the Standard")
+](rules-blockly-standard-ext.html)
+
+See [openHAB Extensions to the standard](rules-blockly-standard-ext.html) section.
+
+## Tutorials or other useful information
+
+- [Getting Started: Rules - Blockly](https://community.openhab.org/t/getting-started-rules-blockly/132453)
+- [How to write openHAB Blockly Libraries](https://community.openhab.org/t/tutorial-how-to-write-block-libraries/130074)
+- [Extending Blockly with new openHAB commands](https://community.openhab.org/t/extending-blockly-with-new-openhab-commands/127169)
+- [Published Blockly Libraries](https://community.openhab.org/c/marketplace/block-libraries/76)

configuration/blockly/rules-blockly-before-using.md

@@ -0,0 +1,101 @@
+---
+layout: documentation
+title: Rules Blockly - Before Using
+---
+<!-- markdownlint-disable MD036 -->
+
+# Before using blockly in openHAB
+
+[return to Blockly Reference](index.html#before-using-blockly)
+
+## 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.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-before-uding}
+
+## **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*.
+  - the exact configuration of the shares can be found on your server at [/etc/samba/smb.conf](https://github.com/openhab/openhabian/blob/main/includes/smb.conf).
+- 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.png](../images/blockly/blockly-openhab-macos-share-1.png)
+  - then choose the folder you want to mount
+
+  ![macos-share-2](../images/blockly/blockly-openhab-macos-share-2.png)
+
+**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
+
+- go to Settings -> Rules
+- press ![plus](../images/blockly/blockly-plus-small.png) 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](../images/blockly/blockly-run-script.png)
+- click on ![run-script-2](../images/blockly/blockly-run-script-2.png) und you should now see this screen
+  ![blockly-edit-screen](../images/blockly/blockly-edit-screen.png)
+- you can now click the ![toolbox-submenu](../images/blockly/blockly-arrow.png) 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
+- Click on ![showcode](../images/blockly/blockly-showcode.png) on the lower right to see the generated code (click again to come back to the blocks)
+
+## Use Frontail for viewing log files
+
+During development the log-block is lot very often which writes information into the log files.
+
+- To be able to conveniently view your log files it is recommended to setup *frontail* which can be achieved easily via [openhabian-config](https://www.openhab.org/docs/installation/openhabian.html#optional-components)
+- Start `openhabian-config` on your server and choose option 20 and then option 21
+- After installation you can view your logs under [openhabian-config](http://myopenhab-server:9001) (adapt the server name)
+- **see [how to log](https://www.openhab.org/docs/administration/logging.html)**
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#before-using-blockly)

configuration/blockly/rules-blockly-date-handling.md

@@ -0,0 +1,105 @@
+---
+layout: documentation
+title: Rules Blockly - Date Handling
+---
+<!-- markdownlint-disable MD036 -->
+
+# Date Handling
+
+[return to Blockly Reference](index.html#date-handling)
+
+## Introduction
+
+Date blocks are used as input parameters for other blocks.
+At the moment some of these blocks are found in the ephemeris section, whilst others are found in the persistence section - they may be equally useful for both.
+These blocks are *typed* to assure correct connection to other blocks.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-date-handling-overview}
+
+## Overview of the Date Handling blocks
+
+**Blocks in the ephemeris section**
+
+![ephemeris-dates](../images/blockly/blockly-date-handling-ephemeris.png)
+
+**Blocks in the persistence section**
+
+![persistence-dates](../images/blockly/blockly-date-handling-persistence.png)
+
+## Date Handling Blocks
+
+### today
+
+![today](../images/blockly/blockly-date-today.png)
+
+Type: *DayOffset*
+
+Ephemeris blocks expect a date formatted as the number of days since today.
+As a result, this block returns 0.
+
+### today +/- x days
+
+![now-plus-minus-offset](../images/blockly/blockly-date-plus.png)
+
+Type: *DayOffset*
+
+Returns the number of days since today, as configured in the number block.
+The number can be positive (offset into the future) or negative (offset into the past).
+
+### date-picker
+
+![date-picker](../images/blockly/blockly-date-picker.png)
+
+Type: *ZonedDateTime*
+
+Returns a date as *ZonedDateTime*.
+The date can be selected from a date picker.
+The time is set to `00:00:00`.
+
+### Get date
+
+![get-date](../images/blockly/blockly-date-get.png)
+
+Type: *ZonedDateTime*
+
+From a String in the format `yyyy-MM-dd`, this block will return the date as *ZonedDateTime*. The input String  may be a variable-block.
+The time will be `00:00:00`.
+
+### Get Date now with offset
+
+![now-with-offset](../images/blockly/blockly-get-now-offset.png)
+
+Type: *ZonedDateTime*
+
+Returns a date as *ZonedDateTime* with offset relative to the current date *and* time.
+
+### Get String representation of date
+
+![date-tostring](../images/blockly/blockly-get-date-string.png)
+
+Type: *String*
+
+Returns the String representation of a given *ZonedDateTime*-block, with or without the time.
+
+### Example
+
+Assuming this block is run at `20:47:36` on `31/01/2022`
+
+![date-text-example](../images/blockly/blockly-date-text-example.png)
+
+The output in the log will be.
+
+```text
+2022-01-31
+2022-01-31 00:00:00
+2022-01-31 20:47:36
+```
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#date-handling)

configuration/blockly/rules-blockly-ephemeris.md

@@ -0,0 +1,67 @@
+---
+layout: documentation
+title: Rules Blockly - Ephemeris
+---
+<!-- markdownlint-disable MD036 -->
+
+# Ephemeris
+
+[return to Blockly Reference](index.html#ephemeris)
+
+## Introduction
+
+The ephemeris category provides blocks with calendar functionality.
+The blocks can be used to determine what type of day today is, or a number of days before or after today is.
+For example, a way to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc.
+
+Definition of holidays can be customised through the *ephemeris.cfg* file.
+See the [Ephemeris configuration page](https://www.openhab.org/docs/configuration/actions.html#configuration) for more information.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-ephemeris-overview}
+
+## Overview of the Ephemeris blocks
+
+![ephemeris-dates](../images/blockly/blockly-ephemeris.png)
+
+## Ephemeris Blocks
+
+### Holiday, weekend or weekday check
+
+![ephemeris-is](../images/blockly/blockly-ephemeris-is.png)
+
+*Function:* this block checks if the given date is a holiday, weekday or weekend.
+
+Type: *boolean* `true` or `false`
+
+**Examples**
+
+![ephemeris-is-example](../images/blockly/blockly-ephemeris-is-example.png)
+
+### Get the holiday name for a particular date
+
+![ephemeris-get-name](../images/blockly/blockly-ephemeris-get-name.png)
+
+*Function:* Returns the holiday name for the given date.
+Will return `null` if no holiday is found for the date.
+
+Type: *String*
+
+### Get the number of days until a specific holiday
+
+![ephemeris-days-until](../images/blockly/blockly-ephemeris-days-until.png)
+
+Function: Return the number of days until the given holiday name, or `-1` if the holiday is not found.
+
+Type: number
+
+Some holidays are already provided by default from openHAB.
+Additional holidays must be configured in *ephemeris.cfg*.
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#ephemeris)

configuration/blockly/rules-blockly-items-things.md

@@ -0,0 +1,199 @@
+---
+layout: documentation
+title: Rules Blockly - Items & Things
+---
+<!-- markdownlint-disable MD036 -->
+
+[return to Blockly Reference](index.html#items-and-things)
+
+*Items* and *Things* are the [major entities of openHAB](https://www.openhab.org/docs/concepts/) to control and monitor the home.
+These can be accessed via the "Items & Things" section of the [Blockly Toolbox]({{base}}/configuration/index.html#blockly-toolbox).
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-items-and-things-overview}
+
+## Overview of the Items and Things category
+
+> ![items-and-things](../images/blockly/blockly-items-and-things.png)
+
+### Item and Thing Blocks
+
+Most of the time you will want to get and set the state of an *item* - set a switch to ON, or get a temperature.
+Sometimes you may want to access the *thing* directly.
+Both are possible using the item-block and thing-block
+
+> ![blockly-item-thing](../images/blockly/blockly-item-thing.png)
+
+However, these blocks are not useful by themselves - they are always used together with another block.
+The example below uses the *get state of item* block to retrieve the *MainSwitch* *item* state, before checking if that is equal to ON within a standard comparison block
+
+![blockly-item-example](../images/blockly/blockly-item-example.png)
+
+## Items
+
+### Item
+
+![blockly-item](../images/blockly/blockly-item.png)
+
+Function: Retrieves a specific **Item** or **Group** for use in other item related functions.
+
+- Clicking 'MyItem' displays a list of **Items** to pick from
+- Technically this block returns the *name* of the item as a String.
+- As a result, this block can be used wherever the item name is required as a String.
+- Learn more about items [here](https://www.openhab.org/docs/configuration/items.html)
+
+### Get Item
+
+![getItem](../images/blockly/blockly-getItem.png)
+
+Function: Gets an **Item** for use in other item related functions
+
+- Clicking 'MyItem' displays a list of **Items** to pick from.
+- Technically this block returns an item *object*, to be used to retrieve specific attributes using other blocks (see below).
+- As this block does not return a String it cannot be directly attached to a log-block, as demonstrated below.
+
+![blockly-getItemStateDoesntFit](../images/blockly/blockly-getItemStateDoesntFit.png)
+
+### Get State of Item
+
+![blockly-getStateOfItem](../images/blockly/blockly-getStateOfItem.png)
+
+Function: Get the current state of an **Item** or **Group**
+
+- Should return the state of an item as a String like ON/OFF, the temperature value etc.
+
+Note: currently a String is not always returned.
+[See this thread](https://community.openhab.org/t/blockly-cannot-split-text-string-from-string-item/130819) for reference and potential workaround.
+
+### Get Members of Group
+
+![blockly-getMembers](../images/blockly/blockly-getMembers.png)
+
+Function: Gets the members of a **group**
+
+- returns a collection of items which should be used with a for-each-block to loop over the items
+- it can be attached to a log-block which would list all items in that block in the form a string representation as follows
+
+```json
+GF_IndirectLights (Type=GroupItem, BaseType=SwitchItem, Members=9, State=OFF, Label=Indirekten Lichter, Category=light, Tags=[Lightbulb], Groups=[Lights]),LichterOG (Type=GroupItem, BaseType=SwitchItem, Members=4, State=ON, Label=Lichter OG, Category=light, Groups=[Lights]),LichterEG (Type=GroupItem, BaseType=SwitchItem, Members=5, State=ON, Label=Lichter EG, Category=light, Groups=[Lights])
+```
+
+- Alternatively you can use the item block var the loop variable to send a command to the items of the group
+
+The following example depicts the above possibilities:
+
+![blockly-getMembersExample](../images/blockly/blockly-getMembersExample.png)
+
+### Get particular attributes of an item
+
+![blockly-getItemAttributes](../images/blockly/blockly-getItemAttributes.png)
+
+Function: Get either the current name, label, state, category, tags, groups, or type of an item as a String
+
+These attributes are returned with the following types:
+
+- name: String
+- label: String
+- state: State
+- category: String
+- tag: Array, e.g.
+
+```json
+[plannedTimes]
+```
+
+- groups: Array, e.g.
+
+```json
+[plannedTimes, timers]
+```
+
+- type: String
+
+Depending on your openHAB version (pre-3.3) this block may not connect as expected.
+As a workaround attach the block to a variable first, and use the variable in the rest of the script.
+
+![blockly-getItemAttributes-fix](../images/blockly/blockly-getItemAttributes-fix.png)
+
+**Special handling for Arrays**
+
+The attributes *groups* and *tags* return an Array of entries.
+Therefore
+
+- they *cannot* be connected to a block that expects a String (e.g. log-block)
+- they *must* be handled using a for-loop as follows
+
+![blockly-specialArrayHandling](../images/blockly/blockly-specialArrayHandling.png)
+
+### Send Command
+
+![blockly-sendCommand](../images/blockly/blockly-sendCommand.png)
+
+Function: Sends a command or posts an update to an **Item** or **Group**.
+
+- value: any state value that is allowed for that item, eg. ON or OFF for a switch.
+- Clicking 'MyItem' displays a list of **Items** to pick one item from
+
+For the difference between *send command* and *post update* two check ["Manipulating States"](https://www.openhab.org/docs/configuration/rules-dsl.html#manipulating-item-states).
+
+**Item-block examples**
+
+**Example 1:**
+
+- Check if *MainSwitch* is ON.
+- If ON, send ON command to *livingroomLight* item.
+
+![blockly-sendCommandExample1](../images/blockly/blockly-sendCommandExample1.png)
+
+**Example 2:**
+
+- Get the state of *MainSwitch* and
+- Immediately send it as a command to *F2_Office_Main_Light*
+
+![blockly-sendCommandExample2)](../images/blockly/blockly-sendCommandExample2.png)
+Ensure that the receiving item can handle the state of the 'sending' item.
+
+## Things
+
+### Thing
+
+![blockly-thing](../images/blockly/blockly-thing.png)
+
+Function: Retrieves a specific **Thing** for use in other thing related functions.
+
+- Clicking 'MyThing' displays a list of **Things** to pick from
+- Technically this block returns the thingUid of the thing as a String
+- Learn more about things [here](https://www.openhab.org/docs/configuration/things.html)
+
+**Example**
+
+![blockly-thingExample](../images/blockly/blockly-thingExample.png)
+
+will write the following into the log
+
+```text
+thing name = nanoleaf:controller:645E3A484A83
+```
+
+### Get Thing Status
+
+![blockly-getThingStatus](../images/blockly/blockly-getThingStatus.png)
+Function: Gets a **Thing Status** for use in other Thing related functions
+
+- Clicking 'MyThing' displays a list of **Things** to pick from.
+- Technically this block returns a [ThingStatus](https://www.openhab.org/docs/concepts/things.html#thing-status)  - a String with one of the following statuses
+  - UNINITIALIZED
+  - INITIALIZING
+  - UNKNOWN
+  - ONLINE
+  - OFFLINE
+  - REMOVING
+  - REMOVED
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#items-and-things)

configuration/blockly/rules-blockly-logging.md

@@ -0,0 +1,50 @@
+---
+layout: documentation
+title: Rules Blockly - Logging
+---
+<!-- markdownlint-disable MD036 -->
+
+# Logging
+
+[return to Blockly Reference](index.html#logging)
+
+## Introduction
+
+This section explains only the blocks that have been added to the standard blocks by openHAB
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-logging-overview}
+
+## Logging and Output
+
+These blocks enable arbitrary content to be published to the [openHAB log](https://www.openhab.org/docs/administration/logging.html).
+
+![logging-overview](../images/blockly/blockly-logging-overview.png)
+
+### Log Statement
+
+![log-statement](../images/blockly/blockly-logging-log.png)
+
+*Function:* Sends an entry to the openHAB log file with a defined severity level.
+
+- A [severity level](https://www.openhab.org/docs/administration/logging.html#defining-what-to-log) can be provided via the dropdown list for the log statement
+
+  - error
+  - warn
+  - info
+  - debug
+  - trace
+
+### Print Statement
+
+![print-to-stdout](../images/blockly/blockly-logging-print.png)
+
+*Function:* creates a print statement with the given text in the rule that logs to *stdout*
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#logging)

configuration/blockly/rules-blockly-notifications.md

@@ -0,0 +1,67 @@
+---
+layout: documentation
+title: Rules Blockly - Notifications
+---
+<!-- markdownlint-disable MD036 -->
+
+# Notifications
+
+[return to Blockly Reference](index.html#notifications)
+
+## Introduction
+
+For use with your [openHAB cloud](https://www.openhab.org/addons/integrations/openhabcloud/) account, these blocks can be used to send notifications to relevant connected devices.
+Notifications can be used as push message to devices running the openHAB client.
+
+General information on cloud notification actions can be found [here](https://www.openhab.org/docs/configuration/actions.html#cloud-notification-actions).
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-notifications-overview}
+
+## Overview of the Notification blocks
+
+![notifications](../images/blockly/blockly-notifications.png)
+
+## Notification Blocks
+
+### Send Notification to specific cloud email user
+
+![notification-to-user](../images/blockly/blockly-notification-to-user.png)
+
+*Function:* Sends a notification to the openHAB mobile app via openHAB cloud to a specific user signed up under the given email address
+
+- **This block does not use the mail binding**, and it is not possible to send a notification to a user who does not have an openHAB cloud account.
+- Notification will only work if devices have the openHAB mobile app installed (either iOS or Android)
+
+### Send Notification to All Devices and users
+
+*Function:* Sends a notification to all devices and all users to the openHAB mobile app.
+
+![notification-to-all](../images/blockly/blockly-notification-to-all.png)
+
+Example Push Message shown under Android:
+
+![notification-on-android](../images/blockly/blockly-notification-on-android.png)
+
+- A message can be provided together with an icon that should be shown on the device.
+Use the [icon names of the openHAB iconset](https://www.openhab.org/docs/configuration/iconsets/classic/).
+- The notification can also be viewed at <https://myopenhab.org/notifications>
+
+### Send Notification to Log Only
+
+![notification-to-log](../images/blockly/blockly-notification-to-log.png)
+
+*Function:* Sends a notification to myopenhab.org only
+
+- This notification is *only* sent to the openHAB cloud log (for example at <https://myopenhab.org/notifications>), **not the local openHAB log**.
+- Notifications are not sent to users' devices.
+- For the time being neither the log level nor the icon is shown in the log of the cloud
+- The notification is not logged on the openhab server
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#notifications)

configuration/blockly/rules-blockly-persistence.md

@@ -0,0 +1,70 @@
+---
+layout: documentation
+title: Rules Blockly - Persistence
+---
+<!-- markdownlint-disable MD036 -->
+
+# Persistence
+
+[return to Blockly Reference](index.html#persistence)
+
+## Introduction
+
+Persistence blocks enable access to and manipulation of historical data stored by the default persistence service.
+For more information on persistence, the default service, and its configuration see the [persistence documentation](https://www.openhab.org/docs/configuration/persistence.html).
+
+The date-blocks shown in this section are described previously in [Date handling blocks](https://community.openhab.org/t/blockly-reference/128785#date-handling-blocks-31).
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-persistence-overview}
+
+## Overview of the Persistence blocks
+
+![persistence](../images/blockly/blockly-persistence.png)
+
+## Persistence Blocks
+
+Persistence blocks enable access of historical data stored by the default persistence service.
+For more information on persistence, the default service, and its configuration see the [persistence documentation](https://www.openhab.org/docs/configuration/persistence.html).
+
+The date-blocks shown in this section are described previously in [Date handling blocks](https://community.openhab.org/t/blockly-reference/128785#date-handling-blocks-31).
+
+### Get statistical value of an item
+
+![statistical-value](../images/blockly/blockly-persistence-get-statistical-value.png)
+
+*Function:* computes any of the below functions for the given item since the time provided by *ZonedDateTime*-Block
+
+- average: gets the average value of the State of a persisted Item since a certain point in time.
+This method uses a time-weighted average calculation
+- delta: gets the difference in value of the State of a given Item since a certain point in time
+- deviation: gets the standard deviation of the state of the given Item since a certain point in time
+- variance: gets the variance of the state of the given item since a certain point in time
+- evolution rate: gets the evolution rate of the state of the given Item in percent since a certain point in time (may be positive or negative)
+- minimum: gets the minimum value of the State of the given Item since a certain point in time
+- maximum: gets the maximum value of the State of the given Item since a certain point in time
+- maximum: gets the sum of the State of the given Item since a certain point in time
+
+Note:  in case no or 0 values are retrieved, make sure that the item in question is actually persisted.
+
+### Check item change / update since a point in time
+
+![item-change](../images/blockly/blockly-persistence-get-item-change.png)
+
+*Function:* checks if an item was updated or changed since a certain point in time
+Type: boolean `true` or `false`
+
+### Provide last updated date of an Item
+
+![item-updated-date](../images/blockly/blockly-persistence-updated-date.png)
+
+*Function:* Provides the last updated date (including time) of an Item
+Type: ZonedDateTime
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#persistence)

configuration/blockly/rules-blockly-run-and-process.md

@@ -0,0 +1,173 @@
+---
+layout: documentation
+title: Rules Blockly - Run & Process
+---
+<!-- markdownlint-disable MD036 -->
+
+# Run & Process (Rules and Scripts)
+
+[return to Blockly Reference](index.html#run-process-rules-and-scripts)
+
+## Introduction
+
+This section contains several possibilities
+
+- Calling Rules or other scripts either located as files on the server or provided via the UI
+- Retrieving attributes provided by the rule context or from the own caller rule.
+- Transforming values via different conversion methods (map, regex, jsonpath)
+
+**A note about Rules and Scripts**
+
+A Script *is* a Rule too. It’s just a special type of rule that only has a single script action and a “Script” tag.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-value-storage-overview}
+
+## Overview of the Run & Process blocks
+
+![run-and-process-blocks](../images/blockly/blockly-run-and-process.png)
+
+## Run & Process Blocks
+
+### Call Script File
+
+![run-script-file](../images/blockly/blockly-run-script.png)
+
+*Function:* Calls a script file with the given name which must be located in the *$OPENHAB_CONF/scripts/* folder.
+
+- No parameters can be provided
+
+### Run Rule or Script created in UI
+
+![run-rule-or-script](../images/blockly/blockly-run-rule.png)
+
+*Function:* calls another *rule* or *script* that was created via the openHAB UI.
+
+The  *ruleUID* can be found in the list of rules or scripts in the second line of the list (like here *helloBlockly* or *helloWorld*)
+![rule-uuid](../images/blockly/blockly-run-rule-uuid.png)
+
+Parameters are optional:
+
+- If not providing parameters leave the *with context* section as is.
+- If providing parameters you **must** replace the *create empty dictionary* block with [the *dictionary* block from the Lists section](https://community.openhab.org/t/blockly-reference/128785#lists-76), modifying the number of key/value pairs to suit.
+
+Notes:
+
+- parameters can be retrieved in the called script via the "get context attribute"-block (see below)
+- the called rule / script cannot return any value
+- it is not possible to access a particular function in another script or rule as scripts / rules have to be perceived as completely autonomous
+- the called rule / script is run synchronously
+
+### Retrieve context attribute from rule
+
+Function: Retrieve context attributes passed by a calling rule/script (see above)
+
+![retrieve-context](../images/blockly/blockly-retrieve-context.png)
+
+This retrieves the value for the key "myKey1" that was passed by the calling rule.
+
+*Example*
+
+![retrieve-context-example](../images/blockly/blockly-retrieve-context-example.png)
+
+### Retrieve rule context information
+
+![retrieve-context-info](../images/blockly/blockly-retrieve-rule-context-info.png)
+
+*Function:* Retrieve event context related information of the rule
+
+A rule carries contextual information when triggered - this block can retrieve that information.
+
+- The rule trigger type defines which of the attributes are available to the rule - they will not all be available.
+- For more detailed information see [Event Object Attributes](https://openhab-scripters.github.io/openhab-helper-libraries/Guides/Event%20Object%20Attributes.html)
+
+## Transform values via Map, Regex or JsonPath and others
+
+OpenHAB provides many [transformations](https://www.openhab.org/docs/configuration/transformations.html):
+
+- [Map](https://www.openhab.org/addons/transformations/map/)
+- [Regex](https://www.openhab.org/addons/transformations/regex/)
+- [JsonPath](https://www.openhab.org/addons/transformations/jsonpath/)
+- [Binary to Json](https://www.openhab.org/addons/transformations/bin2json/)
+- [Exec](https://www.openhab.org/addons/transformations/exec/)
+- [JavaScript](https://www.openhab.org/addons/transformations/javascript/)
+- [Jinja](https://www.openhab.org/addons/transformations/jinja/)
+- [Scale](https://www.openhab.org/addons/transformations/scale/)
+- [XPath](https://www.openhab.org/addons/transformations/xpath/)
+- [XSLT](https://www.openhab.org/addons/transformations/xslt/)
+
+The following describes examples for Map, Regex, and JsonPath
+
+![map](../images/blockly/blockly-transform-map.png)
+![regex](../images/blockly/blockly-transform-regex.png)
+![jsonpath](../images/blockly/blockly-transform-jsonpath.png)
+
+Function: Transform the given value via one of the different transformation methods
+
+### Example 1: Regex
+
+Convert  #123456 into rgb(12,34,56)
+
+![transform-regex](../images/blockly/blockly-transform-example1.png)
+
+### Example 2: JsonPath transformation
+
+Extract the temperature from the following JSON
+
+```json
+{ "device": { "location": "Outside", "status": { "temperature": 23.2 }}}
+```
+
+by using the jsonpath
+
+```json
+$.device.status.temperature
+```
+
+![transform-jsonpath](../images/blockly/blockly-transform-example2.png)
+
+### Example 3: Map transformation
+
+This example applies a map transformation from the map file nanoleaf.map in *$OPENHAB-CONF/transform/*
+
+![transform-map](../images/blockly/blockly-transform-example3.png)
+
+The above, with the below map file
+
+```text
+ON=Ja
+OFF=Nein
+effects=Effekte
+-=?
+NULL=n/a
+hs = Hue/Saturation
+ct = Color Temperature
+```
+
+would result in the following log entry
+
+```bash
+Hue/Saturation
+```
+
+## Inline Script
+
+![inline-script](../images/blockly/blockly-inline-script.png)
+
+*Function:* execute arbitrary ECMAScript content
+
+Provides the possibility to inject any ECMAScript at a given position.
+This should be used in cases when Blockly does not provide the desired functionality.
+Use with diligence.
+
+### Example:
+
+![inline-script-example](../images/blockly/blockly-inline-script-example.png)
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#run-process-rules-and-scripts)

configuration/blockly/rules-blockly-standard-ext.md

@@ -0,0 +1,112 @@
+---
+layout: documentation
+title: Rules Blockly - openHAB Extensions to the Standard
+---
+<!-- markdownlint-disable MD036 -->
+
+# openHAB Extensions to the Standard
+
+[return to Blockly Reference](index.html#openhab-extensions-to-the-standard)
+
+## Introduction
+
+This section explains only the blocks that have been added to the standard blocks by openHAB
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-standard-extension-overview}
+
+## Colors
+
+The Colors section simplifies the selection of  Color Values.
+Technically these color RGB values are provided as a hexadecimal combination of the three values for red, green and blue (hence RGB).
+Each of the individual colors can range from 0 - 255 or 0-FF (hexadecimal).
+A color of r=255, g=255, b=255 would therefore result into #ffffff preceded by a # which identifies it as a hexadecimal number.
+
+![colors-overview](../images/blockly/blockly-colors-overview.png)
+
+Note that typically RGB values are not used within openHAB for color states but instead the Color-Type expects a HSB Type.
+See the special hsb-conversion block below.
+
+### Color Picker
+
+![color-picker](../images/blockly/blockly-colors-picker.png)
+
+*Function:* Lets the user pick from a (limited) set of colors and returns a the hexadecimal number (in the above case the value = #33cc00.
+
+### Random Color
+
+![get-random-color](../images/blockly/blockly-colors-random.png)
+
+*Function:* Returns a random color as a hexcode
+
+### Create RGB color
+
+![create-rgb-color](../images/blockly/blockly-color-create-rgb.png)
+
+*Function:* Returns a color by mixing the given values in a range from 0 - 255 for reg, green and blue as a hexcode
+
+### Blend two colors
+
+![blend-two-colors](../images/blockly/blockly-colors-blend.png)
+
+*Function:* Blends two colors chosen via a color picker into one color by the given ratio.
+
+Tip: this could be used for example with a loop that changes the ratio from 0 to 1 to blend the first color into a second
+
+### Create HSB-color from RGB color (openHAB)
+
+![get-hsb-of](../images/blockly/blockly-colors-hsbof.png)
+
+HSB stands for hue-saturation-brightness which is a different way of describing a color.
+An RGB color can therefore be converted equally into an HSB-color.
+
+*Function:* This a special openHAB block that converts a hexadecimal color code from one of the above blocks into a String that is required when sending a color command to any item that accepts a color.
+
+- use that block and connect one of the above blocks into that one to be able to retrieve the HSB value of that block.
+
+HSB stands for hue-saturation-brightness which is a different way of describing a color.
+An RGB color can therefore be converted equally into an HSB-color.
+
+*Function:* This a special openHAB block that converts a hexadecimal color code from one of the above blocks into a String that is required when sending a color command to any item that accepts a color.
+
+- use that block and connect one of the above blocks into that one to be able to retrieve the HSB value of that block.
+
+**Example:**
+
+![get-hsb-of-example](../images/blockly/blockly-colors-hsbof-example.png)
+
+## Lists
+
+![lists-overview](../images/blockly/blockly-lists-dictionary-overview.png)
+
+### Dictionary for managing key / value pairs
+
+The dictionary is a holder for key value pairs that can be passed along as one.
+Add or remove new key value pairs by clicking on the cog icon to open the popup of the dictionary block (finally click on the cog again to close the popup).
+Then drag the key block on the upper left into the key/value bracket on the right like depicted below:
+
+![dictionary](../images/blockly/blockly-lists-dictionary.png)
+
+Rename the keys as required and then add any value block type to the related key:
+
+Example:
+
+![dictionary-example](../images/blockly/blockly-lists-dictionary-example.png)
+
+### get value of key from dictionary
+
+![dictionary-getkey](../images/blockly/blockly-lists-dictionary-getkey.png)
+
+*Function:* Retrieves the value of the key in the given directory
+
+Example:
+
+![dictionary-getkey-example](../images/blockly/blockly-lists-dictionary-getkey-example.png)
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#openhab-extensions-to-the-standard)

configuration/blockly/rules-blockly-timers-and-delays.md

@@ -0,0 +1,272 @@
+---
+layout: documentation
+title: Rules Blockly - Timers & Delays
+---
+<!-- markdownlint-disable MD036 -->
+
+# Timers & Delays
+
+[return to Blockly Reference](index.html#timers-and-delays)
+
+Timers and Delays are a little more complex but add important functionality to rules. Whilst the "Wait-For"-block is straightforward, the timer blocks should be well understood before being used - they may behave differently than expected. This chapter explains what these blocks do, sometimes displaying generated code to explain what is happening behind the scenes.
+
+- TOC
+{:toc}
+
+{: #blockly-timers-and-delays-overview}
+
+## Overview of the Timers and Delays category
+
+> ![timers-and-delays](../images/blockly/blockly-timers-and-delays-1.png) ![timers-and-delays.png](../images/blockly/blockly-timers-and-delays-2.png)
+
+## Timer Naming
+
+Timers are created and referred to by name, enabling manipulation within a rule.
+
+> **Important**: a named timer is *only* available within the same rule. The same timer *cannot* be accessed via a different rule. A different rule with a timer of the same name results into two separate timers.
+
+### Wait for
+
+![waitfor](../images/blockly/blockly-waitfor.png)
+
+*Function:* Suspends execution of the rule for a given period of time
+
+- unit of time (ms) is milliseconds (1000 ms = 1 second)
+
+*Example*
+
+The following simple example uses a loop to implement a blinking light with a 1 second delay, looping three times:
+
+![waifor-example](../images/blockly/blockly-waitfor-example.png)
+
+### After *period of time* Do With Timer
+
+![blockly-afterperiodtimer](../images/blockly/blockly-afterperiod-timer.png)
+
+*Function:* Schedule a task to be performed once after a specific amount of time has elapsed.
+
+- A number and unit (seconds, minutes up to months) can be chosen after which the commands within the block will be executed
+- Provide the name of the timer, allowing further access to that timer within the same rule. The name also ensures the timer is unique within the rule.
+
+*Example*
+
+10 seconds after the rule has been called, the timer triggers all lights to go off:
+
+![afterperiodtimer-example](../images/blockly/blockly-afterperiod-timer-example.png)
+
+### Reschedule Timer
+
+*Function:*  Sometimes one may want to use the same timer and reschedule the same block of code again. This can be achieved with the reschedule-block
+
+![reschedule-timer](../images/blockly/blockly-reschedule-timer.png)
+
+An example is as follows:
+
+- The code within the timer-block will run after 5 seconds.
+- The last part in the block reschedules the same timer-block for 5 seconds later.
+- And so on, in an endless loop.
+
+![reschedule-timer-example1](../images/blockly/blockly-reschedule-timer-example1.png)
+
+Setting up an endless timer in teh above way is not recommended. The example shown below will stop rescheduling after 3 doorbell rings.
+
+![reschedule-timer-example2](../images/blockly/blockly-reschedule-timer-example2.png)
+
+### After *period of time* Do With Timer with options on retriggering rule
+
+![afterperiod-timer-options](../images/blockly/blockly-afterperiod-timer-options.png)
+
+*Function:* Schedule a task to be performed at a specified period in the future with the ability to reschedule, cancel or ignore the timer **when the rule is retriggered**.
+
+Before using that block, it is important to understand what the idea behind the option of retriggering:
+Though it may not seem to be obvious, the same rule can be retriggered at any time. To allow more control about what is happening in this case the rule is executed again, the following options are available:
+
+**Options on Retrigger**
+
+- *reschedule*: If the same rule that contains this Blockly script is re-triggered, and this specific timer is currently active, this specific timer will be rescheduled (i.e. restart the countdown timer).
+- *cancel*: If the same rule that contains this Blockly script is re-triggered, and this specific timer is currently active, this specific timer will be cancelled. The code within the timer will not be executed.
+- *do nothing*: If the same rule that contains this Blockly script is re-triggered, nothing happens - this will make the block identical to the simple timer-block in function, but the generated code is slightly modified - see below.
+
+![afterperiod-timer-options-block](../images/blockly/blockly-afterperiod-timer-options-block.png)
+
+**Generated code**
+
+The following code example and the following are provided to understand what exactly happens behind the scenes:
+
+```javascript
+if (typeof this.timers['MyTimer'] === 'undefined' || this.timers['MyTimer'].hasTerminated()) {
+  this.timers['MyTimer'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
+    })
+} else {
+  this.timers['MyTimer'].reschedule(zdt.now().plusSeconds(10));
+}
+```
+
+**Simple timer-block**
+
+The simple timer-block generates the code shown underneath the image below.
+
+![simple-timer](../images/blockly/blockly-simple-timer.png)
+
+```javascript
+if (typeof this.timers['simpleTimerBlock'] === 'undefined' || this.timers['simpleTimerBlock'].hasTerminated()) {
+  this.timers['simpleTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
+    })
+}
+```
+
+**Retrigger timer-block**
+
+The retrigger timer-block inserts an additional `else{}` branch into the generated code which will run if:
+
+- The rule is retriggered and
+- the timer already exists and
+- the timer has not yet finished (it's still ticking)
+
+In the case of *do nothing* the `else{}` branch is empty (which turns to be almost equals to the simle-timer).
+
+```javascript
+if (typeof this.timers['nothingTimerBlock'] === 'undefined' || this.timers['nothingTimerBlock'].hasTerminated()) {
+  this.timers['nothingTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
+    })
+} else {
+  // do nothing
+}
+```
+
+In the case of *cancel* the `else{}` branch contains code to cancel the timer.
+
+```javascript
+if (typeof this.timers['cancelTimerBlock'] === 'undefined' || this.timers['cancelTimerBlock'].hasTerminated()) {
+  this.timers['cancelTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
+    })
+} else {
+  this.timers['cancelTimerBlock'].cancel();
+  this.timers['cancelTimerBlock'] = undefined;
+}
+```
+
+In the case of *reschedule* the `else{}` statement contains code to reschedule the timer - restart the countdown. In the example generated code below:
+
+- Imagine the rule is triggered at 0 elapsed seconds.
+- The timer is started with a 10 second countdown.
+- Lets say the rule is triggered again at 5 elapsed seconds.
+- Then timer will be rescheduled for another 10 second countdown, so will execute the code within its block at 15 elapsed seconds.
+
+```javascript
+if (typeof this.timers['rescheduleTimerBlock'] === 'undefined' || this.timers['rescheduleTimerBlock'].hasTerminated()) {
+  this.timers['rescheduleTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
+    logger.info('I am doing my job');
+    })
+} else {
+  this.timers['rescheduleTimerBlock'].reschedule(zdt.now().plusSeconds(10));
+}
+```
+
+### Cancel Timer
+
+![cancel-timer.png](../images/blockly/blockly-cancel-timer.png)
+*Function*: Cancels the existing named timer, preventing code within the timer block from executing.
+
+### Timer is Active
+
+![timer-is-active](../images/blockly/blockly-timer-is-active.png)
+
+*Function:* returns `true` if the timer itself is currently counting down, and the code within the timer will be eventually executed as scheduled. This block will return `false` if the timer doesn't exist, has been cancelled, or has already finished.
+
+### Timer is Running
+
+![timer-is-running](../images/blockly/blockly-timer-is-running.png)
+*Function*: returns `true` if the code *within the timer block* is currently running - i.e. the countdown has finished, and the code within the timer block is currently executing. This event will usually only last a few milliseconds, and you’d be (un)lucky to catch it when your rule retriggers.
+
+### Timer has terminated
+
+![timer-terminated](../images/blockly/blockly-timer-terminated.png)
+*Function*: returns `true` if the timer has finished its countdown, and the code within the timer block has finished running.
+
+### Comprehensive Timer Example
+
+The intent here is to trigger an alarm to the police but allow the timer to be reset in case a reset button has been pressed during the trigger time.
+The rule is triggered when the burglar-alarm-item or the reset-button-item is changed.
+
+![timer-comprehensive](../images/blockly/blockly-timer-comprehensive.png)
+
+---
+
+## Date handling blocks
+
+Date blocks are used as input parameters for other blocks.
+At the moment some of these blocks are found in the ephemeris section, whilst others are found in the persistence section - they may be equally useful for both.
+These blocks are *typed* to assure correct connection to other blocks.
+
+### today
+
+![today](../images/blockly/blockly-date-today.png)
+
+Type: *DayOffset*
+
+Ephemeris blocks expect a date formatted as the number of days since today.
+As a result, this block returns 0.
+
+### today +/- x days
+
+![now-plus-minus-offset](../images/blockly/blockly-date-plus.png)
+
+Type: *DayOffset*
+
+Returns the number of days since today, as configured in the number block.
+The number can be positive (offset into the future) or negative (offset into the past).
+
+### date-picker
+
+![date-picker](../images/blockly/blockly-date-picker.png)
+
+Type: *ZonedDateTime*
+
+Returns a date as *ZonedDateTime*.
+The date can be selected from a date picker.
+The time is set to `00:00:00`.
+
+### Get date
+
+![get-date](../images/blockly/blockly-date-get.png)
+
+Type: *ZonedDateTime*
+
+From a String in the format `yyyy-MM-dd`, this block will return the date as *ZonedDateTime*.
+The input String  may be a variable-block.
+The time will be `00:00:00`.
+
+### Get Date now with offset
+
+![now-with-offset](../images/blockly/blockly-get-now-offset.png)
+
+Type: *ZonedDateTime*
+
+Returns a date as *ZonedDateTime* with offset relative to the current date *and* time.
+
+### Get String representation of date
+
+![date-tostring](../images/blockly/blockly-get-date-string.png)
+
+Type: *String*
+
+Returns the the String representation of a given *ZonedDateTime*-block, with or without the time.
+
+### Example
+
+Assuming this block is run at `20:47:36` on `31/01/2022`
+
+![date-text-example](../images/blockly/blockly-date-text-example.png)
+
+The output in the log will be.
+
+```text
+2022-01-31
+2022-01-31 00:00:00
+2022-01-31 20:47:36
+```
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#timers-and-delays)

configuration/blockly/rules-blockly-value-storage.md

@@ -0,0 +1,65 @@
+---
+layout: documentation
+title: Rules Blockly - Value Storage
+---
+<!-- markdownlint-disable MD036 -->
+
+# Value Storage
+
+[return to Blockly Reference](index.html#value-storage)
+
+## Introduction
+
+These blocks enable storing information *for a rule* that is kept after the rule has run, so it can be reused when the rule is run again later in stateful way.
+Basically a value storage can be perceived as a global variable for the rule instance.
+
+- The values are persisted as a part of the *instance* of the rule
+  - Modifying the rule during development creates a new instance which means the value is reset.
+  - Restarting openHAB creates a new rule instance which also means the value is reset
+  - In most cases both situations are negligible for many rules.
+- If you need full persistence of values that can be used across rules you need to persist the value in one of the persistence engines like MapDB
+- By default the value is *undefined*.
+To check if a value is undefined, use the special "is undefined"-block
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-value-storage-overview}
+
+## Overview of the Value Storage blocks
+
+![value-storage-blocks](../images/blockly/blockly-value-storage.png)
+
+## Value Storage Blocks
+
+### Store Value
+
+![store-value](../images/blockly/blockly-value-store.png)
+
+Function: Stores a value under the key name
+
+### Get Stored Value
+
+![get-stored-value](../images/blockly/blockly-value-get.png)
+
+Function: Retrieves a stored value by the key name
+
+### Check if Value is undefined
+
+![value-is-defined](../images/blockly/blockly-value-is-defined.png)
+
+Function: Checks if a value is undefined
+
+### Example 1: Initialize a key if not set
+
+![example1](../images/blockly/blockly-value-example1.png)
+
+### Example 2: Use the rule instance variable to remember a color that has been set
+
+![example2](../images/blockly/blockly-value-example2.png)
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#value-storage)

configuration/blockly/rules-blockly-voice-and-multimedia.md

@@ -0,0 +1,99 @@
+---
+layout: documentation
+title: Rules Blockly - Voice and Multimedia
+---
+<!-- markdownlint-disable MD036 -->
+
+# Multimedia
+
+[return to Blockly Reference](index.html#voice-and-multimedia)
+
+## Introduction
+
+In general, this section deals with two topics
+
+1) Playing or streaming audio to an audio sink e.g a speaker
+1) Saying a text via using any Text-to-Speech API (e.g. Google's API)
+
+It should be noted that both functionalities do not just work right out of the box because e.g for (1) the audio sinks need to be installed in openHAB and for (2) e.g. the whole Google API needs to be configured in particular with your own personal google account.
+Even though (2) is not trivial but after having done that the usage of the functionality with blockly is very easy and worth the effort.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+{: #blockly-ephemeris-overview}
+
+## Overview of the Voice and Multimedia blocks
+
+![voice-and-multimedia](../images/blockly/blockly-voice-and-multimedia.png)
+
+## Setup
+
+- Audio Sinks
+  - Audio devices are automatically added by their bindings as *sinks* in openHAB
+  - [Reference on how to setup Audio and Audio Sinks](https://www.openhab.org/docs/configuration/multimedia.html)
+- Text-To-Speech
+  - In order to use text-to-speech, you need to install at least one [TTS service](https://www.openhab.org/addons/#voice).
+  - see [openHAB Voice](https://www.openhab.org/docs/configuration/multimedia.html#voice) for more information
+  - in case you only have one TTS service, this becomes your default TTS services.
+  In case you have several TTS services installed, you have to configure one of them as the default which can be done in your [services.cfg](https://github.com/openhab/openhab-distro/blob/master/distributions/distribution-resources/src/main/resources/runtime/etc/services.cfg#L20).
+  See more on that special case [here](https://community.openhab.org/t/where-to-set-default-tts-voice/15450/2)
+
+## Voice and Multimedia Blocks
+
+### Play Audio
+
+![play-audio](../images/blockly/blockly-play-audio.png)
+
+*Function:* Plays an audio file on an audio sink
+
+- the audio file must reside in the sounds-folder of openHAB that can be found [here](https://community.openhab.org/t/blockly-reference/128785#openhab-configuration-files-7)
+- all available audio sinks are automatically provided by openHABs blocklies
+
+### Play Audio with Volume
+
+![img.png](../images/blockly/blockly-play-audio-with-volume.png)
+
+*Function:* Plays an audio file on an audio sink and setting the volume at the same time
+
+same as above but also allowing to provide the volume at the same time
+
+- the audio file must reside in the sounds-folder of openHAB that can be found [here](https://community.openhab.org/t/blockly-reference/128785#openhab-configuration-files-7)
+- all available audio sinks are automatically provided by openHABs blocklies
+
+**Known issue workaround:**
+In several cases (like the google minis) it is known that setting the volume together with playing the sound results into only setting the volume either during playing the sound or even after the sound has played.
+In case this happens the more robust approach is as follows
+
+- Search for the thing of that particular sink and add an in item for the volume channel
+- Then create the following block sequence
+
+![play-audio-known-issue-workaround](../images/blockly/blockly-play-audio-known-issue.png)
+
+### Play Stream
+
+![play-stream](../images/blockly/blockly-play-stream.png)
+
+*Function:* Starts an stream playing on an audio sink
+
+- The audio streams must be reachable from the openHAB server and can therefore be either internally or externally hosted
+- All available audio sinks are automatically provided by openHAB's blocklies
+- Changing the volume needs to be done via the thing volume channel linked to the sink device by sending the respective volume level command to that item
+
+### Stop Stream
+
+![stop-stream](../images/blockly/blockly-stop-stream.png)
+
+*Function:* Stops playing the current stream of the specified audio sink
+
+### Say
+
+![say](../images/blockly/blockly-say.png)
+
+*Function:* Sends the given text to the sink by using the default Text-to-Speech-Service to translate the text based on the chosen language voice into a stream which is then played on that device sink.
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#voice-and-multimedia)