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. */
111 } hrs_sensor_loc_t;
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. */
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 {
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 */
189 void hrs_sensor_location_set(hrs_sensor_loc_t hrs_sensor_loc);
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 */
237 sdk_err_t hrs_service_init(hrs_init_t *p_hrs_init);
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 */
246 uint16_t hrs_service_start_handle_get(void);
247
248 /** @} */
249
250 #endif
251 /** @} */
252 /** @} */
HRS_SENS_LOC_EARLOBE
@ HRS_SENS_LOC_EARLOBE
The sensor location is the earlobe.
Definition: hrs.h:109
hrs_init_t::evt_handler
hrs_evt_handler_t evt_handler
Heart Rate Service event handler.
Definition: hrs.h:150
hrs_evt_t::conn_idx
uint8_t conn_idx
Index of connection.
Definition: hrs.h:130
hrs_init_t::sensor_loc
hrs_sensor_loc_t sensor_loc
The value of Body Sensor Location characteristic is static while in a connection.
Definition: hrs.h:153
HRS_EVT_NOTIFICATION_ENABLED
@ HRS_EVT_NOTIFICATION_ENABLED
Heart Rate value notification has been 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
Mask of Supported characteristics, and configured with Characteristics 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
The sensor location is the wrist.
Definition: hrs.h:106
HRS_SENS_LOC_FOOT
@ HRS_SENS_LOC_FOOT
The sensor location is the 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:273
HRS_SENS_LOC_FINGER
@ HRS_SENS_LOC_FINGER
The sensor location is the finger.
Definition: hrs.h:107
HRS_EVT_READ_BODY_SEN_LOCATION
@ HRS_EVT_READ_BODY_SEN_LOCATION
The peer device reads Body Sensor Location characteristic.
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
Heart Rate Service event 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
Heart Rate value notification has been disabled.
Definition: hrs.h:117
HRS_EVT_RESET_ENERGY_EXPENDED
@ HRS_EVT_RESET_ENERGY_EXPENDED
The peer device requests to 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
The sensor location is the chest.
Definition: hrs.h:105
HRS_SENS_LOC_HAND
@ HRS_SENS_LOC_HAND
The sensor location is the 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
The sensor location is 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
Determine if sensor contact detection is to be supported.
Definition: hrs.h:151