QuickApp emulator (hc3emu)

[jgab 2,647]

Please login or register to see this image.

/monthly_2025_03/image.png.c2f1b1c9c89840da67de7b85b8e0a60d.png" />

 

Note my newest effort is now Plua, <

Please login or register to see this link.

>.

 

HC3Emu is a Lua-based emulator designed to simulate the Fibaro Home Center 3 QuickApp runtime environment. It allows developers to code and test QuickApps offline before deploying them to a physical HC3 controller.
I prefer to develop my QuickApps "offline" using popular IDEs like

Please login or register to see this link.

or

Please login or register to see this link.

. I have thus created "emulators" that emulates the Lua environment that is available on the HC3, with all the fibaro.* functions etc.

This is my last attempt to put together all my past experiences and create a portable “emulator” with just the basics. The idea is that you can add any IDE-specific tools outside the emulator base.

 

(This video is for the older "hc3emu" and has some changes when it comes header directives in the QA file)
 

The new "workflow"

(This video is for the older "hc3emu" and has some changes when it comes header directives in the QA file)
 

It is provided as a "rock" and installed with 

 

Please login or register to see this code.

It's only the luarocks package that is named hc3emu2, as it it's the second rewrite of the emulator. It's still referred to as hc3emu in code and examples-

 

To use this you need a properly installed lua, together with a working installed luarocks. 

1. Properly installed lua means that lua must be installed to be generally available in your system. Sometimes lua is provided together with other programs like ZeroBrane, but then it's only available for ZeroBrane and not other programs.

2. Working luarocks menas that luarocks should be able to compile C libraries. For MacOS and Linux that is generally not a problem and work by default. On Windows it's a bit trickier and usually requires installation of gcc (mingw) See Windows installation tips below.

 

If luarocks is working it will take care of installing additional lua libraries that hc3emu depends on. It’s also a great way to install new versions as I release them (just install again).

 

If you install Lua libraries by hand, the trickiest parts are to install the ones that hc3emu needs.

• luasec, usually depends on a system native openssl library to be installed.
• luasocket

 

If successful it is used like this:

Please login or register to see this code.

 

I’ve tested it in ZeroBrane and VSCode.

For VSCode, it uses the “Lua MobDebug adapter” currently since it currently since it seems to works best. There are a number of different lua debugers for vscode and all of them work with some tweaking and all of them have some trade-offs - MobDebug is still my favorite. 

 

The source code and some examples are available in my GitHub repo:

Please login or register to see this link.

.

However you should not need to clone the repo. 

For VSCode you need a .vscode/launch.json and .vscode/tasks.json in your workspace to correctly start running and debugging your QA.

They are also available in the repo, but is preferable installed by installing the VSCode extension "Hc3Emu Helper". With that extension active you will get a 

"hc3emu2: Current file" launch option to run your QA.

When running the emulator it reads configuration if available from home directory ~/.hc3emu.lua and project/workspace directory ./hc3emu.lua if available.  The minimum is to provide hc3 credentials. Ex.

~/.hc3emu.lua

Please login or register to see this code.

 

Key Features

• Most of the lua functions available in the HC3 QuickApp lua environment
  • fibaro.*
  • hub.* (same as fibaro.*)
  • QuickApp, QuickAppChild, class
  • api.get, api.put, api.post. api.delete
  • json.encode, json.decode
  • plugin.*
  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • net.HTTPClient
  • net.TCPSocket
  • net.UDPSocket

  • net.WebSocketClient

  • net.WebSocketClientTls

  • mqtt.*
  • RefreshStatesSubscriber
• Can automatically deploy proxy QA on HC3 for developing and testing UI. Also useful if other QAs on the HC3 sends commands to your QA you develop...
• Supports QAs with multiple files
• Supports saving the QA to a .fqa file

 

Missing

• WebSocket has minor some issues - it will not automatically ping to keep an idle socket open. What will happen is that after ~20s of no traffic a server will close the socket. Can sometimes be solved with explicit pinging if protocol allows. On the other hand, your QA should be able to deal with server closing socket and open the socket again...

 

