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. */
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. */
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. */
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. */
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. */
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. */
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.*/
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 */
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. */
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  */
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  */
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
Definition: hts.h:117
hts_evt_t
Health Thermometer Service event.
Definition: hts.h:163
HTS_EVT_READ_CHARACTERISTIC
@ HTS_EVT_READ_CHARACTERISTIC
Definition: hts.h:110
HTS_EVT_TEM_MEAS_INDICATION_ENABLE
@ HTS_EVT_TEM_MEAS_INDICATION_ENABLE
Definition: hts.h:103
HTS_EVT_INTM_TEM_NOTIFICATION_DISABLE
@ HTS_EVT_INTM_TEM_NOTIFICATION_DISABLE
Definition: hts.h:106
hts_evt_t::p_data
const uint8_t * p_data
Definition: hts.h:166
HTS_MEAS_FLAG_TEM_UINTS_BIT
@ HTS_MEAS_FLAG_TEM_UINTS_BIT
Definition: hts.h:130
hts_evt_t::evt_type
hts_evt_type_t evt_type
Definition: hts.h:164
hts_evt_t::length
uint16_t length
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
Definition: hts.h:189
hts_meas_val_t::temp_original_value
uint16_t temp_original_value
Definition: hts.h:197
HTS_TEMP_TYPE_MOUTH
@ HTS_TEMP_TYPE_MOUTH
Definition: hts.h:143
HTS_TEMP_TYPE_BODY
@ HTS_TEMP_TYPE_BODY
Definition: hts.h:139
HTS_READ_CHAR_TEMP_TYPE
@ HTS_READ_CHAR_TEMP_TYPE
Definition: hts.h:152
HTS_MEAS_FLAG_TEM_TYPE_BIT
@ HTS_MEAS_FLAG_TEM_TYPE_BIT
Definition: hts.h:132
gr_includes.h
Include Files API.
hts_init_t::char_mask
uint16_t char_mask
Definition: hts.h:207
HTS_READ_CHAR_MEAS_INTL
@ HTS_READ_CHAR_MEAS_INTL
Definition: hts.h:153
HTS_MEAS_FLAG_TIME_STAMP_BIT
@ HTS_MEAS_FLAG_TIME_STAMP_BIT
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
Definition: hts.h:141
HTS_EVT_INVALID
@ HTS_EVT_INVALID
Definition: hts.h:102
hts_init_t::temp_type
hts_temp_meas_loc_t temp_type
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
Definition: hts.h:211
hts_init_t::min_meas_interval_sup
uint16_t min_meas_interval_sup
Definition: hts.h:212
HTS_TEMP_TYPE_RECTUM
@ HTS_TEMP_TYPE_RECTUM
Definition: hts.h:144
HTS_EVT_TEM_MEAS_INDICATION_DISABLE
@ HTS_EVT_TEM_MEAS_INDICATION_DISABLE
Definition: hts.h:104
HTS_TEMPERATURE_CELCIUS
@ HTS_TEMPERATURE_CELCIUS
Definition: hts.h:116
hts_meas_val_t::temp_convert_value
ieee_float32_t temp_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
Definition: hts.h:199
HTS_EVT_MEAS_INTREVAL_INDICATION_ENABLE
@ HTS_EVT_MEAS_INTREVAL_INDICATION_ENABLE
Definition: hts.h:107
hts_init_t
Health Thermometer Service init stucture. This contains all option and data needed for initialization...
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
Definition: hts.h:165
HTS_EVT_INTM_TEM_NOTIFICATION_ENABLE
@ HTS_EVT_INTM_TEM_NOTIFICATION_ENABLE
Definition: hts.h:105
HTS_EVT_MEAS_INTERVAL_INDICATION_DISABLE
@ HTS_EVT_MEAS_INTERVAL_INDICATION_DISABLE
Definition: hts.h:108
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
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
Definition: hts.h:209
hts_init_t::evt_handler
hts_evt_handler_t evt_handler
Definition: hts.h:206
prf_date_time_t
The date and time structure. The packed size is 7 bytes.
Definition: ble_prf_types.h:101
HTS_TEMPERATURE_INTERMEDIATE
@ HTS_TEMPERATURE_INTERMEDIATE
Definition: hts.h:124
HTS_TEMP_TYPE_ARMPIT
@ HTS_TEMP_TYPE_ARMPIT
Definition: hts.h:138
HTS_TEMP_TYPE_EAR
@ HTS_TEMP_TYPE_EAR
Definition: hts.h:140
HTS_EVT_MEAS_INTERVAL_UPDATE
@ HTS_EVT_MEAS_INTERVAL_UPDATE
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
Definition: hts.h:213
hts_meas_val_t::temp_type
hts_temp_meas_loc_t temp_type
Definition: hts.h:200
HTS_TEMP_TYPE_TOE
@ HTS_TEMP_TYPE_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
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
Definition: hts.h:142
HTS_TEMP_TYPE_EAR_DRUM
@ HTS_TEMP_TYPE_EAR_DRUM
Definition: hts.h:146
ieee_float32_t::mantissa
int32_t mantissa
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
Definition: hts.h:123
hts_meas_val_t::temp_meas_type
hts_temp_meas_type_t temp_meas_type
Definition: hts.h:196
hts_temp_meas_loc_t
hts_temp_meas_loc_t
Temperature Type measurement locations.
Definition: hts.h:137