QuickApp emulator (hc3emu)

[jgab 2,647]

Pushed v1.0.21-1

Please login or register to see this code.

• New logic behind proxys. 
  If you have proxies deployed on the HC3 you need to delete and regenerate them, because the com protocol between emulator and proxy changed.
  The advantage is now that we can fire up multiple emulators talking to multiple proxies.
  Vscode allows for multiple workspaces/windows being open, so we can emulate two different QAs communicating with each other via the HC3 and their proxies  
  Just remember to give the emulator different ports with the --%%port=... directive.

Edited February 24, 2025 by jgab

[Brors94 115]

5 hours ago, jgab said:

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 instal hc3emu with luarocks, the system library openssl needs to be installed.

 

On MacOS it's easy to install lua, luarocks, and openssl with the MacOS package manager

Please login or register to see this link.

On Windows it is a bit tricker. I don't have Windows X86, but I recommend the

Please login or register to see this link.

package manager.
For Windows, MinGW needs to be installed so luarocks can compile binary libraries. (use Scoop)

 

In vscode install the extension 

• Lua MobDebug adapter

It is also recommended to install the extension

• Lua Language Server, by Sumneko

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
 

There are some tasks defined that depends on the file

Please login or register to see this link.

in the repo.

Copy vscode.lua to ~/.vscode.lua and the tasks.json will be able to find it. See repo .vscode/tasks.json

There is also a global tasks.json file were the task can be defined and be available in all workspaces...

 

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(!)  

 

 

I will try to install it on windows later today if I got time 

 

 

[jgab 2,647]

10 minutes ago, Brors94 said:

I will try to install it on windows later today if I got time 

Fingers crossed. 

Getting luarocks working on Windows is not trivial.

Have you tried the Scoop package manager for Windows? It seems to be easiest.

You need to install GCC,GDB,Make - available in the MinGW package from Scoop. And the openssl, that should be in the TLS/SSL toolkit package.

Let me know how it went...

 

Alternatively, if you run vscode, copy the .devcontainer that is part of the hc3emu repo - starts a linux with all the right libs...
The container image in the Dockerfile is set to 

Please login or register to see this code.

Just remove the --platform=arm64 and it should build an x86 version on your platform.

Edited February 24, 2025 by jgab

[Brors94 115]

2 minutes ago, jgab said:

Fingers crossed. 

Getting luarocks working on Windows is not trivial.

Have you tried the Scoop package manager for Windows? It seems to be easiest.

You need to install GCC,GDB,Make - available in the MinGW package from Scoop. And the openssl, that should be in the TLS/SSL toolkit package.

Let me know how it went...

 

The scoop package manager is new for me 😅 Also luarocks, but I will try to get it running
Will update you here 😄 
Or maybe ask some dumb questions 😆
 

 

[jgab 2,647]

ZeroBrane installation tips
 

When using luarocks from within Zerobrane install a separate (system) lua interpreter.

Zerobrane comes with lua 5.1 to 5.4 but they are compiled for using Zerobranes own libraries.

Zerobrane itself runs from lua 5.1, but you can select other lua versions for running your app.

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..

 

The advantage is that we can reuse the same interpreter for vscode, and we can setup luarocks to install libraries 

this lua interpreter can access.

 

 

Then install the zerobrane package file from the repo <

Please login or register to see this link.

> into .~/zbstudio/packages/HC3EMUplugin.lua
The file is a Zerobrane studio package file that provides API completions for QuickApps and an interpreter option in the
Project -> Interpreter -> Hc3Emu emulator
to run your QuickApp files.

 

 

Edited May 27, 2025 by jgab

[Christb 33]

Is it possible to have in // fibemu and hc3emu working in Vscode?

I am now familiar with fibemu and want to keep it until I can use hc3emu correctly...

If not, I will install hc3emu in ZeroBrane

Edited February 24, 2025 by Christb

[jgab 2,647]

You can have them both. fibemu you clone my repo/workspace and run in it (more or less)

hc3emu you install a lua library with luarocks and run a simple lua project in vscode including the lua library.

The same for zerobrane...

What's different is launch.json, how you start the QA.

Edited June 1, 2025 by jgab

[Brors94 115]

I am reading the postes you have made in this topic and activated copilot again  
Now I get the "problems in this file"

The 1 file with red was understanding since it had a function with no end for it, so nice to get a notification on that I have to say      (had just made it and not tested the QA) 
But the yellow faults, I dont get 😅
Like this one in main file:

translation file:

Also added some lua extensions you mentioned in some post here

 

 

 

 

 

 

[jgab 2,647]

9 minutes ago, Brors94 said:

I am reading the postes you have made in this topic and activated copilot again  
Now I get the "problems in this file"

The 1 file with red was understanding since it had a function with no end for it, so nice to get a notification on that I have to say      (had just made it and not tested the QA) 
But the yellow faults, I dont get 😅
Like this one in main file:

Please login or register to see this link.

translation file:

Please login or register to see this link.

Also added some lua extensions you mentioned in some post here

 

Yes, it doesn't understand that class "lang" creates a global named "lang". (the class)

so it complains that it's an undefined global.

Also it doesn't like globals staring with lower case, as the convention is that global lua variables should start with uppercase.

The solution for the class hog is either to add "lang" as a global in settings.json
 

Please login or register to see this code.

or if you keep the mouse ptr over the offending word you will get a pop-up menu offering a quick fix, it will help to add a ignore undefined globals to the line.

However, it would complain at the net occurrence of "lang".

I would not recommend to ignore undefined globals for the whole file, it kind of defeats the purpose.

[Brors94 115]

6 hours ago, jgab said:

Fingers crossed. 

Getting luarocks working on Windows is not trivial.

Have you tried the Scoop package manager for Windows? It seems to be easiest.

You need to install GCC,GDB,Make - available in the MinGW package from Scoop. And the openssl, that should be in the TLS/SSL toolkit package.

Let me know how it went...

 

Alternatively, if you run vscode, copy the .devcontainer that is part of the hc3emu repo - starts a linux with all the right libs...
The container image in the Dockerfile is set to 

Please login or register to see this code.

Just remove the --platform=arm64 and it should build an x86 version on your platform.

The alternative here with .devcontainer. 
i can do a:

Please login or register to see this code.

and then do the FROM alpine:latest in the terminal? 🤔

 

2 minutes ago, jgab said:

Yes, it doesn't understand that class "lang" creates a global named "lang". (the class)

so it complains that it's an undefined global.

Also it doesn't like globals staring with lower case, as the convention is that global lua variables should start with uppercase.

The solution for the class hog is either to add "lang" as a global in settings.json
 

Please login or register to see this code.

or if you keep the mouse ptr over the offending word you will get a pop-up menu offering a quick fix, it will help to add a ignore undefined globals to the line.

However, it would complain at the net occurrence of "lang".

I would not recommend to ignore undefined globals for the whole file, it kind of defeats the purpose.

 

Aha, So I should change behaviour on uppercase on globals and okey with lowercase on locals then 🤔 

I had some problems when i started to make quickapps I sometimes med uppercase sometimes not 😆 
So decided to make everything lowercase to make it easier for myself 😆

 

 

 

[jgab 2,647]

10 hours ago, Brors94 said:

The alternative here with .devcontainer. 
i can do a:

Please login or register to see this code.

and then do the FROM alpine:latest in the terminal? 🤔
 

 

No, you build and run the container from within the vscode project you closed - or move the .devcontainer folder over to another vscode workspace and do it there.

You need Docker installed so it can build the container according to the Dockerfile spec.

See 

Please login or register to see this link.

It may be a bit different on Windows - I know that they have the WSL (Windows Subsystem for Linux) you can also develop in from vscode, but I don't know if they use something like a Dockerfile to install libraries and dependencies? 

Please login or register to see this link.

I will actually be able to loan an x86 windows machine the upcoming weekend so I will be able to do some more experimentations on Windows...

Edited February 25, 2025 by jgab

[jgab 2,647]

Example. 

In vscode, open two workspaces with QA projects. Here a Pinger QA and a Ponger QA.

Set different ports for the emulators (--%%port= directive) and start them up.

They will ping/pong each other via their proxies running on the HC3.

 

[jgab 2,647]

Implementation details

 

The first line in your lua file should be

Please login or register to see this code.

When that is run, the function require is defined but there are no QuickApp class defined.

It will then continue with the requirement statement  and load the emulator "hc3emu.lua". 

hc3emu.lua will use the

Please login or register to see this link.

to look up the lua call stack to see what file did the "require" - your lua file in this case.

It will then read in that file, treat it as a QA definition file, and start to interpret it. When it's done it will do os.exit(), so we will never "return" from the first require("hc3emu")

 

To run the file as a QA it loads the file in a separate lua environment, with fibaro.*, net.*, api.* functions defined.

This time when the file is loaded (again), require is not defined but the QuickApp class is defined. 

So it will not do require"hc3emu" this time but continue executing the rest of the code in your lua file.

When your code has loaded/executed, the emulator looks into the QA's lua environment and checks if QuickApp.onInit is defined (by your code).

If so it will create the QuickApp object and call quickApp:onInit(), so your QA starts...

 

The emulator has it's own implementation of api.* and will try to intercept all REST calls to the emulated QA to be handled by the emulator.

If we do a api.get("/devices") it will normally just call the HC3 to get all the devices.

If we do a api.get("/devices/"..self.id) then the emulator will intercept and return the emulated device structure for our QA.

 

If we have specified that our QA should have a proxy, it will check if a proxy already exist at startup, else it will create one on the HC3.

With a proxy api calls dealing with our emulated QA will update both the emulator as well as the proxy.

Ex. self:updateProperty("value",44)

will update the value property in our emulator but also the value property of the proxy QA running on the HC3.

 

The proxy also intercepts all UI actions and send them back to the emulator so the QuickApp UI methods we defined gets called.

Proxy also sends back fibaro.calls directed to it, back to the emulator.

 

<more to come>
 

 

 

[jgab 2,647]

Video showing how to work with quickapp children in the emulator.