Credentials
Install a file named .hc3emu.lua, in your home directory, or workspace folder. If it's in your home directory it is shared between all workspaces.

It should have the content

Please login or register to see this code.

The user/password/url will be used to access the HC3. 

In this example we add two more credentials for accessing a Hue hub. We can then in our QA code create QuickAppVariables with those values

Please login or register to see this code.

This way we don't have to have our credentials in out QA course code and accidentally share it with others...

 

Header directives

• --%%type=<type> - Type of the QA,
  ex. --%%type=com.fibaro.binarySwitch
• --%%name=<name> - Name of the QA,
  ex. --%%name=My QuickApp
• --%%proxy=<true|false> - Make this device a proxy device
• --%%proxy_new=<true|false> - Recreate proxy if exists? Default false
• --%%proxy_set_ui=<true|false> - Set UI for the proxy device at every startup? Default false
• --%%state=<tag> - Tag for the state file,
  ex. --%%state=MyQAState
• --%%time=<time> - Start time for the emulator,
  ex. --%%time=2027/10/10/12:00:00
• --%%speed=<time> - Hours to speed the emulator,
  ex. --%%speed=24*7 -- speed for 1 week
• --%%offline=<true|false> - Run in offline mode,
  ex. --%%offline=true
• --%%logui=<true|false> - Log proxy's current UI at startup,
  ex. --%%logui=true
• --%%webui=<true|false> - Enable emulated web UI for the QA,
  ex. --%%webui=true
• --%%uid=<string> - uid property of the QA,
  ex. --%%uid=12345678-1234-5678-1234-567812345678
• --%%manufacturer=<string> - Manufacturer property of the QA,
  ex. --%%manufacturer=MyCompany
• --%%model=<string> - Model property of the QA,
  ex. --%%model=MyModel
• --%%role=<string> - Device role of the QA,
  ex. --%%role=Light
• --%%description=<string> - Description property of the QA,
  ex. --%%description=My QuickApp
• --%%latitude=<number> - Latitude of the system,
  ex. --%%latitude=59.3293
• --%%longitude=<number> - Longitude of the system,
  ex. --%%longitude=18.0686
• --%%temp=<path> - Path to the temporary directory,
  ex. --%%temp=/tmp/hc3emu
• --%%nodebug=<true|false> - Disable debugging,
  ex. --%%nodebug=true
• --%%norun=<true|false> - Load but do not run the QuickApp,
  ex. --%%norun=true
• --%%silent=<true|false> - Do not print debug messages,
  ex. --%%silent=true
• --%%breakOnLoad=<true|false> - Break on first line when loading the QuickApp,
  ex. --%%breakOnLoad=true
• --%%breakOnInit=<true|false> - Break on first line of QuickApp:onInit(),
  ex. --%%breakOnInit=true
• --%%save=<path> - Save the QA as a .fqa when running,
  ex. --%%save=myQA.fqa
• --%%nodir=<true|false> - Do not create emu directory,
  ex. --%%nodir=true
• --%%conceal=<true|false> - Conceal quickApp variables when saving QA,
  ex. --%%conceal=password:"Set this to the password"
• --%%condensedLog=<true|false> - Use condensed log format,
  ex. --%%condensedLog=true
• --%%pport=<number> - Port for the proxy,
  ex. --%%pport=8265
• --%%wport=<number> - Port for the web server,
  ex. --%%wport=8266
• --%%hport=<number> - Port for the help server,
  ex. --%%hport=8267
• --%%dport=<number> - Port for the debugger,
  ex. --%%dport=8172
• --%%hip=<ip> - IP for the help server,
  ex. --%%hip=127.0.0.1
• --%%url=<url> - URL for the HC3,
  ex. --%%url=

  Please login or register to see this link.

• --%%user=<user> - User for the HC3,
  ex. --%%user=admin
• --%%pwd=<password> - Password for the HC3,
  ex. --%%pwd=admin
• --%%pin=<pin> - PIN for the HC3,
  ex. --%%pin=1234
