Debug JS files in VSC with a debugger (how-to)

Setup, Configuration and Use Beginners
1

Hi all,
anyone ever wished they could debug their OH rules with a debugger ? I mean like using breakpoints, watching variables and all that ? Here you go (JS files only) :slight_smile:

OpenHAB ships GraalJS but not the debug instrument. You supply it. Four steps:

  1. Download 3 JARs, patch their manifest. The JARs (chromeinspector-tool, profiler-tool, json) are plain Maven artifacts. They need one manifest header added (Fragment-Host: org.openhab.osgiify.org.graalvm.truffle.truffle-api) so OSGi merges them into the Truffle classloader. A Python script does this automatically — downloads, patches, deploys to /openhab/addons/:

    python3 wrap_graal_fragments.py --deploy /opt/openhab/addons

  2. Copy a launch config to VS Code. Paste this into .vscode/launch.json:

    {
    "type": "node", "request": "attach",
    "name": "Attach to OpenHAB GraalJS",
    "address": "<YOUR_OPENHAB_IP>", "port": 9229,
    "localRoot": "${workspaceFolder}/automation/js",
    "remoteRoot": "/openhab/conf/automation/js",
    "restart": true, "continueOnAttach": true
}

  3. Expose port 9229 and add JVM flags (Docker only). In docker-compose.yaml:

    ports:
  - "9229:9229"
environment:
  - EXTRA_JAVA_OPTS=...existing... -Dpolyglot.inspect=0.0.0.0:9229 -Dpolyglot.inspect.Suspend=false -Dpolyglot.inspect.WaitAttached=false -Dpolyglot.inspect.Secure=false

  4. Restart. docker compose stop openhab && docker compose rm -f openhab && docker compose up -d openhab

That’s it. Trigger any JS rule, then press :play_button: in VS Code’s debug panel. The rest of this document explains why each step is needed and what to do when something goes wrong.

image
image1043×805 93.1 KB

For more details visit the repo. And ask claude to set it up for you…

Next steps (to make this even easier): Someone add the OSGI wrapped .jar files to the OpenHAB distribution :wink:

2

Nice you got it working! I also tried, but lost interest.

I still have Add Graal chromeinspector-tool by florian-h05 · Pull Request #89 · openhab/openhab-osgiify · GitHub, which I can modify to OSGi-fy all required JARs and add them to the Distro.

Just one thing:
Fragment-Bundle is rather bad practise IMO, rather service loading should be set up properly.

EDIT: I was able to get ServiceLoader working in the OSGi-fied Graal bundles.

3

I currently try to find out if there is a maintainer for the vs-code extension, as I have interest to get this part of the project active again. openHAB with the possibility to maintain rules in git repo including regression tests, using the extension to keep them in sync with the server - combined with the debugger. Sounds like a real USP for openHAB …

I’m not aware of another system that could claim to offer web based rule editing, including Blockly  |  Google for Developers - or fully git tracked rules (including regression tests) and debugging in a local IDE.

see also:

What do you think?

with kind regards,
Patrik

4

Not sure, but at least some modifications recently:

5

Hi @s0170071 and @patrik_gfeller,

I have now properly OSGi-ified the required GraalVM JARs (using OSGi’s ServiceLoader mediator), added them as feature dependency to JS Scripting and implemented a configuration option for JS Scripting to enable/disable the debugger and set its port.
Using this is similar to what @s0170071 has done, but it’s easier to get it running as it only requires changing an add-on setting and restarting openHAB.
See [jsscripting] Implement debugger support by florian-h05 · Pull Request #20440 · openhab/openhab-addons · GitHub.

Testing that PR is a bit difficult as you cannot simply drop the JAR into your addons folder, but you also need to deploy the feature dependencies and setup their start-levels so ServiceLoader mediator works properly.
Maybe you want to wait a bit till you can try it out in the snapshot builds.

6

Hi all,

my PR has been merged (and we now also have integration tests for JS Scripting), you can use the debugger in the latest snapshot builds.
It has to be enabled in the add-on settings and is then available for all scripts after a restart.

@patrik_gfeller @s0170071 Do you know how to debug scripts that are created through the UI? For file-based, it’s pretty straightforward, but how does the mapping between breakpoints and UI scripts happen?

7

@florian-h05 Not yet … At the moment I’m finishing the Jellyfin work to get this released. Then I propose to release a small update of the VS code extension with the changes we already did to verify that we can deploy to the official extension “marketplace”.

Once that works and Jellyfin is merged I’ll concentrate on JavaScript in the extension and start with the debugger. I hope I can integrate directly - but even if that does not work I’ve a backup idea which should work (would involve some more logic in the extension - therefore 2nd choice). I’ll give more details once we can deploy and the current binding work is done.

kind regards,
Patrik

8

I’ll wait with the docs then, the feature is in and will be shipped with 5.2. Docs can be easily updated after the release.

9

Maybe we can target a 1.0.1 release of the extension together with 5.2 to make it visible again and to check if the release process to the marketplace works. There are already some small improvements - and of course the marketing aspect of it.

10

No, sorry. I am not using the UI so I haven’t looked into it.