[HC2] Getting started with Lua

Description

You’re already an expert in creating Magic and Block scenes? Do you want to start making scenes in Lua? This article will show you how to do it!

 

Getting started with Lua

Introduction

To create a scene go to the – > Scenes tab -> Add scene -> Add (Add scene in Lua section)

As you can see some part of the code is already written. Each scene written in Lua should always have a form:


This part is called header. The header is absolutely essential for any scene and is used to define what actions will automatically run the scene. Under the heading %% properties are defined devices’ properties- every change in their value will trigger the scene, under the heading %% events you can find events that will trigger the scene and under the heading %% globals are defined global variables – every change in their value will trigger the scene.

 

Code editing window

The script can be typed in the code editing window. In Lua, type the commands, as in other programming languages in the lines below each other.
If you already know other programming languages, this line does not terminate any sign, although Lua ignores the semicolon at the end of the line, so you do not have to get rid of habits acquired from other programming languages requiring that symbol.

 

Devices

In the Home Center 2 interface, all available devices are characterized by:

type – the type of the device (for ex. binary_light or smoke_sensor).
properties – (for ex. value, dead) – illustrate the current state of the device, the device properties are read-only information such as (Motion Sensor is breached, the on/off switch is on and the shutter is open).
actions – (for ex. turnOn, turnOff) – it represents what actual actions can be performed on the device.
deviceID – unique device number in Home Center 2 database.

The first three deviceID numbers are reserved for:

1 – Home Center
2 – Admin
3 – Weather

For example, if we have a Relay Switch module, we can Turn it ON (turnOn action) or Turn it OFF (turnOff action).
If we have dimmable light we can turn it on, for some exact level (for example for 50%), which is represented by action setValue().

 

Scenes

Using Lua language allows us to program any control algorithm.
First, we will create the simplest possible scene, which will be simple switching on the device.
The function takes at least two arguments:

deviceID – the mentioned device ID
actionName – actions you can perform on the device (ex. turnOn, turnOff, setValue)

 


The phrase “–turn ON function” is a comment and it will be skipped during the execution of the script (The headers are a special case – this place does not apply to comments).
Comments are very useful when writing and analysis of the code, especially when you read it later or another person analyze it. It is good to use comments.

To run the scene it should be saved (SAVE button) and then you can start it up pressing START.
In this way, you can also run this scene from mobile interfaces. It will turn ON the device every time when you will click the RUN button.

 

In this script, we will create a scene that turns OFF the device.
To turn off the device we will use again the same function fibaro:call().
The only difference is that you will choose another action, which will be ‘turnOff’.


 

Now we will create a scene which turns on the device, wait for 3 seconds and turns it off.
To call the time delay we will use fibaro:sleep() function.
Time 3000 is expressed in milliseconds (1s = 1000ms).


The top part of the code is a header, the rest are functions fibaro:call and fibaro:sleep. This scene sends request turnOn to device with deviceID=20, then waits for 3 seconds and sends request turnOff.

 

Debugging

The basic mechanism of almost every programmable languages is a debugger. Debugging is a very useful tool.
Debugger output is printed in the black box below the code, it will inform you about mistakes in syntax or errors.
Debugger does not automatically inform you about mistakes in script logic.
Lua is executed line by line. In the first place, the instructions from the header and then line by line script code is executed.
To check if script arrived at some line, print some message or variable value you can use fibaro:debug().
Let’s create a script containing a simple debugging mechanism:


In this case, scene will only return the string: “Hello world!”.

 

Pass value to a function

Let’s say we have FIBARO Relay Switch with deviceID=15. Type of this device is binary_light. Devices of this type may have several different properties to set. At this point, the most important property for us is “value”.

“Value” is a device property, which contains device state. If value=0 device is off, if the value=1 device is on. To get value from the device you have to use appropriate Lua function. In this case:


Next step will be learning of basic mechanism of programming languages – variables. They store values to use them further. To use a variable in Lua we must declare it:


These commands declare a variable named myValue, and in the next line we assign this variable a value of 20.
If we want to use the device property value, we need to assign a value to the variable.


Now it stores myValue variable stores value of property named “value” for devices with ID 15.

Example of using variable to get device value:

IF-THEN conditional statement

Now you will learn next element of programming languages which is called IF-THEN conditional statement. Conditional statement is a feature which performs specific action depending on declared condition. For example IF deviceID=13 is turned On THEN turn Off deviceID=5.

Every IF-THEN conditional statement has following syntax:


Let’s create a simple IF-THEN conditional statement:


In the first step, we declare a variable named myVariable. Next, system turn on the device with deviceID=14. Then to the myVariable variable system assigns value=1. The next step is to check the condition.
You can use different relational operators to compare to value, eg. value1==value2 is true if both values are equal, value1>value2 is true if value 1 is greater than value2.
If the condition is met (value = 1), then the script goes to the next line and enables the device with deviceID = 7. If condition is false (value=0) then script will omit code between “then” and “end” and finish the script without turning the device on.

Example of using IF-THEN conditional statement in the scene. This scene will switch off the thermostat when the window is opened.

Scene triggered automatically

All previous scripts before had one common feature – single time execution. These scripts worked only when we pressed START button. Of course there are scenes that should be triggered only by the button, but mostly the conception of scenes is that they should be triggered automatically based on e.g. other devices states.
To turn on the scene automatically we need to declare a trigger. Triggers are events that call the scene for script execution.

Trigger “property” informs the scenes engine, that our important property of the device is changing and scene should be executed. We declare it in the header. Trigger using change of property has following syntax:
[deviceID] [property]


It declares trigger for property named “value” of device with ID 50. From now on, every time if the value of device with 50 changes – scene engine will execute the script.

Let’s make a scene triggered automatically:


The scenes triggers every time value of device with ID 50 changes, then if value is equal to 1 it turns on device with ID 13 or turns it off otherwise.

Code hinting

If you are not sure what actual actions your devices can execute you can also preview and use them from the Home Center 2 interface while creating new Lua scene.

Clicking on the action will generate a code for chosen action.

For example, when you click turnOn() action, following code will be generated.

If you’re not sure how to write some part of the code you can make a block scene which works the same and then convert it to the Lua scene.

Find some more Lua scene examples.

 

December 14, 2018   41214    Tutorials    
Total 35 Votes:
6

Tell us how can we improve this post?

+ = Verify Human or Spambot ?

Comments are closed.