GATT Heart Rate Service (HRS) Client

The GATT Heart Rate Service Client is used to retrieve information about heart rate measurements.

Overview

The GATT HRS Client can retrieve information such as the sensor location from a device that provides the Heart Rate Service. It can also configure the Heart Rate Service on a remote device by writing specific values to the Heart Rate Control Point characteristic.

Configuration

Applications use the Scanning module for detecting advertising devices that support the Heart Rate Service. If an advertising device is detected, the application connects to it automatically and starts receiving HRS data.

Once a connection with a remote device providing a Heart Rate Service is established, the client needs service discovery to discover Heart Rate Service handles. If this succeeds, the handles of the Heart Rate Service must be assigned to a HRS client instance using the bt_hrs_client_handles_assign() function. Now, the application is ready to operate with the remote Heart Rate Service.

Usage

Retrieve data from the Heart Rate Service or configure its behavior using the following functions:

Samples using the library

The following nRF Connect SDK samples use this library:

Additional information

Do not use any of the values in the bt_hrs_client object structure directly. All values that should be accessed have accessory functions. The structure is fully defined because the application must be able to allocate memory for it.

Dependencies

API documentation

Header file: include/bluetooth/services/hrs_client.h
Source file: subsys/bluetooth/services/hrs_client.c
group bt_hrs_client

Heart Rate (HR) Service Client API.

Typedefs

typedef void (*bt_hrs_client_notify_cb)(struct bt_hrs_client *hrs_c, const struct bt_hrs_client_measurement *meas, int err)

Heart Rate Measurement notification callback.

This function is called every time the client receives a notification with Heart Rate Measurement data.

Param hrs_c:

[in] Heart Rate Service Client instance.

Param meas:

[in] Heart Rate Measurement received data.

Param err:

[in] 0 if the notification is valid. Otherwise, contains a (negative) error code.

typedef void (*bt_hrs_client_read_sensor_location_cb)(struct bt_hrs_client *hrs_c, enum bt_hrs_client_sensor_location location, int err)

Heart Rate Body Sensor Location read callback.

Param hrs_c:

[in] Heart Rate Service Client instance.

Param location:

[in] Body Sensor Location value.

Param err:

[in] 0 if read operation succeeded and data is valid. Otherwise, contains an error code.

typedef void (*bt_hrs_client_write_cb)(struct bt_hrs_client *hrs_c, uint8_t err)

Heart Rate Control Point write callback.

Param hrs_c:

[in] Heart Rate client instance.

Param err:

[in] 0 if write operation succeeded. Otherwise, contains an error code.

Enums

enum bt_hrs_client_error

Heart Rate Service error codes.

This service defines the following Attribute Protocol Application error codes.

Values:

enumerator BT_HRS_CLIENT_ERROR_CP_NOT_SUPPORTED

Control Point value not supported.

enum bt_hrs_client_cp_value

Heart Rate Control Point values.

The values of the Control Point characteristic.

Values:

enumerator BT_HRS_CLIENT_CP_VALUE_RESET_EE

Resets the value if the Energy Expended field in the Heart Rate Measurement characteristic to 0.

enum bt_hrs_client_sensor_location

Body sensor location values.

Values:

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_OTHER

Body Sensor Location: Other.

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_CHEST

Body Sensor Location: Chest.

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_WRIST

Body Sensor Location: Wrist.

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_FINGER

Body Sensor Location: Finger.

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_HAND

Body Sensor Location: Hand.

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_EAR_LOBE

Body Sensor Location: Ear Lobe.

enumerator BT_HRS_CLIENT_SENSOR_LOCATION_FOOT

Body Sensor Location: Foot.

Functions

int bt_hrs_client_init(struct bt_hrs_client *hrs_c)

Function for initializing the Heart Rate Service Client.

Parameters:

  • hrs_c – [inout] Heart Rate Service Client instance. This structure must be supplied by the application. It is initialized by this function and will later be used to identify this particular client instance.

Return values:

0 – If the client was initialized successfully. Otherwise, a (negative) error code is returned.

int bt_hrs_client_measurement_subscribe(struct bt_hrs_client *hrs_c, bt_hrs_client_notify_cb notify_cb)

Subscribe to Heart Rate Measurement notification.

This function writes CCC descriptor of the Heart Rate Measurement characteristic to enable notification.

Parameters:

  • hrs_c – [in] Heart Rate Service Client instance.

  • notify_cb – [in] Notification callback.

Return values:

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

int bt_hrs_client_measurement_unsubscribe(struct bt_hrs_client *hrs_c)

Remove subscription to the Heart Rate Measurement notification.

