Jeedom plugin to provide a reliable low latency bidirectional client-server communication over websocket protocol.

Events are pushed to clients avoiding long polling (Ajax request) overhead.

Reduce server load by sharing the Jeedom query and broadcast result to multiples clients.

• Install plugin:

  • Upload Websocket.zip file in the Jeedom plugin admin GUI,
  • Set plugin logical id: Websocket,
  • Save and refresh (F5).

• Tune plugin configuration (from plugin configuration GUI):

  • Websocket internal port: any available port (default 8090),
  • Period in seconds between events readings,
  • Period in seconds before closing an unauthenticated connection,
  • Allowed hosts (most important): comma-separated list of hosts which are allowed to connect to websocket, example: myjeedom.ltd,10.0.0.42 (default set to your internal and external Jeedom instance hosts).

• (Optional) proxying websocket port (8090) to regular http (80) / https (443) with Apache (require proxy_wstunnel module) by adding the following lines in /etc/apache2/sites-enabled/000-default.conf:

    <Location "/myawesomesocket">
            ProxyPass ws:https://localhost:8090
            ProxyPassReverse ws:https://localhost:8090
    </Location>
  

• Check daemon configuration:

  • Does webserver user is not www-data?
    • Change line User=www-data
  • Does jeedom path is not /var/www/html/?
    • Change line WorkingDirectory=/var/www/html/plugins/Websocket/core/php
  • Does PHP path is not /usr/bin/php?
    • Change line ExecStart=/usr/bin/php bin/server.php

To get Jeedom events, client:

1. connect to websocket endpoint,
2. send user API key as soon as onopen event occurs,
3. do your useful stuffs with Jeedom events.

JavaScript example:

//1. connect
const websocket = new WebSocket('ws:https://10.0.0.42/myawesomesocket')

//2. send user credentials
websocket.onopen = (e) => {
  const authMsg = JSON.stringify({ apiKey: 'userApiKey' })
  websocket.send(authMsg)
}

//3. Handle events
websocket.onmessage = (e) => {
  //do stuff with Jeedom events (e.data.result)
}
websocket.onerror = (e) => {
  //handle error
}
websocket.onclose = (e) => {
  //handle connection closed
}

• Nioc - Initial work

See also the list of contributors to this project.

This project is powered by the following components:

• Ratchet (MIT)
• NextDom plugin-template (GPLv2)
• Jeedom (GPL)