warema-wms-venetian-blinds-ws-api

v1.0.3

Published

9 months ago

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

Downloads

0High
0Medium
0Low

aemm

warema venetian blinds wms

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 work is the most valuable knowledge base for this package!

Change Log

1.0.3 Apr/01/2024
- Improved layout of HTML demo
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. Then command is performed for each registered blind.
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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

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

Prerequisites, features and limitations

Install

Usage

HTML demo

HTML status

API

How does the Websocket API work?

Commands

Notifcations

Command vnBlindsList

Command scanDevices

ommand getStatus

Command setPosUpdInterval

Command vnBlindGetPosition

Command vnBlindWaveRequest

Command vnBlindGetStatus

Command vnBlindSetPosition

Command vnBlindSlatUp

Command vnBlindSlatDown

Command vnBlindStop

Command vnBlindRemove

Notification wms-vb-registered-devices

Notification wms-vb-scanned-devices

Notification wms-vb-stick-status

Notification wms-vb-blind-position-update

Notification wms-vb-blind-status

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

Notification wms-vb-cmd-result-stop

Credits

Change Log

License