warema-wms-venetian-blinds-ws-api

Websocket api to control Warema venetian blinds by Warema WMS Stick.

Usage no npm install needed!

<script type="module">
  import waremaWmsVenetianBlindsWsApi from 'https://cdn.skypack.dev/warema-wms-venetian-blinds-ws-api';
</script>

README

warema-wms-venetian-blinds-ws-api - WebSocket API for Warema WMS radio control system.

warema-wms-venetian-blinds-ws-api is a websocket API for the Warema WMS (WAREMA Mobile System) radio control system. It is a websocket API mapper for module warema-wms-venetian-blinds.

Table of contents

Prerequisites, features and limitations

See warema-wms-venetian-blinds.

Note:
This module does not replace the initial commissioning of the Warema WMS network by a specialist company.

Install

You can get warema-wms-venetian-blinds-ws-api via npm.

$ npm install warema-wms-venetian-blinds-ws-api

To get WMS network parameters follow instructions in warema-wms-venetian-blinds.

Usage

Example:

//----------------------------------------------------------------------
// Warema WMS venetian blinds WebSocket API
//
// Demo Server
//----------------------------------------------------------------------
const WmsVbWsApi = require( "warema-wms-venetian-blinds-ws-api" );

//----------------------------------------------------------------------
const settingsPar = {
    // wmsKey inclusion mode="00112233445566778899AABBCCDDEEFF"
    wmsKey       : process.env.WMS_KEY||"FEDCBA9876543210FEDCBA9876543210", 
    wmsChannel   : 17,
    // wmsPanid inclusion mode="FFFF"
    wmsPanid     : process.env.WMS_PANID||"FE10", 
    wmsSerialPort: '/dev/ttyUSB0',
    wsPort       : 8080,
    wsPath       : "/wmsvnblind/ws"
  };

var wsApi = new WmsVbWsApi( settingsPar );

// Examples for setting up WmsVbWsApi:
// wsApi.stickUsb.setPosUpdInterval(10000);
// wsApi.stickUsb.setWatchMovingBlindsInterval(200);
// wsApi.getLogger().setLogLevel( 'T' ); // log levels: E: Error, W: Warning, I: Info (Default), D: Debug, T: Trace
// wsApi.stickUsb.setCmdConfirmationNotificationEnabled( true );

console.log( 'started '+JSON.stringify( settingsPar ) );

// In real live add blinds here instead of using 
// "scanDevices" with {options: { autoAssignBlinds: true } }
//
//~ var ki_le = wsApi.stickUsb.vnBlindAdd( 580911, "Kitchen left" );
//~ // ...
//~ var liv_3 = wsApi.stickUsb.vnBlindAdd( 626216, "Living room 3" );
//~ console.log( "Added blinds:\n"+ 
             //~ JSON.stringify( wsApi.stickUsb.vnBlindsList() ) );

This example provides the WebSocket interface on http://127.0.0.1:8080/wmsvnblind/ws.

HTML demo

warema-wms-venetian-blinds-ws-api provides a HTML page as client demo. The example above provides it at http://127.0.0.1:8080/demo.

HTML status

warema-wms-venetian-blinds-ws-api provides a status page which you can call in your web browser. The example above provides it at http://127.0.0.1:8080/.

API

How does the Websocket API work?

Data in both directions is exchanged in JSON format via the WebSocket.

Commands

{
  "command": "<<command name>>",
  "data": { <<data object depending on commmand>> }
}

Notifcations

{
  "topic": "<<topic of data>>",
  "payload": "<<data>>"
}

Command vnBlindsList

{"command":"vnBlindsList","data":{}}

Notifications

  • wms-vb-scanned-devices

Command scanDevices

{"command":"scanDevices","data":{"options":{"autoAssignBlinds":true}}}

Parameters

  • options
    Parameter options is optional.
    { autoAssignBlinds: true }: The venetian blinds assigned to the stick are cleared. Scanned devices of types 20 (Actuator UP) and 21 (Plug receiver) are automatically assigned to the stick.

Notifications

  • wms-vb-scanned-devices

ommand getStatus

Gets status of stick

{"command":"getStatus","data":{}}

Notifications

  • wms-vb-stick-status

Command setPosUpdInterval

{"command":"setPosUpdInterval","data":{"intervalMsec":5000}}

The command sets the interval at which the position of the blinds is read. If you omit the interval or set it to less than 5000 msec, the automatic update of the position is disabled.

Parameters

  • intervalMsec
    Interval for reading current blind position in milliseconds.

Notifications

  • wms-vb-blind-position-update
    This message is emitted when a blind position/angle changes.

Command vnBlindGetPosition

{"command":"vnBlindGetPosition","data":{"blindId":"87240A"}}

Parameters

  • blindId
    • This parameter may be the snr, the snrHex or the name of a venetian blind.
    • If blindId is omitted, the notification message contains an array of all blind's status.

Notifications

  • wms-vb-cmd-result-get-position
    Confirmation of command (if enabled, see module warema-wms-venetian-blinds).
  • wms-vb-blind-position-update
    This notification is sent regardless of whether the position of the blind has changed since the last position determination or not.

Command vnBlindWaveRequest

{"command":"vnBlindWaveRequest","data":{"blindId":"87240A"}}

Parameters

  • blindId
    This parameter may be the snr, the snrHex or the name of a venetian blind.

Notifications

  • wms-vb-blind-position-update
    This notification may be sent if commnad changes the position of the blind.

Command vnBlindGetStatus

{"command":"vnBlindGetStatus","data":{"blindId":"87240A"}}

Parameters

  • blindId
    • This parameter may be the snr, the snrHex or the name of a venetian blind.
    • If blindId is omitted, the notification message contains an array of all blind's status.

Notifications

  • wms-vb-blind-status

Command vnBlindSetPosition

{"command":"vnBlindSetPosition","data":{"blindId":"87240A","position":0,"angle":-100}}

Parameters

  • blindId
    This parameter may be the snr, the snrHex or the name of a venetian blind.
  • position
    Level of the blind in percent from 0 to 100. At position 0 the blind is completely opened. Set the angle to -100 to completely retract the blind into the cover. At position 100 the blind is fully closed.
  • angle
    Angle of the blind's slats in percent from -100 to 100. At angle -100 the slats are completely inclined inwards. At angle 0 the slats are in horizontal position. At angle 100 the slats are completely inclined outwards.

Notifications

  • wms-vb-cmd-result-set-position Confirmation of command (if enabled, see module warema-wms-venetian-blinds).

Command vnBlindSlatUp

The slats tilt up. (The angle is decreased to the next position.)
Available positions of the slats [%]: -100, -66, -33, 0, 33, 66 , 100
When the end position of +/-100% is reached, no more movement takes place (no up/down).

{"command":"vnBlindSlatUp","data":{"blindId":"87240A"}}

Parameters

  • blindId

Notifications

  • wms-vb-blind-position-update
    This notification may be sent if commnad changes the position of the blind.

Command vnBlindSlatDown

The slats tilt down. (The angle is increased to the next position.)
Available positions of the slats [%]: -100, -66, -33, 0, 33, 66 , 100
When the end position of +/-100% is reached, no more movement takes place (no up/down).

{"command":"vnBlindSlatDown","data":{"blindId":"87240A"}}

Parameters

  • blindId

Notifications

  • wms-vb-blind-position-update
    This notification may be sent if commnad changes the position of the blind.

Command vnBlindStop

Stops the venetian blind. Currently progressed requests of vnBlindSetPosition(...) of the blinds concerned are canceled.

{"command":"vnBlindStop","data":{"blindId":"87240A"}}

Parameters

  • blindId
    • This parameter may be the snr, the snrHex or the name of a venetian blind.
    • If blindId is omitted, a stop request is sent to all blinds.

Notifications

  • wms-vb-cmd-result-stop Confirmation of command (if enabled, see module warema-wms-venetian-blinds).
  • wms-vb-blind-position-update
    This notification may be sent if commnad changes the position of the blind.

Command vnBlindRemove

Removes the venetian blind from the stick's registered blind list. Any pending communication to the blinds concerned are canceled.

{"command":"vnBlindRemove","data":{"blindId":"87240A"}}

Parameters

  • blindId
    • This parameter may be the snr, the snrHex or the name of a venetian blind.
    • If blindId is omitted, all blinds are removed from the stick's registered blind list.

Notification wms-vb-registered-devices

{
  "topic": "wms-vb-registered-devices",
  "payload": [
    {
      "snr": 580911,
      "snrHex": "2FDD08",
      "name": "Actuator UP 580911 (2FDD08)"
    },
    {
      "snr": 637180,
      "snrHex": "FCB809",
      "name": "Plug receiver 637180 (FCB809)"
    }
  ]
}

Notification wms-vb-scanned-devices

