.. _lib_hrs_client_readme:

GATT Heart Rate Service (HRS) Client
####################################

.. contents::
   :local:
   :depth: 2

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 the advertising device is detected, the application will connect to it automatically and will start 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 :c:func:`bt_hrs_client_handles_assign` function.

The application is ready to operate with the remote Heart Rate Service.

Usage
*****

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

* :c:func:`bt_hrs_client_measurement_subscribe` - Enable notifications for the Heart Rate Measurement characteristic.

  The notifications are passed to the provided callback function.
  You will receive the current heart rate measurement data.

* :c:func:`bt_hrs_client_sensor_location_read` - Read a heart rate sensor location.

  Check the possible locations in :c:enum:`bt_hrs_client_sensor_location`.

* :c:func:`bt_hrs_client_control_point_write` - Configure a remote Heart Rate Service.

  Check the possible values for a Heart Rate Control Point characteristic in :c:enum:`bt_hrs_client_cp_value`.

Samples using the library
*************************

The following |NCS| samples use this library:

* :ref:`central_and_peripheral_hrs`
* :ref:`bluetooth_central_hr_coded`

Additional information
**********************

Do not use any of the values in the :c:struct:`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
************

* :ref:`gatt_dm_readme`
* :ref:`zephyr:bluetooth_api`:

  * :file:`include/bluetooth/gatt.h`
  * :file:`include/bluetooth/conn.h`

API documentation
*****************

| Header file: :file:`include/bluetooth/services/hrs_client.h`
| Source file: :file:`subsys/bluetooth/services/hrs_client.c`

.. doxygengroup:: bt_hrs_client
   :project: nrf
   :members: