1 /** 2 ***************************************************************************************** 3 * 4 * @file hrs.h 5 * 6 * @brief Heart Rate Service API. 7 * 8 ***************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 ***************************************************************************************** 36 */ 37 38 /** 39 * @addtogroup BLE_SRV BLE Services 40 * @{ 41 * @brief Definitions and prototypes for the BLE Service interface. 42 */ 43 44 /** 45 * @defgroup BLE_SDK_HRS Heart Rate Service (HRS) 46 * @{ 47 * @brief Definitions and prototypes for the HRS interface. 48 * 49 * @details The Heart Rate Service exposes heart rate and other data from a Heart Rate Sensor 50 * intended for fitness applications. This module implements the Heart Rate Service with 51 * the Heart Rate Measurement, Body Sensor Location and Heart Rate Control Point characteristics. 52 * 53 * After \ref hrs_init_t variable is initialized, the application must call \ref hrs_service_init() 54 * to add the Heart Rate Service and Heart Rate Measurement characteristic to the BLE Stack database. 55 * However the value of Heart Rate Measurement characteristic is stored in user space. 56 * 57 * If a device supports Body Sensor Location, \ref hrs_init_t.char_mask should be 58 * set with the mask \ref HRS_CHAR_BODY_SENSOR_LOC_SUP to expose the Body Sensor Location characteristic. 59 * If Energy Expended Field is included in the Heart Rate Measurement characteristic, \ref hrs_init_t. 60 * char_mask must be set with \ref HRS_CHAR_ENGY_EXP_SUP. 61 * 62 * If an event handler is provided by the application, the Heart Rate Service will pass 63 * Heart Rate Service events to the application. 64 * 65 * If Notify is enabled, the notification of Heart Rate Measurement characteristic will be sent 66 * when hrs_heart_rate_measurement_send() is called. 67 */ 68 69 #ifndef __HRS_H__ 70 #define __HRS_H__ 71 72 #include <stdint.h> 73 #include <stdbool.h> 74 #include "gr55xx_sys.h" 75 #include "custom_config.h" 76 77 /** 78 * @defgroup HRS_MACRO Defines 79 * @{ 80 */ 81 82 #define HRS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 83 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Heart Rate Service connections. */ 84 #define HRS_MEAS_MAX_LEN 20 /**< Maximum length of heart rate measurement characteristic. */ 85 #define HRS_MAX_BUFFERED_RR_INTERVALS 9 /**< Size of RR Interval buffer inside service. */ 86 87 /** 88 * @defgroup HRS_CHAR_MASK Characteristics Mask 89 * @{ 90 * @brief Bit masks for the initialization of \ref hrs_init_t.char_mask. 91 */ 92 93 #define HRS_CHAR_MANDATORY 0x0F /**< Bit mask of the mandatory characteristics. */ 94 #define HRS_CHAR_BODY_SENSOR_LOC_SUP 0x30 /**< Bit mask of Body Sensor Location Feature Supported. */ 95 #define HRS_CHAR_ENGY_EXP_SUP 0xC0 /**< Bit mask of Energy Expanded Feature Supported. */ 96 /** @} */ 97 /** @} */ 98 99 /** 100 * @defgroup HRS_ENUM Enumerations 101 * @{ 102 */ 103 /**@brief Values for sensor location. */ 104 typedef enum { 105 HRS_SENS_LOC_OTHER, /**< The sensor location is other. */ 106 HRS_SENS_LOC_CHEST, /**< The sensor location is the chest. */ 107 HRS_SENS_LOC_WRIST, /**< The sensor location is the wrist. */ 108 HRS_SENS_LOC_FINGER, /**< The sensor location is the finger. */ 109 HRS_SENS_LOC_HAND, /**< The sensor location is the hand. */ 110 HRS_SENS_LOC_EARLOBE, /**< The sensor location is the earlobe. */ 111 HRS_SENS_LOC_FOOT, /**< The sensor location is the foot. */ 112 } hrs_sensor_loc_t; 113 114 /**@brief Heart Rate Service event types. */ 115 typedef enum { 116 HRS_EVT_NOTIFICATION_ENABLED, /**< Heart Rate value notification has been enabled. */ 117 HRS_EVT_NOTIFICATION_DISABLED, /**< Heart Rate value notification has been disabled. */ 118 HRS_EVT_RESET_ENERGY_EXPENDED, /**< The peer device requests to reset Energy Expended. */ 119 HRS_EVT_READ_BODY_SEN_LOCATION, /**< The peer device reads Body Sensor Location characteristic. */ 120 } hrs_evt_type_t; 121 /** @} */ 122 123 /** 124 * @defgroup HRS_STRUCT Structures 125 * @{ 126 */ 127 /**@brief Heart Rate Service event. */ 128 typedef struct { 129 uint8_t conn_idx; /**< Index of connection. */ 130 hrs_evt_type_t evt_type; /**< Heart Rate Service event type. */ 131 } hrs_evt_t; 132 /** @} */ 133 134 /** 135 * @defgroup HRS_TYPEDEF Typedefs 136 * @{ 137 */ 138 /**@brief Heart Rate Service event handler type. */ 139 typedef void (*hrs_evt_handler_t)(hrs_evt_t *p_evt); 140 /** @} */ 141 142 /** 143 * @defgroup HRS_STRUCT Structures 144 * @{ 145 */ 146 /**@brief Heart Rate Service Init variable. */ 147 typedef struct { 148 hrs_evt_handler_t evt_handler; /**< Heart Rate Service event handler. */ 149 bool is_sensor_contact_supported; /**< Determine if sensor contact detection is to be supported. */ 150 uint8_t char_mask; /**< Mask of Supported characteristics, and configured with \ref HRS_CHAR_MASK */ 151 hrs_sensor_loc_t 152 sensor_loc; /**< The value of Body Sensor Location characteristic is static while in a connection. */ 153 } hrs_init_t; 154 /** @} */ 155 156 /** 157 * @defgroup HRS_FUNCTION Functions 158 * @{ 159 */ 160 /** 161 ***************************************************************************************** 162 * @brief Set the state of the Sensor Contact Detected bit. 163 * 164 * @param[in] is_sensor_contact_detected: True if sensor contact is detected, false otherwise. 165 ***************************************************************************************** 166 */ 167 void hrs_sensor_contact_detected_update(bool is_sensor_contact_detected); 168 169 /** 170 ***************************************************************************************** 171 * @brief Set the state of the Sensor Contact Supported bit. 172 * 173 * @param[in] is_sensor_contact_supported: New state of the Sensor Contact Supported bit. 174 ***************************************************************************************** 175 */ 176 void hrs_sensor_contact_supported_set(bool is_sensor_contact_supported); 177 178 /** 179 ***************************************************************************************** 180 * @brief Set the Body Sensor Location. 181 * 182 * @details Sets a new value of the Body Sensor Location characteristic. The new value will be sent 183 * to the client the next time the client reads the Body Sensor Location characteristic. 184 * 185 * @param[in] hrs_sensor_loc: New Body Sensor Location. 186 ***************************************************************************************** 187 */ 188 void hrs_sensor_location_set(hrs_sensor_loc_t hrs_sensor_loc); 189 190 /** 191 ***************************************************************************************** 192 * @brief Update Energy measurement if Energy Expended is supported. 193 * 194 * @param[in] energy: New energy measurement. 195 ***************************************************************************************** 196 */ 197 void hrs_energy_update(uint16_t energy); 198 199 /** 200 ***************************************************************************************** 201 * @brief Send Heart Rate measurement if Notify has been enabled. 202 * 203 * @param[in] conn_idx Connection index. 204 * @param[in] heart_rate New heart rate measurement. 205 * @param[in] is_energy_updated Indicate whether update energy expended. 206 * 207 * @return Result of notify value. 208 ***************************************************************************************** 209 */ 210 sdk_err_t hrs_heart_rate_measurement_send(uint8_t conn_idx, uint16_t heart_rate, bool is_energy_updated); 211 212 /** 213 ***************************************************************************************** 214 * @brief Add an RR Interval measurement to the RR Interval buffer. 215 * 216 * @details All buffered RR Interval measurements will be included in the next 217 * Heart Rate Measurement notification. The maximum number of 218 * RR Interval measurement is \ref HRS_MAX_BUFFERED_RR_INTERVALS. If the 219 * buffer is full, the oldest measurement in the buffer will be deleted. 220 * 221 * @param[in] rr_interval New RR Interval measurement (will be buffered until 222 * the next transmission of Heart Rate Measurement). 223 ***************************************************************************************** 224 */ 225 void hrs_rr_interval_add(uint16_t rr_interval); 226 227 /** 228 ***************************************************************************************** 229 * @brief Init a Heart Rate Service instance and add in the DB. 230 * 231 * @param[in] p_hrs_init: Pointer to a Heart Rate Init variable. 232 * 233 * @return Result of service initialization. 234 ***************************************************************************************** 235 */ 236 sdk_err_t hrs_service_init(hrs_init_t *p_hrs_init); 237 /** @} */ 238 239 #endif 240 /** @} */ 241 /** @} */ 242