FIBARO Lua Scenes

General information

In Home Center 3 you can create two types of scenes:

  • Block scene – created using visual drag and drop interface.
  • Lua scene – created using Lua script language in provided code editor.

In this document, we’ll cover Lua scene creation.

Editor

The editor is divided into 3 parts:

  • CONDITION – in this section we implement the triggers and conditions, under which the scene will be started.
  • ACTION – in this section we implement actions that should be performed when the triggers and conditions are met.
  • Debugger – displays debug messages sent by your code. You can filter messages by assigned tags.

To create a Lua scene you must add at least one action. Such a scene can only be started manually or by using another scene. Automatic triggering (using triggers) will not be possible.

Conditions

Actions can be triggered automatically (after trigger meeting condition occurs and other scene conditions are met) or manually. After an event occurs in the system (e.g. device is turned on), the scene checks the triggers. Next, all conditions with logical operators joining them are checked.
Single condition can look like this:

Description of individual fields:

  • type – the type of event in the system, the scene is waiting for (all types will be described later).
  • id – optional field, depending on the condition type can be interpreted differently (will be described later).
  • property – the property the scene is waiting to be changed (different properties will be described later).
  • operator – the way of comparing current property value and provided value (will be described later).
  • value – the value of the property the scene expects.
  • isTrigger – indicates whether a given condition is also a trigger. Permissible values are true and false.

Triggers and conditions are stored in one array. Example:

First condition for device with ID 25 is a trigger. Second condition for devive with ID 26 is only a condition.

To join triggers/condition you must use “operator” field. The “operator” field is required even for scenes with one trigger/condition:

Operator field accepts one of two values:

  • any – at least one of the triggers/conditions must be met.
  • all – all of the triggers/conditions must be met.

Conditions can be joined and mixed:

The example above will start the scene if property “value” changes to true for device with id 25 and for at least one of the devices with id 26 or 27.

Trigger vs condition

Distincting between triggers and conditions is done by setting “isTrigger” field appropriately, if the field is not set, it takes false by default.

  1. Trigger (isTrigger set to true) – an event in the system, specified exactly in the scene, which checks the remaining conditions of the scene.
  2. Condition (isTrigger set to false or not set) – the factor on which the stage execution depends.

The first condition for device with ID 25 is a trigger, while the second condition for device with ID 26 is only a condition. This means that if an event occurs that changes “value” property of device 25 to true, the same event will trigger a check of all triggers used in the scenes. Only when the trigger is met (as in the above scene), further conditions (isTriger = false) are checked. Checking the condition means checking that for device 26 the “value” property is set to true. If so, then all the conditions of the above scene (trigger + condition) have been met and the action can be performed.

There may also be a situation, where the “value” property is changed to true for device 26. This situation will also generate event of changing the value value for a given device. However, because the condition for device 26 is not a trigger, the scene conditions will not be checked (even if the “value” property in device 25 was previously set to true).

Types of triggers and conditions

The following chapter will discuss each type of trigger and the conditions that are available in the system.

Devices

For devices, the interpretation of conditions fields is as follows:

  • type – takes value "device".
  • id – takes the ID of the device for which to check if the given property has the given value.
  • property – the name of the property to check.
  • value – value of the property to compare the current value to.
  • operator – depending on type:
    • text type:
      • "==" – are the texts the same
      • "!=" – are the texts different
    • numeric type:
      • "==" – are the values ​​the same
      • "!=" – are the values ​​different
      • ">" – is the current value greater than the one in the condition
      • ">=" – is the current value greater than or equal to the one in the condition
      • "<" – is the current value lesser than the one in the condition
      • "<=" – is the current value lesser than or equal to the one in the condition
    • logical type:
      • "==" – are the values ​​the same
      • "!=" – are the values ​​different
  • isTrigger – is the condition also a trigger:
    • true – is a trigger
    • false – is only a condition (default)

Examples:

Time and date

