Extending Blockly with new openHAB commands

@rlkoshak @ysc

I need your advice regarding the bug I once created here

Basically the reason is because it is converted to Javascript and comparison works well if

  • the state does not contain a metric (and therefore only contains a number)
    *and one of both has the type of Number

In the case a String (containing a number) is compared with a Number then Javascript converts the String into a Number and the comparison works.

So the reason why it works above in the first case is actually not the reason that is assigned to a variable but because the comparison is done agains a number.

So this all goes together with also the metrics comparison containing units. We would actually need some mechanism where we detect both operands and react accordingly.

I checked the blockly API and tried out several things but have found no way yet to intercept the code generation of the if-block.
What I could imagine though that we implement our own comparison block for OH that could handle that. Do have a better idea?

I started working on these

which results into

logger.info((‘item name=’ + String(event.itemName)));
logger.info((‘item new state=’ + String(event.itemState)));
logger.info(('previous state = ’ + String(event.oldItemState)));
logger.info(('received command = ’ + String(event.itemCommand)));
logger.info((‘received event =’ + String(event.event)));

note that I was not able to add it to the vars-section but added it to the “items & things” section.

  1. With respect to Event Object Attributes — openHAB Helper Libraries documentation there are a few missing - should we add more?

  2. Is it correct that all return a String?

Any other ideas?

Sorry - I ended up working on your PR for longer than I thought (most of the afternoon) and then I had to run away so I didn’t have time to elaborate on what I did.

Actually I had this idea that this one could warrant its own block, because it is quite different than the others (sum, average, min/max etc.) as it doesn’t necessarily return a decimal number, rather a state corresponding to the type of the item. Also there is the quite useful skipEqual option that could be added as a checkbox on the block. So I removed it with the intent of readding it this week as a separate block.

I saw that you reused the EphemerisDate & EphemerisDay types & blocks in the persistence category to specify the dates, which wasn’t quite right. So I renamed them to ZonedDateTime and DayOffset. Note that the PersistenceExtensions methods don’t accept a day offset, only a ZonedDateTime.

But by having a dropdown with hardcoded values, you arbitrarily exclude other transformations (JS, Jinja, Scale, XPath etc.) from being able to be used, and also the user still has to figure out that the corresponding add-ons have to be installed. So I would prefer keeping it open and reinstating the dropdown when we figure out a way to list only those transformations that can be used. Or figure out an UI that has the suggestions, like with the dropdown, but doesn’t limit the available choices to them (I haven’t got a solution for that).

I would prefer the original comparison block to work, but I don’t know if it’ll be possible. The problem is that indeed the oh_getitem_state block returns a string because it is, in fact, a string, as the API always returns states as strings. But behind it could be any type of state. So at first it could make sense to not set an output type so it becomes compatible with any block. That’s basically what happens when you put the state in a variable - you lose the type information.
However that’s not the best either because while in many cases it will work as expected, due to the way JavaScript handles comparisons, it is not at all guaranteed.


The 2 last results in the example above are unfortunate.

The other issue is that standard JS comparisons don’t work with QuantityTypes i.e.:

var QuantityType = Java.type("org.openhab.core.library.types.QuantityType");
var x = new QuantityType("100 °F");
var y = new QuantityType("35 °C");
var z = new QuantityType("40 °C");
print(x < y);
print(x < z);


100 °F
35 °C
false // correct
false // incorrect!
1 // correct
-1 // correct

So in the end we might indeed have to provide a comparison block explicitely for QuantityTypes which would use “compareTo” under the hood - even though I’m not very happy about it as it adds to the confusion.

Thanks for your comprehensive answer.

“So I removed it with the intent of readding it this week as a separate block.”

Let me do it as I already have started with new stuff and me being continuously fighting with git when working on forks don’t want to get into git hell again :wink: It’s a pity though because I loved the fact I finally found out how to make the mutation happen :wink:

As far as the condition thing is concerned - I am pretty sure there is no way to use the original condition block. I have seen threads in that regard to actually fork the original one which clearly points into that direction.

I will now focus on the events block to get it out before christmas on M5 (your merge is already in there) and maybe I will then tackle the first part MVP on the condition thing (see post above)

This points back to the units of measurement/QuantityType discussion above.

There is a baby step that could be used though. If we add a new block that lets the user assign the units to the constant value in the comparison, e.g. 5 w instead of just the 5 that’s in place now then at least the user has the option to handle this case instead of it just blowing up in their face.

A next step would be to detect whether the state is a DecimalType or a QuantityType. If it’s a DecimalType then you can only compare it to a plain old number. If it’s a QuantityType there are some alternatives:

  • QuantityType to QuantityType
  • QuantityType.floatValue to Number
  • QuantityType to new QuantityType(Number, Units from first operand)

The logic becomes a bit complicated as you can see.

I’m hoping to have most of this encapsulated into the JSScripting library but for now we have to do it ourselves.

The JavaScript would look something like this.

var lessThan = function(op1, op2) {
  if(op1.class == QuantityType.class || op2.class == QuantityType) {
    if(op1.class == QuantityType.class && op2.class == QuantityType.class) {
        return op1.compareTo(op2) < 0;
    else if(op1.class == QuantityType.class) { // If op2 isn't a QuantityType convert it to one using the units from op1
        return op1.compareTo(new QuantityType(op2, op1.getUnits()) < 0;
  else {
    // do the comparison normally

The above isn’t complete but it kind of shows the logic we’d need.

The “5 w” type block would turn into

new QuantityType(5, "w")

So in the above, if the 5 were replaced with 5 “w” then the first if in the function above would run and the comparison would be done with units. In all other cases where one or the other operand has units we need to convert the one that isn’t units to have units, or strip the units off of the one with units.

That’s the next best place to put it I think. It will only ever have content that is related to Items or Things.

We need to include event.channel I think. The rest can be left out. Many of them are not supported anyway.

No, newState, and previousState return a State and receivedCommand returns a Command. For example, if a Number Item changed, newState and oldState would be DecimalTypes.

1 Like

Unfortunately I need to come back to the event-Block because if want to return anything back different from String then we need to think about it more in depth and we should not mix that up with the comparison thing above because that would it make even harder.

        ['newState', 'itemState'],            // Change and Updated Event -> State => String or State-Type?
        ['previousState', 'oldItemState'],    // Change and Updated Event -> State =>  String or State-Type?
        ['triggering item name', 'itemName'], // all -> String
        ['type', 'type']]),                   // all -> String
        ['receivedCommand', 'itemCommand'],   // Command -> has attributes but hard to handle the different attributes per type => String
        ['channel', 'channel'],               // ChannelTriggeredEvent  -> has attributes but hard to handle the different attributes per type => String

Look at the comments above

The first two return a State-Object which in OH is basically a type. A type has several subclasses all of which have different methods. Most methods of those types should not be of any interest (like OnOff, Decimal…) as the only thing you would probably want is the value anyway. HSBType does have getters for RGB but that is pretty specific. A State-Block would need to have a “free-attribute” name or you would have to provide the State-Type and from there it could “intelligently” tell which attribute would be available as an attribute.

Note that these can be undefined in case it is CommandEvent.

So in summary at least for the time being I would not implement a Blockly-State-Block which would provide a state back but just return String and name that field “state value”. Later we could provide the state as well that would feed into a block that takes that state and with choosing the expected type it would allow you to retrieve specific attributes for that block (we could also make that an individual block as it returns a different type State then)


Type and Name
Are just Strings. Type actually provides the “short name” of the types class

is only available when the channel was triggered
This is actually a Subtype of Event which has the name attribute and a type which we already have. As the only interesting information is the channel name, I would not give back the channel object but again a String that contains the channel name only.


event.event doesn’t exist actually. We could return “event.” in the code and something (any attribute or method) could be added as a free string but if there was anything we would need that is not covered above in any of the fields for one of the event’s subtypes we should rather explicitly provide them as an attribute in this block here like the channel.


Hopefully you say “Yes” to all because then I would be able finish that topic tonight and can provide a PR by tomorrow which should not be too big for Yannick to review and merge soon (it contains some very minor fixes and additions).

PS: The comparison topic will be only tackled next year (or maybe over the winter holidays). I really want to put some major thoughts into that before doing it.

I’d call it “state string” to be clear that we a reworking with Strings.

My only concern is you can’t do number comparisons and math with a String and that’s a pretty big need.

If I can’t do something like event.itemState > 20 or event.oldItemState > event.itemState that’s a pretty big limitation.


event.event exists sometimes when a rule is triggered by an event Channel and it contains information about the event as a String. We can’t skip this but you don’t need to do anything special about it. Just return it as it is and specify it as a String.

Oh sure, I think that should work because as mentioned further above Javascript is rather resilient to this. If you compare a string with a number (like I described in my ‘own bug’ that I files about that) that comparing is working as JS coverts the string into a number… but to be very sure in this case I do a test case after the implementation.

One thing to be careful of though is that probably won’t work in JSScripting or when using strict.

I’ve been spending a lot of time working with JSScripting and that’s one place where I ran into trouble. We will have to get Blockly to support JSScripting at some point so if we can avoid extra pain later it’s worth at least consideration.

For the short term though if it works in Nashron as Blockly is generating it then that’s fine by me.

Yep, then this is a general program not only at this place. We will have a look as soon as we work on GraalVM. I am sure that Yannick has that somewhat on the roadmap.

Back to work - the PR will come soon :wave: @ysc

I think he already has a PR started and I posted a couple tutorials. It’s not too bad really making something work and I learned something here that I didn’t know about which might make it even better (namely event.type) in some cases.

I started a tutorial over at Migrate from Nashorn to JSScripting for UI Rules. To start I would think Blocky would use the Object.require approach so the differences between Nashorn and JSScripting are minimal. Long therm though I think a number of things that will exist in the Helper Library could make the Blocky implementation easier. I think the biggest gotcha is Thread.sleep breaks and there is as of yet no alternative. That and the String issue are the two big gotchas.

For example, what if the library provided a method to compare two States or compare a State to anything and as long as they are compatible it will give the right answer? That should make your job with the comparison stuff easier I would think.

Will the helper library be part of openhab by default?

Not having sleep is really a big deal breaker. I am sure a lot of people are using it. The problem is that I just quickly researched that topic that this was actually a design session not to have multi-Threading.

Yep. It’s embedded in the add-on now. :slight_smile:

Yes but the usual work around is to do a Promise and await but that only works when you have a loop which normal JS in the browser and Node have but seems to be lacking in GraalVM JavaScript. So you make the promise and try to await and the rule just exits.

We might have to do something ugly in the library like a busy while loop. It’ll be super ugly though because we can’t even yield or nice the loop so it will spike the CPU while “sleeping”.

Here are the final blocks and I can confirm that the comparison works (I used a number = Decimal Type state)

The blocks also have tooltips that tell the user with which events the blocks to use, e.g.

@ysc here is the PR to be reviewed and merged.


Hi Rich,

I need your feedback. We have an issue in the timer handling and there is a bug to it: [BLOCKY] reschedule block triggers only once · Issue #1214 · openhab/openhab-webui · GitHub

It has to do with your proposal to set the timers to undefined. Either I misunderstood something and implemented it wrong or we have an issue that has to be fixed.

See the following

The intention is obvious: it should start after 5 seconds and retrigger over and over again but it doesn’t … and I will explain why…

First let’s make this simpler first by taking out the manual retrigger in the timer like so:

which generates the following code:

1 if (typeof this.timers['MyTimer'] === 'undefined') {
2  this.timers['MyTimer'] = scriptExecution.createTimer(zdt.now().plusSeconds(5), function () {
3   logger.error('timer triggered');
4   this.timers['MyTimer'] = undefined;  // see THIS HERE
5  })
6 } else {
7 this.timers['MyTimer'].reschedule(zonedDateTime.now().plusSeconds(5));
8 }

As far as I remember you wanted to reset (=undefined) the timers after having used it, so I implemented it to appear in line 4.

The problem is if I put back the manual reschedule

it is added before line 4 from above (becoming line 7) and then the whole thing doesn’t work anymore because upon entry in line 4 it is undefined and then line 5 won’t be executed (which is good because it would result into an NPE anyway)

1 if (typeof this.timers['MyTimer'] === 'undefined') {
2 this.timers['MyTimer'] = scriptExecution.createTimer(zdt.now().plusSeconds(5), function () {
3    logger.error('timer triggered');
4    if (typeof this.timers['MyTimer'] !== 'undefined') {
5       this.timers['MyTimer'].reschedule(zdt.now().plusSeconds(5));
6    }
7    this.timers['MyTimer'] = undefined;
8  })
9 } else {
10  this.timers['MyTimer'].reschedule(zonedDateTime.now().plusSeconds(5));

So the only way to fix this is to remove

this.timers[‘MyTimer’] = undefined;
from the generated code but I remember you wanted to have this for a good reason…

It needs to be an if/else.

if (typeof this.timers['MyTimer'] === 'undefined') {
this.timers['MyTimer'] = scriptExecution.createTimer(zdt.now().plusSeconds(5), function () {
   logger.error('timer triggered');
   if (typeof this.timers['MyTimer'] !== 'undefined') {
   else {
     this.timers['MyTimer'] = undefined;
} else {

If one is going to create a looping timer, there really needs to be additional criteria to determine whether or not to reschedule or not or else the timer will loop forever. The user must define some other test (e.g. an Item reaches a given state, a certain number of loops have been performed, a certain amount of time has passed, etc.).

A looping timer is a pretty advanced need so I don’t know how much we need to spend on supporting them right now. The more I think about it, it’s probably going to require a whole new block to generate that if/else construct. There really is no way to code a looping timer without that sort of construct.

Removing the setting of the timer back to undefined breaks a bunch of other more common timer use cases.

1 Like

While thinking about finding a solution I wonder of that makes sense because isn’t “this.timers[‘MyTimer’]” in line 6 undefined already because it is the else branch of !== ‘undefined’?
So why would I set it to undefined if is already undefined?

I think the right thinking is that want to suppress the setting to undefined only in case I reschedule a timer? :thinking:

Here is a less theoretical example of a looping timer.

var count = 5;
var this.timer['MyTimer'] = ScriptExectution.createTimer(zdt.now().plusSeconds(5), function() {
    if(count > 0) {
        count = count - 1;
    else {
        this.timers['MyTimer'] = undefined;

Compare that to your code. You’ve missed the whole inside the Timer function part of it all.

But now you have to consider the case that the Timer exists and is counting down when the rule is triggered again. So we add:

if(this.timer['MyTimer'] === undefined) {
  var count = 5;
  var this.timer['MyTimer'] = ScriptExectution.createTimer(zdt.now().plusSeconds(5), function() {
    if(count > 0) {
      count = count - 1;
    else {
        this.timers['MyTimer'] = undefined;
// else do nothing

If the timer doesn’t exist (i.e. is undefined) when the rule runs we initialize a count variable. We create a looping timer. *Inside the function that the timer runs we check to see if it’s run five times. If not, we decrement the count and reschedule the timer. If it has we set the timer to undefined and are done.

If the timer does exist when the rule runs we do nothing. Of course, if the timer did exist you could cancel the old one and start a new one. That’s a valid use case to.

But the key point is inside the body of the Timer you have two choices: reschedule or exit. The User needs to define under what circumstances the timer is rescheduled (or conversely when the timer should stop looping).

It’s not as simple as not setting the timer to undefined when looping and setting it to undefined all other times.

NOTE: the count variable is just an example. A user may want to wait for an Item to reach a certain state, or a certain amount of time to have passed, or some other criteria.

Hi Yannick,

I only today stumbled over something that really took me quite a while to find out why it didn’t work and I wonder how we can improve this.

I took the following block

and then I used the cog to add a value like so

and ended up having this

then I tried to attach a value like so

but it wouldn’t connect. I even looked into the code and didn’t find a setCheck that validates the block type. There isn’t any. The problem is completely different and completely unobvious.

You must not use the default dictionary block (the shadow block, that is) that comes with the run script

Instead you have to bring in a new dictionary block (which by the way has a darker color than the shadow_block)

and then everything works as expected

Do you have any idea what the root case is that the shadow block doesn’t behave like the real one and what we can do to guide the user more clearly the s/he must add a real dictionary first before it will work?

At least we should make this clearer via the tooltip, I think.