• --%%u=<table> - Add UI element to the QuickApp,
  ex. --%%u={button="btn1",text="Click me",onReleased="myFunction"}
• --%%debug=<flags> - Set debug flags,
  ex. --%%debug=system:true,api:true,onAction:true
• --%%file=<path,method> - Add file to the QuickApp,
  ex. --%%file=./myfile.lua,init
• --%%var=<name:value> - Add variable to the QuickApp,
  ex. --%%var=MyVar:"MyValue"
• --%%install=<user,pass,url> - Install the QuickApp on the HC3,
  ex. --%%install=admin,admin,

  Please login or register to see this link.

 

List of debug flags

• system=<boolean> --System debug (combined)
• api=<boolean> --Log API errors
• device=<boolean> --Device lifecycle debug
• http=<boolean> --log HTTP requests
• timer=<boolean> --Timer operations
• time=<boolean> --Time operations
• onAction=<boolean> --Log onAction calls
• onUIEvent=<boolean> --Log onUIEvent calls
• notrace=<boolean> --No trace log
• rawrefresh=<boolean> --Raw refresh log
• refresh=<boolean> --Refresh log
• warn=<boolean> --Warning log
• server=<boolean> --Server log
• web=<boolean> --Web server log

 

Installation tips

When using luarocks from within Zerobrane you must run a separate (system) installed lua interpreter.

When interpreter is selected from within Zerobrane (Project -> Lua interpreter -> ...) it will use per default lua interpreters that come bundled with Zerobrane and sometimes they are compiled in a way that they don't like binary libraries compiled by other systems like luarocks. On MacOS that can be ex. x86 vs arm binaries. The builtin Lua interpreter also uses old bundled Lua libraries not compatible with hc3emu.
 

To make zerobrane use your own installed lua 5.4  do, Preferences -> Settings: System, and set

Please login or register to see this code.

In my case I have installed lua 5.4 in /opt/homebrew/bin/lua, but you may have installed it somewhere else..

This way, luarocks will install libraries that will be used by the right lua.

 

For vscode, the normal behavior is that the plugin use the system installed lua.

 

When managed to install the hc3emu luarock without errors, it's time to setup the environment.

The easiest way to generate the necessary configuration setup is to run a small QA that looks like

Please login or register to see this code.

Ex.

Please login or register to see this code.

It will generate a config file ~/-hc3emu.json in your home directory with the user, password and url parameters set.

(Don't forget to remove the --%%install line or QA afterward so you don't have your credentials visible in your code...)

 

Specific installation tips

• For

  Please login or register to see this link.

  • Please login or register to see this link.

• For

  Please login or register to see this link.

   

• Please login or register to see this link.

• Please login or register to see this link.

• Please login or register to see this link.

   (Only need to install VSCode and Docker)

 

Other information

• Please login or register to see this link.

• Using proxy device
• Working with QuickAppChild devices
• Debugging tips

• Please login or register to see this link.

Edited October 7, 2025 by jgab

[jgab 2,647]

Pushed v1.0.2-1

• Fix bug in net.HTTPClient
• Fix bug in net.TCPSocket

[jgab 2,647]

Here is a test QA I use to check what works...

Please login or register to see this code.

 

Edited February 21, 2025 by jgab

[jgab 2,647]

Pushed v1.0.3-1

• Fix bug in net.HTTPClient (forgot https support)
• Initial version of net.WebSocketClient

[jgab 2,647]

Pushed v1.0.4-1

• Numerous bufixes
• Code cleanup
• Another small bug in net.HTTPClient and improvements for net.TCPClient
• Some issues with WebSocket (especially wss:) - working on it...

[jgab 2,647]

Pushed v1.0.5-1

• More bugfixes
• More code cleanup
• new json decoder with reasonable performance
• Runs my EventRunner5 project, which is really a stress-test for any lua environment, so this is probably starting to become my development environment of choice...

[jgab 2,647]

Pushed v1.0.7-1

