Add support for Dolphin/EnOcean PTM 215B

[pfink]

I have some battery-less wall switches based on Dolphin/EnOcean PTM 215B that I'd like to integrate (technical manual can be found here).

My setup:

• Raspberry Pi 3B
• openHAB 2.3
• Raspbian Stretch
• Bluez 5.43
• Generic BLE 4.0 USB adapter

Some information that I found out so far:

• Bluetooth version unclear for me (but maybe not relevant)? I guess BLE 4.0 or BLE 4.2.
• Currently, the wall switches don't get discovered at all. Neither via this binding nor via bluetoothctl (also not when trying to do radio-based commissioning according the docs, chapter 5.3). Other BLE devices are found without any issues.
• According to the docs, the wall switches send data telegrams on each press/release event on all three advertising channels. The data channels aren't used at all.
• Authentication should happen via AES-128 CCM (counter with CBC-MAC), the security key can be read manually via QR Code on the switch, via NFC or with radio-based/BLE commissioning. But radio-based/BLE commissioning is maybe disabled, depending on the manufacturer where the end product was bought. EnOcean's default is enabled. If disabled, it can be reenabled via NFC. Anyhow, for a start I'd prefer to manually read the security key via QR code and put it statically to a textual configuration, as it seems to be the simplest approach to start with.

@vkolotov: I'm a ESH/openHAB developer, but I'm quite new to the BLE protocol. If you could give me some hints and point me to the right direction, I may could come up with a PR.

[vkolotov]

Hi @pfink, thanks for that.

• BT version is not important.
• Since your switches are battery-less, this means that they only advertise data when you actuate them. So I'd suggest to try to continuously switch it on and off until you see in the OH inbox. Otherwise, you could try to add them manually. Let me know how it goes, if not working for you I'll try to explain how to do it manually.
• Re " advertising channels" that's good, this means that you don't have to be connected to them. This is expected, good design.
• Not sure why would you need any authentication though as you've mentioned that they advertise data without establishing any secure connection. Try what I suggested above. The binding supports some basic authentication methods, e.g. auth via pin code, but that should not be required in your instance.

I'm happy to help you, let's start with getting them into inbox first.

[pfink]

OMG... Before my first post, I troubleshooted two days to get the buttons discovered including that I tried to manually add them, everything unsuccessful. The solution was as dumb as easy: I did not press the button often enough :( As you suggested, I flooded openHAB now with very often button presses (> 10) and now they're discovered..... Thank you very much!

Via online channel and by putting online timeout to 1 sec, I'm now already able to detect whether a button was pressed at all. Next step would be to distinguish which button was pressed. My preferred solution would be to implement/offer a system.rawrocker channel.

Of course, I'm also open to simpler/easier solutions for a start :)

[vkolotov]

Good stuff! Very interesting to see battery-less devices to work with the binding :) What channels have been discovered? Can you post a screenshot?

[pfink]

Sure! This is a complete list:

• bluetooth:ble:xxxx:online
• bluetooth:ble:xxxx:connected
• bluetooth:ble:xxxx:authenticated
• bluetooth:ble:xxxx:connection-control
• bluetooth:ble:xxxx:connected-adapter
• bluetooth:ble:xxxx:rssi
• bluetooth:ble:xxxx:tx-power
• bluetooth:ble:xxxx:estimated-distance
• bluetooth:ble:xxxx:adapter
• bluetooth:ble:xxxx:location
• bluetooth:ble:xxxx:last-updated

Device Name is just the MAC address.

[vkolotov]

how about "unknown" channels?

That's how you do stuff with BT binding. The binding should discover some channels (BT characteristics) automatically. So that you can use them. I assume there will be several channels per each button. If it is like that, you only need to extend the binding with some XML files to get the channels to be recognised automatically, I assume they will be radioboxes/switches in OH.

See here: https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/blob/master/gatt-extensions.md

[vkolotov]

Once you've changed "GATT parsing strategy" you will need to wait until the binding reloads and then refresh PaperUI page with your things to see new channels. IMPORTANT: they will appear only after the binding receives data, e.g. you will need to switch on/off your buttons to discover all unknown channels.

[vkolotov]

This would be an example of "unknown" characteristics (MiFlora device):

000071fe-0000-1000-8000-00805f9b34fb is an unknown characteristic.

[pfink]

I removed the Thing again, activated recognition of unknown channels as per your advice, and discovered + added it again. Where should I see these unknown channels? I don't find anything in PaperUI. I also checked /var/lib/openhab2/jsondb/org.eclipse.smarthome.core.thing.Thing.json, but there seems to be nothing more than I already posted.

[vkolotov]

Try to switch on / off more, continuously switch it for 30-60 secs let's say :) . Wait some time, reload browser tab with PaperUI to see new channels.

[vkolotov]

How many buttons does your switch have?

[vkolotov]

Right, I've skimmed the doc you have attached.

The way how your switch transmit data is via so called "manufacturer data". The binding supports it, a new channel (single) should be created for it. That channel contains the following (as per the doc):

Sequence Counter (4 byte)
The Sequence Counter is a continuously incrementing counter used for security
processing. It is initialized to 0 at the time of production and incremented for each
telegram (data telegram or commissioning telegram) sent.
 Switch Status (1 byte)
The Switch Status field reports the button action. The encoding of this field is described
in chapter 4.7.
 Optional Data (0 / 1 / 2 or 4 byte)
PTM 215B provides the option to transmit additional user-defined data within each
data telegram. This data can be used to identify user-specific properties.
The length of the Optional Data field is defined in the Configuration register as described
in chapter 6.7.7.
 Security Signature (4 byte)
The Security Signature is used to authenticate PTM 215B radio telegrams as described
in chapter 4.8

we are interested in Switch Status (1 byte).

[vkolotov]

I'll need to double check if the binding supports the "manufacturer data", should be.

[pfink]

I have rockers with 2 buttons and also those with 4 buttons. But I think there is the very same radio module behind them. Unfortunately, no additional channels get discovered. I guess this could be because the binding does not know the security key. I think the whole security and commissioning process described in the docs would make no sense if everyone can just publicly read the data ;-)

[pfink]

(see section 4.8 in the docs)

[vkolotov]

Right, I've checked it :) It is not implementing manufacturer data thingy, but it would be easy to add as this is very-very similar to an existing functionality (advertised service data).

Check this out:

eclipse-smarthome-bluetooth-binding/src/main/java/org/sputnikdev/esh/binding/bluetooth/handler/BluetoothDeviceHandler.java

Line 157 in 3bf8b0f

public void serviceDataChanged(Map<URL, byte[]> serviceData) {

That one implements "advertised service data" which is very similar to "manufacturer service data", in fact the later should be easier as there will be only 1 data point comparing to many for "service data".

Here is what needs to be implemented: https://github.com/sputnikdev/bluetooth-manager/blob/d239d59a5368d05d06f59dc62faeb3e355716f23/src/main/java/org/sputnikdev/bluetooth/manager/BluetoothSmartDeviceListener.java#L70

Let me know if it makes sense for you?