hrs_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file hrs_c.h
5 *
6 * @brief Heart Rate Service Client 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 */
42
43 /**
44 * @defgroup BLE_SDK_HRS_C Heart Rate Service Client (HRS_C)
45 * @{
46 * @brief Heart Rate Service Client module.
47 *
48 * @details The Heart Rate Service Client contains the APIs and types, which can be used by the
49 * application to discovery of Heart Rate Service of peer and interact with it.
50 *
51 * The application must provide an event handler to register, then call \ref hrs_client_init().
52 * After Heart Rate Service Client discoveries peer Heat Rate Service, application can call
53 * \ref hrs_c_heart_rate_meas_notify_set(), then will receive heart rate data from peer,
54 * also can call \ref hrs_c_sensor_loc_read() and \ref hrs_c_ctrl_point_set() to get sensor
55 * location information and reset energy.
56 */
57
58 #ifndef __HRS_C_H__
59 #define __HRS_C_H__
60
61 #include "gr55xx_sys.h"
62 #include "ble_prf_types.h"
63 #include "custom_config.h"
64 #include <stdint.h>
65 #include <stdbool.h>
66
67 /**
68 * @defgroup HRS_C_MACRO Defines
69 * @{
70 */
71 #define HRS_C_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
72 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of HRS Client connections. */
73 #define HRS_C_RR_INTERVALS_NUM_MAX 9 /**< Maximum number of RR intervals in HRS notifications. */
74 #define HRS_C_CTRL_POINT_ENERGY_EXP 0x01 /**< Value for control point characteristic. */
75 /** @} */
76
77 /**
78 * @defgroup HRS_C_ENUM Enumerations
79 * @{
80 */
81 /**@brief Heart Rate Service Client event type. */
82 typedef enum
83 {
84 HRS_C_EVT_INVALID, /**< HRS Client invalid event. */
85 HRS_C_EVT_DISCOVERY_COMPLETE, /**< HRS Client has found HRS service and its characteristics. */
86 HRS_C_EVT_DISCOVERY_FAIL, /**< HRS Client found HRS service failed because of invalid operation or no found at the peer. */
87 HRS_C_EVT_HR_MEAS_NTF_SET_SUCCESS, /**< HRS Client has set Notification of Heart Rate Measure characteristic. */
88 HRS_C_EVT_HR_MEAS_VAL_RECEIVE, /**< HRS Client has received Heart Rate Measure value notification from peer. */
89 HRS_C_EVT_SENSOR_LOC_READ_RSP, /**< HRS Client has received Sensor Location Value read response. */
90 HRS_C_EVT_CTRL_POINT_SET, /**< HRS Client has set Control Point completely. */
91 HRS_C_EVT_WRITE_OP_ERR, /**< Error occured when HRS Client writen to peer. */
92 } hrs_c_evt_type_t;
93
94 /**@brief Heart Rate Service Measurement flag bit. */
95 typedef enum
96 {
97
98 HRS_C_BIT_RATE_FORMAT = 0x01, /**< Heart Rate Value Format bit. */
99 HRS_C_BIT_SENSOR_CONTACT_DETECTED = 0x02, /**< Sensor Contact Detected bit. */
100 HRS_C_BIT_SENSOR_CONTACT_SUPPORTED = 0x04, /**< Sensor Contact Supported bit. */
101 HRS_C_BIT_ENERGY_EXPENDED_STATUS = 0x08, /**< Energy Expended Status bit. */
102 HRS_C_BIT_INTERVAL = 0x10, /**< RR-Interval bit. */
103 } hrs_c_flag_bit_t;
104
105 /**@brief Values for sensor location. */
106 typedef enum
107 {
108 HRS_C_SENS_LOC_OTHER, /**< The sensor location is other. */
109 HRS_C_SENS_LOC_CHEST, /**< The sensor location is the chest. */
110 HRS_C_SENS_LOC_WRIST, /**< The sensor location is the wrist. */
111 HRS_C_SENS_LOC_FINGER, /**< The sensor location is the finger. */
112 HRS_C_SENS_LOC_HAND, /**< The sensor location is the hand. */
113 HRS_C_SENS_LOC_EARLOBE, /**< The sensor location is the earlobe. */
114 HRS_C_SENS_LOC_FOOT, /**< The sensor location is the foot. */
115 } hrs_c_sensor_loc_t;
116 /** @} */
117
118 /**
119 * @defgroup HRS_C_STRUCT Structures
120 * @{
121 */
122 /**@brief Heart Rate Measurement characteristic value structure. */
123 typedef struct
124 {
125 bool is_sensor_contact_detected; /**< True if sensor contact has been detected. */
126 uint16_t hr_value; /**< Heart Rate Value. */
127 uint8_t rr_intervals_num; /**< Number of RR intervals. */
128 float rr_intervals[HRS_C_RR_INTERVALS_NUM_MAX]; /**< RR intervals. */
129 uint16_t energy_expended; /**< The accumulated energy expended in kilo Joules since the last time it was reset. */
130 } hrs_c_hr_meas_t;
131
132 /**@brief Handles on the connected peer device needed to interact with it. */
133 typedef struct
134 {
135 uint16_t hrs_srvc_start_handle; /**< HRS Service start handle. */
136 uint16_t hrs_srvc_end_handle; /**< HRS Service end handle. */
137 uint16_t hrs_hr_meas_handle; /**< HRS Heart Rate Measurement characteristic Value handle which has been got from peer. */
138 uint16_t hrs_hr_meas_cccd_handle; /**< HRS CCCD handle of Heart Rate Measurement characteristic which has been got from peer. */
139 uint16_t hrs_sensor_loc_handle; /**< HRS Sensor Location characteristic Value handle which has been got from peer. */
140 uint16_t hrs_ctrl_point_handle; /**< HRS Control Point characteristic Value handle which has been got from peer. */
141 } hrs_c_handles_t;
142
143 /**@brief Heart Rate Service Client event. */
144 typedef struct
145 {
146 uint8_t conn_idx; /**< The connection index. */
147 hrs_c_evt_type_t evt_type; /**< HRS Client event type. */
148 union
149 {
150 hrs_c_hr_meas_t hr_meas_buff; /**< Buffer of heart rate measurement value. */
151 hrs_c_sensor_loc_t sensor_loc; /**< Sensor location. */
152 } value; /**< Decoded result of value received. */
153 } hrs_c_evt_t;
154 /** @} */
155
156 /**
157 * @defgroup HRS_C_TYPEDEF Typedefs
158 * @{
159 */
160 /**@brief Heart Rate Service Client event handler type. */
161 typedef void (*hrs_c_evt_handler_t)(hrs_c_evt_t *p_evt);
162 /** @} */
163
164 /**
165 * @defgroup HRS_C_FUNCTION Functions
166 * @{
167 */
168 /**
169 *****************************************************************************************
170 * @brief Register HRS Client event handler.
171 *
172 * @param[in] evt_handler: Heart Rate Service Client event handler.
173 *
174 * @return Result of initialization.
175 *****************************************************************************************
176 */
177 sdk_err_t hrs_client_init(hrs_c_evt_handler_t evt_handler);
178
179 /**
180 *****************************************************************************************
181 * @brief Discovery Heart Rate Service on peer.
182 *
183 * @param[in] conn_idx: Index of connection.
184 *
185 * @return Operation result.
186 *****************************************************************************************
187 */
188 sdk_err_t hrs_c_disc_srvc_start(uint8_t conn_idx);
189
190 /**
191 *****************************************************************************************
192 * @brief Enable or disable peer Heart Rate Measurement characteristic notify.
193 *
194 * @param[in] conn_idx: Index of connection.
195 * @param[in] is_enable: True or false.
196 *
197 * @return Operation result.
198 *****************************************************************************************
199 */
200 sdk_err_t hrs_c_heart_rate_meas_notify_set(uint8_t conn_idx, bool is_enable);
201
202 /**
203 *****************************************************************************************
204 * @brief Read Sensor Location characteristic value.
205 *
206 * @param[in] conn_idx: Index of connection.
207 *
208 * @return Operation result.
209 *****************************************************************************************
210 */
211 sdk_err_t hrs_c_sensor_loc_read(uint8_t conn_idx);
212
213 /**
214 *****************************************************************************************
215 * @brief Set Control Point characteristic value.
216 *
217 * @param[in] conn_idx: Index of connection.
218 * @param[in] ctrl_value: Value of control point.
219 *
220 * @return Operation result.
221 *****************************************************************************************
222 */
223 sdk_err_t hrs_c_ctrl_point_set(uint8_t conn_idx, uint16_t ctrl_value);
224 /** @} */
225
226 #endif
227 /** @} */
228 /** @} */
229
hrs_c_disc_srvc_start
sdk_err_t hrs_c_disc_srvc_start(uint8_t conn_idx)
Discovery Heart Rate Service on peer.
hrs_c_flag_bit_t
hrs_c_flag_bit_t
Heart Rate Service Measurement flag bit.
Definition: hrs_c.h:96
hrs_c_handles_t::hrs_hr_meas_handle
uint16_t hrs_hr_meas_handle
HRS Heart Rate Measurement characteristic Value handle which has been got from peer.
Definition: hrs_c.h:137
HRS_C_EVT_INVALID
@ HRS_C_EVT_INVALID
HRS Client invalid event.
Definition: hrs_c.h:84
hrs_c_handles_t::hrs_srvc_start_handle
uint16_t hrs_srvc_start_handle
HRS Service start handle.
Definition: hrs_c.h:135
HRS_C_BIT_INTERVAL
@ HRS_C_BIT_INTERVAL
RR-Interval bit.
Definition: hrs_c.h:102
hrs_c_evt_t::evt_type
hrs_c_evt_type_t evt_type
HRS Client event type.
Definition: hrs_c.h:147
HRS_C_SENS_LOC_FOOT
@ HRS_C_SENS_LOC_FOOT
The sensor location is the foot.
Definition: hrs_c.h:114
hrs_c_evt_type_t
hrs_c_evt_type_t
Heart Rate Service Client event type.
Definition: hrs_c.h:83
hrs_client_init
sdk_err_t hrs_client_init(hrs_c_evt_handler_t evt_handler)
Register HRS Client event handler.
HRS_C_EVT_HR_MEAS_NTF_SET_SUCCESS
@ HRS_C_EVT_HR_MEAS_NTF_SET_SUCCESS
HRS Client has set Notification of Heart Rate Measure characteristic.
Definition: hrs_c.h:87
hrs_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: hrs_c.h:134
HRS_C_SENS_LOC_HAND
@ HRS_C_SENS_LOC_HAND
The sensor location is the hand.
Definition: hrs_c.h:112
hrs_c_heart_rate_meas_notify_set
sdk_err_t hrs_c_heart_rate_meas_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer Heart Rate Measurement characteristic notify.
HRS_C_SENS_LOC_CHEST
@ HRS_C_SENS_LOC_CHEST
The sensor location is the chest.
Definition: hrs_c.h:109
gr55xx_sys.h
GR55XX System API.
hrs_c_evt_handler_t
void(* hrs_c_evt_handler_t)(hrs_c_evt_t *p_evt)
Heart Rate Service Client event handler type.
Definition: hrs_c.h:161
HRS_C_EVT_WRITE_OP_ERR
@ HRS_C_EVT_WRITE_OP_ERR
Error occured when HRS Client writen to peer.
Definition: hrs_c.h:91
HRS_C_BIT_SENSOR_CONTACT_SUPPORTED
@ HRS_C_BIT_SENSOR_CONTACT_SUPPORTED
Sensor Contact Supported bit.
Definition: hrs_c.h:100
HRS_C_EVT_CTRL_POINT_SET
@ HRS_C_EVT_CTRL_POINT_SET
HRS Client has set Control Point completely.
Definition: hrs_c.h:90
HRS_C_BIT_RATE_FORMAT
@ HRS_C_BIT_RATE_FORMAT
Heart Rate Value Format bit.
Definition: hrs_c.h:98
HRS_C_BIT_SENSOR_CONTACT_DETECTED
@ HRS_C_BIT_SENSOR_CONTACT_DETECTED
Sensor Contact Detected bit.
Definition: hrs_c.h:99
hrs_c_evt_t
Heart Rate Service Client event.
Definition: hrs_c.h:145
hrs_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: hrs_c.h:146
hrs_c_hr_meas_t::rr_intervals_num
uint8_t rr_intervals_num
Number of RR intervals.
Definition: hrs_c.h:127
hrs_c_handles_t::hrs_ctrl_point_handle
uint16_t hrs_ctrl_point_handle
HRS Control Point characteristic Value handle which has been got from peer.
Definition: hrs_c.h:140
ble_prf_types.h
Profile/Service Common Types.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
HRS_C_EVT_DISCOVERY_FAIL
@ HRS_C_EVT_DISCOVERY_FAIL
HRS Client found HRS service failed because of invalid operation or no found at the peer.
Definition: hrs_c.h:86
HRS_C_SENS_LOC_WRIST
@ HRS_C_SENS_LOC_WRIST
The sensor location is the wrist.
Definition: hrs_c.h:110
HRS_C_SENS_LOC_OTHER
@ HRS_C_SENS_LOC_OTHER
The sensor location is other.
Definition: hrs_c.h:108
hrs_c_hr_meas_t::energy_expended
uint16_t energy_expended
The accumulated energy expended in kilo Joules since the last time it was reset.
Definition: hrs_c.h:129
hrs_c_sensor_loc_t
hrs_c_sensor_loc_t
Values for sensor location.
Definition: hrs_c.h:107
hrs_c_evt_t::sensor_loc
hrs_c_sensor_loc_t sensor_loc
Sensor location.
Definition: hrs_c.h:151
hrs_c_hr_meas_t
Heart Rate Measurement characteristic value structure.
Definition: hrs_c.h:124
HRS_C_EVT_HR_MEAS_VAL_RECEIVE
@ HRS_C_EVT_HR_MEAS_VAL_RECEIVE
HRS Client has received Heart Rate Measure value notification from peer.
Definition: hrs_c.h:88
hrs_c_handles_t::hrs_hr_meas_cccd_handle
uint16_t hrs_hr_meas_cccd_handle
HRS CCCD handle of Heart Rate Measurement characteristic which has been got from peer.
Definition: hrs_c.h:138
HRS_C_EVT_DISCOVERY_COMPLETE
@ HRS_C_EVT_DISCOVERY_COMPLETE
HRS Client has found HRS service and its characteristics.
Definition: hrs_c.h:85
hrs_c_handles_t::hrs_sensor_loc_handle
uint16_t hrs_sensor_loc_handle
HRS Sensor Location characteristic Value handle which has been got from peer.
Definition: hrs_c.h:139
HRS_C_RR_INTERVALS_NUM_MAX
#define HRS_C_RR_INTERVALS_NUM_MAX
Maximum number of RR intervals in HRS notifications.
Definition: hrs_c.h:73
hrs_c_hr_meas_t::hr_value
uint16_t hr_value
Heart Rate Value.
Definition: hrs_c.h:126
HRS_C_SENS_LOC_EARLOBE
@ HRS_C_SENS_LOC_EARLOBE
The sensor location is the earlobe.
Definition: hrs_c.h:113
hrs_c_ctrl_point_set
sdk_err_t hrs_c_ctrl_point_set(uint8_t conn_idx, uint16_t ctrl_value)
Set Control Point characteristic value.
hrs_c_handles_t::hrs_srvc_end_handle
uint16_t hrs_srvc_end_handle
HRS Service end handle.
Definition: hrs_c.h:136
HRS_C_BIT_ENERGY_EXPENDED_STATUS
@ HRS_C_BIT_ENERGY_EXPENDED_STATUS
Energy Expended Status bit.
Definition: hrs_c.h:101
hrs_c_hr_meas_t::is_sensor_contact_detected
bool is_sensor_contact_detected
True if sensor contact has been detected.
Definition: hrs_c.h:125
HRS_C_SENS_LOC_FINGER
@ HRS_C_SENS_LOC_FINGER
The sensor location is the finger.
Definition: hrs_c.h:111
HRS_C_EVT_SENSOR_LOC_READ_RSP
@ HRS_C_EVT_SENSOR_LOC_READ_RSP
HRS Client has received Sensor Location Value read response.
Definition: hrs_c.h:89
hrs_c_evt_t::hr_meas_buff
hrs_c_hr_meas_t hr_meas_buff
Buffer of heart rate measurement value.
Definition: hrs_c.h:150
hrs_c_sensor_loc_read
sdk_err_t hrs_c_sensor_loc_read(uint8_t conn_idx)
Read Sensor Location characteristic value.