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:

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:

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

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

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

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.