Bluetooth EnOcean¶
The Bluetooth EnOcean library allows passive observation of wall switches and sensors based on Bluetooth LE from EnOcean, such as wall switches based on the Push Button Transmitter module (PTM 215B) and the Easyfit Motion Detector with Illumination (EMDCB) sensor module. The library is only capable of observing the output of the devices, and does not send anything back. NFC-based configuration is not supported.
The library supports different types of commissioning for both wall switches and sensors:
Radio-based commissioning.
Manually inputting data from other commissioning methods, such as NFC or QR codes.
The library supports replay protection based on sequence numbers. Only new, authenticated packets from commissioned devices will go through to the event callbacks.
If the CONFIG_BT_SETTINGS
subsystem is enabled, the device information of all commissioned devices are stored persistently using the Settings subsystem, including the sequence number information.
For a demonstration of the library features, see the Bluetooth: EnOcean sample.
Supported devices¶
This library supports both PTM 215B-based switches and the sensor module enabled for Bluetooth LE:
Easyfit Single/Double Rocker Wall Switch for Bluetooth LE - EWSSB/EWSDB
Easyfit Single/Double Rocker Pad for Bluetooth LE - ESRPB/EDRPB
By default, the library supports one EnOcean device, and the Bluetooth: EnOcean sample supports only up to four devices. However, when using the library with your application, you can configure the limit of supported devices to a higher number.
Usage¶
The EnOcean library uses bt_le_scan_cb_register()
to receive Bluetooth advertisement packets from nearby EnOcean devices.
The Bluetooth stack must be initialized separately, and Bluetooth scanning must be started by the application.
The Bluetooth mesh stack does this automatically, so when combined, the application does not need to perform any additional initialization.
Commissioning¶
Before the library is able to process sensor or button messages from nearby EnOcean devices, the devices must be commissioned. By default, the commissioning behavior may be triggered by interacting with the devices, as explained in the following sections.
To enable radio-based commissioning in your application, call bt_enocean_commissioning_enable()
.
Commissioning wall switches¶
EnOcean Easyfit wall switches may be put into the commissioning mode by completing the following sequence:
Press and hold one of the buttons for more than 7 seconds before releasing it.
Quickly press and release the same button (hold for less than 2 seconds).
Press and hold the same button again for more than 7 seconds before releasing it.
The switch will transmit its security key, which the library picks up and stores before calling the bt_enocean_callbacks.commissioned
callback.
To exit the commissioning mode on a wall switch device, press any of the other buttons on the switch.
The library will now be reporting button presses through the bt_enocean_callbacks.button
callback.
Commissioning sensor units¶
To have the EnOcean Easyfit sensor unit modules publish their security key, short-press the front button of the device.
The library registers the security key and stores it before calling bt_enocean_callbacks.commissioned
.
The sensor unit never enters the commissioning mode. After publishing its security key, the sensor unit automatically goes back to reporting sensor readings at periodic intervals.
Note
EnOcean devices may be configured to disable radio-based commissioning through NFC. In such case, the security key must be obtained through manual input.
Observing output¶
After commissioning an EnOcean device, its activity may be monitored through the bt_enocean_handlers
callback functions passed to bt_enocean_init()
.
See the Bluetooth: EnOcean for a demonstration of the handler callback functions.
Dependencies¶
The EnOcean library depends on the CONFIG_BT_OBSERVER
capability in the Bluetooth stack to function.
To enable persistent storage of device commissioning data, the CONFIG_BT_SETTINGS
subsystem must also be enabled.
API documentation¶
include/bluetooth/enocean.h
subsys/bluetooth/enocean.c
-
group
bt_enocean
API for interacting with EnOcean Bluetooth wall switches and sensors.
Defines
-
BT_ENOCEAN_SWITCH_OA
¶ Double rocker switch top left button (OA)
-
BT_ENOCEAN_SWITCH_IA
¶ Double rocker switch bottom left button (IA)
-
BT_ENOCEAN_SWITCH_OB
¶ Double rocker switch top right button (OB)
-
BT_ENOCEAN_SWITCH_IB
¶ Double rocker switch bottom right button (IB)
-
BT_ENOCEAN_SWITCH_O
¶ Single rocker switch top button (O)
-
BT_ENOCEAN_SWITCH_I
¶ Single rocker switch bottom button (I)
Typedefs
-
typedef void (*
bt_enocean_foreach_cb_t
)(struct bt_enocean_device *dev, void *user_data)¶ Visitor callback for bt_enocean_foreach.
- Parameters
dev – EnOcean device
user_data – User data passed to bt_enocean_foreach.
Enums
Type of button event
Values:
Buttons were released.
Buttons were pressed.
Functions
-
void
bt_enocean_init
(const struct bt_enocean_callbacks *cb)¶ Initialize the EnOcean subsystem.
- Parameters
cb – Set of callbacks to receive events with.
-
void
bt_enocean_commissioning_enable
(void)¶ Enable automatic commissioning.
This function must be called for the module to start accepting commissioning packets.
-
void
bt_enocean_commissioning_disable
(void)¶ Disable automatic commissioning.
Automatic commissioning will be disabled until bt_enocean_commissioning_enable is called. Manual commissioning through bt_enocean_commission is unaffected.
-
int
bt_enocean_commission
(const bt_addr_le_t *addr, const uint8_t key[16], uint32_t seq)¶ Manually commission an EnOcean device.
Allows devices to be commissioned based on out of band data, like NFC or QR codes.
- Parameters
addr – Address of the commissioned device.
key – Encryption key for the commissioned device.
seq – Most recent sequence number of the device.
- Returns 0
The device has been successfully commissioned.
- Returns -EEXIST
This device has already been commissioned.
- Returns -ENOMEM
There’s not enough space to commission a new device.
- Returns -ECANCELED
The commissioning callback rejected the device.
- Returns -EBUSY
Failed allocating persistent storage data.
-
void
bt_enocean_decommission
(struct bt_enocean_device *dev)¶ Forget an EnOcean device.
Removes the EnOcean device’s security information, freeing up space for new devices. May be used directly in the bt_enocean_callbacks::commissioning callback to reject a device before it gets commissioned.
- Parameters
dev – Device to forget.
-
uint32_t
bt_enocean_foreach
(bt_enocean_foreach_cb_t cb, void *user_data)¶ Call the given callback for each commissioned enocean device.
- Parameters
cb – Callback to call for each device
user_data – User data to pass to the callback.
- Returns
The number of devices visited.
-
struct
bt_enocean_sensor_data
¶ - #include <enocean.h>
EnOcean sensor data message.
-
struct
bt_enocean_device
¶ - #include <enocean.h>
EnOcean device representation.
-
struct
bt_enocean_callbacks
¶ - #include <enocean.h>
EnOcean callback functions. All callbacks are optional.
Public Members
Callback for EnOcean Switch button presses.
This callback is called for every new button message from a commissioned EnOcean Switch. The set of changed button states on the switch is represented as a bitfield, with 4 bits representing the individual buttons.
See the
BT_ENOCEAN_SWITCH_*
defines for button mapping. Note that the single rocker switches only engages the third and fourth buttons.- Parameters
device – EnOcean device generating the message.
action – Button action type.
changed – Bitfield of buttons affected by the action.
opt_data – Optional data array from the message, or NULL.
opt_data_len – Length of the optional data.
-
void (*
sensor
)(struct bt_enocean_device *device, const struct bt_enocean_sensor_data *data, const uint8_t *opt_data, size_t opt_data_len)¶ Callback for EnOcean Sensor reports.
This callback is called for every new sensor message from a commissioned EnOcean Switch.
The
data
parameter contains a set of optional fields, represented as pointers. Unknown fields are NULL pointers, and must be ignored.- Parameters
device – EnOcean device generating the message.
data – Sensor data.
opt_data – Optional data array from the message, or NULL.
opt_data_len – Length of the optional data.
-
void (*
commissioned
)(struct bt_enocean_device *device)¶ Callback for EnOcean commissioning.
This callback is called for every new EnOcean device being commissioned.
All devices must be commissioned before they can be observed. See the EnOcean device’s user guide for details.
A device can be rejected inside the callback by calling bt_enocean_decommission with the
device's
address.- Parameters
device – Device that got commissioned.
-
void (*
loaded
)(struct bt_enocean_device *device)¶ Callback for EnOcean devices being loaded from persistent storage.
This callback is called for every commissioned EnOcean device recovered from persistent storage.
- Parameters
device – Device that was loaded.
-