View source for Blockly


==Introduction==
Blockly is an simple way to get started with automation and scripting in Domoticz.
It's not as powerful as LUA and the other types of scripting that can also be used but an easy start
<br>
[[File:blockymonday.PNG]]
<br>
This is how a script could look.
<br>
Blockly framework is developed by google.
[https://en.wikipedia.org/wiki/Blockly Wikipedia]

==Getting started==
First you need to have set up your system with some sensors, switches and such.

Go to '''Setup -> More Options -> Events''' in this view you see a "+" sign in a tab to choose what script you want to write.

In top right corner

*Choose Blockly as scripting language
*Give your script a name
*Select when this script should be triggered: All/Device/Security/Time. Choose '''Device''' for now

[[File:Blockly_example.png]]

From top left corner

*Start scripting by dragging in an "If/Do" block from the control area. The "If" part is your set of criteria that will trigger what happens under "Do".
*Drag a compare block to the "If" part of your block. (top one under logic).
*Drag a device from the devices area to the first part of the compare block. (You can then change the device from the dropdown.)
*Drag the the "On" block to the second.

In the "Do" connection you can either place a set block from the logic area and/or a notification block from the messages area.<br>

*So drag a "Set block to the "do" section
*Drag a device and On/Off block to the set block.

[[File:Blockly example duplicate on switch.PNG]]
<br>
You should have a block looking something like this now. Quite unusable but a start 

*Choose Event active and push Save.

Now you probably want to turn off the device too with some other event. Well there is an "Else-if statement for that where you can create multiple If statements.

==Triggers==
'''All'''<br>The script will be triggered by all possible triggers as mentioned below. This will mean the script can be triggered a lot so be very careful to use this option as it could slow down domoticz!

'''Device'''<br>
If a change on a device like a switch should start the script. Use "Device"
Ex. Turning on a light after sunset. the switch(device) trigger the script and you can check if time is after sunset to trigger something.

'''Security'''<br>
A change in Security status triggers the script to run.

'''Time'''<br>
If time should start evaluation of a script (each minute). Use "Time"
Ex. At sunset check if all doors are closed to trigger a reminder. The main event here is time=sunset ant therefor time is what should trigg the script to run. if you would use device as trigger for the same script it would check if you closed the door and then if time is at sunset.
 
'''UserVariable'''<br>
A change in a UserVariable triggers the script to run.

==Logic blocks==
===Control===
Control block to contain a action/reaction<br>
[[File:Blockly control.PNG]]
 '''Notes!'''
 An if statement within an if statement (aka nested if statements) is not supported by the interpreter.

====If Else====
If you need more than one "if" this is what you use. You can't stack "If" control blocks but you can make an extended block by using the Else-if.<br>
Open the Blue gear popup and drag the "Else if" to the bottom of "If" and you get an extended control block.<br>
[[File:Blockly control elsif conf.PNG]]

 '''Notes!'''
 Else-if just works as stacked "If". All of the comparison rules are executed and not as in other languages as one or the other.
 You can not stack multiple "If"-statements after each other. You need to use an "Else-if" block.

===Logic===
Logic blocks are used to compare and set values in for example an "If" block<br>
[[File:Blockly Logic.PNG]]<br>

 '''Compare'''<br>
 [[File:Blockly logic comparator.PNG]]<br>
 This block setup checks if Temperature sensor "Badrum" is 10 or above and if either "Nexa ch3" is on or "Nexa ch4" is not at level 0 to be true.<br>
 Pseudo code. (Badrum >= 10) AND ( (Nexa_Ch3==On) OR (Nexa_ch4!=0) ) <br>
 This can be used in the "If-Block" under "If"

 '''Set'''<br>
 [[File:Blockly logic set.PNG]]<br>
 This block sets "Nexa ch4" to 23% dim level and after 10 seconds "Nexa ch3" to On
 This can be used in the "If-Block" under "Do"<br>
 Only use "Set" for switchable/dimmable devices.

 '''Note, External/Inline inputs'''<br>
 [[File:Blockly logic and inline external.PNG]]<br>
 If you right click on a block with multiple inputs, You can choose how the inputs should look by setting inline/external inputs.<br>

===Time===
Check if time events are true<br>
[[File:Blockly time.PNG]]<br>

 '''Compare'''<br>
 If you use Time as trigger for your script the evaluation of time would be:<br>
 First row triggers on Sunrise.<br>
 Second row triggers all day between 00:00 and 15:00. it should be combined with another condition if you don't want it to trigg continuously.<br>
 [[File:Blockly time compare.PNG]]

===Messages===
[[File:Blockly messages.PNG]]<br>

 '''Send message'''<br>
 [[File:Blockly message send.PNG]]<br>
 You can use expressions in your notifications/email and SMS messages like: (Where 1234 is the [[Idx]] of the sensor)<br>
 Example. "My temperature is <nowiki>{{temperaturedevice[1234]}}</nowiki> degrees, and the humidity is <nowiki>{{humiditydevice[1234]}}</nowiki> %"<br>
 Possible expressions: ''temperaturedevice, dewpointdevice, humiditydevice, barometerdevice, utilitydevice, weatherdevice, raindevice, rainlasthourdevice, uvdevice, winddirdevice, windspeeddevice, windgustdevice, variable''

 '''Message formatting'''<br>
 You can use basic HTML formatting in for example e-mail messages.<br>
 Examples:
 Line break: <nowiki><br></nowiki><br>Bold text: <nowiki><b>This text is bold</b></nowiki>
 Images: <img src="img_girl.jpg" width="500" height="600">
 Hyperlinks: <a href="<nowiki>https://www.w3schools.com</nowiki>">Visit W3Schools<nowiki></a></nowiki>
 Tables:
 <nowiki><table style="width:100%"></nowiki>
   <nowiki><tr></nowiki>
     <nowiki><th>Firstname</th></nowiki>
     <nowiki><th>Lastname</th></nowiki> 
   <nowiki></tr></nowiki>
   <nowiki><tr></nowiki>
     <nowiki><td></nowiki>Jill<nowiki></td></nowiki>
     <nowiki><td></nowiki>Smith<nowiki></td></nowiki>
   <nowiki></tr></nowiki>
   <nowiki><tr></nowiki>
     <nowiki><td></nowiki>Eve<nowiki></td></nowiki>
     <nowiki><td></nowiki>Jackson<nowiki></td></nowiki>
   <nowiki></tr></nowiki>
 <nowiki></table></nowiki>

===Security===
[[File:Blockly security.PNG]]<br>
The Security panel is only an advanced button with a couple of states. The rest of the logic for an alarm needs to be written by you. This device gives you the status of the security panel.

<br />

===Debug/Log===
This block is very useful for debug. Put a text block in the debug block or a switch/sensor or so and print it to the log to see what it does or what the status of a sensor is.<br>
[[File:Blockly log.PNG]]

===Devices===
Device blocks have a pull down with all the available devices of that type in your Domoticz server.

====Switches====
[[File:Blockly devices switch.PNG]]<br>
Switch devices can be used with the "Set" block and also compare.

====Temperature====
[[File:Blockly devices temp.PNG]]

====Humidity====
[[File:Blockly devices hum.PNG]]

====Dewpoint====
====Barometer====
====Weather====
====Utility====

====User Variables====
You can set up [[User_variables]] (in Setup -> More options -> User Variables) and access them in blockly.)<br>
To use a variable as an On/Off type set it up as String and give it a current value of "Off"<br>
[[File:Blockly user vars.PNG]]