For time and date, the interpretation of conditions fields is as follows:

  • type – takes value "date".
  • property – takes value "cron".
  • value – is an array of text values whose subsequent elements take the following:
    • minutes – takes value from 0 to 59,
    • hours – takes value from od 0 to 23,
    • day of month – takes value from od 1 to 31,
    • month – takes value from od 1 to 12,
    • day of week – takes value from od 1 to 7,
    • year
  • operator – for differen types:
    • "match" – whether the date matches the date in the condition, in this operator we can use "*" which means any match.
    • "match==" – are the dates the same.
    • "match!=" – are the dates ​​different.
    • "match>" – is the date later than date in the condition.
    • "match>=" – is the date the same or later than date in the condition.
    • "match<" – is the date earlier than date in the condition.
    • "match<=" – is the date the same or earlier than date in the condition.
  • isTrigger – is the condition also a trigger:
    • true – is a trigger
    • false – is only a condition (default)
      With time conditions, you should use isTrigger carefully, especially for time intervals.
      Every minute the system emits an event that results in checking scenes triggers. Inappropriate use of the timer can trigger the scene every minute.

Examples:
Every day at 15:30.

13.06.2018 at 12:30.

Every Monday and Wednesday at 15:30.

Every Monday and Wednesday and Friday.

25th day of every month.

Every day between 9:00 and 10:00. No isTrigger means it is false.

Interval

For intervals, the interpretation of conditions fields is as follows:

  • type – takes value "date".
  • property – takes value "cron".
  • value – consists of 2 fields:
    • date – is the starting date of the interval and is an array of text values whose subsequent elements take the following:
      • minutes – takes value from 0 to 59,
      • hours – takes value from od 0 to 23,
      • day of month – takes value from od 1 to 31,
      • month – takes value from od 1 to 12,
      • day of week – takes value from od 1 to 7,
      • year
    • interval – time in seconds between each execution.
  • operator – takes value "matchInterval".
  • isTrigger – is the condition also a trigger:
    • true – is a trigger (recommended)
    • false – is only a condition (default)

Examples:
Condition true every 5 minutes, starting at 12:00 5.04.2019

Sunrise and sunset

For sunrise and sunset, the interpretation of conditions fields is as follows:

  • type – takes value "date".
  • property – takes one of two values:
    • "sunrise" – sunrise,
    • "sunset" – sunset.
  • value – time in minutes before/after sunrise/sunset:
    • Values lower than 0 indicate how many minutes before sunrise/sunset the scene should start.
    • Value 0 means that the scene should take place at sunrise/sunset.
    • Values greater than 0 indicate how many minutes after sunrise/sunset the scene should start.
  • operator – takes value "==".
  • isTrigger – is the condition also a trigger:
    • true – is a trigger (recommended)
    • false – is only a condition (default)

Examples:
Everyday 60 minutes before sunset.

Everyday 120 minutes after sunset.

Everyday at sunrise.

Weather

For weather, the interpretation of conditions fields is as follows:

  • type – takes value "weather".
  • property – takes one of these values:
    • "Temperature" – temperature,
    • "Wind" – windspeed,
    • "WeatherCondition" – weather condition,
    • "Humidity" – air humidity.
  • value – values depend on used property, available values:
    • Temperature – numerical value, the temperature unit depends on the system settings. If the unit is changed after creating the scene, the scene should be corrected by the user, because after changing the unit in the system, the value will not be automatically recalculated.
    • Wind – numerical value, the wind unit depends on system settings. If the unit is changed after creating the scene, the scene should be corrected by the user, because after changing the unit in the system, the value will not be automatically recalculated.
    • WeatherCondition – text value of selected weather condition:
      • "cloudy"
      • "rain"
      • "snow"
      • "storm"
      • "clear"
      • "fog"
      • "unavailable"
    • Humidity – numerical value.
  • operator – depending on type:
    • text type:
      • "==" – are the texts the same
      • "!=" – are the texts different
    • numeric type:
      • "==" – are the values ​​the same
      • "!=" – are the values ​​different
      • ">" – is the current value greater than the one in the condition
      • ">=" – is the current value greater than or equal to the one in the condition
      • "<" – is the current value lesser than the one in the condition
      • "<=" – is the current value lesser than or equal to the one in the condition
  • isTrigger – is the condition also a trigger:
    • true – is a trigger
    • false – is only a condition (default)

Examples:
True, when temperature drops below 20°C or 20°F (depending on settings).

True, when when wind speed is higher than 15[km/h] or 15[mph] (depending on settings).

