New binding: Selve rollershutter binding

netgab · August 16, 2018, 6:09pm

Hello board,
I’m an openHab user for some time now. Now I got something new … an USB dongle, that contains a Gateway solution for Selve rollershutter RF motors.
The USB key is basically a virtual Serial port towards the Operating System. I tested it with a current Debian release and it automatically creates a virtual Serial port (/dev/tty ….).

The commands for the rollershutters is passed in XML (using screen or minicom or putty or or or…) to the RF Gateway.
The Vendor selve offers a Pretty good documentation regarding the API
(Software für SmartHome "SELVE Home" herunterladen | SELVE) - sorry it’s in German.

So the Question is … should I use an existing “Serial” binding for it? From my Point of view it is more user friedly to develop a Special binding for this, that a user must not the bothered with the API directly. What do you think?

I’m a Network Consultant and used to program in Python, C#, PowerShell and of curse the litte bash helpers. However, I’m completely new to Java but I’m keen to give it a try.

So here are some Questions:

Do you think this binding is worth it? Meaning is there a user base, that is interested in it?
It it better to not do it and use an existing General Serial binding (and probably write a how-to for the Integration of the “selve USB key” as a use-case?
A good hint how to start. As i wrote before, I’m started here: https://www.openhab.org/docs/developer/contributing/contributing.html#the-repositories
Which Namespace to Chose?

Thanks in Advance
netgab / joe

P.S.: Don’t know why my browser auto-corrects the upper- and lowercase in this text in a weird way … just ignore the incorrect case-sensitivity

rlkoshak · August 16, 2018, 7:36pm

That’s a good way to prototype and work through the details of the API. Once you know the ins and outs of the API it might inform design decisions when you start to build the binding itself.

There is at least one user who is interested in it, you. And binds are like Field of Dreams, if you build it they will come.

Like I said, that isn’t a bad approach. It lets you focus on one thing (the API) without needing to tackle the added complexity of learning Java and working with the OH libraries and such. Several bindings developed this way.

Read all of the articles under Developer Guide.

Follow the convention the other bindings use. I think it would be org.openhab.binding.selve but verify.

Good luck!

Syn · January 10, 2019, 10:55am

Hi Johannes @netgab,
did you start (or have even finished) building the selve roller shutter binding?
Thanks for your reply!
Christoph

netgab · January 10, 2019, 11:05am

Hi Christoph @Syn,
sorry - not even started with the binding (too lazy learning Java)
However I managed to get it working using the # Serial Binding.

Are you interested in the details?

Syn · January 10, 2019, 11:12am

Yes, I will get some selve blinds shortly. So I would be very happy, if you could share your way of making them work with openhab!

netgab · January 10, 2019, 12:00pm

Well … that’s good … finally there’s a reason to document the whole stuff because someone is interested.

**Optional: Device symlink **
First of all my openhab runs on a Debian Linux system. You have to make sure, that the USB key is recognized by the system (e.g. dmesg) or lsusb.
Because the device name of the USB key must be hardcoded in the openhab application I make sure, that a generic symlink is created for the /dev/ttyUSB device, which is used by openhab. Example:

$ ls /dev/ttyUSB -la
crw-rw-rw- 1 root dialout 188, 0 Jan 10 06:26 /dev/ttyUSB0
lrwxrwxrwx 1 root root         7 Dec  8 15:55 /dev/ttyUSB_selve -> ttyUSB0

So in my case I tell openhab to use the device /dev/ttyUSB_selve. For most Debian systems this can be acomplished using an udev rule. I created a new file:
/etc/udev/rules.d/10-USBSelve_TTY.rules
SUBSYSTEM==“tty”, ATTRS{idVendor}==“0403”, ATTRS{idProduct}==“6015”, ATTRS{serial}==“DM00B3ZB”, ATTRS{product}==“FT230X Basic UART”, SYMLINK+=“ttyUSB_selve”, GROUP=“dialout”, MODE=“0666”

You have to edit the idVendor, idProduct, product and serial attribute. The values can be obtained by the dmesg output when plugging in the key. An alternative is:
udevadm info --name=/dev/ttyUSB --attribute-walk

**Basic config (Linux): **
In the file “/etc/default/openhab2” I had to add the serial port to the JAVA_OPTS variable by adding the line (section JAVA OPTIONS for good documentation)
EXTRA_JAVA_OPTS=“-Dgnu.io.rxtx.SerialPorts=/dev/ttyUSB_selve”
==> Openhab needs to be restarted now

Items file (/etc/openhab2/items/selve.items)
Example for one rollershutter:

Rollershutter  rollershutter_selve_living_state     { serial="/dev/ttyUSB_selve@115200,UP(<methodCall><methodName>selve.GW.iveo.commandManual</methodName><array><base64>AQAAAAAAAAA=</base64><int>1</int></array></methodCall>),DOWN(<methodCall><methodName>selve.GW.iveo.commandManual</methodName><array><base64>AQAAAAAAAAA=</base64><int>2</int></array></methodCall>),STOP(<methodCall><methodName>selve.GW.iveo.commandManual</methodName><array><base64>AQAAAAAAAAA=</base64><int>0</int></array></methodCall>)"}

Basically the base64 string (example above AQAAAAAAAAA=) controls which rollershutter to use. This is documented in the Selve XML API documentation.
In very short:
Per rollershutter you assign a channel in the USB RF gateway. More or less this is the same as when you program a selve remote control. I won’t go into details here, because this is not an openhab specific issue. This is all selve black magic. Read the selve documentation for this One little hint: What helps is the XML API Windows Tool from selve to debug the whole stuff. (SELVE | Your partner for everything to do with roller shutters & sun protection)

Back to the Base64 string:
The channel ID mask is 8 Byte long. Each bit of represents one channel ID. If the bit in the mask is set to “1” to corresponding channel is used for the operation.
Now the brainf*** begins. First of all you need to determine the right bit for the corresponding channel. As documented in the XML API of selve here are some examples for the mask:
Byte 0.0 IveoID 0
Byte 0.7 IveoID 7
Byte 1.0 IveoID 8
Byte 7.7 IveoID 63

Now… how to get the base64 string for one (or a set of IDs)? Examples:
Channel 1 (Mask address Byte block index 0 / first bit [least significant])
Hex: 01 00 00 00 00 00 00 00
Bin: 00000001 00000000 00000000 00000000 00000000 00000000 00000000 00000000
Base64: AQAAAAAAAAA=

Channel 2 (Mask address Byte block index 0 / second bit [least significant])
Hex: 02 00 00 00 00 00 00 00
Bin: 00000010 00000000 00000000 00000000 00000000 00000000 00000000 00000000
Base64: AgAAAAAAAAA=

Channel 3 (Mask address Byte block index 0 / third bit [least significant])
Hex: 04 00 00 00 00 00 00 00
Bin: 00000100 00000000 00000000 00000000 00000000 00000000 00000000 00000000
Base64: BAAAAAAAAAA=

[…]

Channel 11 (Mask address Byte block index 1 / third bit [least significant])
Hex: 00 04 00 00 00 00 00 00
Bin: 00000000 00000100 00000000 00000000 00000000 00000000 00000000 00000000
Base64: AAQAAAAAAAA=

Of course you can control multiple channels at the same time.
Example Channel 1 and 2
Hex: 03 00 00 00 00 00 00 00
Bin: 00000011 00000000 00000000 00000000 00000000 00000000 00000000 00000000
Base64: AwAAAAAAAAA=

Hex to Base64 conversion: Base64 to hex: Encode and decode bytes online - cryptii

Again - please read and understand the XML API and the USB key itself!

Syn · January 10, 2019, 2:29pm

Thanks a lot! When the blinds are installed, I will have a closer look. And maybe I’m going to bother you with some questions

Syn · May 8, 2019, 6:01pm

Thanks again for your guide, it has helped me a lot. Let me add some notes and things I stumbled upon:

First of all: don’t forget to install the serial binding

Second, regarding the udev rule: be aware of double quotes, when you paste and copy (" vs. “ and ”)

Third the selve stuff itself:
I have commeo roller shutters, and I don’t need the whole base64 stuff (you could use it, but you haven’t) and there are of course other API calls.
So maybe it is helpful for other users to post the way I put it together (maybe there’s a better way to get the actual state of the roller shutters?!):

selve.items

String          rollershutter_selve_gw_responses     { serial="/dev/ttyUSB_selve@115200"}
String          rollershutter_selve_gw_command     { serial="/dev/ttyUSB_selve@115200"}

Rollershutter  rollershutter_selve_WZi_li     { serial="/dev/ttyUSB_selve@115200,UP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>1</int><int>1</int><int>0</int></array></methodCall>),DOWN(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>2</int><int>1</int><int>0</int></array></methodCall>),STOP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>0</int><int>1</int><int>0</int></array></methodCall>)"}
Switch         rollershutter_selve_WZi_li_pos1   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>3</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Switch         rollershutter_selve_WZi_li_pos2   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>5</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Number         rollershutter_selve_akt_WZi_li   "Aktuelle Position WZi li [SCALE(selve.scale):%s]" <rollershutter>

Rollershutter  rollershutter_selve_WZi_re     { serial="/dev/ttyUSB_selve@115200,UP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>1</int><int>1</int><int>1</int><int>0</int></array></methodCall>),DOWN(<methodCall><methodName>selve.GW.command.device</methodName><array><int>1</int><int>2</int><int>1</int><int>0</int></array></methodCall>),STOP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>1</int><int>0</int><int>1</int><int>0</int></array></methodCall>)"}
Switch         rollershutter_selve_WZi_re_pos1   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>1</int><int>3</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Switch         rollershutter_selve_WZi_re_pos2   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>1</int><int>5</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Number         rollershutter_selve_akt_WZi_re   "Aktuelle Position WZi re [SCALE(selve.scale):%s]" <rollershutter>

Rollershutter  rollershutter_selve_Kue_li     { serial="/dev/ttyUSB_selve@115200,UP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>2</int><int>1</int><int>1</int><int>0</int></array></methodCall>),DOWN(<methodCall><methodName>selve.GW.command.device</methodName><array><int>2</int><int>2</int><int>1</int><int>0</int></array></methodCall>),STOP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>2</int><int>0</int><int>1</int><int>0</int></array></methodCall>)"}
Switch         rollershutter_selve_Kue_li_pos1   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>2</int><int>3</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Switch         rollershutter_selve_Kue_li_pos2   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>2</int><int>5</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Number         rollershutter_selve_akt_Kue_li   "Aktuelle Position Kue li [SCALE(selve.scale):%s]" <rollershutter>

Rollershutter  rollershutter_selve_Kue_re     { serial="/dev/ttyUSB_selve@115200,UP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>3</int><int>1</int><int>1</int><int>0</int></array></methodCall>),DOWN(<methodCall><methodName>selve.GW.command.device</methodName><array><int>3</int><int>2</int><int>1</int><int>0</int></array></methodCall>),STOP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>3</int><int>0</int><int>1</int><int>0</int></array></methodCall>)"}
Switch         rollershutter_selve_Kue_re_pos1   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>3</int><int>3</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Switch         rollershutter_selve_Kue_re_pos2   { serial="/dev/ttyUSB_selve@115200,ON(<methodCall><methodName>selve.GW.command.device</methodName><array><int>3</int><int>5</int><int>1</int><int>0</int></array></methodCall>)", expire="15s,OFF"}
Number         rollershutter_selve_akt_Kue_re   "Aktuelle Position Kue re [SCALE(selve.scale):%s]" <rollershutter>

selve.rules

rule "roller shutter"
when
    Item rollershutter_selve_gw_responses received update
then
val String xml = rollershutter_selve_gw_responses.state.toString
    if(xml.contains("selve.GW.device.getValues")){
        val String rollade = xml.split("<").get(18).replace("string>", "")
        val rollade_status = xml.toString.split("<").get(10).replace("int>", "")
        if(rollade == "WZi li"){
            rollershutter_selve_akt_WZi_li.postUpdate(rollade_status)
        }
        else if(rollade == "WZi re"){
            rollershutter_selve_akt_WZi_re.postUpdate(rollade_status)
        }
        else if(rollade == "Kue li"){
            rollershutter_selve_akt_Kue_li.postUpdate(rollade_status)
        }
        else if(rollade == "Kue re"){
            rollershutter_selve_akt_Kue_re.postUpdate(rollade_status)
        }
    } else if(xml.contains("selve.GW.command.device")){
//        do nothing
    } else if(xml.contains("selve.GW.event.device")){
        val String rollade = xml.split("<").get(18).replace("string>", "")
        val rollade_status = xml.split("<").get(10).replace("int>", "")
        if(rollade == "WZi li"){
            rollershutter_selve_akt_WZi_li.postUpdate(rollade_status)
        }
        else if(rollade == "WZi re"){
            rollershutter_selve_akt_WZi_re.postUpdate(rollade_status)
        }
        else if(rollade == "Kue li"){
            rollershutter_selve_akt_Kue_li.postUpdate(rollade_status)
        }
        else if(rollade == "Kue re"){
            rollershutter_selve_akt_Kue_re.postUpdate(rollade_status)
        }
    }
end

rule "roller shutter cron"
when
    Time cron "0 0/15 * 1/1 * ? *"
then
    rollershutter_selve_gw_command.sendCommand("<methodCall><methodName>selve.GW.device.getValues</methodName><array><int>0</int></array></methodCall>")
    Thread::sleep(220)
    rollershutter_selve_gw_command.sendCommand("<methodCall><methodName>selve.GW.device.getValues</methodName><array><int>1</int></array></methodCall>")
    Thread::sleep(220)
    rollershutter_selve_gw_command.sendCommand("<methodCall><methodName>selve.GW.device.getValues</methodName><array><int>2</int></array></methodCall>")
    Thread::sleep(220)
    rollershutter_selve_gw_command.sendCommand("<methodCall><methodName>selve.GW.device.getValues</methodName><array><int>3</int></array></methodCall>")
end

selve.scale

[..51]=0%
]51..6553]=10%
]6553..13106]=20%
]13106..19659]=30%
]19659..26212]=40%
]26212..32765]=50%
]32765..39318]=60%
]39318..45871]=70%
]45871..52424]=80%
]52424..58977]=90%
[58977..65535]=100%

