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. */
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. */
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. */
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. */
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. */
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  */
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  */
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  */
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
Definition: hrs_c.h:136
HRS_C_EVT_INVALID
@ HRS_C_EVT_INVALID
Definition: hrs_c.h:83
hrs_c_handles_t::hrs_srvc_start_handle
uint16_t hrs_srvc_start_handle
Definition: hrs_c.h:134
HRS_C_BIT_INTERVAL
@ HRS_C_BIT_INTERVAL
Definition: hrs_c.h:101
hrs_c_evt_t::evt_type
hrs_c_evt_type_t evt_type
Definition: hrs_c.h:146
HRS_C_SENS_LOC_FOOT
@ HRS_C_SENS_LOC_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
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
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
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
Definition: hrs_c.h:90
HRS_C_BIT_SENSOR_CONTACT_SUPPORTED
@ HRS_C_BIT_SENSOR_CONTACT_SUPPORTED
Definition: hrs_c.h:99
HRS_C_EVT_CTRL_POINT_SET
@ HRS_C_EVT_CTRL_POINT_SET
Definition: hrs_c.h:89
HRS_C_BIT_RATE_FORMAT
@ HRS_C_BIT_RATE_FORMAT
Definition: hrs_c.h:97
HRS_C_BIT_SENSOR_CONTACT_DETECTED
@ HRS_C_BIT_SENSOR_CONTACT_DETECTED
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
Definition: hrs_c.h:145
hrs_c_hr_meas_t::rr_intervals_num
uint8_t rr_intervals_num
Definition: hrs_c.h:126
hrs_c_handles_t::hrs_ctrl_point_handle
uint16_t hrs_ctrl_point_handle
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:290
HRS_C_EVT_DISCOVERY_FAIL
@ HRS_C_EVT_DISCOVERY_FAIL
Definition: hrs_c.h:85
HRS_C_SENS_LOC_WRIST
@ HRS_C_SENS_LOC_WRIST
Definition: hrs_c.h:109
HRS_C_SENS_LOC_OTHER
@ HRS_C_SENS_LOC_OTHER
Definition: hrs_c.h:107
hrs_c_hr_meas_t::energy_expended
uint16_t energy_expended
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
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
Definition: hrs_c.h:87
hrs_c_handles_t::hrs_hr_meas_cccd_handle
uint16_t hrs_hr_meas_cccd_handle
Definition: hrs_c.h:137
HRS_C_EVT_DISCOVERY_COMPLETE
@ HRS_C_EVT_DISCOVERY_COMPLETE
Definition: hrs_c.h:84
hrs_c_handles_t::hrs_sensor_loc_handle
uint16_t hrs_sensor_loc_handle
Definition: hrs_c.h:138
HRS_C_RR_INTERVALS_NUM_MAX
#define HRS_C_RR_INTERVALS_NUM_MAX
Definition: hrs_c.h:72
hrs_c_hr_meas_t::hr_value
uint16_t hr_value
Definition: hrs_c.h:125
HRS_C_SENS_LOC_EARLOBE
@ HRS_C_SENS_LOC_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
Definition: hrs_c.h:135
HRS_C_BIT_ENERGY_EXPENDED_STATUS
@ HRS_C_BIT_ENERGY_EXPENDED_STATUS
Definition: hrs_c.h:100
hrs_c_hr_meas_t::is_sensor_contact_detected
bool is_sensor_contact_detected
Definition: hrs_c.h:124
HRS_C_SENS_LOC_FINGER
@ HRS_C_SENS_LOC_FINGER
Definition: hrs_c.h:110
HRS_C_EVT_SENSOR_LOC_READ_RSP
@ HRS_C_EVT_SENSOR_LOC_READ_RSP
Definition: hrs_c.h:88
hrs_c_evt_t::hr_meas_buff
hrs_c_hr_meas_t hr_meas_buff
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.