hrs.h
Go to the documentation of this file.
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. If Energy Expended Field is included
59  * in the Heart Rate Measurement characteristic, \ref hrs_init_t.char_mask must be set with \ref HRS_CHAR_ENGY_EXP_SUP.
60  *
61  * If an event handler is provided by the application, the Heart Rate Service will pass
62  * Heart Rate Service events to the application.
63  *
64  * If Notify is enabled, the notification of Heart Rate Measurement characteristic will be sent
65  * when hrs_heart_rate_measurement_send() is called.
66  */
67 
68 #ifndef __HRS_H__
69 #define __HRS_H__
70 
71 #include "gr_includes.h"
72 #include "custom_config.h"
73 #include <stdint.h>
74 #include <stdbool.h>
75 
76 /**
77  * @defgroup HRS_MACRO Defines
78  * @{
79  */
80 
81 #define HRS_CONNECTION_MAX 10 /**< Maximum number of Heart Rate Service connections. */
82 #define HRS_MEAS_MAX_LEN 20 /**< Maximum length of heart rate measurement characteristic. */
83 #define HRS_MAX_BUFFERED_RR_INTERVALS 9 /**< Size of RR Interval buffer inside service. */
84 
85 /**
86  * @defgroup HRS_CHAR_MASK Characteristics Mask
87  * @{
88  * @brief Bit masks for the initialization of \ref hrs_init_t.char_mask.
89  */
90 
91 #define HRS_CHAR_MANDATORY 0x0F /**< Bit mask of the mandatory characteristics. */
92 #define HRS_CHAR_BODY_SENSOR_LOC_SUP 0x30 /**< Bit mask of Body Sensor Location Feature Supported. */
93 #define HRS_CHAR_ENGY_EXP_SUP 0xC0 /**< Bit mask of Energy Expanded Feature Supported. */
94 /** @} */
95 /** @} */
96 
97 /**
98  * @defgroup HRS_ENUM Enumerations
99  * @{
100  */
101 /**@brief Values for sensor location. */
102 typedef enum
103 {
104  HRS_SENS_LOC_OTHER, /**< The sensor location is other. */
105  HRS_SENS_LOC_CHEST, /**< The sensor location is the chest. */
106  HRS_SENS_LOC_WRIST, /**< The sensor location is the wrist. */
107  HRS_SENS_LOC_FINGER, /**< The sensor location is the finger. */
108  HRS_SENS_LOC_HAND, /**< The sensor location is the hand. */
109  HRS_SENS_LOC_EARLOBE, /**< The sensor location is the earlobe. */
110  HRS_SENS_LOC_FOOT, /**< The sensor location is the foot. */
112 
113 /**@brief Heart Rate Service event types. */
114 typedef enum
115 {
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. */
121 /** @} */
122 
123 /**
124  * @defgroup HRS_STRUCT Structures
125  * @{
126  */
127 /**@brief Heart Rate Service event. */
128 typedef struct
129 {
130  uint8_t conn_idx; /**< Index of connection. */
131  hrs_evt_type_t evt_type; /**< Heart Rate Service event type. */
132 } hrs_evt_t;
133 /** @} */
134 
135 /**
136  * @defgroup HRS_TYPEDEF Typedefs
137  * @{
138  */
139 /**@brief Heart Rate Service event handler type. */
140 typedef void (*hrs_evt_handler_t)(hrs_evt_t *p_evt);
141 /** @} */
142 
143 /**
144  * @defgroup HRS_STRUCT Structures
145  * @{
146  */
147 /**@brief Heart Rate Service Init variable. */
148 typedef struct
149 {
150  hrs_evt_handler_t evt_handler; /**< Heart Rate Service event handler. */
151  bool is_sensor_contact_supported; /**< Determine if sensor contact detection is to be supported. */
152  uint8_t char_mask; /**< Mask of Supported characteristics, and configured with \ref HRS_CHAR_MASK */
153  hrs_sensor_loc_t sensor_loc; /**< The value of Body Sensor Location characteristic is static while in a connection. */
154 } hrs_init_t;
155 /** @} */
156 
157 /**
158  * @defgroup HRS_FUNCTION Functions
159  * @{
160  */
161 /**
162  *****************************************************************************************
163  * @brief Set the state of the Sensor Contact Detected bit.
164  *
165  * @param[in] is_sensor_contact_detected: True if sensor contact is detected, false otherwise.
166  *****************************************************************************************
167  */
168 void hrs_sensor_contact_detected_update(bool is_sensor_contact_detected);
169 
170 /**
171  *****************************************************************************************
172  * @brief Set the state of the Sensor Contact Supported bit.
173  *
174  * @param[in] is_sensor_contact_supported: New state of the Sensor Contact Supported bit.
175  *****************************************************************************************
176  */
177 void hrs_sensor_contact_supported_set(bool is_sensor_contact_supported);
178 
179 /**
180  *****************************************************************************************
181  * @brief Set the Body Sensor Location.
182  *
183  * @details Sets a new value of the Body Sensor Location characteristic. The new value will be sent
184  * to the client the next time the client reads the Body Sensor Location characteristic.
185  *
186  * @param[in] hrs_sensor_loc: New Body Sensor Location.
187  *****************************************************************************************
188  */
190 
191 /**
192  *****************************************************************************************
193  * @brief Update Energy measurement if Energy Expended is supported.
194  *
195  * @param[in] energy: New energy measurement.
196  *****************************************************************************************
197  */
198 void hrs_energy_update(uint16_t energy);
199 
200 /**
201  *****************************************************************************************
202  * @brief Send Heart Rate measurement if Notify has been enabled.
203  *
204  * @param[in] conn_idx Connection index.
205  * @param[in] heart_rate New heart rate measurement.
206  * @param[in] is_energy_updated Indicate whether update energy expended.
207  *
208  * @return Result of notify value.
209  *****************************************************************************************
210  */
211 sdk_err_t hrs_heart_rate_measurement_send(uint8_t conn_idx, uint16_t heart_rate, bool is_energy_updated);
212 
213 /**
214  *****************************************************************************************
215  * @brief Add an RR Interval measurement to the RR Interval buffer.
216  *
217  * @details All buffered RR Interval measurements will be included in the next
218  * Heart Rate Measurement notification. The maximum number of
219  * RR Interval measurement is \ref HRS_MAX_BUFFERED_RR_INTERVALS. If the
220  * buffer is full, the oldest measurement in the buffer will be deleted.
221  *
222  * @param[in] rr_interval New RR Interval measurement (will be buffered until
223  * the next transmission of Heart Rate Measurement).
224  *****************************************************************************************
225  */
226 void hrs_rr_interval_add(uint16_t rr_interval);
227 
228 /**
229  *****************************************************************************************
230  * @brief Init a Heart Rate Service instance and add in the DB.
231  *
232  * @param[in] p_hrs_init: Pointer to a Heart Rate Init variable.
233  *
234  * @return Result of service initialization.
235  *****************************************************************************************
236  */
238 
239 /**
240  *****************************************************************************************
241  * @brief Provide the interface for other modules to obtain the hrs service start handle .
242  *
243  * @return The hrs service start handle.
244  *****************************************************************************************
245  */
247 
248 /** @} */
249 
250 #endif
251 /** @} */
252 /** @} */
HRS_SENS_LOC_EARLOBE
@ HRS_SENS_LOC_EARLOBE
Definition: hrs.h:109
hrs_init_t::evt_handler
hrs_evt_handler_t evt_handler
Definition: hrs.h:150
hrs_evt_t::conn_idx
uint8_t conn_idx
Definition: hrs.h:130
hrs_init_t::sensor_loc
hrs_sensor_loc_t sensor_loc
Definition: hrs.h:153
HRS_EVT_NOTIFICATION_ENABLED
@ HRS_EVT_NOTIFICATION_ENABLED
Definition: hrs.h:116
hrs_evt_t
Heart Rate Service event.
Definition: hrs.h:129
hrs_init_t::char_mask
uint8_t char_mask
Definition: hrs.h:152
hrs_sensor_contact_detected_update
void hrs_sensor_contact_detected_update(bool is_sensor_contact_detected)
Set the state of the Sensor Contact Detected bit.
hrs_service_init
sdk_err_t hrs_service_init(hrs_init_t *p_hrs_init)
Init a Heart Rate Service instance and add in the DB.
hrs_rr_interval_add
void hrs_rr_interval_add(uint16_t rr_interval)
Add an RR Interval measurement to the RR Interval buffer.
hrs_sensor_location_set
void hrs_sensor_location_set(hrs_sensor_loc_t hrs_sensor_loc)
Set the Body Sensor Location.
gr_includes.h
Include Files API.
HRS_SENS_LOC_WRIST
@ HRS_SENS_LOC_WRIST
Definition: hrs.h:106
HRS_SENS_LOC_FOOT
@ HRS_SENS_LOC_FOOT
Definition: hrs.h:110
hrs_evt_type_t
hrs_evt_type_t
Heart Rate Service event types.
Definition: hrs.h:115
hrs_heart_rate_measurement_send
sdk_err_t hrs_heart_rate_measurement_send(uint8_t conn_idx, uint16_t heart_rate, bool is_energy_updated)
Send Heart Rate measurement if Notify has been enabled.
hrs_sensor_loc_t
hrs_sensor_loc_t
Values for sensor location.
Definition: hrs.h:103
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:257
HRS_SENS_LOC_FINGER
@ HRS_SENS_LOC_FINGER
Definition: hrs.h:107
HRS_EVT_READ_BODY_SEN_LOCATION
@ HRS_EVT_READ_BODY_SEN_LOCATION
Definition: hrs.h:119
hrs_service_start_handle_get
uint16_t hrs_service_start_handle_get(void)
Provide the interface for other modules to obtain the hrs service start handle .
hrs_evt_t::evt_type
hrs_evt_type_t evt_type
Definition: hrs.h:131
hrs_init_t
Heart Rate Service Init variable.
Definition: hrs.h:149
HRS_EVT_NOTIFICATION_DISABLED
@ HRS_EVT_NOTIFICATION_DISABLED
Definition: hrs.h:117
HRS_EVT_RESET_ENERGY_EXPENDED
@ HRS_EVT_RESET_ENERGY_EXPENDED
Definition: hrs.h:118
hrs_energy_update
void hrs_energy_update(uint16_t energy)
Update Energy measurement if Energy Expended is supported.
HRS_SENS_LOC_CHEST
@ HRS_SENS_LOC_CHEST
Definition: hrs.h:105
HRS_SENS_LOC_HAND
@ HRS_SENS_LOC_HAND
Definition: hrs.h:108
hrs_evt_handler_t
void(* hrs_evt_handler_t)(hrs_evt_t *p_evt)
Heart Rate Service event handler type.
Definition: hrs.h:140
HRS_SENS_LOC_OTHER
@ HRS_SENS_LOC_OTHER
Definition: hrs.h:104
hrs_sensor_contact_supported_set
void hrs_sensor_contact_supported_set(bool is_sensor_contact_supported)
Set the state of the Sensor Contact Supported bit.
hrs_init_t::is_sensor_contact_supported
bool is_sensor_contact_supported
Definition: hrs.h:151