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