True, when weather turns cloudy.

True, when humidity rises above 80%.

Location

For location, the interpretation of conditions fields is as follows:

  • type – takes value "location".
  • property – ID of location the user enters/leaves (numerical).
  • id – ID of the user (numerical).
  • value – takes one of two values:
    • "leave" – user leaves the location
    • "enter" – user enters the location
  • operator – depending on type:
    • "==" – are the values the same
    • "!=" – are the values different
  • isTrigger – is the condition also a trigger:
    • true – is a trigger
    • false – is only a condition (default)

Examples:
True, when user 36 enters location 2.

Custom events

For custom events, the interpretation of conditions fields is as follows:

  • type – takes value "custom-event".
  • property – name of the custom event (text).
  • isTrigger – takes value true.

Examples:
True, when custom event with name "event_name" occurs.

Alarms

For alarms, the interpretation of conditions fields is as follows:

  • type – takes value "alarm".
  • property – takes one of these values:
    • "armed" – check if zone with given id is armed
    • "breached" – check if zone with given id is breached
    • "homeArmed" – check if alarm for whole house is armed
    • "homeBreached" – check if alarm in house is breached
  • id – zone ID, required only for properties "armed" and "breached".
  • value – takes one of these values:
    • true – if alarm is armed/breached for zone/house
    • false – if alarm is NOT armed/breached for zone/house
  • operator – depending on type:
    • "==" – are the values the same
    • "!=" – are the values different
  • isTrigger – is the condition also a trigger:
    • true – is a trigger
    • false – is only a condition (default)

Examples:
True, when zone 1 was armed.

True, when zone 1 was disarmed.

True, when alarm in zone 1 was breached.

True, when alarm in zone 1 was deactivated.

True, when whole house was armed.

True, when whole house was disarmed.

True, when alarm in house was breached.

True, when alarm in house was deactivated.

Gateway startup

For gateway startup, the interpretation of conditions fields is as follows:

  • type – takes value "se-start".
  • property – takes value "start".
  • value – takes value "true".
  • operator – takes one of these values:
    • "==" – are the values the same
    • "!=" – are the values different
  • isTrigger – is the condition also a trigger:
    • true – is a trigger (recommended)
    • false – is only a condition (default)

Examples:
Trigger on every startup.

Profiles

For profiles, the interpretation of conditions fields is as follows:

  • type – takes value "profile".
  • property – takes value "activeProfile".
  • value – ID of profile to check.
  • operator – takes one of these values:
    • "==" – are the values the same
    • "!=" – are the values different
  • isTrigger – is the condition also a trigger:
    • true – is a trigger (recommended)
    • false – is only a condition (default)

Examples:
True, when Profile 1 was set as active.

Akcje

Actions are executed one after the other (except for “fibaro.setTimeout” – described further). Following actions are available:

sourceTrigger

The variable stores the trigger object that started the scene. It results directly from the triggers defined in the previous section, but is extended by a manual start. Type of the trigger is identified by type property, which can be one of the following:

  • manual
  • alarm
  • custom-event
  • date
  • device
  • global-variable
  • location
  • panic
  • profile
  • se-start
  • weather
  • climate

Examples values of sourceTrigger variable.

Manual start

Trigger based on device property change

Property centralSceneEvent for device with id 298 triggered the scene.

Time trigger

Specific time and date triggered the scene.

Trigger based on alarm state change

Arming zone with id 4 triggered the scene.

api.delete

api.delete(uri)

Delete resource using geteway API. Parameters:

  • uri – path to the resource without /api prefix.

Action returns: {response data, response HTTP code}.

Examples:
Delete global variable with name “test”.

api.get

api.get(uri)

Get resource using geteway API. Parameters:

  • uri – path to the resource without /api prefix.

Action returns: {response data, response HTTP code}.

Examples:
Get value of global variable with name “test”.

api.post

api.post(uri, dane)

Send POST method request to the geteway API. Parameters:

  • uri – path to the resource without /api prefix,
  • dane – data to send with the request.

Action returns: {response data, response HTTP code}.

Examples:
Create global variable with name “test” and value “sampleValue”.

api.put

api.put(uri, dane)

Send PUT method request to the geteway API. Parameters:

  • uri – path to the resource without /api prefix,
  • dane – data to send with the request.

