Blockly Reference

openHAB Blockly Reference

openHAB specific Blockly language block reference

Authors: Stefan Höhn / started by Andrew Rowe

Blocks available as of version OpenHAB 3.2.0 release

Known issues:

The following issues in 3.2.0 have been fixed here and will be available in 3.3 M1 (may be 3.2.1,too)

  • Get Item attribute has the wrong block type. As a result it cannot be connected to any other block and cannot be used directly. As a Workaround assign the Block to a variable and the use that variable.

  • The block “get context attribute” has the wrong block type. As a result it cannot be connected to any other block and cannot be used directly. As a Workaround assign the Block to a variable and the use that variable.

  • Get Item attribute returning categories will return a collection of Strings that cannot be used with further blocks.

  • Group member handling (no fix to be expected soon)

image of openHAB specific block categories


Table of Contents


Introduction

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 section. However, this art 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).

The basic idea behind the visual paradigm and representation within openHAB is based on the Google Blockly Support which has been integrated and which provides the basic blocks for programming like

  • Logic-Blocks for comparison
  • Loop-Blocks for repeatable actions
  • Math-Blocks for calculations
  • Text-Blocks for Text/String manipulations
  • List-Blocks for iterating over and manipulation collections
  • Color-Blocks for easy handling of color settings
  • Variables to store / retrieve values
  • and functions to provide reusable block functionality

All of the above 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 almost 50 specific blocks have been provided that are tailored for easy access of openHAB’s capabilities. The following will provide a detailed description of these 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.

Looking for help

It is highly recommended to click on help (right click on any of the blocks) which will then link you to the functionality which the block provides. 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 you start using openHAB Blocklies

OpenHAB Configuration Files

In some situations the openhab configuration files need to be found in their location (often referred as $OPENHAB_CONF). These can be found

  • 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 you will have the different folder locations under Technical information.
  • Use openHAB-conf when mounting it from Windows or MacOS

Link the openHAB share in macOS

  • Finder → Go → Connect to Server
  • via accessing them directly on the openHAB server /etc/openhab
  • all methods will reveal the following folders
    • html
    • icons
    • items
    • services
    • html
    • persistence
    • rules
    • scripts
    • sitemaps
    • sounds
    • things
    • transform

More information

  • How to create a blockly rule via the UI
    • go to Settings → Rules
    • press image 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 image
    • click on und you should now see this screen

  • you can now open the image 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 image on the lower right to see the generated code (click again to come back to the blocks)

  • Use Frontail logging service
    • To be able to conveniently view your log files it is recommended to setup frontail which can be achieved easily via openhabian-config
    • Start openhabian-config on your server and choose option 20 and then option 21
    • After installation you can view your logs under http://myopenhab-server:9001


Items and Things

Items and Things are the major entities of openHAB (see Concepts | openHAB) to control and monitor the home. These can be accessed via the “Items & Things” section.

Overview of the Items and Things category

The most common task is to either retrieve the state (like ON/OFF or a temperature) from an item or change the value of the item. In some case access of the whole openHAB thing is even required. Therefore openHAB blockly provides two blocks that allow the access of the thing.

image

Note that they are always used in conjunction with another block as the block on its own would not have a useful effect. An example could be retrieving the state of an item for a condition or to change the value of an item to switch on a light. For example to switch on the “Living Room Light” when the “Main Switch” is pressed then you could you the item-block like so (we get into the details of the following block in a minute):

Item

image

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 which can also be used in any place where the name of the picked item is needed as a String
  • Learn more about items here

Get Item

image

Function: Gets an Item for use in other item related functions

  • Clicking ‘MyItem’ displays a list of Items to pick from.
  • Technically this block really returns an item object which then can be used to further retrieve specific attributes from that item like the state or other attributes of that object (see below).
  • Note the fact that it does not return a String but the item object instead prevents the block for example to be connected to a simple log statement like in the following example

Get State of Item

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 for reference and potential workaround.

Get Members of Group

----------------- Work in progress - under discussion -----------------

see the following thread for the time being

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
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])

Get particular attributes of an item

Function: Get either the current name, label, state, category, tags, groups, or type of an item as a String

These are the fields and types that are returned

  • name: String
  • label: String
  • state: State
  • category: String
  • tag: Array, e.g.
