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