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