wss.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file wss.h
5  *
6  * @brief Weight Scale 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_WSS Weight Scale Service (WSS)
46  * @{
47  * @brief Weight Scale Service module.
48  *
49  * @details The Weight Scale (WS) Service exposes weight and related data from a weight scale
50  * (Server) intended for consumer healthcare as well as sports/fitness applications.
51  *
52  * After \ref wss_init_t variable is intialized, the application must call \ref wss_service_init()
53  * to add Weight Scale Feature and Weight Measurement characteristics to the BLE Stack database
54  * according to \ref wss_init_t.char_mask.
55  */
56 
57 #ifndef __WSS_H__
58 #define __WSS_H__
59 
60 #include "gr55xx_sys.h"
61 #include "custom_config.h"
62 #include "ble_prf_utils.h"
63 #include <stdint.h>
64 #include <stdbool.h>
65 
66 /**
67  * @defgroup WSS_MACRO Defines
68  * @{
69  */
70 #define WSS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
71  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Weight Scale Service connections. */
72 #define WSS_MEAS_VAL_LEN_MAX 15 /**< Maximum length of Weight Measurment value. */
73 #define WSS_CACHE_MEAS_NUM_MAX 25 /**< Maximum number of cache muasurements value for each user. */
74 #define WSS_FEAT_VAL_LEN_MAX 1 /**< Maximum length of WS Feature value. */
75 #define WSS_MEAS_UNSUCCESS 0xFFFF /**< Measurement Unsuccessful. */
76 /**
77  * @defgroup WSS_CHAR_MASK Characteristics Mask
78  * @{
79  * @brief Bit masks for the initialization of \ref wss_init_t.char_mask.
80  */
81 #define WSS_CHAR_FEAT_MANDATORY 0x3F /**< Bit mask for mandatory characteristic in WSS. */
82 /** @} */
83 /** @} */
84 
85 /**
86  * @defgroup WSS_MEAS_FLAG_BIT Measurement Flag Bits
87  * @{
88  * @brief Weight Scale Measurement Flags.
89  */
91 {
92  WSS_MEAS_FLAG_UNIT_SI = 0x00, /**< Flag bit for SI Measurement Units Present. */
93  WSS_MEAS_FLAG_UNIT_IMPERIAL = 0x01, /**< Flag bit for Imperial Measurement Units Present. */
94  WSS_MEAS_FLAG_DATE_TIME_PRESENT = 0x02, /**< Flag bit for Time Stamp Present. */
95  WSS_MEAS_FLAG_USER_ID_PRESENT = 0x04, /**< Flag bit for User ID Present. */
96  WSS_MEAS_FLAG_BMI_HEIGHT_PRESENT = 0x08, /**< Flag bit for BMI and Height Present. */
97 };
98 /** @} */
99 
100 /**
101  * @defgroup WSS_ENUM Enumerations
102  * @{
103  */
104 /**@brief Weight Scale Feature characteristic bit values.*/
105 typedef enum
106 {
107  /* Supported Flags */
108  WSS_FEAT_TIME_STAMP = 0x00000001, /**< Time Stamp supported. */
109  WSS_FEAT_MULTI_USER = 0x00000002, /**< Multiple Users supported. */
110  WSS_FEAT_BMI = 0x00000004, /**< BMI supported. */
111 
112  /* Weight Measurement Resolution */
113  WSS_FEAT_MASS_RES_500G = 0x00000008, /**< Resolution of 0.5kg or 1lb. */
114  WSS_FEAT_MASS_RES_200G = 0x00000010, /**< Resolution of 0.2kg or 0.5lb. */
115  WSS_FEAT_MASS_RES_100G = 0x00000018, /**< Resolution of 0.1kg or 0.2lb. */
116  WSS_FEAT_MASS_RES_50G = 0x00000020, /**< Resolution of 0.05kg or 0.1lb. */
117  WSS_FEAT_MASS_RES_20G = 0x00000028, /**< Resolution of 0.02kg or 0.05lb. */
118  WSS_FEAT_MASS_RES_10G = 0x00000030, /**< Resolution of 0.01kg or 0.02lb. */
119  WSS_FEAT_MASS_RES_5G = 0x00000038, /**< Resolution of 0.005kg or 0.01lb. */
120 
121  /* Height Measurement Resolution */
122  WSS_FEAT_HEIGHT_RES_10MM = 0x00000080, /**< Resolution of 0.01m or 1in. */
123  WSS_FEAT_HEIGHT_RES_5MM = 0x00000100, /**< Resolution of 0.005m or 0.5in. */
124  WSS_FEAT_HEIGHT_RES_1MM = 0x00000180, /**< Resolution of 0.001m or 0.1in. */
125 
126  WSS_FEAT_FULL_BIT = 0x000001BF,
127 } wss_feature_t;
128 
129 /**@brief WSS Weight Measurement resolutions. */
130 typedef enum
131 {
132  WSS_MASS_RES_500G, /**< Resolution of 0.5kg or 1lb. */
133  WSS_MASS_RES_200G, /**< Resolution of 0.2kg or 0.5lb. */
134  WSS_MASS_RES_100G, /**< Resolution of 0.1kg or 0.2lb. */
135  WSS_MASS_RES_50G, /**< Resolution of 0.05kg or 0.1lb. */
136  WSS_MASS_RES_20G, /**< Resolution of 0.02kg or 0.05lb. */
137  WSS_MASS_RES_10G, /**< Resolution of 0.01kg or 0.02lb. */
138  WSS_MASS_RES_5G, /**< Resolution of 0.005kg or 0.01lb. */
140 
141 /**@brief WSS Height Measurement resolutions. */
142 typedef enum
143 {
144  WSS_HEIGHT_RES_10MM, /**< Resolution of 0.01m or 1in. */
145  WSS_HEIGHT_RES_5MM, /**< Resolution of 0.005m or 0.5in. */
146  WSS_HEIGHT_RES_1MM, /**< Resolution of 0.001m or 0.1in. */
148 
149 /**@brief WSS unit types. */
150 typedef enum
151 {
152  WSS_UNIT_SI, /**< Weight in kilograms and height in meters */
153  WSS_UNIT_IMPERIAL, /**< Weight in pounds and height in inches */
154 } wss_unit_t;
155 
156  /**@brief Weight Scale Service event type. */
157 typedef enum
158 {
159  WSS_EVT_INVALID, /**< Indicate that invalid event. */
160  WSS_EVT_MEAS_INDICATION_ENABLE, /**< Indicate that body composition measurement indication has been enabled. */
161  WSS_EVT_MEAS_INDICATION_DISABLE, /**< Indicate that body composition measurement indication has been disabled. */
162  WSS_EVT_MEAS_INDICATION_CPLT, /**< Indicate that BC Measurement has been indicated. */
163  WSS_EVT_MEAS_READ_CHARACTERISTIC, /**< The peer reads the characteristic. */
164 } wss_evt_type_t;
165 /** @} */
166 
167 /**
168  * @defgroup WSS_STRUCT Structures
169  * @{
170  */
171 /**@brief Weight Scale Measurement data. */
172 typedef struct
173 {
174  uint16_t weight; /**< Weight. */
175  prf_date_time_t time_stamp; /**< Time stamp. */
176  uint8_t user_id; /**< User index. */
177  uint16_t bmi; /**< Bmi. */
178  uint16_t height; /**< Height. */
180 
181 /**@brief Weight Scale Service event. */
182 typedef struct
183 {
184  wss_evt_type_t evt_type; /**< The WSS event type. */
185  uint8_t conn_idx; /**< The index of the connection. */
186  const uint8_t *p_data; /**< Pointer to event data. */
187  uint16_t length; /**< Length of event data. */
188 } wss_evt_t;
189 /** @} */
190 
191 /**
192  * @defgroup WSS_TYPEDEF Typedefs
193  * @{
194  */
195 /**@brief Weight Scale Service event handler type. */
196 typedef void (*wss_evt_handler_t)(wss_evt_t *p_evt);
197 /** @} */
198 
199 /**
200  * @defgroup WSS_STRUCT Structures
201  * @{
202  */
203 /**@brief Weight Scale Service Init variable. */
204 typedef struct
205 {
206  wss_evt_handler_t evt_handler; /**< Weight Scale Service event handler. */
207  uint32_t feature; /**< Initial value for features. */
208  uint8_t char_mask; /**< Initial mask of Supported characteristics, and configured with \ref WSS_CHAR_MASK */
209  wss_unit_t wss_unit; /**< Initial the unit system as SI or Imperial. */
210  wss_mass_res_t wss_mass_res; /**< Initial resolution of mass value. */
211  wss_height_res_t wss_height_res; /**< Initial resolution of height value. */
212  bool multi_user_present; /**< Flag which indicates if multiple user is present. */
213  bool time_stamp_present; /**< Flag which indicates if time stamp is present. */
214  bool bmi_present; /**< Flag which indicates if bmi is present. */
215 } wss_init_t;
216 /** @} */
217 
218 /**
219  * @defgroup WSS_FUNCTION Functions
220  * @{
221  */
222 /**
223  *****************************************************************************************
224  * @brief Initialize a Weight Scale Service instance and add in the DB.
225  *
226  * @param[in] p_wss_init: Pointer to WSS Service initialization variable.
227  *
228  * @return Result of service initialization.
229  *****************************************************************************************
230  */
232 
233 /**
234  *****************************************************************************************
235  * @brief Send Weight Scale Measurement indication..
236  *
237  * @param[in] conn_idx: Connection index.
238  * @param[in] p_meas: Pointer to weight scale measurement data.
239  * @param[in] cache_num: The number of measurement caches.
240  *
241  * @return Result of indicate value.
242  *****************************************************************************************
243  */
244 sdk_err_t wss_measurement_send(uint8_t conn_idx, wss_meas_val_t *p_meas, uint8_t cache_num);
245 
246 /** @} */
247 
248 #endif
249 /** @} */
250 /** @} */
251 
wss_feature_t
wss_feature_t
Weight Scale Feature characteristic bit values.
Definition: wss.h:106
WSS_FEAT_HEIGHT_RES_1MM
@ WSS_FEAT_HEIGHT_RES_1MM
Resolution of 0.001m or 0.1in.
Definition: wss.h:124
WSS_UNIT_IMPERIAL
@ WSS_UNIT_IMPERIAL
Weight in pounds and height in inches.
Definition: wss.h:153
wss_meas_val_t::bmi
uint16_t bmi
Bmi.
Definition: wss.h:177
wss_init_t::multi_user_present
bool multi_user_present
Flag which indicates if multiple user is present.
Definition: wss.h:212
wss_meas_flag_bits
wss_meas_flag_bits
Definition: wss.h:91
WSS_MEAS_FLAG_UNIT_IMPERIAL
@ WSS_MEAS_FLAG_UNIT_IMPERIAL
Flag bit for Imperial Measurement Units Present.
Definition: wss.h:93
wss_evt_t::length
uint16_t length
Length of event data.
Definition: wss.h:187
wss_init_t
Weight Scale Service Init variable.
Definition: wss.h:205
wss_unit_t
wss_unit_t
WSS unit types.
Definition: wss.h:151
wss_evt_t
Weight Scale Service event.
Definition: wss.h:183
wss_evt_type_t
wss_evt_type_t
Weight Scale Service event type.
Definition: wss.h:158
WSS_MEAS_FLAG_USER_ID_PRESENT
@ WSS_MEAS_FLAG_USER_ID_PRESENT
Flag bit for User ID Present.
Definition: wss.h:95
WSS_MASS_RES_10G
@ WSS_MASS_RES_10G
Resolution of 0.01kg or 0.02lb.
Definition: wss.h:137
wss_meas_val_t::height
uint16_t height
Height.
Definition: wss.h:178
WSS_FEAT_MASS_RES_5G
@ WSS_FEAT_MASS_RES_5G
Resolution of 0.005kg or 0.01lb.
Definition: wss.h:119
wss_init_t::wss_height_res
wss_height_res_t wss_height_res
Initial resolution of height value.
Definition: wss.h:211
WSS_FEAT_MASS_RES_20G
@ WSS_FEAT_MASS_RES_20G
Resolution of 0.02kg or 0.05lb.
Definition: wss.h:117
gr55xx_sys.h
GR55XX System API.
WSS_MEAS_FLAG_UNIT_SI
@ WSS_MEAS_FLAG_UNIT_SI
Flag bit for SI Measurement Units Present.
Definition: wss.h:92
wss_init_t::wss_mass_res
wss_mass_res_t wss_mass_res
Initial resolution of mass value.
Definition: wss.h:210
wss_init_t::wss_unit
wss_unit_t wss_unit
Initial the unit system as SI or Imperial.
Definition: wss.h:209
wss_meas_val_t::user_id
uint8_t user_id
User index.
Definition: wss.h:176
wss_meas_val_t::time_stamp
prf_date_time_t time_stamp
Time stamp.
Definition: wss.h:175
WSS_FEAT_BMI
@ WSS_FEAT_BMI
BMI supported.
Definition: wss.h:110
WSS_EVT_MEAS_INDICATION_ENABLE
@ WSS_EVT_MEAS_INDICATION_ENABLE
Indicate that body composition measurement indication has been enabled.
Definition: wss.h:160
WSS_MASS_RES_5G
@ WSS_MASS_RES_5G
Resolution of 0.005kg or 0.01lb.
Definition: wss.h:138
WSS_HEIGHT_RES_10MM
@ WSS_HEIGHT_RES_10MM
Resolution of 0.01m or 1in.
Definition: wss.h:144
wss_service_init
sdk_err_t wss_service_init(wss_init_t *p_wss_init)
Initialize a Weight Scale Service instance and add in the DB.
WSS_EVT_MEAS_READ_CHARACTERISTIC
@ WSS_EVT_MEAS_READ_CHARACTERISTIC
The peer reads the characteristic.
Definition: wss.h:163
WSS_MASS_RES_200G
@ WSS_MASS_RES_200G
Resolution of 0.2kg or 0.5lb.
Definition: wss.h:133
wss_evt_t::p_data
const uint8_t * p_data
Pointer to event data.
Definition: wss.h:186
WSS_FEAT_MASS_RES_200G
@ WSS_FEAT_MASS_RES_200G
Resolution of 0.2kg or 0.5lb.
Definition: wss.h:114
WSS_EVT_MEAS_INDICATION_CPLT
@ WSS_EVT_MEAS_INDICATION_CPLT
Indicate that BC Measurement has been indicated.
Definition: wss.h:162
WSS_HEIGHT_RES_1MM
@ WSS_HEIGHT_RES_1MM
Resolution of 0.001m or 0.1in.
Definition: wss.h:146
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
WSS_FEAT_MASS_RES_50G
@ WSS_FEAT_MASS_RES_50G
Resolution of 0.05kg or 0.1lb.
Definition: wss.h:116
wss_init_t::char_mask
uint8_t char_mask
Initial mask of Supported characteristics, and configured with Characteristics Mask.
Definition: wss.h:208
prf_date_time_t
The date and time structure.
Definition: ble_prf_types.h:101
wss_measurement_send
sdk_err_t wss_measurement_send(uint8_t conn_idx, wss_meas_val_t *p_meas, uint8_t cache_num)
Send Weight Scale Measurement indication.
WSS_EVT_MEAS_INDICATION_DISABLE
@ WSS_EVT_MEAS_INDICATION_DISABLE
Indicate that body composition measurement indication has been disabled.
Definition: wss.h:161
WSS_FEAT_MASS_RES_10G
@ WSS_FEAT_MASS_RES_10G
Resolution of 0.01kg or 0.02lb.
Definition: wss.h:118
WSS_MEAS_FLAG_DATE_TIME_PRESENT
@ WSS_MEAS_FLAG_DATE_TIME_PRESENT
Flag bit for Time Stamp Present.
Definition: wss.h:94
WSS_HEIGHT_RES_5MM
@ WSS_HEIGHT_RES_5MM
Resolution of 0.005m or 0.5in.
Definition: wss.h:145
wss_init_t::feature
uint32_t feature
Initial value for features.
Definition: wss.h:207
wss_height_res_t
wss_height_res_t
WSS Height Measurement resolutions.
Definition: wss.h:143
WSS_EVT_INVALID
@ WSS_EVT_INVALID
Indicate that invalid event.
Definition: wss.h:159
WSS_FEAT_MASS_RES_100G
@ WSS_FEAT_MASS_RES_100G
Resolution of 0.1kg or 0.2lb.
Definition: wss.h:115
WSS_MASS_RES_500G
@ WSS_MASS_RES_500G
Resolution of 0.5kg or 1lb.
Definition: wss.h:132
WSS_FEAT_HEIGHT_RES_10MM
@ WSS_FEAT_HEIGHT_RES_10MM
Resolution of 0.01m or 1in.
Definition: wss.h:122
WSS_FEAT_HEIGHT_RES_5MM
@ WSS_FEAT_HEIGHT_RES_5MM
Resolution of 0.005m or 0.5in.
Definition: wss.h:123
wss_init_t::time_stamp_present
bool time_stamp_present
Flag which indicates if time stamp is present.
Definition: wss.h:213
WSS_MASS_RES_100G
@ WSS_MASS_RES_100G
Resolution of 0.1kg or 0.2lb.
Definition: wss.h:134
WSS_FEAT_MASS_RES_500G
@ WSS_FEAT_MASS_RES_500G
Resolution of 0.5kg or 1lb.
Definition: wss.h:113
ble_prf_utils.h
Profile/Service Utilities API.
wss_evt_t::evt_type
wss_evt_type_t evt_type
The WSS event type.
Definition: wss.h:184
WSS_MASS_RES_20G
@ WSS_MASS_RES_20G
Resolution of 0.02kg or 0.05lb.
Definition: wss.h:136
wss_init_t::bmi_present
bool bmi_present
Flag which indicates if bmi is present.
Definition: wss.h:214
wss_meas_val_t::weight
uint16_t weight
Weight.
Definition: wss.h:174
WSS_MASS_RES_50G
@ WSS_MASS_RES_50G
Resolution of 0.05kg or 0.1lb.
Definition: wss.h:135
wss_init_t::evt_handler
wss_evt_handler_t evt_handler
Weight Scale Service event handler.
Definition: wss.h:206
wss_meas_val_t
Weight Scale Measurement data.
Definition: wss.h:173
WSS_MEAS_FLAG_BMI_HEIGHT_PRESENT
@ WSS_MEAS_FLAG_BMI_HEIGHT_PRESENT
Flag bit for BMI and Height Present.
Definition: wss.h:96
wss_mass_res_t
wss_mass_res_t
WSS Weight Measurement resolutions.
Definition: wss.h:131
wss_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: wss.h:185
WSS_FEAT_TIME_STAMP
@ WSS_FEAT_TIME_STAMP
Time Stamp supported.
Definition: wss.h:108
WSS_UNIT_SI
@ WSS_UNIT_SI
Weight in kilograms and height in meters.
Definition: wss.h:152
wss_evt_handler_t
void(* wss_evt_handler_t)(wss_evt_t *p_evt)
Weight Scale Service event handler type.
Definition: wss.h:196
WSS_FEAT_MULTI_USER
@ WSS_FEAT_MULTI_USER
Multiple Users supported.
Definition: wss.h:109