====Scenes/groups====
[[File:Blockly devices scene.PNG]]

====Cameras====
[[File:Blockly devices cameras.PNG]]

====Setpoints====
[[File:Blockly devices setpoint.PNG]]

====Zwave Alarms====


==Activate the automation==
You just need to save it as "on"

==Tips and tricks==
I have tested nested booleans up to "if ((devicea = on and deviceb = on) and (devicec = off and deviced = off)", theoretically it should do larger ones but that will only make it harder to follow the event anyway.

In the "do" connection you can either place a set block from the logic area or a notification block from the messages area. Only set switchable devices (i.e. not a thermometer) or notifications. There are three set blocks:
 1. Normal set: just switches the device
 2. Set for x minutes: switches the device back to its opposite state after specified amount of minutes 
 3. Set random within x minutes: switch a device somewhere random within the specified number of minutes.  
To specify the number of minutes use the number block in the logic area.

Triggering mechanism: As with the scripting logic, the blockly events are triggered by:

*time: every minute, the system checks all blockly rules that mention a time condition and evaluates them.
*device: if a device changes state for whatever reason, the system checks all blockly rules to see if the device is mentioned and then evaluates the "if" condition(s).

Stuff to keep in mind:

(if weekday > wednesday) set lamp=on will set the lamp on every one minute from thursday through tuesday. So always put on a second check, for instance (if weekday > wednesday and lamp = off) set lamp=on

Try to avoid single if statements.

The same event will not fire unless the previous one completes. If an action is set using "Set For x minutes" or "Random within x minutes" or "Set After x seconds", the same event will not schedule until the first one completes.

User variables can be checked and set using the compare and set blocks. Use the numeric and string fields (available in the user variables box) to compare and set them. Keep the type of variable in mind (e.g. for an integer variable use the numeric box to check and set it).

To learn the basics on how to use Blockly, try the examples found here: http://blockly-demo.appspot.com/static/apps/index.html
==Examples==
 Set a dummy switch called "Post" to On only when magnet sensor "$POSTBOX" changes to On<br>
 Post indicator needs to be reset manually when postbox is emptied. (Using the $-sign in the device name hides the magnetic device from the switches view)
 ''Set trigger to Device''<br>
 [[File:Blockly example postbox.PNG]]<br>

 Set a Dummy Dawn Sensor(called Natt) based on Sunset/Sunrise
 ''Set trigger to Time''<br>
 [[File:Blockly example dawn.PNG]]<br>

 Let Kodi control some lights depending on if it's Paused, playing Video or Audio
 ''Set trigger to Device''<br>
 [[File:Blokly example kodi.PNG]]<br>

 Utilize S2 momentary switch on fibaro dimmer2($KökS2) to toggle a group of lights
 ''Set trigger to Device''<br>
 [[File:Blockly example s2 switch group.PNG]]<br>
 Script uses a variable called kitchenswitch (string) to toggle between states.

===More examples===

*[[Wakeuplight]]
*[[Alarm_Setup]]
*[http://www.domoticz.com/forum/viewtopic.php?f=15&t=31&start=60&hilit=blocky Blockly examples]

[[Category:Blockly]]
[[Category:Scripting]]