The proxy on the HC3 will create the children, but we run the code for them in the emulator.
In this case I use the QwikChild library which lets me easily update, ex the custom UI of one of the children,

and regenerate the new child by changing its UID.

 

[jgab 2,647]

Pushed v1.0.24-1

Please login or register to see this code.

• many small bugfixes
• new tools functions 

 

When running in the emulator we have access to fibaro.hc3emu.* containing a lot of convenient functions to manage the emulator.

Please login or register to see this code.

 

...and we can run test program like this

Please login or register to see this code.

 

Edited February 26, 2025 by jgab

[jgab 2,647]

Installing Windows 11 and WSL

 

I have been successful in installing the environment in WSL (Windows Subsystem for Linux)

I choose a standard Ubuntu distro (noble 24.04.2)

 

The approach is that in VSCode (installed in Windows 11), you do a

"Connect to WSL using Distro..." and choose Ubuntu

After installation you will have a terminal in Vscode logged in to the linux distro.

 

If the installed linux run as root, you can create a new user with

Please login or register to see this code.

Then open 

/etc/wsl.conf
and add

Please login or register to see this code.

Disconnect from the WSL instance, or exit in shell

then issue a

Please login or register to see this code.

from PowerShell or CMD. When you restart, the default user should be set.

 

When you connect again to WSL from within VScode you will get a terminal logged in as your user and you can start to install what we need

Please login or register to see this code.

Wen that is done, create file ~/.hc3emu.lua in your home directory with the content

Please login or register to see this code.

 

...and you should be able to start to code with the emulator

 

Here is a video where I do the installation. It doesn't show the "wsl --terminate Ubuntu" step as it was done in a window not recorded.

Also, I don't create the ~/.hc3emu.lua file, because I only test a local example from the repo

 

 

Edited February 28, 2025 by jgab

[jgab 2,647]

Installing on Windows 11 native

 

This is the way I have succeeded in installing for Windows 11. I don't have Windows 10, but if you succeed with this instructions on Win10, let me know.

 

1. You can install mingw, lua, luarocks, and openssl with

Please login or register to see this link.

 package manager.

Please login or register to see this code.

(I do recommend to install git also with scoop).

Scoops is nice because it installs stuff in a single place and it's easy to uninstall a package.

Take note of the scoops app directory. Usually that is

C:\Users\<user>\scoop\apps

 

2. The luasocket rock needs to be installed by hand. 
Download the rock spec file

Please login or register to see this link.

. Must be this file and version.

Now you can build and install it with

Please login or register to see this code.

 

3. Install luasec

When running the luarocks install command we need to specify the directories where openssl was installed
OPENSSL_DIR=<scoop apps directory>\openssl\current

OPENSSL_LIBDIR=<scoop apps directory>\openssl\current\lib\VC\x64\MD

My command looks like this:

Please login or register to see this code.

When it's done, to install hc3emu it should be

Please login or register to see this code.

To update hc3emu to a new version just rerun luarocks install hc3emu command. 
No need to update/install luasocket and luasec again as they never change...

 

4. Setup lua library path

Run 

Please login or register to see this code.

and it will print out what to set 
LUA_PATH

and
LUA_CPATH

to. Go into settings environment variables and set these variables (ignore the PATH variable that is also printed).
LUA_CPATH is usually already set by the lua interpreter, but replace it with the new LUA_CPATH

You may need to restart Windows for it to take...

 

If you want to run zerobrane instead of vscode (or both), install zerobrane-studio

Please login or register to see this code.

In zerobrane studio, Go to Preferences -> Settings: System, and set

Please login or register to see this code.

...where my lua interpreter is set. Yours may be in another place.

In zerobrane, then choose Project -> Lua interpreter -> Lua 5.4

and it will use the installed lua.

Well, that's it.

Edited March 15, 2025 by jgab

[jgab 2,647]

Pushed v1.0.35-1

Please login or register to see this code.

• many small bugfixes and more stability
• emulated quickApp file manipulation api works
• speed time more robust and accurate
• better shellscript support.
  See example tools/hc3tool.lua (separate post to follow)

[jgab 2,647]

Pushed v1.0.42-1

Please login or register to see this code.

• More bugfixes and much better stability.
• Separe file (tools/vscode.lua) supporting vscode tasks

Have been developing a quite complex QA recently that has been forcing me to evolve the emulator quite a lot.

Now it's the best tool so far for me to code QuickApps...

 

Separate support for vscode tasks for

• uploading QA to HC3 from editor
• update/upload individual file from editor to QA on HC3
• Download QA from Hc3 and unpack it to individual lua files with directives for the emulator

Also, the complex QA mention is a generic QA for downloading/updating HC3 QAs from GitHub.

Working in vscode it's a breeze to update QAs and push new versions with this mechanism... about to move over some of my QAs to this download model.

I used to have QAUpdater QA in the past but it was too complex to maintain and update - this is much easier...

 

 

 

[jgab 2,647]

Have managed to install for Windows 11 (not that difficult, when you know how...). Haven't tried Win10 so don't know if it works for that version.