This function writes CCC descriptor of the Heart Rate Measurement characteristic to disable notification.

Parameters:

  • hrs_c – [in] Heart Rate Service Client instance.

Return values:

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

int bt_hrs_client_sensor_location_read(struct bt_hrs_client *hrs_c, bt_hrs_client_read_sensor_location_cb read_cb)

Read Body Sensor Location characteristic.

Parameters:

  • hrs_c – [in] Heart Rate Service Client instance.

  • read_cb – [in] Read complete callback.

Return values:

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

bool bt_hrs_client_has_sensor_location(struct bt_hrs_client *hrs_c)

Check if Heart Rate Service has the Body Sensor Location characteristic.

This function can be called after bt_hrs_client_handles_assign to check if the Body Sensor Location characteristic was found during service discovery.

Return values:

  • true – If the Body Sensor Location is found.

  • false – If the Body Sensor Location is not found.

int bt_hrs_client_control_point_write(struct bt_hrs_client *hrs_c, enum bt_hrs_client_cp_value value, bt_hrs_client_write_cb write_cb)

Write Heart Rate Control Point characteristic.

Parameters:

  • hrs_c – [in] Heart Rate Service Client instance.

  • value – [in] Control Point value to write.

  • write_cb – [in] Write complete callback.

Return values:

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

bool bt_hrs_client_has_control_point(struct bt_hrs_client *hrs_c)

Check if Heart Rate Service has the Heart Rate Control Point characteristic.

This function can be called after bt_hrs_client_handles_assign to check if the Heart Rate Control Point characteristic was found during service discovery.

Return values:

  • true – If the Heart Rate Control Point is found.

  • false – If the Heart Rate Control Point is not found.

int bt_hrs_client_handles_assign(struct bt_gatt_dm *dm, struct bt_hrs_client *hrs_c)

Function for assigning handles to Heart Rate Service Client instance.

Call this function when a link has been established with a peer to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module.

Parameters:

  • dm – [in] Discovery object.

  • hrs_c – [inout] Heart Rate Service Client instance for associating the link.

Return values:

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

struct bt_hrs_flags
#include <hrs_client.h>

Heart Measurement flags structure.

Public Members

uint8_t value_format

Value Format flag.

uint8_t sensor_contact_detected

Sensor Contact detected flag.

uint8_t sensor_contact_supported

Sensor Contact supported flag.

uint8_t energy_expended_present

Energy Expended preset flag.

uint8_t rr_intervals_present

RR-intervals present flag.

struct bt_hrs_client_measurement
#include <hrs_client.h>

Data structure of the Heart Rate Measurement characteristic.

Public Members

struct bt_hrs_flags flags

Flags structure.

uint8_t rr_intervals_count

RR-intervals count.

uint16_t rr_intervals[CONFIG_BT_HRS_CLIENT_RR_INTERVALS_COUNT]

RR-intervals represented by 1/1024 second as unit. Present if bt_hrs_flags::rr_intervals_present is set. The interval with index 0 is older than the interval with index 1.

uint16_t hr_value

Heart Rate Measurement Value in beats per minute unit.

uint16_t energy_expended

Energy Expended in joule unit. Present if bt_hrs_flags::energy_expended_present is set.

struct bt_hrs_client_hr_meas
#include <hrs_client.h>

Heart Rate Measurement characteristic structure.

Public Members

uint16_t handle

Value handle.

uint16_t ccc_handle

Handle of the characteristic CCC descriptor.

struct bt_gatt_subscribe_params notify_params

GATT subscribe parameters for notification.

bt_hrs_client_notify_cb notify_cb

Notification callback.

struct bt_hrs_client_body_sensor_location
#include <hrs_client.h>

Body Sensor Location characteristic structure.

Public Members

uint16_t handle

Value handle.

struct bt_gatt_read_params read_params

Read parameters.

bt_hrs_client_read_sensor_location_cb read_cb

Read complete callback.

struct bt_hrs_client_control_point
#include <hrs_client.h>

Heart Rate Control Point characteristic structure.

Public Members

uint16_t handle

Value handle.

struct bt_gatt_write_params write_params

Write parameters.

bt_hrs_client_write_cb write_cb

Write complete callback.

struct bt_hrs_client
#include <hrs_client.h>

Heart Rate Service Client instance structure. This structure contains status information for the client.

Public Members

struct bt_conn *conn

Connection object.

struct bt_hrs_client_hr_meas measurement_char

Heart Rate Measurement characteristic.

struct bt_hrs_client_body_sensor_location sensor_location_char

Sensor Body Location characteristic.

struct bt_hrs_client_control_point cp_char

Heart Rate Control Point characteristic.

atomic_t state

Internal state.