[plannedTimes]
  • groups: Array, e.g.
[plannedTimes, timers]
  • type: String

Special handling for Arrays

The attributes groups and tags are returning an Array of entries. Therefore

  • they cannot be connected to a block that expects a String (e.g. like the log-block)
  • they need to be handled with the help of a for-loop like in the following example

Important note: In 3.2.0 there is a bug that prevents the block to be connected (there is fix already waiting to be released). In the meantime as a workaround just assign the block to a variable and then use that variable (for example in an if-statement) as follows

Send Command

For information when to use “send command or post update” see “manipulating states”.

Block image:

Example

Function: Sends a command or posts an update to an Item or Group

  • valid input for value is 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
  • see more details on coma

Comprehensive Example for using items

Example 1:

In this case the state of the item MainSwich is checked if it is on. If this is the case, then “ON” is sent via a command to the item livingroomLight.

Example 2:

In the case the rule containing the above block is triggered, the state of the MainSwitch is retrieved and directly send to the light (expecting ON or OFF in both cases)

Thing

image

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

Example

This block


returns

thing name = nanoleaf:controller:645E3A484A83

Get Thing Status

image

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 really returns a ThingStatus which is a String representation of one of the following enumerations
    • UNINITIALIZED,
    • INITIALIZING,
    • UNKNOWN,
    • ONLINE,
    • OFFLINE,
    • REMOVING,
    • REMOVED

Timers and Delays

In general, Timers and Delays are one of the most important functionality in rules that become a bit more complex. While the “Wait-For”-block is rather straightforward, the timer blocks should be well understood before being used and in particular if they seem to behave different from what you expect. Therefore the following chapter tries to explain in depth what the blocks do and some cases even generated code might be shown to explain what is really happening behind the scenes.

Timer Naming

Timers are created by referring to it with a name to allow later manipulation within a rule.

It is important to understand that a named timer is only available within the same rule and therefore cannot be accessed via a different rule or expressed in a different way: The same timer name used in two different rules results into two separate timers!

image of Timers and Delays category

Wait for

image

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 1 sec delay for three times:

After period of time Do With Timer

Function: Schedule a task to be performed once at a specified period in the future

  • A number and magnitude (seconds, minutes up to months) can be chosen at which the commands within the block should be executed
  • The name of the timer has to be provided which allows further access to that timer and also makes that timer unique for processing

Example

10 seconds after the rule has been called, the timer triggers all lights to go off:

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

An example of using that approach is as the following which starts after 5 seconds and is then retriggered 5 seconds later which then retriggers itself after 5 second and so on.

Note that the example above is not recommended because it turns out to be endless which is something one probably don’t want to have. A bit more complex way but smarter way is by using a variable to keep track of the number of repeats:

After period of time Do With Timer with options on retriggering rule

Function: Schedule a task to be performed at a specified period in the future with the ability to reschedule, cancel or ignore the timer in the situation when the rule is retriggered.

Before just using that block, it is important to really understand what the idea behind the option of retriggering is. So please read carefully even though it may appear a bit technical at that point.

The main topic is what should happen in case the same block is revisited because the rule was triggered again. Therefore this block allows to react with different

Options on Retrigger

image

Before we can understand what the options do, let’s look at the code of the simple timer block which is described in the previous chapter

and generates the following code

if (typeof this.timers['simpleTimerBlock'] === 'undefined' || this.timers['simpleTimerBlock'].hasTerminated()) {
  this.timers['simpleTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
    })
}

This is the important part to be understood:

What happens is that an else branch is being added that does something if the rule and therefore the code is retriggered plus when the timer exists already and is hasn’t terminated (which means it is waiting to trigger the code eventually when the time has come).

  1. "do nothing": The block should not do any special

which compared to the simple timer block is almost the same but the else branch has been added but with no content (to make it explicit in the code that nothing is happening in this case)

if (typeof this.timers['nothingTimerBlock'] === 'undefined' || this.timers['nothingTimerBlock'].hasTerminated()) {
  this.timers['nothingTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
    })
} else {
  // do nothing
}
  1. "cancel": The block should cancel the timer

In the case the timer exists and hasn’t terminated and the rule has been retriggered then cancel that timer.

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;
}
  1. "retrigger": The block should retrigger the timer

In the case the timer exists and hasn’t terminated and the rule has been retriggered then retrigger that timer.

