hts.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file hts.h
5 *
6 * @brief Health Thermometer 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_HTS Health Thermometer Service (HTS)
46 * @{
47 * @brief Definitions and prototypes for the HTS interface.
48 *
49 * @details The Health Thermometer Service exposes temperature and other data related to a
50 * thermometer used for healthcare applications. This module implements the Health
51 * Thermometer Service with the Temperature Meaturement, Temperature Type, Intermediate
52 * Temperature, and Measurement Interval characteristics.
53 *
54 * After \ref hts_init_t variable is initialized, the application must call \ref hts_service_init()
55 * to optionally add the Health Thermometer Service, Temperature Meaturement, Temperature Type,
56 * Intermediate Temperature, and Measurement Interval characteristics to the BLE stack database
57 * according to \ref hts_init_t.char_mask. However the value of Temperature Type is stored within
58 * \ref hts_init_t.temp_type which locates in user space.
59 */
60
61 #ifndef _HTS_H_
62 #define _HTS_H_
63
64 #include "gr55xx_sys.h"
65 #include "custom_config.h"
66 #include "ble_prf_utils.h"
67 #include <stdint.h>
68 #include <stdbool.h>
69
70 /**
71 * @defgroup HTS_MACRO Defines
72 * @{
73 */
74 #define HTS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
75 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Health Thermometer Service connections. */
76 #define HTS_TEM_MEAS_MAX_LEN 20 /**< Maximum length of temperature measurement encode. */
77 #define HTS_TEM_TYPE_MAX_LEN 1 /**< Maximum length of temperature type value. */
78 #define HTS_INTM_TEM_MAX_LEN 20 /**< Maximun length of intermediate temperature encode. */
79 #define HTS_MEAS_INTERVAL_MAX_LEN 2 /**< Maximum length of measurement interval value. */
80 #define HTS_MEAS_INTV_DFLT_MIN 2 /**< Minimun interval of temperature measurement (in unit of 1s). */
81 #define HTS_MEAS_INTV_DFLT_MAX 10 /**< Maximum interval of temperature measurement (in unit of 1s). */
82
83 /**
84 * @defgroup HTS_CHAR_MASK Characteristics Mask
85 * @{
86 * @brief Bit masks for the initialization of \ref hts_init_t.char_mask.
87 */
88 #define HTS_CHAR_MANDATORY 0x000f /**< Bit mask for mandatory characteristic in HTS. */
89 #define HTS_CHAR_TEM_TYPE_SUP 0x003f /**< Bit mask for temperature type characteristic that is optional. */
90 #define HTS_CHAR_INTM_TEM_SUP 0x01c0 /**< Bit mask for intermediate temperature characteristic that is optional. */
91 #define HTS_CHAR_MEAS_INTERVAL_SUP 0x1e00 /**< Bit mask for mearsurement interval characteristic that is optional. */
92 #define HTS_CHAR_FULL 0x1fff /**< Bit mask of the full characteristic. */
93 /** @} */
94 /** @} */
95
96 /**
97 * @defgroup HTS_ENUM Enumerations
98 * @{
99 */
100 /**@brief Health Thermometer Service event type.*/
101 typedef enum
102 {
103 HTS_EVT_INVALID, /**< Indicate that invalid event. */
104 HTS_EVT_TEM_MEAS_INDICATION_ENABLE, /**< Indicate that temperature measurement indication has been enabled. */
105 HTS_EVT_TEM_MEAS_INDICATION_DISABLE, /**< Indicate that temperature measurement indication has been disabled. */
106 HTS_EVT_INTM_TEM_NOTIFICATION_ENABLE, /**< Indicate that intermediate temperature notification has been enabled. */
107 HTS_EVT_INTM_TEM_NOTIFICATION_DISABLE, /**< Indicate that intermediate temperature notification has been disbled. */
108 HTS_EVT_MEAS_INTREVAL_INDICATION_ENABLE, /**< Indicate that measurement interval indication has been enabled. */
109 HTS_EVT_MEAS_INTERVAL_INDICATION_DISABLE, /**< Indicate that measurement interval indication has been disabled. */
110 HTS_EVT_MEAS_INTERVAL_UPDATE, /**< Indicate that measurement interval has been updated. */
111 HTS_EVT_READ_CHARACTERISTIC, /**< The peer reads the characteristic. */
112 } hts_evt_type_t;
113
114 /**@brief Health Thermometer temperature unit, */
115 typedef enum
116 {
117 HTS_TEMPERATURE_CELCIUS, /**< Indicate that temperature measurement Value Unit is celcius. */
118 HTS_TEMPERATURE_FAHRENHEIT, /**< Indicate that temperature measurement Value Unit is fahrenheit. */
119 } hts_temp_unit_t;
120
121 /**@brief Health Thermometer temperature measurement type. */
122 typedef enum
123 {
124 HTS_TEMPERATURE_STABLE, /**< Stable type of temperature. */
125 HTS_TEMPERATURE_INTERMEDIATE, /**< Intermediary type of temperature. */
126 } hts_temp_meas_type_t;
127
128 /**@brief Health Thermometer Measurement flag bits. */
129 typedef enum
130 {
131 HTS_MEAS_FLAG_TEM_UINTS_BIT = (0x01<<0), /**< Bit for temperature uints. */
132 HTS_MEAS_FLAG_TIME_STAMP_BIT = (0x01<<1), /**< Bit for time stamp. */
133 HTS_MEAS_FLAG_TEM_TYPE_BIT = (0x01<<2), /**< Bit for temperature type. */
134 } hts_flag_bit_t;
135
136 /**@brief Temperature Type measurement locations. */
137 typedef enum
138 {
139 HTS_TEMP_TYPE_ARMPIT = 0x01, /**< Temperature measurement location: armpit. */
140 HTS_TEMP_TYPE_BODY, /**< Temperature measurement location: body. */
141 HTS_TEMP_TYPE_EAR, /**< Temperature measurement location: ear. */
142 HTS_TEMP_TYPE_FINGER, /**< Temperature measurement location: finger. */
143 HTS_TEMP_TYPE_GI_TRACT, /**< Temperature measurement location: Gi tract. */
144 HTS_TEMP_TYPE_MOUTH, /**< Temperature measurement location: mouth. */
145 HTS_TEMP_TYPE_RECTUM, /**< Temperature measurement location: rectum. */
146 HTS_TEMP_TYPE_TOE, /**< Temperature measurement location: toe. */
147 HTS_TEMP_TYPE_EAR_DRUM, /**< Temperature measurement location: ear drum. */
148 } hts_temp_meas_loc_t;
149
150 /**@brief The parameters for \ref HTS_EVT_READ_CHARACTERISTIC. */
151 typedef enum
152 {
153 HTS_READ_CHAR_TEMP_TYPE, /**< The peer reads the Temperature Type characteristic. */
154 HTS_READ_CHAR_MEAS_INTL, /**< The peer reads the Measurement Interval characteristic. */
155 } hts_read_characteristic_t;
156 /** @} */
157
158 /**
159 * @defgroup HTS_STRUCT Structures
160 * @{
161 */
162 /**@brief Health Thermometer Service event. */
163 typedef struct
164 {
165 hts_evt_type_t evt_type; /**< The HTS event type. */
166 uint8_t conn_idx; /**< The index of the connection. */
167 const uint8_t *p_data; /**< Pointer to the event data. */
168 uint16_t length; /**< Length of the event data. */
169 } hts_evt_t;
170 /** @} */
171
172 /**
173 * @defgroup HTS_TYPEDEF Typedefs
174 * @{
175 */
176 /**@brief Health Thermometer Service event handler type.*/
177 typedef void (*hts_evt_handler_t)(hts_evt_t *p_evt);
178
179 /**@brief Health Thermometer Service date time type.*/
180 typedef prf_date_time_t hts_date_time_t;
181 /** @} */
182
183 /**
184 * @defgroup HTS_STRUCT Structures
185 * @{
186 */
187 /**@brief SFLOAT format (IEEE-11073 32-bit FLOAT, defined as a 32-bit vlue with 24-bit mantissa and 8-bit exponent. */
188 typedef struct
189 {
190 int8_t exponent; /**< Base 10 exponent, only 8 bits */
191 int32_t mantissa; /**< Mantissa, only 24 bits */
192 } ieee_float32_t;
193
194 /**@brief Health Theromometer Measurement Character value structure. */
195 typedef struct
196 {
197 hts_temp_meas_type_t temp_meas_type; /**< Stable or intermediary type of temperature. */
198 uint16_t temp_original_value; /**< Temperature measurement original value. */
199 ieee_float32_t temp_convert_value; /**< Temperature measurement convert value. */
200 hts_date_time_t time_stamp; /**< Time Stamp. */
201 hts_temp_meas_loc_t temp_type; /**< Temperature Type measurement location. */
202 } hts_meas_val_t;
203
204 /**@brief Health Thermometer Service init stucture. This contains all option and data needed for initialization of the service. */
205 typedef struct
206 {
207 hts_evt_handler_t evt_handler; /**< Health Thermometer Service event handler. */
208 uint16_t char_mask; /**< Initial mask of Supported characteristics, and configured with \ref HTS_CHAR_MASK */
209 hts_temp_unit_t temperature_units; /**< Initial if Temperature is in Fahrenheit unit, Celcius otherwise. */
210 bool time_stamp_present; /**< Initial if Time Stamp is present. */
211 hts_temp_meas_loc_t temp_type; /**< Initial temperature type measurement location. */
212 uint16_t meas_interval; /**< Initial temperature measurement interval. */
213 uint16_t min_meas_interval_sup; /**< Initial minimum temperature measurement interval support. */
214 uint16_t max_meas_interval_sup; /**< Initial maximum temperature measurement interval support. */
215 } hts_init_t;
216 /** @} */
217
218 /**
219 * @defgroup HTS_FUNCTION Functions
220 * @{
221 */
222 /**
223 *****************************************************************************************
224 * @brief Initialize a Health Thermometer Service instance and add in the DB.
225 *
226 * @param[in] p_hts_init: Pointer to Health Thermometer Service initialization variable
227 *
228 * @return Result of service initialization.
229 *****************************************************************************************
230 */
231 sdk_err_t hts_service_init(hts_init_t *p_hts_init);
232
233 /**
234 *****************************************************************************************
235 * @brief Send temperature measurement if indication or notification has been enabled.
236 *
237 * @param[in] conn_idx: Connnection index.
238 * @param[in] p_meas: The pointer to new health temperature measurement.
239 *
240 * @return Result of indicate value
241 *****************************************************************************************
242 */
243 sdk_err_t hts_measurement_send(uint8_t conn_idx, hts_meas_val_t *p_meas);
244
245 /**
246 *****************************************************************************************
247 * @brief Send temperature measurement interval if indication has been enabled.
248 *
249 * @param[in] conn_idx: Connnection index.
250 *
251 * @return Result of indicate value
252 *****************************************************************************************
253 */
254 sdk_err_t hts_measurement_interval_send(uint8_t conn_idx);
255 /** @} */
256
257 #endif
258 /** @} */
259 /** @} */
hts_service_init
sdk_err_t hts_service_init(hts_init_t *p_hts_init)
Initialize a Health Thermometer Service instance and add in the DB.
HTS_TEMPERATURE_FAHRENHEIT
@ HTS_TEMPERATURE_FAHRENHEIT
Indicate that temperature measurement Value Unit is fahrenheit.
Definition: hts.h:118
hts_evt_t
Health Thermometer Service event.
Definition: hts.h:164
HTS_EVT_READ_CHARACTERISTIC
@ HTS_EVT_READ_CHARACTERISTIC
The peer reads the characteristic.
Definition: hts.h:111
HTS_EVT_TEM_MEAS_INDICATION_ENABLE
@ HTS_EVT_TEM_MEAS_INDICATION_ENABLE
Indicate that temperature measurement indication has been enabled.
Definition: hts.h:104
HTS_EVT_INTM_TEM_NOTIFICATION_DISABLE
@ HTS_EVT_INTM_TEM_NOTIFICATION_DISABLE
Indicate that intermediate temperature notification has been disbled.
Definition: hts.h:107
hts_evt_t::p_data
const uint8_t * p_data
Pointer to the event data.
Definition: hts.h:167
HTS_MEAS_FLAG_TEM_UINTS_BIT
@ HTS_MEAS_FLAG_TEM_UINTS_BIT
Bit for temperature uints.
Definition: hts.h:131
hts_evt_t::evt_type
hts_evt_type_t evt_type
The HTS event type.
Definition: hts.h:165
hts_evt_t::length
uint16_t length
Length of the event data.
Definition: hts.h:168
hts_temp_unit_t
hts_temp_unit_t
Health Thermometer temperature unit,.
Definition: hts.h:116
ieee_float32_t::exponent
int8_t exponent
Base 10 exponent, only 8 bits.
Definition: hts.h:190
hts_meas_val_t::temp_original_value
uint16_t temp_original_value
Temperature measurement original value.
Definition: hts.h:198
HTS_TEMP_TYPE_MOUTH
@ HTS_TEMP_TYPE_MOUTH
Temperature measurement location: mouth.
Definition: hts.h:144
HTS_TEMP_TYPE_BODY
@ HTS_TEMP_TYPE_BODY
Temperature measurement location: body.
Definition: hts.h:140
HTS_READ_CHAR_TEMP_TYPE
@ HTS_READ_CHAR_TEMP_TYPE
The peer reads the Temperature Type characteristic.
Definition: hts.h:153
HTS_MEAS_FLAG_TEM_TYPE_BIT
@ HTS_MEAS_FLAG_TEM_TYPE_BIT
Bit for temperature type.
Definition: hts.h:133
hts_init_t::char_mask
uint16_t char_mask
Initial mask of Supported characteristics, and configured with Characteristics Mask.
Definition: hts.h:208
gr55xx_sys.h
GR55XX System API.
HTS_READ_CHAR_MEAS_INTL
@ HTS_READ_CHAR_MEAS_INTL
The peer reads the Measurement Interval characteristic.
Definition: hts.h:154
HTS_MEAS_FLAG_TIME_STAMP_BIT
@ HTS_MEAS_FLAG_TIME_STAMP_BIT
Bit for time stamp.
Definition: hts.h:132
hts_measurement_send
sdk_err_t hts_measurement_send(uint8_t conn_idx, hts_meas_val_t *p_meas)
Send temperature measurement if indication or notification has been enabled.
HTS_TEMP_TYPE_FINGER
@ HTS_TEMP_TYPE_FINGER
Temperature measurement location: finger.
Definition: hts.h:142
HTS_EVT_INVALID
@ HTS_EVT_INVALID
Indicate that invalid event.
Definition: hts.h:103
hts_init_t::temp_type
hts_temp_meas_loc_t temp_type
Initial temperature type measurement location.
Definition: hts.h:211
hts_date_time_t
prf_date_time_t hts_date_time_t
Health Thermometer Service date time type.
Definition: hts.h:180
hts_init_t::meas_interval
uint16_t meas_interval
Initial temperature measurement interval.
Definition: hts.h:212
hts_init_t::min_meas_interval_sup
uint16_t min_meas_interval_sup
Initial minimum temperature measurement interval support.
Definition: hts.h:213
HTS_TEMP_TYPE_RECTUM
@ HTS_TEMP_TYPE_RECTUM
Temperature measurement location: rectum.
Definition: hts.h:145
HTS_EVT_TEM_MEAS_INDICATION_DISABLE
@ HTS_EVT_TEM_MEAS_INDICATION_DISABLE
Indicate that temperature measurement indication has been disabled.
Definition: hts.h:105
HTS_TEMPERATURE_CELCIUS
@ HTS_TEMPERATURE_CELCIUS
Indicate that temperature measurement Value Unit is celcius.
Definition: hts.h:117
hts_meas_val_t::temp_convert_value
ieee_float32_t temp_convert_value
Temperature measurement convert value.
Definition: hts.h:199
hts_read_characteristic_t
hts_read_characteristic_t
The parameters for HTS_EVT_READ_CHARACTERISTIC.
Definition: hts.h:152
hts_meas_val_t::time_stamp
hts_date_time_t time_stamp
Time Stamp.
Definition: hts.h:200
HTS_EVT_MEAS_INTREVAL_INDICATION_ENABLE
@ HTS_EVT_MEAS_INTREVAL_INDICATION_ENABLE
Indicate that measurement interval indication has been enabled.
Definition: hts.h:108
hts_init_t
Health Thermometer Service init stucture.
Definition: hts.h:206
hts_evt_handler_t
void(* hts_evt_handler_t)(hts_evt_t *p_evt)
Health Thermometer Service event handler type.
Definition: hts.h:177
hts_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: hts.h:166
HTS_EVT_INTM_TEM_NOTIFICATION_ENABLE
@ HTS_EVT_INTM_TEM_NOTIFICATION_ENABLE
Indicate that intermediate temperature notification has been enabled.
Definition: hts.h:106
HTS_EVT_MEAS_INTERVAL_INDICATION_DISABLE
@ HTS_EVT_MEAS_INTERVAL_INDICATION_DISABLE
Indicate that measurement interval indication has been disabled.
Definition: hts.h:109
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
ieee_float32_t
SFLOAT format (IEEE-11073 32-bit FLOAT, defined as a 32-bit vlue with 24-bit mantissa and 8-bit expon...
Definition: hts.h:189
hts_init_t::time_stamp_present
bool time_stamp_present
Initial if Time Stamp is present.
Definition: hts.h:210
hts_init_t::evt_handler
hts_evt_handler_t evt_handler
Health Thermometer Service event handler.
Definition: hts.h:207
prf_date_time_t
The date and time structure.
Definition: ble_prf_types.h:101
HTS_TEMPERATURE_INTERMEDIATE
@ HTS_TEMPERATURE_INTERMEDIATE
Intermediary type of temperature.
Definition: hts.h:125
HTS_TEMP_TYPE_ARMPIT
@ HTS_TEMP_TYPE_ARMPIT
Temperature measurement location: armpit.
Definition: hts.h:139
HTS_TEMP_TYPE_EAR
@ HTS_TEMP_TYPE_EAR
Temperature measurement location: ear.
Definition: hts.h:141
HTS_EVT_MEAS_INTERVAL_UPDATE
@ HTS_EVT_MEAS_INTERVAL_UPDATE
Indicate that measurement interval has been updated.
Definition: hts.h:110
hts_evt_type_t
hts_evt_type_t
Health Thermometer Service event type.
Definition: hts.h:102
hts_flag_bit_t
hts_flag_bit_t
Health Thermometer Measurement flag bits.
Definition: hts.h:130
hts_init_t::max_meas_interval_sup
uint16_t max_meas_interval_sup
Initial maximum temperature measurement interval support.
Definition: hts.h:214
hts_meas_val_t::temp_type
hts_temp_meas_loc_t temp_type
Temperature Type measurement location.
Definition: hts.h:201
HTS_TEMP_TYPE_TOE
@ HTS_TEMP_TYPE_TOE
Temperature measurement location: toe.
Definition: hts.h:146
hts_meas_val_t
Health Theromometer Measurement Character value structure.
Definition: hts.h:196
ble_prf_utils.h
Profile/Service Utilities API.
hts_init_t::temperature_units
hts_temp_unit_t temperature_units
Initial if Temperature is in Fahrenheit unit, Celcius otherwise.
Definition: hts.h:209
hts_measurement_interval_send
sdk_err_t hts_measurement_interval_send(uint8_t conn_idx)
Send temperature measurement interval if indication has been enabled.
HTS_TEMP_TYPE_GI_TRACT
@ HTS_TEMP_TYPE_GI_TRACT
Temperature measurement location: Gi tract.
Definition: hts.h:143
HTS_TEMP_TYPE_EAR_DRUM
@ HTS_TEMP_TYPE_EAR_DRUM
Temperature measurement location: ear drum.
Definition: hts.h:147
ieee_float32_t::mantissa
int32_t mantissa
Mantissa, only 24 bits.
Definition: hts.h:191
hts_temp_meas_type_t
hts_temp_meas_type_t
Health Thermometer temperature measurement type.
Definition: hts.h:123
HTS_TEMPERATURE_STABLE
@ HTS_TEMPERATURE_STABLE
Stable type of temperature.
Definition: hts.h:124
hts_meas_val_t::temp_meas_type
hts_temp_meas_type_t temp_meas_type
Stable or intermediary type of temperature.
Definition: hts.h:197
hts_temp_meas_loc_t
hts_temp_meas_loc_t
Temperature Type measurement locations.
Definition: hts.h:138