Action returns: {response data, response HTTP code}.

Examples:
Change value of global variable with name “test” to value “sampleValue2”.

fibaro.call

fibaro.call(id, action_name, arguments)

Executes an action on the device.
Parameters:

  • id – identifier of the device on which we want to execute the action.
  • action_name – the name of the action we want to execute.
  • arguments – list of arguments that the action accepts.

Examples:

  • Execute “turnOn” action on device with id 30.

  • Execute “setParameter” action on device with id 31 with arguments:
    • parameter number – 11
    • size of the parameter in bytes – 1
    • value of the parameter to set – 128

fibaro.call(ids, action_name, arguments)

Executes an action on devices.
Parameters:

  • ids – list of device identifiers on which to execute the action.
  • action_name – the name of the action we want to execute.
  • arguments – list of arguments the action accepts.

Example:
Execute “turnOn” action on devices with id 30 and 32.

fibaro.callGroupAction

fibaro.callGroupAction(action_name, arguments)

Executes an action on the devices.
Parameters:

  • action_name – the name of the action we want to execute.
  • arguments – list of arguments that the function accepts and device filter.

The action returns a list of devices on which it was performed.

Examples:
Calling the turnOn action on com.fibaro.zwaveDevice devices that do not have the battery interface.

fibaro.get

fibaro.get(id, property_name)

Gets value of device property and the date it was last modified.
Parameters:

  • id – device ID for which we want to retrieve the property value.
  • property_name – name of the property which value we want to retrieve.

Action returns: {value, last modification time}.

Examples:
Get the value and the date of the last modification for the value property for device 54

fibaro.getValue

fibaro.getValue(id, property_name)

Gets the value of the given property.
Parameters:

  • id – device ID for which we want to retrieve the property value.
  • property_name – name of the property which value we want to retrieve.

Action returns only value of the property.

Examples:
Retrieving the value of the value property for device id 54

fibaro.getType

fibaro.getType(id)

Gets the device type.
Parameters:

  • id – device ID for which we want to retrieve its type.

The action returns the device type.

Examples:
Retrive type of device 54

fibaro.getName

fibaro.getName(id)

Gets the device name.
Parameters:

  • id – device ID for which we want to retrieve its name.

The action returns the device name.

Examples:
Retrive name of device 54

fibaro.getRoomID

fibaro.getRoomID(id)

Gets the ID of the room to which the device is assigned.
Parameters:

  • id_urządzenia – device ID for which we want to retrieve its room ID.

The action returns the ID of the room to which the device is assigned.

Examples:
Retrieve ID of the room for device 54

fibaro.getSectionID

fibaro.getSectionID(id)

Gets the ID of the section to which the device is assigned.
Parameters:

  • id_urządzenia – device ID for which we want to retrieve its section ID.

The action returns the ID of the section to which the device is assigned.

Examples:
Retrieve ID of the section for device 54

fibaro.getRoomName

fibaro.getRoomName(id)

Gets the room name.
Parameters:

  • id – room ID for which we want to retrieve name.

The action returns room name.

Examples:
Retrive name for room 219

fibaro.getRoomNameByDeviceID

fibaro.getRoomNameByDeviceID(id)

Gets the name of the room to which the device is assigned.
Parameters:

  • id – device ID for which we want to retrieve its room name.

The action returns room name.

Examples:
Retrieve name of the room for device 54

fibaro.wakeUpDeadDevice

fibaro.wakeUpDeadDevice(id)

Wake up the device.
Parameters:

  • id – device ID to wake up.

Examples:
Wake up device 54

fibaro.getDevicesID

fibaro.getDevicesID(filter)

Returns a list of device IDs that match the given filters.
Parameters:

  • filter – the way we want to filter the devices.

fibaro.getAllDeviceIds

fibaro.getAllDeviceIds()

Returns a list of objects of all devices.

fibaro.getIds

fibaro.getIds(devices)

Returns a list of device IDs for given devices.

  • devices – accepts list of device objects.

fibaro.homeCenter.systemService.reboot

fibaro.homeCenter.systemService.reboot()

Restart the gateway.

fibaro.homeCenter.systemService.suspend

fibaro.homeCenter.systemService.suspend()

