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 <stdint.h> 65 #include <stdbool.h> 66 #include "gr55xx_sys.h" 67 #include "custom_config.h" 68 #include "ble_prf_utils.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 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 HTS_TEMPERATURE_CELCIUS, /**< Indicate that temperature measurement Value Unit is celcius. */ 116 HTS_TEMPERATURE_FAHRENHEIT, /**< Indicate that temperature measurement Value Unit is fahrenheit. */ 117 } hts_temp_unit_t; 118 119 /**@brief Health Thermometer temperature measurement type. */ 120 typedef enum { 121 HTS_TEMPERATURE_STABLE, /**< Stable type of temperature. */ 122 HTS_TEMPERATURE_INTERMEDIATE, /**< Intermediary type of temperature. */ 123 } hts_temp_meas_type_t; 124 125 /**@brief Health Thermometer Measurement flag bits. */ 126 typedef enum { 127 HTS_MEAS_FLAG_TEM_UINTS_BIT = (0x01<<0), /**< Bit for temperature uints. */ 128 HTS_MEAS_FLAG_TIME_STAMP_BIT = (0x01<<1), /**< Bit for time stamp. */ 129 HTS_MEAS_FLAG_TEM_TYPE_BIT = (0x01<<2), /**< Bit for temperature type. */ 130 } hts_flag_bit_t; 131 132 /**@brief Temperature Type measurement locations. */ 133 typedef enum { 134 HTS_TEMP_TYPE_ARMPIT = 0x01, /**< Temperature measurement location: armpit. */ 135 HTS_TEMP_TYPE_BODY, /**< Temperature measurement location: body. */ 136 HTS_TEMP_TYPE_EAR, /**< Temperature measurement location: ear. */ 137 HTS_TEMP_TYPE_FINGER, /**< Temperature measurement location: finger. */ 138 HTS_TEMP_TYPE_GI_TRACT, /**< Temperature measurement location: Gi tract. */ 139 HTS_TEMP_TYPE_MOUTH, /**< Temperature measurement location: mouth. */ 140 HTS_TEMP_TYPE_RECTUM, /**< Temperature measurement location: rectum. */ 141 HTS_TEMP_TYPE_TOE, /**< Temperature measurement location: toe. */ 142 HTS_TEMP_TYPE_EAR_DRUM, /**< Temperature measurement location: ear drum. */ 143 } hts_temp_meas_loc_t; 144 145 /**@brief The parameters for \ref HTS_EVT_READ_CHARACTERISTIC. */ 146 typedef enum { 147 HTS_READ_CHAR_TEMP_TYPE, /**< The peer reads the Temperature Type characteristic. */ 148 HTS_READ_CHAR_MEAS_INTL, /**< The peer reads the Measurement Interval characteristic. */ 149 } hts_read_characteristic_t; 150 /** @} */ 151 152 /** 153 * @defgroup HTS_STRUCT Structures 154 * @{ 155 */ 156 /**@brief Health Thermometer Service event. */ 157 typedef struct { 158 hts_evt_type_t evt_type; /**< The HTS event type. */ 159 uint8_t conn_idx; /**< The index of the connection. */ 160 const uint8_t *p_data; /**< Pointer to the event data. */ 161 uint16_t length; /**< Length of the event data. */ 162 } hts_evt_t; 163 /** @} */ 164 165 /** 166 * @defgroup HTS_TYPEDEF Typedefs 167 * @{ 168 */ 169 /**@brief Health Thermometer Service event handler type.*/ 170 typedef void (*hts_evt_handler_t)(hts_evt_t *p_evt); 171 172 /**@brief Health Thermometer Service date time type.*/ 173 typedef prf_date_time_t hts_date_time_t; 174 /** @} */ 175 176 /** 177 * @defgroup HTS_STRUCT Structures 178 * @{ 179 */ 180 /**@brief SFLOAT format (IEEE-11073 32-bit FLOAT, defined as a 32-bit vlue with 24-bit mantissa and 8-bit exponent. */ 181 typedef struct { 182 int8_t exponent; /**< Base 10 exponent, only 8 bits */ 183 int32_t mantissa; /**< Mantissa, only 24 bits */ 184 } ieee_float32_t; 185 186 /**@brief Health Theromometer Measurement Character value structure. */ 187 typedef struct { 188 hts_temp_meas_type_t temp_meas_type; /**< Stable or intermediary type of temperature. */ 189 uint16_t temp_original_value; /**< Temperature measurement original value. */ 190 ieee_float32_t temp_convert_value; /**< Temperature measurement convert value. */ 191 hts_date_time_t time_stamp; /**< Time Stamp. */ 192 hts_temp_meas_loc_t temp_type; /**< Temperature Type measurement location. */ 193 } hts_meas_val_t; 194 195 /**@brief Health Thermometer Service init stucture. 196 * This contains all option and data needed for initialization of the service. */ 197 typedef struct { 198 hts_evt_handler_t evt_handler; /**< Health Thermometer Service event handler. */ 199 uint16_t 200 char_mask; /**< Initial mask of Supported characteristics, and configured with \ref HTS_CHAR_MASK */ 201 hts_temp_unit_t temperature_units; /**< Initial if Temperature is in Fahrenheit unit, Celcius otherwise. */ 202 bool time_stamp_present; /**< Initial if Time Stamp is present. */ 203 hts_temp_meas_loc_t temp_type; /**< Initial temperature type measurement location. */ 204 uint16_t meas_interval; /**< Initial temperature measurement interval. */ 205 uint16_t min_meas_interval_sup; /**< Initial minimum temperature measurement interval support. */ 206 uint16_t max_meas_interval_sup; /**< Initial maximum temperature measurement interval support. */ 207 } hts_init_t; 208 /** @} */ 209 210 /** 211 * @defgroup HTS_FUNCTION Functions 212 * @{ 213 */ 214 /** 215 ***************************************************************************************** 216 * @brief Initialize a Health Thermometer Service instance and add in the DB. 217 * 218 * @param[in] p_hts_init: Pointer to Health Thermometer Service initialization variable 219 * 220 * @return Result of service initialization. 221 ***************************************************************************************** 222 */ 223 sdk_err_t hts_service_init(hts_init_t *p_hts_init); 224 225 /** 226 ***************************************************************************************** 227 * @brief Send temperature measurement if indication or notification has been enabled. 228 * 229 * @param[in] conn_idx: Connnection index. 230 * @param[in] p_meas: The pointer to new health temperature measurement. 231 * 232 * @return Result of indicate value 233 ***************************************************************************************** 234 */ 235 sdk_err_t hts_measurement_send(uint8_t conn_idx, hts_meas_val_t *p_meas); 236 237 /** 238 ***************************************************************************************** 239 * @brief Send temperature measurement interval if indication has been enabled. 240 * 241 * @param[in] conn_idx: Connnection index. 242 * 243 * @return Result of indicate value 244 ***************************************************************************************** 245 */ 246 sdk_err_t hts_measurement_interval_send(uint8_t conn_idx); 247 /** @} */ 248 249 #endif 250 /** @} */ 251 /** @} */ 252