diff --git a/configuration/blockly-getItemAttributes.png b/configuration/blockly-getItemAttributes.png new file mode 100644 index 000000000..c0783d2c6 Binary files /dev/null and b/configuration/blockly-getItemAttributes.png differ diff --git a/configuration/blockly/rules-blockly-date-handling.md b/configuration/blockly/rules-blockly-date-handling.md index b38e8237d..81cf986a9 100644 --- a/configuration/blockly/rules-blockly-date-handling.md +++ b/configuration/blockly/rules-blockly-date-handling.md @@ -224,11 +224,14 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo ### Get String representation of date ("text of") +![get-date-string](../images/blockly/blockly-get-date-string-without.png) + ![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. +Returns the String representation of a given _ZonedDateTime_-block, with, without the time or formatted in openHAB time (like in the logs). +It also allows to return the date in a custom format which can be provided in a separate block. since 3.3: also returns the same datetime format that is used by openHAB itself diff --git a/configuration/blockly/rules-blockly-items-things.md b/configuration/blockly/rules-blockly-items-things.md index b427bc5d2..2bf6a9802 100644 --- a/configuration/blockly/rules-blockly-items-things.md +++ b/configuration/blockly/rules-blockly-items-things.md @@ -139,8 +139,10 @@ These attributes are returned with the following types: - name: String - label: String - state: State +- numeric state: Number +- quantity state: [Quantity](rules-blockly-uom.html#unit-of-measurement-blocks) - category: String -- tag: Array, e.g. +- tags: Array, e.g. ```json [plannedTimes] diff --git a/configuration/blockly/rules-blockly-standard-ext.md b/configuration/blockly/rules-blockly-standard-ext.md index 755eaf797..c2508b9c8 100644 --- a/configuration/blockly/rules-blockly-standard-ext.md +++ b/configuration/blockly/rules-blockly-standard-ext.md @@ -43,6 +43,12 @@ _Function:_ The bitwise NOT (~) operator inverts the bits of its operand. ![blockly-bitwise-not.png](../images/blockly/blockly-bitwise-not.png) +### Rounding + +The standard block has been extended to provide a rounding function with the ability to set the number of decimal places: + +![math-round](../images/blockly/blockly-math-round.png) + ## Text The Text section is the general section that allows text or string manipulation @@ -143,6 +149,8 @@ Example ![lists-overview](../images/blockly/blockly-lists-dictionary-overview.png) ![lists-overview-concat](../images/blockly/blockly-lists-concatenate.png) +![blockly-map-for-each](../images/blockly/blockly-map-for-each.png) + ### Dictionary for managing key / value pairs The dictionary is a holder for key value pairs that can be passed along as one. @@ -167,6 +175,18 @@ _Function:_ Retrieves the value of the key in the given directory ![dictionary-getkey-example](../images/blockly/blockly-lists-dictionary-getkey-example.png) +### Loop over a dictionary + +This block can be found in the Loops section and is a dedicated block that allows to iterate over the elements of a dictionary. +The loop provides the value into the variable that was choosen in the drop down. +See the examples below how the loop can be used. + +![map-for-each](../images/blockly/blockly-map-for-each.png) + +Either the dictionary itself can be provided directly or via a variable. + +![dictionary-foreach-example](../images/blockly/blockly-map-foreach-example.png) + ### Concatenate lists ![lists-overview-concat](../images/blockly/blockly-lists-concatenate.png) diff --git a/configuration/blockly/rules-blockly-timers-and-delays.md b/configuration/blockly/rules-blockly-timers-and-delays.md index c651f62b0..2b6d5568d 100644 --- a/configuration/blockly/rules-blockly-timers-and-delays.md +++ b/configuration/blockly/rules-blockly-timers-and-delays.md @@ -18,13 +18,24 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo ## 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) +![timers-and-delays](../images/blockly/blockly-timers-overview.png) -## Timer Naming +## Timer Naming and Scope 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. +A timer is by default created within the scope of that particular rule which is called a "private" timer. +When the timer is created as a shared timer it can also be accessed under this name from a different rule. + +![timer-scope](../images/blockly/blockly-timer-shared.png) + +This example starts a timer in Rule 1 + +![timer-shared](../images/blockly/blockly-timer-example-shared-1.png) + +and cancels the same timer in Rule 2 + +![timer-shared-cancel](../images/blockly/blockly-timer-shared-cancel.png) ### Wait for @@ -97,12 +108,14 @@ Though it may not seem to be obvious, the same rule can be retriggered at any ti 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 () { - }) +if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) { + cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () { + cache.private.remove('MyTimer'); + })); } else { - this.timers['MyTimer'].reschedule(zdt.now().plusSeconds(10)); -} + cache.private.get('MyTimer').reschedule(time.ZonedDateTime.now().plusSeconds(10)); +}; + ``` **Simple timer-block** @@ -112,10 +125,12 @@ 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 () { - }) -} +if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) { + cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () { + cache.private.remove('MyTimer'); + })); +}; + ``` **Retrigger timer-block** @@ -129,24 +144,27 @@ The retrigger timer-block inserts an additional `else{}` branch into the generat In the case of _do nothing_ the `else{}` branch is empty (which turns to be almost equals to the simple-timer). ```javascript -if (typeof this.timers['nothingTimerBlock'] === 'undefined' || this.timers['nothingTimerBlock'].hasTerminated()) { - this.timers['nothingTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () { - }) +if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) { + cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () { + cache.private.remove('MyTimer'); + })); } 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 () { - }) +if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) { + cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () { + cache.private.remove('MyTimer'); + })); } else { - this.timers['cancelTimerBlock'].cancel(); - this.timers['cancelTimerBlock'] = undefined; -} + cache.private.remove('MyTimer').cancel(); +}; + ``` In the case of _reschedule_ the `else{}` statement contains code to reschedule the timer - restart the countdown. In the example generated code below: @@ -157,18 +175,19 @@ In the case of _reschedule_ the `else{}` statement contains code to reschedule t - 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'); - }) +if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) { + cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () { + cache.private.remove('MyTimer'); + })); } else { - this.timers['rescheduleTimerBlock'].reschedule(zdt.now().plusSeconds(10)); -} + cache.private.get('MyTimer').reschedule(time.ZonedDateTime.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 diff --git a/configuration/blockly/rules-blockly-uom.md b/configuration/blockly/rules-blockly-uom.md index 423e8d5c8..966cf3c7d 100644 --- a/configuration/blockly/rules-blockly-uom.md +++ b/configuration/blockly/rules-blockly-uom.md @@ -27,17 +27,38 @@ The following example block gives a good idea of what can be done with the Unit ### Unit of Measurement Blocks -These blocks allow you to add, substract, multiply and divide measurements, which include a [**unit**](docs/concepts/units-of-measurement.html#list-of-units) of measurement which is also called a Quantity Type, as well as comparing values against each other. +These blocks allow you to convert to, add, substract, multiply and divide measurements, which include a [**unit**](docs/concepts/units-of-measurement.html#list-of-units) of measurement which is also called a Quantity Type, as well as comparing values against each other. -## Quantity Block +### Smart block input type handling + +Note that the block is smart enough to either take either one of the three blocks + +- "get item block" (which returns the whole Item object and from which the block retrieves state value) +- "get state item block" (which returns the Item state and from which the block retrieves state value) +- "item block" (which returns only the name of the Item and from which the block retrieves quantity state of the Item) + +or you can directly access the to retrieve the quantity state. + +![uom-smart-input-handling](../images/blockly/uom_block_smart_input.png) + +Blockly cannot detect the type that is contained in a variable so it expects an item object. +This allows to iterate over a group of item members which returns a list of item objects: + +![uom-#-var](../images/blockly/blockly-quantity-loop-var.png) + +This approach is valid for all blocks in this section except _Quantity Conversion_ which expects a Quantity. + +## Quantity Blocks A _Quantity_ is the combination of a value and a unit of measurement, which means that the blocks require a _Quantity_ as an input and generate a _Quantity_ as an output. Even though the quantity block looks similar to the standard text block it actually wraps a string into a _Quantity_ type. _Function:_ The following block takes a string of "10 W" (10 Watts) and converts into a quantity of 10 W which then can be used for computations. Instead of using a constant string, the block can also take the output of an item or a variable and convert it into a quantity. +The second block below allows easier handling in some special cases where you like to supply value and unit seperately. ![blockly-quantity](../images/blockly/blockly-quantity.png) +![blockly-quantity-unit](../images/blockly/blockly-quantity-with-unit.png) ![blockly-quantity-temperature-item](../images/blockly/blockly-quantity-temp-item.png) ### Quantity computation @@ -49,10 +70,14 @@ _Function:_ The block allows to compute the following operations with two quanti - division - multiplication -It only takes a [quantity block](#quantity-block) as an input and also returns a quantity as an output +It only takes a [quantity block](rules-blockly-uom.html#quantity-blocks) as an input and also returns a quantity as an output. ![blockly-quantity-multiplication](../images/blockly/blockly-quantity-multiplication.png) +Due to the smart type detection even this short form works as expected: + +![blockly-quantity-smart-computation](../images/blockly/blockly-quantity-smart-computation.png) + Amazingly, this multiplication results into the right quantity of 100 W². ### Quantity Comparison @@ -65,6 +90,10 @@ The following shows how it can be used in an if-statement: ![blockly-quantity-comparison-if](../images/blockly/blockly-quantity-comparison-if.png) +More examples: + +![blockly-quantity-comparison-examples](../images/blockly/blockly-quantity-comparison-examples.png) + ### Quantity Conversion _Function:_ The block provides the conversion from one quantity to another. @@ -73,6 +102,10 @@ _Function:_ The block provides the conversion from one quantity to another. The result of that operation would be 0.01 kW. +The following examples show how to use it with an Item: + +![blockly-quantity-conversion-item](../images/blockly/blockly-quantity-conversion-item.png) + ## Return to Blockly Reference [return to Blockly Reference](index.html#items-and-things) diff --git a/configuration/images/blockly/blockly-afterperiod-timer-example.png b/configuration/images/blockly/blockly-afterperiod-timer-example.png index 0f39e1eb9..54c14e33b 100644 Binary files a/configuration/images/blockly/blockly-afterperiod-timer-example.png and b/configuration/images/blockly/blockly-afterperiod-timer-example.png differ diff --git a/configuration/images/blockly/blockly-afterperiod-timer-options.png b/configuration/images/blockly/blockly-afterperiod-timer-options.png index 3659873d6..4798c9e59 100644 Binary files a/configuration/images/blockly/blockly-afterperiod-timer-options.png and b/configuration/images/blockly/blockly-afterperiod-timer-options.png differ diff --git a/configuration/images/blockly/blockly-afterperiod-timer.png b/configuration/images/blockly/blockly-afterperiod-timer.png index a1e5b0361..c1bdec40e 100644 Binary files a/configuration/images/blockly/blockly-afterperiod-timer.png and b/configuration/images/blockly/blockly-afterperiod-timer.png differ diff --git a/configuration/images/blockly/blockly-cancel-timer.png b/configuration/images/blockly/blockly-cancel-timer.png index 4921046ce..4ae60b6af 100644 Binary files a/configuration/images/blockly/blockly-cancel-timer.png and b/configuration/images/blockly/blockly-cancel-timer.png differ diff --git a/configuration/images/blockly/blockly-get-date-string-without.png b/configuration/images/blockly/blockly-get-date-string-without.png new file mode 100644 index 000000000..e877b600f Binary files /dev/null and b/configuration/images/blockly/blockly-get-date-string-without.png differ diff --git a/configuration/images/blockly/blockly-get-date-string.png b/configuration/images/blockly/blockly-get-date-string.png index e18b13750..5ab9867a9 100644 Binary files a/configuration/images/blockly/blockly-get-date-string.png and b/configuration/images/blockly/blockly-get-date-string.png differ diff --git a/configuration/images/blockly/blockly-getItemAttributes.png b/configuration/images/blockly/blockly-getItemAttributes.png index b53066180..c0783d2c6 100644 Binary files a/configuration/images/blockly/blockly-getItemAttributes.png and b/configuration/images/blockly/blockly-getItemAttributes.png differ diff --git a/configuration/images/blockly/blockly-map-for-each.png b/configuration/images/blockly/blockly-map-for-each.png new file mode 100644 index 000000000..f1e58753c Binary files /dev/null and b/configuration/images/blockly/blockly-map-for-each.png differ diff --git a/configuration/images/blockly/blockly-map-foreach-example.png b/configuration/images/blockly/blockly-map-foreach-example.png new file mode 100644 index 000000000..7c4ba5982 Binary files /dev/null and b/configuration/images/blockly/blockly-map-foreach-example.png differ diff --git a/configuration/images/blockly/blockly-math-round.png b/configuration/images/blockly/blockly-math-round.png new file mode 100644 index 000000000..6d8a71e22 Binary files /dev/null and b/configuration/images/blockly/blockly-math-round.png differ diff --git a/configuration/images/blockly/blockly-quantity-comparison-examples.png b/configuration/images/blockly/blockly-quantity-comparison-examples.png new file mode 100644 index 000000000..fe4f17849 Binary files /dev/null and b/configuration/images/blockly/blockly-quantity-comparison-examples.png differ diff --git a/configuration/images/blockly/blockly-quantity-conversion-item.png b/configuration/images/blockly/blockly-quantity-conversion-item.png new file mode 100644 index 000000000..f1d521fdf Binary files /dev/null and b/configuration/images/blockly/blockly-quantity-conversion-item.png differ diff --git a/configuration/images/blockly/blockly-quantity-loop-var.png b/configuration/images/blockly/blockly-quantity-loop-var.png new file mode 100644 index 000000000..5f78f5e03 Binary files /dev/null and b/configuration/images/blockly/blockly-quantity-loop-var.png differ diff --git a/configuration/images/blockly/blockly-quantity-smart-computation.png b/configuration/images/blockly/blockly-quantity-smart-computation.png new file mode 100644 index 000000000..abfa80688 Binary files /dev/null and b/configuration/images/blockly/blockly-quantity-smart-computation.png differ diff --git a/configuration/images/blockly/blockly-quantity-with-unit.png b/configuration/images/blockly/blockly-quantity-with-unit.png new file mode 100644 index 000000000..d3042b700 Binary files /dev/null and b/configuration/images/blockly/blockly-quantity-with-unit.png differ diff --git a/configuration/images/blockly/blockly-reschedule-timer-example1.png b/configuration/images/blockly/blockly-reschedule-timer-example1.png index 48a37fbf0..be9d5c487 100644 Binary files a/configuration/images/blockly/blockly-reschedule-timer-example1.png and b/configuration/images/blockly/blockly-reschedule-timer-example1.png differ diff --git a/configuration/images/blockly/blockly-reschedule-timer-example2.png b/configuration/images/blockly/blockly-reschedule-timer-example2.png index 36e9f6dbd..7123d3272 100644 Binary files a/configuration/images/blockly/blockly-reschedule-timer-example2.png and b/configuration/images/blockly/blockly-reschedule-timer-example2.png differ diff --git a/configuration/images/blockly/blockly-reschedule-timer.png b/configuration/images/blockly/blockly-reschedule-timer.png index e0e214919..0d955b467 100644 Binary files a/configuration/images/blockly/blockly-reschedule-timer.png and b/configuration/images/blockly/blockly-reschedule-timer.png differ diff --git a/configuration/images/blockly/blockly-simple-timer.png b/configuration/images/blockly/blockly-simple-timer.png index 0983ed8e8..8f6c50251 100644 Binary files a/configuration/images/blockly/blockly-simple-timer.png and b/configuration/images/blockly/blockly-simple-timer.png differ diff --git a/configuration/images/blockly/blockly-timer-comprehensive.png b/configuration/images/blockly/blockly-timer-comprehensive.png index 733d62988..924d085b0 100644 Binary files a/configuration/images/blockly/blockly-timer-comprehensive.png and b/configuration/images/blockly/blockly-timer-comprehensive.png differ diff --git a/configuration/images/blockly/blockly-timer-example-shared-1.png b/configuration/images/blockly/blockly-timer-example-shared-1.png new file mode 100644 index 000000000..d61e5a5c6 Binary files /dev/null and b/configuration/images/blockly/blockly-timer-example-shared-1.png differ diff --git a/configuration/images/blockly/blockly-timer-is-active.png b/configuration/images/blockly/blockly-timer-is-active.png index b6d5ca286..668eb8727 100644 Binary files a/configuration/images/blockly/blockly-timer-is-active.png and b/configuration/images/blockly/blockly-timer-is-active.png differ diff --git a/configuration/images/blockly/blockly-timer-is-running.png b/configuration/images/blockly/blockly-timer-is-running.png index ca56c050b..a1c05ccf5 100644 Binary files a/configuration/images/blockly/blockly-timer-is-running.png and b/configuration/images/blockly/blockly-timer-is-running.png differ diff --git a/configuration/images/blockly/blockly-timer-running.png b/configuration/images/blockly/blockly-timer-running.png deleted file mode 100644 index b6f4ed99c..000000000 Binary files a/configuration/images/blockly/blockly-timer-running.png and /dev/null differ diff --git a/configuration/images/blockly/blockly-timer-shared-cancel.png b/configuration/images/blockly/blockly-timer-shared-cancel.png new file mode 100644 index 000000000..3ba1414a4 Binary files /dev/null and b/configuration/images/blockly/blockly-timer-shared-cancel.png differ diff --git a/configuration/images/blockly/blockly-timer-shared.png b/configuration/images/blockly/blockly-timer-shared.png new file mode 100644 index 000000000..e1c367dd8 Binary files /dev/null and b/configuration/images/blockly/blockly-timer-shared.png differ diff --git a/configuration/images/blockly/blockly-timer-terminated.png b/configuration/images/blockly/blockly-timer-terminated.png index b6f4ed99c..bde5a0173 100644 Binary files a/configuration/images/blockly/blockly-timer-terminated.png and b/configuration/images/blockly/blockly-timer-terminated.png differ diff --git a/configuration/images/blockly/blockly-timers-and-delays-1.png b/configuration/images/blockly/blockly-timers-and-delays-1.png deleted file mode 100644 index 8cb90a3c0..000000000 Binary files a/configuration/images/blockly/blockly-timers-and-delays-1.png and /dev/null differ diff --git a/configuration/images/blockly/blockly-timers-and-delays-2.png b/configuration/images/blockly/blockly-timers-and-delays-2.png deleted file mode 100644 index a75f7dd8c..000000000 Binary files a/configuration/images/blockly/blockly-timers-and-delays-2.png and /dev/null differ diff --git a/configuration/images/blockly/blockly-timers-and-delays-small.png b/configuration/images/blockly/blockly-timers-and-delays-small.png index 99f4bfff1..662ba751c 100644 Binary files a/configuration/images/blockly/blockly-timers-and-delays-small.png and b/configuration/images/blockly/blockly-timers-and-delays-small.png differ diff --git a/configuration/images/blockly/blockly-timers-overview.png b/configuration/images/blockly/blockly-timers-overview.png new file mode 100644 index 000000000..86a91a9c8 Binary files /dev/null and b/configuration/images/blockly/blockly-timers-overview.png differ diff --git a/configuration/images/blockly/blockly-uom-example.png b/configuration/images/blockly/blockly-uom-example.png index dc7b78e7b..356c1726a 100644 Binary files a/configuration/images/blockly/blockly-uom-example.png and b/configuration/images/blockly/blockly-uom-example.png differ diff --git a/configuration/images/blockly/blockly-uom-small.png b/configuration/images/blockly/blockly-uom-small.png index a43f0d8b5..9a19a9ba5 100644 Binary files a/configuration/images/blockly/blockly-uom-small.png and b/configuration/images/blockly/blockly-uom-small.png differ diff --git a/configuration/images/blockly/blockly-uom.png b/configuration/images/blockly/blockly-uom.png index 90634798a..3b209174c 100644 Binary files a/configuration/images/blockly/blockly-uom.png and b/configuration/images/blockly/blockly-uom.png differ diff --git a/configuration/images/blockly/uom_block_smart_input.png b/configuration/images/blockly/uom_block_smart_input.png new file mode 100644 index 000000000..3a8da8d23 Binary files /dev/null and b/configuration/images/blockly/uom_block_smart_input.png differ