Put the gateway in Sleep Mode.

fibaro.homeCenter.notificationService.publish

fibaro.homeCenter.notificationService.publish(request)

Publish notification.
Parameters:

  • request – object on the basis of which the notification will be created:
    • type – notification type, one of the following:
      • "FirmwareUpdateNotification"
      • "GenericDeviceNotification"
      • "GenericSceneNotification"
      • "GenericSystemNotification"
      • "MobilePopupNotification"
      • "ZwaveReconfigurationNotification"
    • priority – notification priority, one of the following:
      • "info" – lowest priority
      • "warning" – medium priority
      • "alert" – highest priority
    • data – notification data, depending on type:
      • FirmwareUpdateNotification
        • deviceId – device ID
        • progress – configuration progress (numerical value)
        • info – information about update (text value)
        • status – one of the following:
          • "Available"
          • "QueuedForUpdate"
          • "Downloading"
          • "WaitingForCommunication"
          • "Updating"
          • "UpdateOk"
          • "UpdateFail"
          • "UpToDate"
          • "QueuedForCheck"
      • GenericDeviceNotification
        • deviceId – device ID
        • title – notification title (text value)
        • text – notification description (text value)
        • icon – notification icon (optional), object, accepting the following fields:
          • path – path to the icon
          • source – source of the icon
      • GenericSceneNotification
        • sceneId – scene ID.
        • title – notification title (text value)
        • text – notification description (text value)
      • GenericSystemNotification
        • subType – one of the following:
          • "Generic"
          • "EmailInvalid"
          • "DeviceNotConfigured"
          • "DeviceNoTemplate"
          • "NoFibaroPartitionInAlarm"
          • "ZwavePollingTime"
          • "UserNameDuplicated"
        • name – notification title (text value)
        • text – notification description (text value)
        • url – text value
        • urlText – text value
      • MobilePopupNotification
        • title – notification title (text value)
        • text – notification description (text value)
        • button – table of objects describing buttons and their operation. The object has the following fields:
          • buttonId – button ID,
          • type – button type, one of the following:
            • "STANDARD"
            • "CALL_112"
            • "CANCEL"
          • caption – text value,
          • onPressedAction – action performed when the button is pressed
      • ZwaveReconfigurationNotification
        • taskId – task ID (numerical value)
        • deviceId – device ID
        • status – one of the following:
          • "Pending"
          • "WaitingForWakeup"
          • "Reconfiguring"
          • "Failed"
          • "Canceled"
          • "Successful"
          • "Aborted"
        • name – notification title (text value)

Examples:
Publish GenericDeviceNotification notification.

fibaro.homeCenter.notificationService.update

fibaro.homeCenter.notificationService.update(id, request)

Updates the notification.
Parameters:

Examples:
Update notification 10.

fibaro.homeCenter.notificationService.remove

fibaro.homeCenter.notificationService.remove(id)

Deletes the notification. Parameters:

  • id – ID of notification to delete

Examples:
Delete notification 60.

fibaro.alert(alert_type, user_ids, notification_content)

Send custom notification.

  • alert_type – one of the notification types: “email”, “sms” or “push”
  • user_ids – list of user identifiers to send the notification to
  • notification_content – content of the notification to send

Examples:
Send notification with “Test notification” content using email to users with id 2, 3 and 4.

fibaro.emitCustomEvent

fibaro.emitCustomEvent(event_name)

Emitting Custom Event with the specified name.
Parameters:

  • event_name – the name of the event we want to emit

Examples:
Emitting the event with the name “TestEvent”.

fibaro.debug

fibaro.debug(tag, message)

Displaying debug level text message in the debugging console.
Parameters:

  • tag – message tag, can be used to filter messages
  • message – the content of the message which shows up in the debug window

Examples:
Display “Test message” in a debug window with the tag “TestTag”:

fibaro.trace

fibaro.trace(tag, message)

Displaying trace level text message in the debugging console.
Parameters:

  • tag – message tag, can be used to filter messages
  • message – the content of the message which shows up in the debug window

Examples:
Display “Test message” in a debug window with the tag “TestTag”:

fibaro.warning

fibaro.warning(tag, message)