weisslein · June 9, 2020, 1:20pm

Hi everybody,

first of all thanks for this selve example. I used this example on my raspberry pi 3, but I had some problems with the strings from the serial binding. I was not able to proceed the data until I removed all of the tabs, spaces from the selve gateway.
The solution was the addition of the following line in the rule: xml.replaceAll(‘(\r\n|\n\r|\r|\n|\t)’, ‘’)

    ...    
    var String xml = rollershutter_selve_gw_responses.state.toString
    xml = xml.replaceAll('(\r\n|\n\r|\r|\n|\t)', '')
    if(xml.contains("selve.GW.device.getValues")){
    ...

Now the selve gateway works without any problems. thx

Christian79 · May 1, 2021, 6:38pm

Hi Christoph, hi Johannes,

thank you for the nice tutorial. It helped me a lot to get the Selve system set up. I am using OpenHab 3. I had to make a couple of changes in the rule to also support multiple commands over the serial port. That is the case, when all rollshutters start move up or down. I am not sure, if it is the best approach, but it works

triggers:
  - id: "1"
    configuration:
      itemName: SelveGatewayResponses
    type: core.ItemStateUpdateTrigger
conditions: []
actions:
  - inputs: {}
    id: "2"
    configuration:
      type: application/vnd.openhab.dsl.rule
      script: >-
        val gateway = SelveGatewayResponses.state.toString      
        val xml = '<?xml version="1.0" encoding="UTF-8"?><selve>' + gateway.replace('<?xml version="1.0" encoding="UTF-8"?>', '').replaceAll('(\r\n|\n\r|\r|\n|\t)', '') + '</selve>'
        logInfo("SelveRollladenGatewayRule", "XML:" + xml)

        val Number count = Integer::parseInt(transform("XPATH", "count(//selve/methodCall)", xml)) 
        logInfo("SelveRollladenGatewayRule", "Count:" + count)

        for(var index=1; index <= count; index++) {
          val method = transform("XPATH", "/descendant::methodCall[" + index + "]/node()", xml) 
          if(method == "selve.GW.event.device") {
            val rollladen = transform("XPATH", "/descendant::methodCall[" + index + "]/array/int[1]", xml)
            val position = transform("XPATH", "/descendant::methodCall[" + index + "]/array/int[3]", xml)
            logInfo("SelveRollladenGatewayRule", "Rolladen:" + rollladen + ", Position:" + position)
            switch(rollladen) {
              case "0": {
                Rollladen1PositionInPercent.sendCommand(Integer::parseInt(transform("SCALE", "selve.scale", position)))
              }
              case "1": {
                Rollladen2PositionInPercent.sendCommand(Integer::parseInt(transform("SCALE", "selve.scale", position)))
              }

              ...

              case "12": {
                Rollladen13PositionInPercent.sendCommand(Integer::parseInt(transform("SCALE", "selve.scale", position)))
              }
            }
          }
        }
    type: script.ScriptAction

I however cannot get the Rollshutter Item to work, when pressing the UP or DOWN arrow:

Rollershutter  Rollladen1     { serial="/dev/ttyUSB_Selve@115200,UP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>1</int><int>1</int><int>0</int></array></methodCall>),DOWN(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>2</int><int>1</int><int>0</int></array></methodCall>),STOP(<methodCall><methodName>selve.GW.command.device</methodName><array><int>0</int><int>0</int><int>1</int><int>0</int></array></methodCall>)"}

I only get it to work, when creating a separate rule for each command.

triggers:
  - id: "1"
    configuration:
      itemName: Rollladen1
      command: UP
    type: core.ItemCommandTrigger
conditions: []
actions:
  - inputs: {}
    id: "2"
    configuration:
      type: application/vnd.openhab.dsl.rule
      script: logInfo("Rollladen1", "Event")
        SelveGatewayCommand.sendCommand("<methodCall><methodName>selve.GW.command.device</methodName><array><int>9</int><int>1</int><int>1</int><int>0</int></array></methodCall>")
    type: script.ScriptAction

Does anybody have an idea, what I am doing wrong? Did I miss something? It sounds strange, if I would have to create separate rule for each command, when the command it self is already included in the device configuration.

Thanks upfront

Kind regards,

Christian

roelwelters · October 18, 2021, 10:13am

Hi any plans on creating a binding for this?
I have some selve shutters but am not a programmer and it looks like this method is a bit over my head.

Ola_G · March 22, 2023, 7:48am

Hi
I had similar problem and I think I solved it finally.

I used a java application as a bridge between selve RF dongle USB and mqtt in my OH3 setup on rpi4B.
I found it in git repository ( written by Sischi)

I had problem it running in docker on my RPI , so I compiled java in docker on my laptop and then copy only .jar file back to RPI.

My basic configurations :
my things file :

Thing mqtt:topic:selveO (mqtt:broker:myMQTTBroker) {
Channels:
    Type number   : selvePos0   [ stateTopic="selve/commeo/device/0/state", commandTopic="selve/commeo/device/0/cmnd",transformationPattern="JSONPATH:$.position",formatBeforePublish="{\"command\": \"DRIVE_POS\", \"value\":\"%.0f\"}",min=0, max=100, step=5]
    Type number   : selvePos1   [ stateTopic="selve/commeo/device/1/state", commandTopic="selve/commeo/device/1/cmnd",transformationPattern="JSONPATH:$.position",formatBeforePublish="{\"command\": \"DRIVE_POS\", \"value\":\"%.0f\"}",min=0, max=100, step=5]
    Type number   : selvePos2   [ stateTopic="selve/commeo/device/2/state", commandTopic="selve/commeo/device/2/cmnd",transformationPattern="JSONPATH:$.position",formatBeforePublish="{\"command\": \"DRIVE_POS\", \"value\":\"%.0f\"}",min=0, max=100, step=5]
    Type number   : selvePos3   [ stateTopic="selve/commeo/device/3/state", commandTopic="selve/commeo/device/3/cmnd",transformationPattern="JSONPATH:$.position",formatBeforePublish="{\"command\": \"DRIVE_POS\", \"value\":\"%.0f\"}",min=0, max=100, step=5]
    Type number   : selvePos4   [ stateTopic="selve/commeo/device/4/state", commandTopic="selve/commeo/device/4/cmnd",transformationPattern="JSONPATH:$.position",formatBeforePublish="{\"command\": \"DRIVE_POS\", \"value\":\"%.0f\"}",min=0, max=100, step=5]
}```

my items :

```javascript
Number  SelveO0 "selve0  [%d ]"  {channel="mqtt:topic:selveO:selvePos0", autoupdate="true"}
Number  SelveO1 "selve1  [%d ]"  {channel="mqtt:topic:selveO:selvePos1", autoupdate="true"}
Number  SelveO2 "selve2  [%d ]"  {channel="mqtt:topic:selveO:selvePos2", autoupdate="true"}
Number  SelveO3 "selve3  [%d ]"  {channel="mqtt:topic:selveO:selvePos3", autoupdate="true"}
Number  SelveO4 "selve4  [%d ]"  {channel="mqtt:topic:selveO:selvePos4", autoupdate="true"}

Selve-bridge app is documented well, and works almost out of box , just enable and configure mqtt server and your selve dongle port name .

I have slight problem with self updating value on web interface , I can control shutters , but when value change it dose not propagate back to web slider ( but variable itself updates) .
But i’m not using this interface for control , so its not a big fuss ( I’m using HASP with lcd touch screen)

sitemap:

Slider item=SelveO1 icon="rollershutter"

Ola