• More bug fixes and clean-ups...
• Better performance
• os.exit() and plugin.restart() shuts down the emulator gracefully resp. restarts the QA. Minimizes the risk that we are left with open ports...
• --%%save='MyQA.fqa" will save a .fqa version on disk of the QA every time the emulator runs.
• api.post("/quickApp",fqa) and api.get("/quickApp/export/<deviceId>") works, so 

  Please login or register to see this code.

  will upload the QA to the HC3. If you have defined the UI in the HC3 proxy for the QA, the exported QA will have the same UI elements.

I will add some directives for defining the UI in the QA code, like with the other emulators.

[Brors94 115]

48 minutes ago, jgab said:

Pushed v1.0.7-1

• More bug fixes and clean-ups...
• Better performance
• os.exit() and plugin.restart() shuts down the emulator gracefully resp. restarts the QA. Minimizes the risk that we are left with open ports...
• --%%save='MyQA.fqa" will save a .fqa version on disk of the QA every time the emulator runs.
• api.post("/quickApp",fqa) and api.get("/quickApp/export/<deviceId>") works, so 

  Please login or register to see this code.

  will upload the QA to the HC3. If you have defined the UI in the HC3 proxy for the QA, the exported QA will have the same UI elements.

I will add some directives for defining the UI in the QA code, like with the other emulators.

 

 

Do you recommend to start using this instead of fibemu?  

 

 

 

[jgab 2,647]

22 minutes ago, Brors94 said:

 

 

Do you recommend to start using this instead of fibemu?  

 

 

 

Wait a week...   

[Brors94 115]

8 minutes ago, jgab said:

Wait a week...   

Will do

[jgab 2,647]

I think in general, fibemu for vscode is nice. 

What I didn't like with it is the rather complicated setup with having to download the GitHub directory for the complete vscode project and how to update etc.

fibemu is implemented 40% in python, providing all the lua network functions. My thinking was to not depend on platform dependent lua libraries for that.

However, I have found out that there are some issues with python libraries too, moving between platforms.

