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. */
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. */
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. */
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. */
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. */
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. */
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.*/
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 */
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. */
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  */
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  */
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