Direction and Distance Finding Service (DDFS)

The Bluetooth® Low Energy GATT Direction and Distance Finding Service is a custom service that allows publication of distance, azimuth and elevation measurement data. It also allows adjusting the measurement configuration parameters.

Note

The current implementation is experimental.

Service UUID 

The 128-bit vendor-specific service UUID is 21490000-494a-4573-98af-f126af76f490.

Characteristic UUIDs
Characteristic	UUID
Distance Measurement	`21490001-494a-4573-98af-f126af76f490`
Azimuth Measurement	`21490002-494a-4573-98af-f126af76f490`
Elevation Measurement	`21490003-494a-4573-98af-f126af76f490`
DDF Feature	`21490004-494a-4573-98af-f126af76f490`
Control Point	`21490005-494a-4573-98af-f126af76f490`

Characteristics 

This service has the following characteristics.

Distance Measurement Characteristic 

Notify:: Enable notifications for the Distance Measurement Characteristic to receive measurements.

Azimuth Measurement Characteristic 

Notify:: Enable notifications for the Azimuth Measurement Characteristic to receive measurements.

Elevation Measurement Characteristic 

Notify:: Enable notifications for the Elevation Measurement Characteristic to receive measurements.

DDF Feature Characteristic 

Read:: Read the supported features.

Control Point Characteristic 

Write:: Write data to the Control Point Characteristic to change the configuration.

API documentation 

Header file: include/bluetooth/services/ddfs.h

Source file: subsys/bluetooth/services/ddfs.c

group bt_ddfs

API for the Direction and Distance Finding Service (DDFS).

Defines

BT_UUID_DDFS_VAL: UUID of the DDF Service.

BT_UUID_DDFS_DISTANCE_MEAS_VAL: UUID of the Distance Measurement Characteristic.

BT_UUID_DDFS_AZIMUTH_MEAS_VAL: UUID of the Azimuth Measurement Characteristic.

BT_UUID_DDFS_ELEVATION_MEAS_VAL: UUID of the Elevation Measurement Characteristic.

BT_UUID_DDFS_FEATURE_VAL: UUID of the Feature Characteristic.

BT_UUID_DDFS_CTRL_POINT_VAL: UUID of the Control Point Characteristic.

BT_UUID_DDFS

BT_UUID_DDFS_DISTANCE_MEAS

BT_UUID_DFFS_AZIMUTH_MEAS

BT_UUID_DFFS_ELEVATION_MEAS

BT_UUID_DDFS_FEATURE

BT_UUID_DFFS_CTRL_POINT

Enums

enum bt_ddfs_dm_ranging_mode

Ranging mode

Values:

enumerator BT_DDFS_DM_RANGING_MODE_RTT: Round trip timing

enumerator BT_DDFS_DM_RANGING_MODE_MCPD: Multi-carrier phase difference

enum bt_ddfs_quality

Measurement quality definition.

Values:

enumerator BT_DDFS_QUALITY_OK: Good measurement quality

enumerator BT_DDFS_QUALITY_POOR: Poor measurement quality

enumerator BT_DDFS_QUALITY_DO_NOT_USE: Measurement not for use

enumerator BT_DDFS_QUALITY_NONE: Measurement quality not specified

Functions

int bt_ddfs_distance_measurement_notify(struct bt_conn *conn, const struct bt_ddfs_distance_measurement *measurement)

Function for sending Distance Measurement value.

The application calls this function after having performed a Distance Measurement. If notification has been enabled, the measurement data is encoded and sent to the client.

Parameters:

conn – [in] Pointer to connection object, or NULL if sent to all connected peers.
measurement – [in] Pointer to new distance measurement.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

int bt_ddfs_azimuth_measurement_notify(struct bt_conn *conn, const struct bt_ddfs_azimuth_measurement *measurement)

Function for sending Azimuth Measurement value.

The application calls this function after having performed an Azimuth Measurement. If notification has been enabled, the measurement data is encoded and sent to the client.

Parameters:

conn – [in] Pointer to connection object, or NULL if sent to all connected peers.
measurement – [in] Pointer to new azimuth measurement.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

int bt_ddfs_elevation_measurement_notify(struct bt_conn *conn, const struct bt_ddfs_elevation_measurement *measurement)

Function for sending Elevation Measurement value.

The application calls this function after having performed an Elevation Measurement. If notification has been enabled, the measurement data is encoded and sent to the client.

Parameters:

conn – [in] Pointer to connection object, or NULL if sent to all connected peers.
measurement – [in] Pointer to new elevation measurement.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

int bt_ddfs_init(const struct bt_ddfs_init_params *init)

Function for initializing the Direction and Distance Finding Service.

Parameters:

init – [in] Initialization parameters.

Return values:

0 – If the operation was successful. Otherwise, a negative error code is returned.

struct bt_ddfs_features

#include <ddfs.h>

Public Members

uint8_t ranging_mode_rtt: Distance Measurement RTT ranging mode supported bit.

uint8_t ranging_mode_mcpd: Distance Measurement MCPD ranging mode supported bit.

struct bt_ddfs_dm_config

#include <ddfs.h>

Distance Measurement configuration parameters.

Public Members

enum bt_ddfs_dm_ranging_mode mode: Ranging mode

bool high_precision: High-precision calculations enabled

struct bt_ddfs_cb

#include <ddfs.h>

Pointers to the callback functions for service events.

Public Members

int (*dm_ranging_mode_set)(uint8_t mode)

Indicates that the ranging mode for Distance Measurement is set.

Param mode:: New ranging mode for distance measurement.
Retval 0:: If the operation was successful. Otherwise, a negative error code is returned.

int (*dm_config_read)(struct bt_ddfs_dm_config *config)

Indicates that the configuration for Distance Measurement is read.

Param config:: Pointer to configuration object.
Retval 0:: If the operation was successful. Otherwise, a negative error code is returned.

void (*am_notification_config_changed)(bool enabled)

Azimuth Measurement state callback.

Indicate the CCCD descriptor status of the Azimuth Measurement characteristic.

Param enabled:: Azimuth Measurement notification status.

void (*dm_notification_config_changed)(bool enabled)

Distance Measurement state callback.

Indicate the CCCD descriptor status of the Distance Measurement characteristic.

Param enabled:: Distance Measurement notification status.

void (*em_notification_config_changed)(bool enabled)

Elevation Measurement state callback.

Indicate the CCCD descriptor status of the Elevation Measurement characteristic.

Param enabled:: Elevation Measurement notification status.

struct bt_ddfs_distance_measurement

#include <ddfs.h>

Structure of distance measurement results.

Public Members

enum bt_ddfs_quality quality: Quality indicator

bt_addr_le_t bt_addr: Bluetooth LE Device Address

enum bt_ddfs_dm_ranging_mode ranging_mode: Mode used for ranging

uint16_t ifft: MCPD: Distance estimate based on IFFT of spectrum

uint16_t phase_slope: MCPD: Distance estimate based on average phase slope estimation

uint16_t rssi_openspace: RSSI: Distance estimate based on Friis path loss formula

uint16_t best: Best effort distance estimate

uint16_t rtt: RTT: Distance estimate based on RTT measurement

struct bt_ddfs_azimuth_measurement

#include <ddfs.h>

Structure of azimuth measurement results.

Public Members

enum bt_ddfs_quality quality: Quality indicator

bt_addr_le_t bt_addr: Bluetooth LE Device Address

uint16_t value: Azimuth estimate

struct bt_ddfs_elevation_measurement

#include <ddfs.h>

Structure of elevation measurement results.

Public Members

enum bt_ddfs_quality quality: Quality indicator

bt_addr_le_t bt_addr: Bluetooth LE Device Address

int8_t value: Elevation estimate

struct bt_ddfs_init_params

#include <ddfs.h>

Direction and Distance Finding Service initialization parameters.

Public Members

struct bt_ddfs_features dm_features: Initial value for features.

const struct bt_ddfs_cb *cb: Callback functions structure.