Setup

This is a note on installing the EventRunner framework.

First, I really recommend setting up an IDE off-line on a PC/Mac to test and debug scenes created with the framework before deploying them on the HC2.

• I recommend ZeroBrane Studio. It's free and cross platform. I guess that any other IDE with support for Lua would work.
• Download and install Lualibs with Fibaro/JSON APIs. The link also has a tutorial how to setup ZeroBrane. The "library" files may need to go in special directories for your IDE/Lua installation.
• Download 'EventRunner.lua', 'EventRunnerDebug.lua', ’example_rules.lua', and ’globals.data’ and and put them in your working directory. Or download the whole repository. Be aware that the version number in the EventRunner.lua file and the EventRunnerDebug.lua must be the same or it will complain. This may occur if I update the files but you have old scenes based on earlier version of the framework. Fire up the IDE and load 'EventRunner.lua' and run it. It is setup to run test examples from the 'example_rules.lua' file (Note! it depends on the HomeTable definition in ’globals.data’).
• Play around with enabling other scenarios in that file.

There are a few variables in the beginning of the 'EventRunner.lua' file that affect the execution.

• _sceneName = "AutoLight". Set to the name of your scene, ex "AutoLight". It's printed as a part of the start-up message.
• _deviceTable = "devicemap". Not mandatory, but good practice to give a name to your HomeTable global. Allows you to code like HT = json.decode(fibaro:getGlobalValue(_deviceTable))
• _ruleLogLength = 80. When logging, truncate printout.
• _HueIP = "192.168.1.153". Set to Hue bridge IP. If set to nil will not start Hue system.
• _HueUserName="xyz". Set to Hue user name.
• _myNodeRed = "http://192.168.1.50:1880/eventrunner" . Not mandatory, Ex. used for Event.postRemote(_myNodeRed,{type='test}) Then there are some variables that only affect the FrameWork when running offline.
• _GUI = false. Open WX GUI for event triggers, Requires Lua 5.1 in ZBS
• _SPEEDTIME = 2436. Offline only, Speed through X hours, set to false will run in real-time. Very convenient for debugging schedulers running over days... Ex. 247 will speed through 1 week.
• _EVENTSERVER = true. Starts port on 6872 listening for incoming events (Node-red, HC2 etc)
• _REMOTE=false. If set to true will use FibaroSceneAPI to call functions on HC2, else emulate them locally...
• hc2_user. HC2 credentials, used for api.x/FibaroSceneAPI calls
• hc2_pwd. HC2 credentials, used for api.x/FibaroSceneAPI calls
• hc2_ip. ip address to HC2, used for api.x/FibaroSceneAPI calls

There is also a _debugFlags table where logging of various subsystems in the framework can be turned on

_debugFlags = {post=true,invoke=false,eventserver=true,triggers=false,dailys=false,timers=false,rule=false,ruleTrue=false,fibaro=true,fibaroGet=false,fibaroSet=false,sysTimers=false, scene=true }

The EventRunnerDebug.lua file is included in the framework but is only included if running off-line as HC2 doesn't support 'dofile'. However, this is the point as the file contains HC2 functions needed for off-line running. Like 'setTimeout', 'net.HTTPClient' etc, and implementations of fibaro:* functions.

The default EventRunner scene will have the below structure (for EventRunner.lua, EventRunnerLite is slightly different)

--[[
%% properties
%% events
%% globals
%% autostart
--]]
-- Don't forget to declare triggers from devices in the header!!!
_version = "1.10"  -- fix5, Jan 13, 2019 

--[[
-- EventRunner. Event based scheduler/device trigger handler
-- Copyright 2018 Jan Gabrielsson. All Rights Reserved.
-- Email: [email protected]
--]]
if not _SCENERUNNER then 

  _sceneName     = "Demo"      -- Set to scene/script name
  _deviceTable   = "devicemap" -- Name of your HomeTable variable
  _ruleLogLength = 80          -- Log message cut-off, defaults to 40
  _HueIP = "192.168.1.153"     -- Set to Hue bridge IP. If set to nil will not start Hue system.
  _HueUserName=nil             -- Set to Hue user name. 
  _GUI = false                 -- Offline only, Open WX GUI for event triggers, Requires Lua 5.1 in ZBS
  _SPEEDTIME = 24*36           -- Offline only, Speed through X hours, set to false will run in real-time
  _EVENTSERVER=true            -- Starts port on 6872 listening for incoming events (Node-red, HC2 etc)

  _myNodeRed = "http://192.168.1.50:1880/eventrunner"  -- Ex. used for Event.postRemote(_myNodeRed,{type='test})

-- debug flags for various subsystems...
  _debugFlags = { post=true,invoke=false,eventserver=true,triggers=false,dailys=false,timers=false,rule=false,ruleTrue=false,fibaro=true,fibaroGet=false,fibaroSet=false,sysTimers=false, scene=true }

end
-- If running offline we need our own setTimeout and net.HTTPClient() and other fibaro funs...
if dofile then dofile("EventRunnerDebug.lua") require('mobdebug').coro() end

---------------- Here you place rules and user code, called once --------------------
function main()
  local rule = Rule.eval
  --_System.copyGlobalsFromHC2()             -- copy globals from HC2 to ZBS
  --_System.writeGlobalsToFile("test.data")  -- write globals from ZBS to file, default 'globals.data'
  --_System.readGlobalsFromFile()            -- read in globals from file, default 'globals.data'

  --local devs = json.decode(fibaro:getGlobalValue(_deviceTable)) -- Read in "HomeTable" global
  --Util.defvars(devs)                                            -- Make HomeTable defs available in EventScript
  --Util.reverseMapDef(devs)                                      -- Make HomeTable names available for logger

  dofile("example_rules.lua")      -- some example rules to try out...
end -- main()

------------------- EventModel - Don't change! --------------------  
<Rest of the framework code>

The user defined event handlers or rules goes in the main() function in the beginning of the file. Default is to include some example rules defined in "example-rules.lua" but you replace that with your own Lua event handlers or EventScript rules. Ex.

---------------- Callbacks to user code --------------------
function main()
  local devs = json.decode(fibaro:getGlobalValue(_deviceTable))
  Util.defvars(devs)
  Util.reverseMapDef(devs)
  -- lets start
  
  Event.event({type='property', deviceID=dev.kitchen.lamp, value='$>0'},
    function(env) Log(LOG.LOG,"Lamp (deviceID:%s) was turned on",dev.kitchen.lamp) end)

  Rule.eval("@sunset-15 => front.lamp:on; log('Turning on lamp in the evening')")

end -- main()

Typically, you want to read in some configuration data stored in a fibaro global when starting up. Like a HomeTable containing deviceID definitions. If you store the name of your HomeTable variable in '_deviceTable' and also creates a "globals.data" file in the working directory with your home table data (and other globals) it will be read in when the framework starts. The format of the file is a json format and reasonable easy to edit. However, you can copy your globals from the HC2 to the file by running these commands in main()

_System.readGlobalsFromHC2()
_System.writeGlobalsToFile()

Then it is easy to move the code between off-line testing and the HC2; when running off-line testing, doing a fibaro:getGlobalValue(_deviceTable) will read the hometable from the file, but when running on the HC2 it will read the fibaro global.

Calling 'Util.defvars' will make the table definitions available for EventScript rules, and 'Util.reverseMapDef' makes the debug output nicer when printing deviceIDs.

---------------- Callbacks to user code --------------------
function main()
--  local devs = json.decode(fibaro:getGlobalValue(_deviceTable))
--  Assume devs will be assigned the following structure
  local devs = {kitchen = {lamp=6, sensor=9}, front={lock=19, lamp=11}}

  Util.defvars(devs) -- Calling defvars on 'devs' we will make 'kitchen.lamp', 'kitchen.sensor', 'front.lock', 'front.lamp'available from within EventScript rules
  
  Util.reverseMapDef(devs) -- Calling reverseMapDef on devs makes the debug output use 'kitchen.lamp' instead of 6...
  -- lets start

  Rule.eval("@sunset-15 => front.lamp:on; log('Turning on lamp in the evening')")

end -- main()

_SPEEDTIME as described in the beginning is very convenient to speed through long time periods when debugging off-line. However, inside main(), as the first thing, it is also possible to set what time it should be when the script starts running which is convenient if one wants to test certain time periods. (and it's also possible to change the _SPEEDTIME variable)

function main()
_System.setTime("08:00",24*36) -- set clock to 08:00 when running, and run for 36 days
...
end

A lot of design has gone into being able to run the framework on a PC/Mac for debugging and make it behave as on the HC2. It saves a lot of time and improves the chance that the HC2 will stay up. With _REMOTE set to true the rules will call fibaro functions via the API so lamps are turned on/off etc. Be aware though that if running on _speedtime, lamps will flicker… Note, that it is not possible to speed timers on the HC2.

Also, even if you are not using the EventRunner framework with Lua event handlers or EventScript rules it is still a very convenient test bench for HC2 code in general. Inside 'main() .. end' all fibaro functions are available, fibaro:sleep(), HTTPClient, setTimeout works etc... and it it's possible to run faster than realtime, set breakpoints etc. Often when I try to help others in the forum with standard lua scenes I can quickly bring the code into the EventRunner man() function and test and debug it without having to do a lot of changes...

So, debug the rules on a PC/Mac and when they behave as expected copy the the whole framework/scene to the HC2 and it should run correct!