[New in development] Bidirectional WebSocket channel between Python plugins and the Web UI

[gizmocuz]

Hi all,

A new feature just landed in the development branch that lets a Python plugin talk directly and in real time to a
custom Web UI page (and back) over Domoticz's existing WebSocket connection — no polling, no extra HTTP endpoints.

What it does

- A plugin can push arbitrary data to the frontend at any time with one call.
- A custom page can send commands back to the plugin.
- Everything is keyed by the plugin, so it works correctly even when you have multiple hardware instances of the same
plugin — a page receives messages from all instances, and a command fans out to all of them (or you can target one).
Every message carries the originating HardwareID.

Plugin side (Python)

Push to subscribed pages (dict is sent as JSON, or send a plain string; 64-bit ints like JS timestamps are fine):

Code: Select all

  Domoticz.WebSocketSend({"type": "tick", "value": 42})
  

Receive commands from a page (optional callback; safe to omit):

Code: Select all

  def onWebSocketMessage(self, Data):
      # Data is a string (JSON text when the page sent an object)
      Domoticz.Log("Got: %s" % Data)
  

Frontend side (custom page)

The livesocket service gained four helpers:

Code: Select all

  livesocket.subscribePlugin('MyPluginKey');
  livesocket.onPluginMessage('MyPluginKey', function (msg) {
      // msg = { plugin, hwid, data }
  });
  livesocket.sendPluginCommand('MyPluginKey', { cmd: 'ping' });   // optional 3rd arg: hwid
  livesocket.unsubscribePlugin('MyPluginKey');
  

The topic is simply plugin:<your plugin key> — i.e. the exact key= from your plugin's XML header. Subscriptions
survive reconnects automatically.

Documentation

Full reference (the Domoticz.WebSocketSend callable API, the onWebSocketMessage callback, the
topic/multi-instance/hwid contract, security, and a complete custom-page example):

https://wiki.domoticz.com/Developing_a_Python_plugin

See the new "Plugin WebSocket Channel" section (under UI), plus the WebSocketSend entry in the C++ Callable API table
and the onWebSocketMessage entry in the Callbacks list.

Working example

A complete, runnable example ships in the source tree:

plugins/examples/WebSocketChannelTest/ — a plugin (plugin.py) plus an AngularJS custom page (wschanneltest.html)
demonstrating live push, ping→pong round-trip, multi-instance fan-out, and install/remove of a
custom page into www/templates. Note: Domoticz only discovers plugins in plugins/<Name>/, so copy the folder to e.g.
plugins/WebSocketChannelTest/ to run it.

This is in development now — available if you build from source, and in the current beta. Feedback welcome, but if there needs to be made changes/enhancements, create a github issue