Search the Community

This is a vscode setup for QA development. It contains an emulator so you can run the QA in vscode and debug it, optionally sending commands to and synching with the HC3. It has support for code completion and syntax highlighting. It has some workflow tasks to download QAs from the HC3, edit them and package and upload them when done. It's tested on Windows 11 and MacOS, and should work on Linux too. The repository for downloading it is here https://github.com/jangabrielsson/fibemu Some documentation is available here https://github.com/jangabrielsson/fibemu/raw/main/FibEmu.pdf (work in progress) ...and here is the movie (how to install on Windows 11) This is how the setup looks in Vscode. It gives you a way to develop and run a QuickApp offline on your PC/Mac/Linux and let it interact with the HC3 in a controlled way. There is also a simple UI to interact with the QAs UI and see events etc. Steps to run Have pyton3 installed on your machine. pip install the needed python libraries from requirements.txt >pip install -r requirements.txt Create a config.json file with the credentials to access the HC3. See config.json.example Install the vscode extension "Local Lua Debugger" by Tom Blind Create a QA file in the directory, select launcher "Fibenv QA file (remote)" and run debug F5 For other examples, see files in the examples/ directory (it's the QA files I use to test compatibility...) The .gitignore file included, excludes the subdirectories ./dev and ./test so they can be used to test your own code without impacting the rest of the repository. If you want your own repository - see instructions below how to link the right folders. For installing the python libraries, I would recommend to create an virtual environment for python in the folder before doing the pip install -r requirements.txt... The trick here is that we have a a python wrapper for the lua runtime (Lupa) so we solve dependencies on luasocket etc. and we don't need any special headers in the QA lua file to invoke/include the emulator/apis to make the QA being able to execute (we don't even need Lua installed on our machine ) To give some hints to the emulator what type of QA we have etc. we can give directive similar to TQAE in our QA file (but a bit different) Ex. --%%name=MyQA --%%type=com.fibaro.binarySwitch --%%file=qa3_1.lua,extra; --%%remote=devices:788,790 --%%remote=globalVariables:myVar,anotherVar --%%debug=libraryfiles:false,userfilefiles:false function QuickApp:onInit() self:debug(self.name,self.type,self.id) fibaro.call(788,"turnOn") end Note the --%%remote directive It instructs the emulator that it's ok to call device 788,789 o the HC3. As a default, the emulator treats all resources as local (we can read from HC3 but then treat them as local copies) and we enable resources we want to interact with on the HC3 as 'remote'. This goes for other resources also like 'globalVariables'. It integrates with the lua debugger so we can set breakpoints etc. Still work in progress and stuff that doesn't work so well yet - will update the post as it progresses... There is the beginning of an emulator UI at http://127.0.0.1:5004/ Currently implemented APIs have a swagger page at http://127.0.0.1:5004/docs Port (5004) can be changed Supported APIs fibaro.debug(tag,str) fibaro.warning(tag,str) fibaro.trace(tag,str) fibaro.error(tag,str) fibaro.call(deviceID, actionName, ...) fibaro.getType(deviceID) fibaro.getValue(deviceID, propertyName) fibaro.getName(deviceID) fibaro.get(deviceID,propertyName) fibaro.getGlobalVariable(varName) fibaro.setGlobalVariable(varName ,value) fibaro.getRoomName(roomID) fibaro.getRoomID(deviceID) fibaro.getRoomNameByDeviceID(deviceID) fibaro.getSectionID(deviceID) fibaro.getIds(devices) fibaro.getAllDeviceIds() fibaro.getDevicesID(filter) fibaro.scene(action, sceneIDs) fibaro.profile(profile_id, action) fibaro.callGroupAction(action,args) fibaro.alert(alert_type, user_ids, notification_content) fibaro.alarm(partition_id, action) fibaro.setTimeout(ms, func) fibaro.clearTimeout(ref) fibaro.setInterval(ms, func) fibaro.clearInterval(ref) fibaro.emitCustomEvent(name) fibaro.wakeUpDeadDevice(deviceID) fibaro.sleep(ms) net.HTTPClient() net.TCPSocket() net.UDPSocket() net.WebSocketClient() net.WebSocketClientTLS() --mqtt.Client.connect(uri, options) --no yet --<mqttclient>:addEventListener(message,handler) --no yet --<mqttclient>:subscribe(topic, options) --no yet --<mqttclient>:unsubscribe(topics, options) --no yet --<mqttclient>:publish(topic, payload, options) --no yet --<mqttclient>::disconnect(options) --no yet api.get(call) api.put(call <, data>) api.post(call <, data>) api.delete(call <, data>) setTimeout(func, ms) clearTimeout(ref) setInterval(func, ms) clearInterval(ref) json.encode(expr) json.decode(string) plugin.mainDeviceId ---plugin.deleteDevice(deviceId) --not yet plugin.restart(deviceId) plugin.getProperty(id,prop) plugin.getChildDevices(id) plugin.createChildDevice(prop) class QuickAppBase class QuickApp class QuickAppChild class <name> property(get,set) QuickApp:onInit() -- called at startup if defined QuickApp - self:setVariable(name,value) QuickApp - self:getVariable(name) QuickApp - self:debug(...) QuickApp - self:trace(...) QuickApp - self:warning(...) QuickApp - self:error(...) QuickApp - self:updateView(elm,type,value) QuickApp - self:updateProperty(name,value) QuickApp - self:createChildDevice(props,device) QuickApp - self:initChildDevices(table) The general setup to develop your own QAs is the have the repo 'fibemu' downloaded in a separate directory. Then create your own vscode development directory and copy the fibemu/.vscode/launch.json and fibemu/.vscode/settings.json to your own .vscode directory. Then inside your .vscode make a soft link from .vscode/emufiles to fibemu/.vscode/emufiles. This way you can pull down new version of fibemu without messing up your own directory and development. Also setup your config.json with credentials. Implementation Some implementation notes. Supported REST APIs. Workflow There are some defined vscode Tasks that help in remotely uploading and updating the QA on the HC3 from within the vscode environment "QA, download fqa" downloads an QA from the HC3 and saves it as a .fqa file. The task will prompt for deviceID and path where to store. The path/dir needs to exist "QA, download and unpack" downloads an QA from the HC3 and saves all QA files as .lua files. It also adds fibemu headers in the main file so it can be opened and run with the emulator . The task will prompt for deviceId and path where to store. The path/dir needs to exist "QA, upload" will upload the QA to the HC3. It will prompt for QA file. If '.' is given as argument it will upload the current opened file. This will create a new QA, with a new deviceId on the HC3. "QA, update" will try to update QA files, viewLayout, uiCallbacks, and quickAppVariables of an existing QA on the HC3. If '.' is given as argument the file must have set the fibemu header --%%id=<ID> so it knows what QA to update. One can also give the deviceId of the QA on the HC3 that should be updated. This is convenient when developing and avoiding new IDs being "consumed". Sometimes when you update a QA you would not like to update the quickAppVariables. In that case give '-' instead '.' for the current opened file, or -deviceId for an exiting QA on the HC3. Scripts A advantage with the emulator is that we have access to more lua functions than on the HC3 which allow us to write some maintenance scripts QA backup. Backs up QAs from the HC3 to a local directory, keeping the 3 last versions QA distribution. Packs a development file to a .fqa, initialises some quickAppVariables, adds readme.txt file and zips it to an archive. Known issues While the QA is running, break-points can't be added. This is a limitation of the debugger used. Just add the break-point and restart the QA. When the emulator crashes, it may leave a process open that keeps the port 5004 in use. The emulator will complain at restart that the port is already bound. You may need to manually kill the process. On Mac: >kill -9 $(lsof -ti:5004)