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 is 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:

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 the bt_le_scan_cb_register() function 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

The devices must be commissioned so that the library can process sensor or button messages from nearby EnOcean devices. 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 the bt_enocean_commissioning_enable() function.

Commissioning wall switches

To set the EnOcean Easyfit wall switches into the commissioning mode, complete the following sequence:

  1. Press and hold one of the buttons for more than seven seconds before releasing it.

  2. Quickly press and release the same button (hold for less than two seconds).

  3. Press and hold the same button again for more than seven seconds before releasing it.

The switch transmits its security key, and the library picks up and stores the key 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

You can configure EnOcean devices 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, you can monitor its activity through the bt_enocean_handlers callback functions passed to the bt_enocean_init() function. 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 enable persistent storing of device commissioning data, you must also enable the CONFIG_BT_SETTINGS Kconfig option.

API documentation

Header file: include/bluetooth/enocean.h
Source file: 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.

Param dev:

EnOcean device

Param user_data:

User data passed to bt_enocean_foreach.

Enums

enum bt_enocean_button_action

Type of button event

Values:

enumerator BT_ENOCEAN_BUTTON_RELEASE

Buttons were released.

enumerator BT_ENOCEAN_BUTTON_PRESS

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.

Return values:

  • 0 – The device has been successfully commissioned.

  • -EEXIST – This device has already been commissioned.

  • -ENOMEM – There’s not enough space to commission a new device.

  • -ECANCELED – The commissioning callback rejected the device.

  • -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.

Public Members

bool *occupancy

Current occupancy status.

uint16_t *light_sensor

Light level in sensor (lx).

uint16_t *battery_voltage

Backup battery voltage (mV).

uint16_t *light_solar_cell

Light level in solar cell (lx).

uint8_t *energy_lvl

Energy level (percent).

struct bt_enocean_device
#include <enocean.h>

EnOcean device representation.

Public Members

uint32_t seq

Most recent sequence number.

uint8_t flags

Internal flags field.

int8_t rssi

Most recent RSSI measurement.

bt_addr_le_t addr

Device address.

uint8_t key[16]

Device key.

struct bt_enocean_callbacks
#include <enocean.h>

EnOcean callback functions. All callbacks are optional.

Public Members

void (*button)(struct bt_enocean_device *device, enum bt_enocean_button_action action, uint8_t changed, const uint8_t *opt_data, size_t opt_data_len)

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.

Param device:

EnOcean device generating the message.

Param action:

Button action type.

Param changed:

Bitfield of buttons affected by the action.

Param opt_data:

Optional data array from the message, or NULL.

Param 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.

Param device:

EnOcean device generating the message.

Param data:

Sensor data.

Param opt_data:

Optional data array from the message, or NULL.

Param 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.

Param device:

Device that got commissioned.

void (*decommissioned)(struct bt_enocean_device *device)

Callback for EnOcean decommissioning.

This callback is called for every new EnOcean device being decommissioned.

Param device:

Device that got decommissioned.

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.

Param device:

Device that was loaded.