Let’s say the rule was triggered at “time = 0”. In this case it is expected that after 10 seconds the log statement is executed (time=10). Now let’s imagine the during the first 10 seconds at “time = 5” the rule is retriggered. In this case the timer will be rescheduled from the beginning which means it waits for another 10 seconds from now which will execute the log statement only at “time=15”.

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

image

Function: Prevents the scheduled timer from executing.

Timer is Active

image

Function: returns true if the timer will be executed as scheduled, i.e. it has not been cancelled or completed.

Timer is Running

image

Function: returns true if the code is currently executing (i.e. the timer activated the code but it is not done running).

Timer has terminated

image

Function: returns true if the code has run and completed.

Comprehensive Timer Example

The intent 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 in case the burglar-alarm-item or the reset-button-item is changed.


Date handling blocks

It is important to understand how these block work because there are provided as input parameter for the ephemeris and persistence blocks. Note that these blocks are typed which makes sure they can applied at the right position of other blocks. Some of the blocks can be found in the ephemeris section, some others are located in the persistence section.

today: image.
Type: DayOffset

When ephemeris blocks expect a date as an input it actually expects to see the relative number of days from today (hence the offset) which effectively will result into today being zero. This is why, if you print out the “today” block you will not get the date of today but 0.

today +/- x days:
image
Type: DayOffset

Similar like today but returning the entered offset which can be negative (into the past) or positive (into the future).

date-picker:
image


Type: ZonedDateTime

Allows picking a date which is returned as ZonedDateTime

Get date
image
Type: ZonedDateTime
Allows providing the date in the format yyyy-MM-dd as a String (for example via a String variable) and returns a ZonedDateTime

Get Date now with offset:
image
Type: ZonedDateTime
Returns a ZonedDateTime based on now with the given offset applied

Get String representation of date


Type: String

Returns the the string representation of a given ZonedDateTime Block.

Example

Given the fact that now is at the 31st of December 2021 all three blocks will return the same String representation only that the first two will have a time of 00:00:00 whereas the third will contain correct time included in the string


Ephemeris

image of Ephemeris category

The ephemeris category provides blocks that provide some calendar functionality. It is a way to determine what type of day today 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.

It is important to understand that “magic” behind computing the holidays relies on a configuration file at $OPENHAB_CONF/services/ephemeris.cfg on the openHAB server which has to be configured to your needs (copy the default file from /var/lib/openhab/config/org/openhab to /etc/openhab/services and then manipulate it from there)

For more information see the ephemeris action page and in particular Ephemeris documentation

Holiday, weekend or weekday check

image

Function: this block checks if the given block of type ZonedDateTime is a holiday, weekend or weekend depending on the given selection
Type: boolean

Examples:

Get the holiday name for a particular date

image
Function: Returns the holiday name for the given date
Type: String

Get the number of days until a specific holiday


Function: Return the number of days until the given holiday name
Type: number

  • the holiday must be configured in the configuration file
  • additional “holiday” names like personal birthdays can be configured

Voice and Multimedia

image of Voice and Multimedia category

In general, this section deals with two topics

  1. Playing or streaming audio to an audio sink e.g a speaker
  2. Saying a text via by utilising the 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. 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.

Setup

  • Audio Sinks
  • Text-To-Speech
    • In order to use text-to-speech, you need to install at least one TTS service.
    • see openHAB Voice for more information
    • in case you only have one TTS service, this is then your default TTS services. In case you have several TTS services installed, then you have to configure one of them as the default which can be done in your services.cfg . See more on that special case here

Play Audio

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
  • all available audio sinks are automatically provided by openHABs blocklies

Play Audio with Volume

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
  • all available audio sinks are automatically provided by openHABs blocklies

Known issue workaround:
In several case (like the google minis) it is known that setting the volume alongside 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 Stream

Function: Starts an stream playing on an audio sink

  • the audio streams must be reachable from the openHAB server and could be therefore either internal or externally hosten
  • all available audio sinks are automatically provided by openHABs 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

Function: Stops a playing the current stream on the specified audio sink

Say

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.

Notifications

Notifications can be used to send information to openHAB devices via the openHAB cloud platform so make sure this is setup first. Notifications can be used as push message to devices running the openHAB client.

image of Notifications category

Send Notification to specific cloud email user

Function: Sends a notification via openHAB cloud to a specific user signed up under the given email address

  • It does not use the mail binding and it is not possible to send a notification to a user who has not been signed up in openHAB cloud
  • the notifications only work if the devices has openHAB client installed (either iOS or Android)

Send Notification to All Devices and users

Function: Sends a notification to all devices and all users

Example Push Message shown under Android:

Send Notification to Log Only

Function: Sends a notification to the myopenhab.org

  • Do not mix up the myopenhab.org log with the openhab-server log. The notification is only sent to the logs of the cloud service which can be found under openHAB Cloud - Log in.
  • No information to any user is sent in this case
  • 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

Persistence

Overview of the Persistence category

Persistence blocks allow to access the openHAB database that stories item values regularly and compute statistical analysis date from that. For more information see the persistence documentation.

See the date block section for an explanation of the date blocks of the persistence section.

Get statistical value of an item


with the choice of
image

Function: computes any of the above functions for the given item since the point in 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 thregiven item since a certain point in time
  • 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 in fact being persisted.

Check item change / update since a point in time

Function: checks if an item was updated or changed since a certain point in time
Type: boolean

Provide last updated date of an Item


Function: Provides the last updated date of an Item
Type: ZonedDateTime


Value Storage

Overview of the Value Storage category

The aim of these blocks is to allow storing information for a rule that is kept after the rule has been run, so it can be reused when the rule is run again later in stateful way.

  • 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 you need to persist the value in one of the persistence engines like MapDB
  • By default the value is undefined. This cannot achieved by checking against the value “undefined”. To check if a value is undefined, use the special “is undefined”-block

Store Value

Function: Stores a value under the key name

Get Stored Value

image

Function: Retrieves a stored value by the key name

Check if Value is undefined

Planned to be released for 3.3 M1

image

Function: Checks if a value is undefined

Example 1: Initializes a key if not set

Example 2: Uses the rule instance variable to remember a color that has been set


Run & Process (Rules and Scripts)

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. It’s an important thing to realize as it does seem to create confusion and problems when people don’t understand that scripts really are not something all that different.

Planned to be released for 3.3 M1

  • Adding inline Script

Call Script File

image

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 of UI

image

Function: calls another rule or script that was provided via the openHAB User Interface which can be perceived as reusable code used multiple times by other calls.

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, modifying the number of key/value pairs to suit (default is currently 3).

Don’t forget to edit the ruleUID that should be called - you find the uid in the list of rules or script in the second line of the list (like here helloBlockly or helloWorld)
image

  • parameters can be retrieved 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 attributes from rule

Function: Retrieve parameters within a called rule that we passed by a calling rule (see above)

image

This retrieves the value for the key “myKey1” that was passed by the calling rule.

Note: Unfortunately there is a bug in 3.2.0 which does not allow to connect that block to any other block except a variable. So the workaround for using in relation to the example above is as follows

Example

Retrieve rule context information

Function: Retrieve event context related information of the rule

A rule carries contextual information that allows to retrieve relevant information in case the rule was triggered.

  • not every of the attributes is always available as it depends of the rule trigger type
  • For more detailed information please see Event Object Attributes

Planned to be released for 3.3 M1

  • triggered event

Transform values via Map, Regex or JsonPath



Function: Transform the given value via one of the three transformation methods (map, regex, jsonpath)

Examples

Example1: Regex

Converting #123456 into rgb(12,34,56)

Example 2: JsonPath transformation
get the temperature from the following JSON

{ “device”: { “location”: “Outside”, “status”: { “temperature”: 23.2 }}}

by using the jsonpath

$.device.status.temperature

Example 3: Applying a map transformation from the map file nanoleaf.map in the $OPENHAB-CONF/transform

resulting into Hue/Saturation

map file content

ON=Ja
OFF=Nein
effects=Effekte
-=?
NULL=n/a
hs = Hue/Saturation
ct = Color Temperature

Inline Script

Planned to be released for 3.3 M1

image

Function: enter arbitrary script content at position of the block

The main idea is to provide the possibility to inject any ECMAScript at a given position. This should only be used in cases when blockly does not provide the same functionality as it is still missing.

Therefore use very sparsely and with caution.

Example:

Logging and Output

For general information regarding logging see the openHAB Logging description

