Search the Community

This setup is designed for QA development using Visual Studio Code (VSCode). It includes an emulator, allowing you to run and debug QAs directly in VSCode. This setup is compatible with HC3, offering features such as code completion, syntax highlighting, and workflow tasks for downloading, editing, packaging, and uploading QAs to/from HC3. Tested on Windows 11 and MacOS, this setup should also work on Linux. You can download the repository from here. Documentation, still in progress, is available here. Additionally, there's a video tutorial on installing this setup on Windows 11. The setup in VSCode looks as shown in the image. This configuration allows you to develop and run a QuickApp (QA) offline on your PC, Mac, or Linux system, and interact with the HC3 in a controlled manner. There's also a simple Web user interface for interacting with the QAs and monitoring events (available at http://127.0.0.1:5004/frontend) To get started: Install Python 3 on your machine. NOTE! Only Python v3.11 and 3.12 is supported. in settings.json set "fibpython":".venv/bin/python", fibpython should point to your executable python. In the example it points to a python venv in the workspace, but it could point anywhere you have installed python. There is a settings.templ provided as a base for your own settings.json (should be in the .vscode directory) To test if the installation is ok , in the vscode terminal window, type what you set the fibpython path to. ex: .venv/bin/python and see if it works. Install the required Python libraries from requirements.txt using >pip install -r requirements.txt. Make sure they install for the python interpreter that is pointed out by fibpython. Create a config.json file with credentials to access the HC3, based on the config.json.example. Install the VSCode extension "Local Lua Debugger" by Tom Blind. Create a QA file in the directory, choose the launcher "Fibenv QA file (remote)," and start debugging with F5. For more examples, refer to the files in the examples/ directory. The included .gitignore file excludes the ./dev and ./test subdirectories, allowing you to test your own code without affecting the rest of the repository. For installing Python libraries, it's recommended to create a virtual environment in the folder first. This setup includes a Python wrapper for the Lua runtime (Lupa), addressing dependencies on luasocket and others, eliminating the need for Lua installation on your machine. To instruct the emulator about the type of QA, directives similar to TQAE can be used in the QA file, but with slight differences, as shown in the example. 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'. The setup integrates with the Lua debugger, allowing for breakpoint setting and more. Note that this project is still in progress, and updates will be provided as improvements are made. The emulator UI can be accessed at http://127.0.0.1:5004/, with a Swagger page for implemented APIs at http://127.0.0.1:5004/docs. The port (5004) can be changed as needed. Supported APIs include various fibaro and net functions, along with api calls and plugin functions. The setup also includes classes for QuickApp development and management. 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) ...and corresponding hub.* functions 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 RefreshStateSubscriber 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:removeChildDevice(id) QuickApp - self:initChildDevices(table) QuickApp - self:isTypeOf(typ) QuickApp - self:callAction(name, ...) QuickApp - self:setName(name) QuickApp - self:setEnabled(bool) QuickApp - self:setVisible(bool) getHierarchy() For your own QA development have the repo 'fibemu' downloaded in a separate directory. Then create your own vscode development directory, and initialise that as a git repo if you want. With that open, do File->Add Folder to Workspace, and add the fibemu folder. This is what Vscode calls a "multi-root" workspace and it. Create a lua (QuickApp file) in your directory. First line in your QuickApp file should be the offset to your directory --%%root=../<name of your dir>/ So if you have a multi-root workspace now that looks like o fibemu o myDirectory You set the root to ../myDirectory/ Then press F5 to start to debug. The launch commands and other will be taken from the fibemu folder. This way you can pull down new version of fibemu without messing up your own directory and development. Also, don't forget to setup your config.json with credentials (copy from fibemu/config.json.example) Here is a link to the multi-project setup instructions (may include a video in the future) 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 An 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)