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.