image

Log Statement

image

Function: Sends an entry to the openHAB log file

  • A severity level can be provided via the dropdown list for the log statement

    • error
    • warn
    • info
    • debug
    • trace

Print Statement

image

Function: creates a print statement with the given text in the rule


Blockly Standard Categories and openHAB Extensions

This section explains only the blocks that have been added to the standard blocks by openHAB

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.

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

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

image

Function: Returns a random color as a hexcode

Create RGB color

image

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

image

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)

Planned to be released for 3.3 M1

image

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:

Lists

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:

Rename the keys as required and then add any value block type to the related key:

Example:

get value of key from dictionary

image
Function: Retrieves the value of the key in the given directory

Example:

17 Likes

reserved

1 Like

If you like I can make this a wiki so others can edit it. Though in practice few will and they will just post comments anyway.

Looks good so far!

Yes please Rich
I think at least Stefan will want to add stuff

Done.

1 Like

I definitely will engage :partying_face:

Thanks, @rlkoshak

1 Like

Can you share the URL to the wiki?

It is the first post here…

:rofl: I wasn’t aware that I can edit the post. Thanks #dummyme

As it was turned into a wiki post, you can :wink:

I started contributing and I wonder if the images should have an internal or external link, so we can later integrate this page into the official openhab documentation?

No idea …
@Confectrician ??

All the image links will need to be reworked no matter what you choose so I wouldn’t worry about it until it’s time to move them over to the docs. It would help though to save off the images somewhere with reasonable names because the images will need to be checked in along with the text as part of the PR. But the way the image tags work in the docs you’ll have to rework the links anyway so don’t worry too much about setting up something external for this post to host the images.

Ok, thanks for the info. Not really a good process unfortunately and not really temping to put many images in :wink: ( I will do anyway). Can we not push this page earlier to GitHub and then work on it there?

If you want you can create a WIP PR and work on it there.

However you’ll also have to run a separate service to build the pages so you can preview them as you write which involves a bit more work in the long run.

I’ve never tried to collaborate with more than one author on the same PR though so I don’t know how easy that is to do.

And you will pretty much cut off any chance of contributions or suggestions from the target audience. If they are coding in Blockly, they are almost certainly not going to be reviewing and contributing to a PR in progress on Github.

In my experience, the little bit of work at the end managing the images is less than the extra work required and some of the draw backs in terms of contributions and exposure to make it worth writing the first draft here on the forum and then moving them over.

I checked the Rules | openHAB in the repo which is at openhab-docs/rules-dsl.md at main · openhab/openhab-docs · GitHub and turns out to be a Markdown file, isn’t it? And it seems to have the picture referenced to the relative folder images. So it should be easy to clone the repo and write the md-file locally and see how it looks with an MD-Viewer. Does it come out quite differently after running the build or would that be worth trying?

Another question: Is there the possibility to have sub pages? I feel that the documentation will become quite comprehensive and long and would actually profit from being broken down in separate pages but I seems that openHAB Docs only has one level of page hierarchy, does it?

Yes but…

All the external references (such as for images or links to other pages) is not MD as far as I’m aware. There are some other small quirks that you probably won’t run into.

That never worked for me well enough to rely on it.

That’s a discussion for @Confectrician as the keeper of the overall structure of the docs for what is the best way. You can have subpages. Look at the UI Guide’s Component Reference page (which I believe is automatically built from the actual widgets and not from the MD files, but that would still work. Or you can have a sequence of pages similar to the Getting Started Tutorial which are all at the same level but grouped together on the left hand side.

I could see a single page with a generic “here is how to create a rule with Blockly” with a reference table that has links to a separate page, or parts of a separate page with the detailed info for that block.

As far as i know deeper hierarchies should be possible, but we only allow one level hierarchy in the sidebar navigation, so it does not get to overgrown.

2 Likes

So we could have a main page that would link down to the sub pages (which are not shown in the menu to the left), right?

Yes, this would be the current behavior.

We could for sure check, if we can define something different for blockly.
This should be a fair amount of research.
@ysc do you have something in mind about the navigation setting we configured in vuepress?

We can add a blockly section for testing purposes at any time.
Changes will only be available for the snapshot docs anyway until the next release of openHAB is published.
So we can’t destroy that much while testing things out. :slight_smile:

1 Like