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.
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.
--[[
%% 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.
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:
Function | Description |
---|---|
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: |
These are the functions most likely to be used when a scene has been triggered.
Function | Description |
---|---|
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"); |
These functions allow additional system information to be extracted, as follows:
Function | Description |
---|---|
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:
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) endwrites 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. |
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.
Questions or comments, please e-mail us at info@snys.nl