Displaying warning level text message in the debugging console. Parameters:

  • tag – message tag, can be used to filter messages
  • message – the content of the message which shows up in the debug window

Examples:
Display “Test message” in a debug window with the tag “TestTag”:

fibaro.error

fibaro.error(tag, message)

Displaying error level text message in the debugging console.
Parameters:

  • tag – message tag, can be used to filter messages
  • message – the content of the message which shows up in the debug window

Examples:
Display “Test message” in a debug window with the tag “TestTag”:

fibaro.alarm

fibaro.alarm(partition_id, action)

Executes specified action on one partition.
Parameters:

  • partition_id – partition on which we want to execute the action,
  • action – the action we want to execute. Available actions: “arm”, “disarm”

Examples:
Arm partition no. 1:

fibaro.alarm(action)

Executes specified action on all partitions.
Parameters:

  • action – action to be executed on all partitions. Available actions: “arm”, “disarm”

Examples:
Disarm all partitions:

fibaro.scene

fibaro.scene(action, scenes_ids)

Executes given action on a scene.
Parameters:

  • action – the action we want to perform on scenes, one of the following:
    • "execute" – uruchomienie sceny
    • "kill" – zatrzymanie sceny
  • scenes_ids – list of scenes IDs to perform the action on

Examples:
Execute scenes with IDs 1, 2, 3.

Stop scenes with IDs 1, 2, 3

fibaro.profile

fibaro.profile(profile_id, action)

Executes specified action on the user profile.
Parameters:

  • profile_id – ID of the profile on which we want to perform the action
  • action – the action we want to execute on the profile. Currently, only "activateProfile" action is available (activating the profile)

Examples:
Activate profile with ID 1.

fibaro.getGlobalVariable

fibaro.getGlobalVariable(variable_name)

Get the value of the global variable.
Parameters:

  • variable_name – name of variable to get the value of

Examples:
Get the value of variable testVariable.

fibaro.setGlobalVariable

fibaro.setGlobalVariable(variable_name, variable_value)

Set the value of the global variable.
Parameters:

  • variable_name – the name of the variable we want to update
  • variable_value – the new value for the variable

Example:/
Change the value of testVariable to testValue.

fibaro.setTimeout

fibaro.setTimeout(delay, function)

Performs the function asynchronously with a delay. Parameters:

  • delay – delay in milliseconds after which the specified function will be performed,
  • function – function, which will be executed with the delay.

Examples:
Execute function with 30s delay which turns on the device (ID 40) and sets profile 1 as active.

json.encode

json.encode(table)

Convert Lua table to the text represented in JSON format.
Parameters:

  • table – Lua table

Examples:
Display sourceTrigger in the debug console.

json.decode

json.decode(tekst)

Convert the text represented in JSON format to Lua table.
Parameters:

  • text – data in JSON format

Examples:

Examples

Włączenie urządzenia, gdy inne urządzenie zostanie włączone:

Condtions:

Actions:

Turning on the device with a 30-second delay and sending an email to user 2 with the text Test notification when another device is turned on between 9:00 and 10:00

Condtions:

Actions:

Invert device state

Condtions:

Actions:

Turn on the light (devices 51, 52, 53) when the motion sensor (device 54) is breached but only at night

Condtions:

Actions:

At sunrise open the blinds at 50% and turn on the dimmers at 50%

Actions:

When user 36 leaves the location 2, close the blinds and arm the alarm

Actions:

Get information about visible motion sensors and lights in the default room

Actions:

Turn on watering after pushing the Button with ID 2066 or meeting one of the following conditions: on Monday, Wednesday or Friday at 6:00, temperature is above 3 degrees and is one of the following weather conditions: foggy, clear or cloudy

Condtions:

Actions:

Turn on watering after pushing the Button with ID 2066 or meeting one of the following conditions: on Monday, Wednesday or Friday at 6:00, temperature is above 3 degrees, soil moisture sensor with ID 35 detects moisture below 20%, and is one of the following weather conditions: foggy, clear or cloudy

Condtions:

Actions:

Turn on watering after pushing the Button with ID 2066 or meeting one of the following conditions: on Monday, Wednesday or Friday at 6:00

Condtions:

Actions:

Close the valves and send an email with notification if one of the water sensors has been activated

Condtions:

Actions: