Fibaro Lua API: Devices

Fibaro devices are defined to the Fibaro environment as part of the device dependent installation process. Your device will normally come with instructions for adding it to your Home Center(HC) system. The HC will identify your device through an allocated device ID.

Device IDs

Fibaro allocates one or more unique ids to each physical device. In most cases two ids are allocated, one for the Master and the other for the Slave component. You can think of the Master as being a logical representation of the device within the HC and the Slave as the z-wave remote component. Example: to obtain property values of a wall plug we use the Slave id as the values are from the wall plug itself (as received by the HC and held in its database). If however we wish

to poll the wall plug (to request the DB be updated with most recent information) then we use the Master device id, the HC will know to issue the poll request across the z-wave network to the Slave. Some devices such as the motion sensor have multiple slave ids representing the different components of the device e.g. motion detection, light level and temperature.

You can determine the device id by selecting the device from the devices panel. The ID: value provided to the right of any icon is the Slave id, the Master id is provided in the block diagram below the icon. If you are coding a Lua scene then you will have a device list in the left hand column, hovering with the mouse over the required device will also give the Slave id as well as a list of properties used by the device and actions that the device will carry out when instructed.

Triggering a Scene when a Device changes State

--[[
%% properties
deviceID property
--]]

A Lua scene prefixes the lua code with a comments section containing the Fibaro trigger criteria i.e. when the scene is to be run (triggered). To trigger a scene when a Fibaro monitored device changes state the scene must trigger on properties with subsequent lines identifying the device and the property that must change for the scene to be triggered, as shown to the right.

--[[
%% properties
39 power
--]]

In the example to the left, the scene will be run when the measured power utilisation on a wall plug (specified by device ID 39) changes by an amount defined by the wall plug advanced parameters. The scene can interrogate the device for the actual power usage.

--[[
%% properties
8  value
19 value
24 value
--]]

In this other example the scene will be triggered if one of the motion sensors, device IDs 8, 19, 24 are "breached" or return to "safe" state.

Lua Functions for Devices

As well as providing scene triggers the Fibaro Lua API provides a number of functions that allow a Lua scene to inspect and control devices as follows:

Device Control

FunctionDescription
fibaro:call( deviceID, action) Requests that the specified action be carried out on the device.
Example:
  fibaro:call( 39, "turnOn");
Note that there is an undocumented action "poll" which instructs the master ID to poll the slave for an update in device property values irrespective of the device's reporting parameters. Once polling is complete get() and getValue() will return the updated parameters. Use this function with caution to avoid overloading the z-wave network.
fibaro:callGroupAction( device_filter, action) Requests that the specified action be carried out on each device that matches the device_mask. For details about device masks, see fibaro:getDevicesId()
Example:

Device Interrogation

These are the functions most likely to be used when a scene has been triggered.

FunctionDescription
fibaro:get( deviceID, property) Returns two string parameters, first the value of the requested device property, second the time the property was last reported/modified. Device status reporting will be dependent upon device activity (plug switched on, motion detected, significant change in temperature etc) and the reporting requested through the device's advanced parameters.
Example:
  local value, lastModTime = fibaro:get( 39, "power");
fibaro:getValue( deviceID, property) Returns the value of the requested device property.
Example:
  local value = fibaro:getValue( 8, "value");
fibaro:getModificationTime( "deviceID", property) Returns the timestamp associated with a change to the value of the requested property. Device reporting frequency will be dependent upon device activity (plug switched on, motion detected, significant change in temperature etc) and the report filtering requested through the devices advanced parameters.
Example:
  local lastMod = fibaro:getModificationTime( 8, "value");
  fibaro:debug("Device 8 last updated: " ..(os.time()-lastMod)
    .. " seconds ago");

Additional Device Functions

These functions allow additional system information to be extracted, as follows:

FunctionDescription
fibaro:getDevicesId( { device_mask } ) Searches through the entire list of system ids to construct a map/array of system ids that match the supplied mask table n.b. an empty device_mask = {} returns an array of all device ids. Possible values for device mask are one or more of:
  • properties = {property1 = value}
  • interfaces = {value1, value2, etc}
  • roomId = roomID
  • etc......
See output from http://HC_IP_address/api/devices for a list of possible values for each parameter in the mask.
Example:
  local lastMod = fibaro:getModificationTime( 8, "value");
  fibaro:debug("Device 8 last updated: " ..( os.time()-lastMod)
    .. " seconds ago");
    
  local devMask = {
          interfaces = { "light"},
          roomID = fibaro:getRoomID(45)
        };
  local devArray = fibaro:getDevicesId(devMask);
  for k,v in  ipairs(devArray) do
    fibaro:debug(v)
  end
writes the device id of each device designated as a light in the same room as device 45 n.b. will include device 45 if this is a light.
fibaro:getName( deviceID) Returns the name provided on the device configuration panel.
Example:
local deviceName = fibaro:getName( 39);
fibaro:getRoomID( deviceID) Returns the id of the room in which the device is located.
Example:
  local roomId = fibaro:getRoomID( 8);
fibaro:getRoomName( "roomID") Returns the name of the room associated with roomID. If roomID was obtained for a device via the getRoomID() function then the name returned here is that selected on the device configuration panel.
Example:
function fmtDevText(devID, text)
  local devName = fibaro:getName(devID);
  local roomName = fibaro:getRoomName(fibaro:getRoomID(devID));
  return  string.gsub( string.gsub( text, "#N", devName), "#R", roomName);
end

  fibaro:debug(fmtDevText(idPlug, 'device #N in room #R is: '
    ..(fibaro:get( idPlug, "value") == "1" and "ON" or "OFF")));
Will log a message of the form: "device Desk Light in room Study is ON"
fibaro:getSectionID( deviceID) Returns the id of the section in which the device is located.
Example:
  local sectionId = fibaro:getSectionID( 8);
fibaro:getType( deviceID) Returns the device type as can be found via http://HC_IP_address/api/devices, listed as "Device kind" on the device general panel or simply "Typ" when hovering over an entry in the device list displayed on a scene edit panel.

Listing Device Properties Programmatically

You can create a scene using the lua code below and this will display the properties and values of the device whose id you place in the path variable e.g. path = "/devices/128";

--[[ 
            List Device / Scene Properties 
             
   Supply the global_variable_name or device_id and comment out 
    the redundant path assignment. 
--]]

--   local path = "/globalVariables/global_variable_name";
   local path = "/devices/device_id";

function doTable( tab, indt)
   if type(tab) ~= 'table' then
      print(string.format("%s%s",indt,tostring(tab)))
   elseif tab[1] then
      for i,j in ipairs(tab) do
         doTable(j,indt)
      end
   else
      for i,j in pairs(tab) do
         if type(j) == 'table' then
            print(string.format("%sTable %s",indt,tostring(i)))
            doTable(j,indt.."--")
         else
             print(string.format("%s%s=%s",indt,tostring(i),tostring(j)))
         end
      end
   end
end

   response, status = api.get(path);
   if status ~= 200 then
      fibaro:debug('Status: '..status..' on GET for '..path);
      fibaro:abort();
   end;

   doTable(response, '');

Unfortunately I cannot take credit for the clever little doTable() function, that lists the contents of a lua table. I think this was taken from a "Stack Overflow" article but I can no longer be sure.

 

Fibaro Globals
Next
Fibaro
Lua API
Contents

Questions or comments, please e-mail us at info@snys.nl