{
  "topic": "wms-vb-scanned-devices",
  "payload": {
    "devices": [
      {
        "snr": 627233,
        "snrHex": "219209",
        "type": "02",
        "typeStr": "Stick/software   "
      },
      {
        "snr": 637180,
        "snrHex": "FCB809",
        "type": "21",
        "typeStr": "Plug receiver    "
      }
    ]
  }
}

Notification wms-vb-stick-status

[
    {
        "topic": "wms-vb-stick-status",
        "payload": {
            "name": "/dev/ttyUSB0",
            "startupTS": "2020-01-27T08:48:49.598Z",
            "status": "ready",
            "posUpdIntervalMsec": 5000,
            "wmsSentCount": 36,
            "wmsSentTS": "2020-01-27T08:52:54.698Z",
            "wmsRecievedCount": 30,
            "wmsRecievedTs": "1970-01-01T00:00:00.000Z",
            "wmsComDuration": 1159,
            "wmsComMaxDuration": 83,
            "wmsComAvgDuration": 39,
            "wmsRetryCount": 6,
            "wmsRetryTs": "1970-01-01T00:00:00.000Z",
            "wmsRetryRate": 0.16666666666666666,
            "wmsTimeoutCount": 0,
            "wmsTimeoutTS": "1970-01-01T00:00:00.000Z",
            "wmsTimeoutRate": 0
        }
    }
]

Notification wms-vb-blind-position-update

A message with this topic is emitted, when a change of the position of a blind is detected or command vnBlindGetPosition is called.

{
  "topic": "wms-vb-blind-position-update",
  "payload": {
    "snr": 664711,
    "snrHex": "87240A",
    "name": "Actuator UP 664711 (87240A)",
    "position": 50,
    "angle": -100
  }
}

Notification wms-vb-blind-status

{
  "topic": "wms-vb-blind-status",
  "payload": [{
    "snr": 664711,
    "snrHex": "87240A",
    "name": "Actuator UP 664711 (87240A)",
    "creationTs": "2020-01-27T08:52:02.318Z",
    "posCurrent": {
      "pos": 4,
      "ang": -33
    },
    "posRequested": {
      "pos": 0,
      "ang": -100
    },
    "wmsSentCount": 167,
    "wmsSentTS": "2020-01-27T09:06:03.955Z",
    "wmsRecievedCount": 167,
    "wmsRecievedTs": "1970-01-01T00:00:00.000Z",
    "wmsComDuration": 5615,
    "wmsComMaxDuration": 50,
    "wmsComAvgDuration": 34,
    "wmsRetryCount": 0,
    "wmsRetryTs": "1970-01-01T00:00:00.000Z",
    "wmsRetryRate": 0,
    "wmsTimeoutCount": 0,
    "wmsTimeoutTS": "1970-01-01T00:00:00.000Z",
    "wmsTimeoutRate": 0
  }]
}

Notification wms-vb-cmd-result-set-position

Result of command vnBlindSetPosition. In case of error property error contains details.

{
  "topic": "wms-vb-cmd-result-set-position",
  "payload": {
    "error": "",
    "snr": 664711,
    "snrHex": "87240A",
    "name": "Actuator UP 664711 (87240A)",
    "position": 0,
    "angle": -100
  }
}

Notification wms-vb-cmd-result-stop

Result of command vnBlindStop. In case of error property error contains details.

{
  "topic": "wms-vb-cmd-result-stop",
  "payload": {
    "error": "",
    "snr": 664711,
    "snrHex": "87240A",
    "name": "Actuator UP 664711 (87240A)"
  }
}

Credits

Many thanks to "Pman" and "willjoha" on https://forum.iobroker.net/topic/7336/iobroker-mit-warema-wms-web-control! Your research is the basis for this package.

Change Log

  • 1.0.0, 1.0.1 November/11/2021
    • Adopting features of version 2.0.0. of warema-wms-venetian-blinds
    • Improved example code
    • Possibility to set log level
  • 0.0.14, 0.0.15, 0.0.16 September/27/2021
    • Added attribute moving in payload of topic wms-vb-blind-position-update
    • Fixed issues in readme.md.
  • 0.0.13
    • Documentation of vnBlindGetStatus: May be called without blindId.
  • 0.0.12
    • Added vnBlindRemove.
  • 0.0.10, 0.0.11
    • Commands vnBlindStop, vnBlindGetPosition and vnBlindGetStatus can optionally be called without blindId. Then command is performed for each registered blind.
    • vnBlindGetStatus notification wms-vb-blind-status returns an array in payload.
  • 0.0.9
    • First production release.

License

warema-wms-venetian-blinds-ws-api is MIT licensed and all it's dependencies are MIT licensed.