Luarocks is quite good at installing (platform dependent) lua libraries. So with this model, if you have installed luarocks so that libraries you install are available to your lua interpreter.
E.g. then you can setup a project in any directory and just do require(hc3emu") and you are up and running. No need to deal with my GitHub repo of the project.

To upgrade, you just do

Please login or register to see this code.

and you have the latest version. You can even downgrade by doing

Please login or register to see this code.

...and it works as well with vscode as it does with ZeroBrane,

...and it should work both on Mac and Windows. 

 

The other things is that hc3emu is the cleanest emulator (code wise) I've done so far, so it should be much easier to maintain going forward.

Edited February 11, 2025 by jgab

[jgab 2,647]

Pushed v1.0.8-2

Please login or register to see this code.

• --%%ui directives support
• Beginning of offline support when no access to the HC3, some of the simpler APIs
  --%%offline=true
  • /globalVariables
  • /settings/info
  • /settings/location
  • /settings/home
  • /devices
  • /rooms
  • /sections

[jgab 2,647]

Pushed v1.0.10-1

Please login or register to see this code.

• Better WebSocket support. Only wss: currently. It works with my Sonos QA (wss with headers, api-key and security protocol)

  • sock:connect("wss://ws.postman-echo.com/raw") works

  • sock:connect("wss://echo.websocket.org/") fails, ssl handshake results in connection closed(!)
    fibemu with a python lib for websockets works with  wss://echo.websocket.org, so it should be possible...

[jgab 2,647]

Directives

Directives are comments in the QA files interpreted as directives to the emulator. Ex. name and type of QA.

 

• name=<name>
  Ex. 

  Please login or register to see this code.

• type=<type>
  Ex.

  Please login or register to see this code.

• id=<number>
  The deviceID assigned to the emulated QA. If not given will default to 5001.
  If a proxy is used, the id will get the id of the proxy on the HC3.
  Ex.

  Please login or register to see this code.

• interfaces={<list of interfaces>}
  Optional, consists of interfaces the QA should have.
  Ex.

  Please login or register to see this code.

• proxy=<name>
  The name of the proxy created/used on the HC3. If a QA with the name already exists on the HC3 it is reused. Otherwise it is created.
  If the name is prefixed with a dash "-", the QA, if it exists, will be deleted and proxy set to false. A way to clean up...
  Ex.

  Please login or register to see this code.

   

• var=<name>:<value>
  Will assign a quickAppVariable with name and value to be available when QA starts up
  Ex.

  Please login or register to see this code.

  The value is evaluated and a predefined variable 'config' is set to the configuration files read in.
  This means that if we have a config file looking like { secret = "my secret" }
  we can assign a variable the secret like this

  Please login or register to see this code.

  and it will get the value "my secret". This is useful as we can have credentials in the config file and not having to write them in our QA code... and accidentally upload the QA to the community/github with the credentials visible.
• conceal=<name>:<value>
  This will change the value of the quickAppVariable named <var> when it's saved as a .fqa.
  It allows for removing sensitive credentials when the .fqa is saved for upload to forums etc. The <value> can be a boilerplate value to inform the user what value the quickAppVariable should have.
  Ex.

  Please login or register to see this code.

• file=<filename>:<qafilename>
  Add the lua file <filename> to the projects as a "QA file" named <qafilename>
  This is the way to build multi-file QAs. The files will be loaded and can be debugged like any "required" file, but they are also included in the .fqa when the QA is saved.
  Ex.

  Please login or register to see this code.

• save=<filename>
  If set to a filename, the QA will be saved to that file every time the QA runs. It will be saved as a .fqa file.
  Ex.

  Please login or register to see this code.

• dark=<boolean>
  If true will use lighter colors for console log. If false will use darker colors for console log
  Ex.

  Please login or register to see this code.

• color=<boolean>
  If true will log messages in the console using colors. <default is true>.
• offline=<boolean>
  If true will not issue commands to the HC3, but instead try to use local resource database.
• state=<filename>
  Name of the file where emulator state is store. Ex. is QA's internalSTorage saved here. Also when running offline, the file is used to save resources created. devices, globalVariables etc.
  Ex.

  Please login or register to see this code.

• stateReadOnly=<boolean>
  If true will only read from the state database, not save. Useful for testing.
• latitude=<float number>
• longitude=<float number>
  Latitude and longitude for the emulator. Used to provide sunrise and sunset hour in offline mode. When online, this is fetched from the HC3.
• time=<string>
  Optional simulated time. 
  Ex.

  Please login or register to see this code.

  will set the simulated time to 10s before midnight on New years even 2026. os.time() and os.date() will return the new time. Useful for testing QAs that deals with dates...
• port=<number>
  Will set the socket port used for listening for events from the HC3 proxy. Default 8264.
  If you run more than one emulator in parallel you need to have define different ports.
• debug=<name>:<value>
  Debug flags affecting what is logged in the console...
• project=<number>
  If set to a deviceId of a QA on the HC3, it will at every run write a .project file in the workspace with the deviceId and the files that the running QA consists of. The .project file can be used by tools synching files to the HC3.
  Ex. vscode.lua task setup. See separate post.
• logUI=<boolean>
  If true will log the current UI elements declaration of the proxy to the console. Can be copied and pasted into the QA code to keep the QAs UI declarations in sync with the proxy. Default is false.
• u=<UI declaration>

 

UI declaration specify the UI elements that we want the proxy to have. They are only set when the proxy is initially created. After that, it's easiest to edit the UI in the HC3 QA editor. If the --%%logUI is set, the new UI declarations will be logged to the console at QA startup and can be copied and pasted into the QA, keeping the QA and the proxy UI in sync.

Types of elements.

Please login or register to see this code.

Every --%%u directive defines a new line in the QA UI.

To include more elements on the same line include them in a {...} list.
Ex.
 

Please login or register to see this code.

 

 

Edited May 27, 2025 by jgab

[jgab 2,647]

Pushed v1.0.15-1

Please login or register to see this code.

• Lots of small bug fixes - starting to use it for my own QA development now.
• New time and speed directives.
  --%%time=2025/12/31 23:59
  allows to set a simulated time. Nice when testing time logic in QA...
  --%%speed=24*7
  Speeds the emulator for a number of hours, in this example, 1 week.
   

Please login or register to see this code.

Please login or register to see this attachment.

...sometimes you don't want to wait a week to see if your QA logic was right  

[jgab 2,647]

v1.0.16 supports creating shellscripts...

Please login or register to see this code.

If set to executable...

Please login or register to see this code.

Works in linux and Mac, don't know how to make the same trick on Windows..

[jgab 2,647]

Pushed v1.0.18-1

Please login or register to see this code.

• Lots of small bug fixes..

When running in the emulator, many emulator functions are available in fibaro.hc3emu.*
Ex.

Please login or register to see this code.

will download a QA from the HC3 and "unpack" it into separate files in direct "path".

If QA deviceId 88 has the name "My QA" and has 2 extra QA files names "lib" and "log"

Please login or register to see this code.

will result in

Please login or register to see this code.

Instead if we do 

Please login or register to see this code.

then we get

Please login or register to see this code.

 

The main file, MyQA.lua in this case will have the correct --%% directives to include the extra QA files.

Note, the directory, "test" in this example, must exist.

Edited February 23, 2025 by jgab

[jgab 2,647]

We can do a shell script for downloading and unpack a QA.
 

Please login or register to see this code.

Move to a directory and execute the script... In this example downloading my Hue QA.

Please login or register to see this code.

[jgab 2,647]

Pushed v1.0.19-1

Please login or register to see this code.

• bugfixes and special support for vscode. See separate post

[jgab 2,647]

Vscode installation tips

 

To be able to run the emulator it is required that lua and luarocks are installed in the system (Windows, MacOS, Linux) in a way that it is globally runnable, e.g. from a terminal/shell.

The reason is that the launch.json script is starting the "lua" program. It may work with a custom launch.json with the path to a specific lua installation.
Just make sure that the packages that luarocks installs are accessible by that specific lua. In the emulator we will do

Please login or register to see this code.

and the lua running needs to find the installed (by luarocks) lua library named "hc3emu".

To have lua and luarocks installed, see installation tips in first post.

 

In vscode install the extension 

• Lua MobDebug adapter

It is also recommended to install the extension

• Lua Language Server, by Sumneko

 

There is also a vscode extension giving api completion and QA snippets

Please login or register to see this attachment.

 

Setup a configuration file for hc3emu. Best is to create a file .hc3emu.lua in your home directory

Please login or register to see this code.

In that file, set the credentials to log in to the HC3
Ex.
 

Please login or register to see this code.

It is also possible to setup a workspace specific configuration file named "hc3emu_cfg.lua" that overrides values in the global config file.

In the

Please login or register to see this link.

there are examples of .vscode/settings.json,  .vscode/launch.json, and  .vscode/tasks.json

that sets up configurations to run Lua and some convenient tasks..
Note that much of the content of those files can be setup in vscode global files to avoid having to copy them into every new vscode workspace.

Ex. in the User settings.json add a "launch" item

Please login or register to see this code.

Also, in settings.json there are the possibility to add "approved" Lua globals, so you don't get warnings for 'fibaro', 'QuickApp' etc. See repo .vscode/settings.json

 

It's possible to add the HC3 credentials by setting environment variables that the emulator will read. Put them in the vscode settings file and include an"env" entry in the launch item above.

Please login or register to see this code.

 

Located <

Please login or register to see this link.

>, is a tasks.json file that provides VSCode tasks integration with commands to upload/download QAs to the HC3 etc.

 

It may also be convenient to setup a global snippets file to easily add the hc3emu header needed.

Example of that would look like
 

Please login or register to see this code.

Then when typing 'hc3emu' a popup will give the option to insert the header template.

 

In vscode I also recommend installing the copilot extension that help you coding with AI (chatgpt). It's starting to get better at Lua...

Also, keep an eye on the "Problems" tab in the bottom console/terminal window. Here all possible errors in your workspace is highlighted. Try to keep the problems at 0, even if it requires you to change your coding style - it does create more robust code.

The whole hc3emu project currently has 0 problems(!)  

Edited June 2, 2025 by jgab