Direction and Distance Finding Service (DDFS)

Service UUID
Characteristics
API documentation

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

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 – Pointer to connection object, or NULL if sent to all connected peers.
measurement – 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 a Azimuth Measurement. If notification has been enabled, the measurement data is encoded and sent to the client.

Parameters

conn – Pointer to connection object, or NULL if sent to all connected peers.
measurement – Pointer to new azituth 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 a Elevation Measurement. If notification has been enabled, the measurement data is encoded and sent to the client.

Parameters

conn – Pointer to connection object, or NULL if sent to all connected peers.
measurement – 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 – 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

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 distanance 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 enebled)

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 enebled)

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 enebled)

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.