Fibaro Lua Scenes

Scenes allow automated actions to be conditionally processed when status change reports are received from sensors or on a pre-defined timer basis. Scenes can also be triggered manually to provide assistance in complex or multiple step processes e.g. turn on power to the TV, switch the TV on and dim the lights. Scene logic can be "Magic (simple)", "Graphic Block" or "Lua".

Lua as a full programming language enables complex conditional processing based on input from and interrogation of multiple sensors e.g. if first the garden sensor and then within 10 seconds the backdoor sensor are breached someone has just entered the house via the backdoor. This ability provides for better automation, in this example we have both direction (into the house) and we have a sensor double check (in case insects are triggering the garden sensor again!).

Scene Triggers

A Lua scene identifies to the Fibaro API exactly which triggers should cause the scene to run using a %%trigger_name statement and if necessary on the following lines parameters (filters) for the trigger, all within Lua comments, see the examples below.

--[[
%% autostart
%% globals
TimeOfDay
--]]
or
--[[
%% properties
39 power
--]]

Trigger names can be:

Devices
Globals

Use the buttons to the right for expanded descriptions of these statements.

Note that a scene will be invoked on each occaision that the trigger criteria are met. A wall plug for example may trigger a power dependent scene multiple times as an attached device is switched on and reaches normal operating power usage. You define how many concurrent copies of the scene may run, when this number is exceeded you will receive the too many instances error message. Testing is normally required to ensure that the trigger condition desired is the one being processed e.g.

  if ( power < 100) then
    fibaro:abort();
  end;

Will exit a scene if it was entered at some intermediate power usage level during device power up. The scene drops through the condition if it has been triggered for a power above 100W when presumably the attached device has completed power up. The number of times the scene is triggered will be dependent on the number of z-wave reports from the wall-plug and this number can be affected through the advanced wall-plug parameters in the device configuration.

  if ( fibaro:countScenes() > 1) then
    fibaro:abort();
  end;
  fibaro:sleep(10000);

If the above scene were long running e.g. it sleeps for some seconds, then we can check for concurrent trigger processing due to triggers at say 120W and again at 200W as shown in the example to the left.

Lua Functions for Scenes

FunctionDescription
fibaro:getSourceTrigger(); Returns a table identifying the resource associated with the scene trigger. Values returned are as follows:
Requested TriggerReturned Value(s)Reason scene was started
%% autostarttype:autostartHome Center has started or the scene has been modified and saved.
%% globals
variable_name(s)
type:global
name:
The named global variable has had its value changed.
%% properties
device id and property
type:property
deviceID:
propertyName:
The named property for a device has changed. Device's id and the name of the property that has changed are provided.
type:otherThe scene has been manually triggered.

In the following code snippet we test for being triggered due to a power change on the TV. In which case we record the actual power consumption in variable tvPower.

--[[
%% properties
77 power
--]]
  local idTV = 77;
  local tvPower;
  local trigger = fibaro:getSourceTrigger();
  if (( trigger['type'] == "property")
     and ( trigger['deviceID'] == idTV )) then
     tvPower = tonumber(fibaro:getValue( idTV, "power"));
  end;

Note:

  1. This technique is most appropriate when we have multiple devices in the trigger list. As it stands the scene will only run when device 77 has reported a change in power usage.
  2. Although we assign the device ID 77 to idTV, unfortunately we still have to hardcode 77 in the trigger list.
fibaro:getSourceTriggerType();

Returns only the type value (as listed above). May be used when trigger has n o associated parameters or when only a single device or variable may trigger the scene, the device or variable name then being implicit to the trigger.
Example:

if ( getSourceTriggerType() == "autostart") then
    fibaro:abort();
  end;
fibaro:abort();Terminates current scene processing.
fibaro:countScenes() Returns the number of copies of this scene that are active, including the current scene. Multiple simultaneous copies of a scene run when the scene takes longer to complete than the time between trigger events.
fibaro:sleep(milli-seconds); Suspends the scene for the number of milli-seconds specified.

Additional Scene Functions

fibaro:countScenes(sceneID) Returns the number of running copies of the specified scene. Multiple simultaneous copies of a scene run when the scene takes longer to complete than the time between trigger events.
fibaro:startScene(sceneID
[ , { table } ] )
Starts the specified scene optionally passing parameters in a table (see Calling a Scene below for details). It is often useful to record the required sceneID in a global variable say myTestSceneID and then use the function fibaro:startScene( fibaro:getGlobalValue( 'myTestSceneID'));
fibaro:killScenes(sceneID) Kills, terminates all running instances of the specified scene.
fibaro:setSceneEnabled(sceneID,
[ true | false ] )
Enable or disable the specified scene.
fibaro:isSceneEnabled(sceneID) Returns true if the specified scene is enabled, otherwise false.
fibaro:setSceneRunConfig(sceneID,
[ 'TRIGGER_AND_MANUAL' | 'MANUAL_ONLY' | 'DISABLED' ] )
Sets whether the scene can be triggered, run on request or not run at all. This is the "Run Scene" parameter on the Scene's General tab with options Automatic, Manual or Disabled
fibaro:getSceneRunConfig(sceneID) Returns a string containing one of the setRunConfig() parameter options.

Calling a Scene

Using the fibaro:startScene() function it is possible to call another scene, this function will also work from a virtual device. The code snippet below illustrates how to use the startScene() function and pass data parameters across to the other scene.

  fibaro:startScene(71, {"Charlie","Chaplin"});

Above is the call to scene 71 with a table containing two parameters for use by the scene. Note: the scene id is available on the general tab of the target scene.

--[[
--]]
  if (fibaro:args()) then
    local nameFirst, nameLast = fibaro:args()[1], fibaro:args()[2];
    fibaro:debug("Welcome "..nameFirst.." "..nameLast);
    fibaro:debug( string.format("Welcome %s %s", nameFirst, nameLast));
  end;

The called scene first checks for a passed table and then uses the supplied parameters. Note the two fibaro:debug functions write the exact same message to the log. The string.format() function will be familiar to C programmers (think printf) and this option is less overhead compared to concatenating the variables one at a time.

 

Devices
Next
API Ref.
Contents