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 0x7F /**< Bit mask for mandatory characteristic in WSS. */
82 /** @} */
83 /** @} */
84 
85 /**
86  * @defgroup WSS_ENUM Enumerations
87  * @{
88  */
89 /**@brief Weight Scale Measurement Flags.*/
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 /**@brief Weight Scale Feature characteristic bit values.*/
100 typedef enum
101 {
102  /* Supported Flags */
103  WSS_FEAT_TIME_STAMP = 0x00000001, /**< Time Stamp supported. */
104  WSS_FEAT_MULTI_USER = 0x00000002, /**< Multiple Users supported. */
105  WSS_FEAT_BMI = 0x00000004, /**< BMI supported. */
106 
107  /* Weight Measurement Resolution */
108  WSS_FEAT_MASS_RES_500G = 0x00000008, /**< Resolution of 0.5kg or 1lb. */
109  WSS_FEAT_MASS_RES_200G = 0x00000010, /**< Resolution of 0.2kg or 0.5lb. */
110  WSS_FEAT_MASS_RES_100G = 0x00000018, /**< Resolution of 0.1kg or 0.2lb. */
111  WSS_FEAT_MASS_RES_50G = 0x00000020, /**< Resolution of 0.05kg or 0.1lb. */
112  WSS_FEAT_MASS_RES_20G = 0x00000028, /**< Resolution of 0.02kg or 0.05lb. */
113  WSS_FEAT_MASS_RES_10G = 0x00000030, /**< Resolution of 0.01kg or 0.02lb. */
114  WSS_FEAT_MASS_RES_5G = 0x00000038, /**< Resolution of 0.005kg or 0.01lb. */
115 
116  /* Height Measurement Resolution */
117  WSS_FEAT_HEIGHT_RES_10MM = 0x00000080, /**< Resolution of 0.01m or 1in. */
118  WSS_FEAT_HEIGHT_RES_5MM = 0x00000100, /**< Resolution of 0.005m or 0.5in. */
119  WSS_FEAT_HEIGHT_RES_1MM = 0x00000180, /**< Resolution of 0.001m or 0.1in. */
120 
121  WSS_FEAT_FULL_BIT = 0x000001BF,
122 } wss_feature_t;
123 
124 /**@brief WSS Weight Measurement resolutions. */
125 typedef enum
126 {
127  WSS_MASS_RES_500G, /**< Resolution of 0.5kg or 1lb. */
128  WSS_MASS_RES_200G, /**< Resolution of 0.2kg or 0.5lb. */
129  WSS_MASS_RES_100G, /**< Resolution of 0.1kg or 0.2lb. */
130  WSS_MASS_RES_50G, /**< Resolution of 0.05kg or 0.1lb. */
131  WSS_MASS_RES_20G, /**< Resolution of 0.02kg or 0.05lb. */
132  WSS_MASS_RES_10G, /**< Resolution of 0.01kg or 0.02lb. */
133  WSS_MASS_RES_5G, /**< Resolution of 0.005kg or 0.01lb. */
135 
136 /**@brief WSS Height Measurement resolutions. */
137 typedef enum
138 {
139  WSS_HEIGHT_RES_10MM, /**< Resolution of 0.01m or 1in. */
140  WSS_HEIGHT_RES_5MM, /**< Resolution of 0.005m or 0.5in. */
141  WSS_HEIGHT_RES_1MM, /**< Resolution of 0.001m or 0.1in. */
143 
144 /**@brief WSS unit types. */
145 typedef enum
146 {
147  WSS_UNIT_SI, /**< Weight in kilograms and height in meters */
148  WSS_UNIT_IMPERIAL, /**< Weight in pounds and height in inches */
149 } wss_unit_t;
150 
151  /**@brief Weight Scale Service event type. */
152 typedef enum
153 {
154  WSS_EVT_INVALID, /**< Indicate that invalid event. */
155  WSS_EVT_MEAS_INDICATION_ENABLE, /**< Indicate that body composition measurement indication has been enabled. */
156  WSS_EVT_MEAS_INDICATION_DISABLE, /**< Indicate that body composition measurement indication has been disabled. */
157  WSS_EVT_MEAS_INDICATION_CPLT, /**< Indicate that BC Measurement has been indicated. */
158  WSS_EVT_MEAS_READ_CHARACTERISTIC, /**< The peer reads the characteristic. */
159 } wss_evt_type_t;
160 /** @} */
161 
162 /**
163  * @defgroup WSS_STRUCT Structures
164  * @{
165  */
166 /**@brief Weight Scale Measurement data. */
167 typedef struct
168 {
169  uint16_t weight; /**< Weight. */
170  prf_date_time_t time_stamp; /**< Time stamp. */
171  uint8_t user_id; /**< User index. */
172  uint16_t bmi; /**< Bmi. */
173  uint16_t height; /**< Height. */
175 
176 /**@brief Weight Scale Service event. */
177 typedef struct
178 {
179  wss_evt_type_t evt_type; /**< The WSS event type. */
180  uint8_t conn_idx; /**< The index of the connection. */
181  const uint8_t *p_data; /**< Pointer to event data. */
182  uint16_t length; /**< Length of event data. */
183 } wss_evt_t;
184 /** @} */
185 
186 /**
187  * @defgroup WSS_TYPEDEF Typedefs
188  * @{
189  */
190 /**@brief Weight Scale Service event handler type. */
191 typedef void (*wss_evt_handler_t)(wss_evt_t *p_evt);
192 /** @} */
193 
194 /**
195  * @defgroup WSS_STRUCT Structures
196  * @{
197  */
198 /**@brief Weight Scale Service Init variable. */
199 typedef struct
200 {
201  wss_evt_handler_t evt_handler; /**< Weight Scale Service event handler. */
202  uint32_t feature; /**< Initial value for features. */
203  uint8_t char_mask; /**< Initial mask of Supported characteristics, and configured with \ref WSS_CHAR_MASK */
204  wss_unit_t wss_unit; /**< Initial the unit system as SI or Imperial. */
205  wss_mass_res_t wss_mass_res; /**< Initial resolution of mass value. */
206  wss_height_res_t wss_height_res; /**< Initial resolution of height value. */
207  bool multi_user_present; /**< Flag which indicates if multiple user is present. */
208  bool time_stamp_present; /**< Flag which indicates if time stamp is present. */
209  bool bmi_present; /**< Flag which indicates if bmi is present. */
210 } wss_init_t;
211 /** @} */
212 
213 /**
214  * @defgroup WSS_FUNCTION Functions
215  * @{
216  */
217 /**
218  *****************************************************************************************
219  * @brief Initialize a Weight Scale Service instance and add in the DB.
220  *
221  * @param[in] p_wss_init: Pointer to WSS Service initialization variable.
222  * @param[in] p_bcs_start_handle: Pointer to the included service(BCS) start handle.
223  * @return Result of service initialization.
224  *****************************************************************************************
225  */
226 sdk_err_t wss_service_init(wss_init_t *p_wss_init, uint16_t *p_bcs_start_handle);
227 
228 /**
229  *****************************************************************************************
230  * @brief Send Weight Scale Measurement indication..
231  *
232  * @param[in] conn_idx: Connection index.
233  * @param[in] p_meas: Pointer to weight scale measurement data.
234  * @param[in] cache_num: The number of measurement caches.
235  *
236  * @return Result of indicate value.
237  *****************************************************************************************
238  */
239 sdk_err_t wss_measurement_send(uint8_t conn_idx, wss_meas_val_t *p_meas, uint8_t cache_num);
240 
241 /** @} */
242 
243 #endif
244 /** @} */
245 /** @} */
246 
wss_feature_t
wss_feature_t
Weight Scale Feature characteristic bit values.
Definition: wss.h:101
WSS_FEAT_HEIGHT_RES_1MM
@ WSS_FEAT_HEIGHT_RES_1MM
Resolution of 0.001m or 0.1in.
Definition: wss.h:119
WSS_UNIT_IMPERIAL
@ WSS_UNIT_IMPERIAL
Weight in pounds and height in inches.
Definition: wss.h:148
wss_meas_val_t::bmi
uint16_t bmi
Bmi.
Definition: wss.h:172
wss_init_t::multi_user_present
bool multi_user_present
Flag which indicates if multiple user is present.
Definition: wss.h:207
wss_evt_t::length
uint16_t length
Length of event data.
Definition: wss.h:182
wss_init_t
Weight Scale Service Init variable.
Definition: wss.h:200
wss_unit_t
wss_unit_t
WSS unit types.
Definition: wss.h:146
wss_evt_t
Weight Scale Service event.
Definition: wss.h:178
wss_evt_type_t
wss_evt_type_t
Weight Scale Service event type.
Definition: wss.h:153
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:132
wss_meas_val_t::height
uint16_t height
Height.
Definition: wss.h:173
WSS_FEAT_MASS_RES_5G
@ WSS_FEAT_MASS_RES_5G
Resolution of 0.005kg or 0.01lb.
Definition: wss.h:114
wss_init_t::wss_height_res
wss_height_res_t wss_height_res
Initial resolution of height value.
Definition: wss.h:206
WSS_FEAT_MASS_RES_20G
@ WSS_FEAT_MASS_RES_20G
Resolution of 0.02kg or 0.05lb.
Definition: wss.h:112
gr55xx_sys.h
GR55XX System API.
WSS_FEAT_FULL_BIT
@ WSS_FEAT_FULL_BIT
Definition: wss.h:121
wss_init_t::wss_mass_res
wss_mass_res_t wss_mass_res
Initial resolution of mass value.
Definition: wss.h:205
wss_init_t::wss_unit
wss_unit_t wss_unit
Initial the unit system as SI or Imperial.
Definition: wss.h:204
wss_meas_val_t::user_id
uint8_t user_id
User index.
Definition: wss.h:171
wss_meas_val_t::time_stamp
prf_date_time_t time_stamp
Time stamp.
Definition: wss.h:170
WSS_FEAT_BMI
@ WSS_FEAT_BMI
BMI supported.
Definition: wss.h:105
WSS_EVT_MEAS_INDICATION_ENABLE
@ WSS_EVT_MEAS_INDICATION_ENABLE
Indicate that body composition measurement indication has been enabled.
Definition: wss.h:155
WSS_MASS_RES_5G
@ WSS_MASS_RES_5G
Resolution of 0.005kg or 0.01lb.
Definition: wss.h:133
WSS_HEIGHT_RES_10MM
@ WSS_HEIGHT_RES_10MM
Resolution of 0.01m or 1in.
Definition: wss.h:139
WSS_EVT_MEAS_READ_CHARACTERISTIC
@ WSS_EVT_MEAS_READ_CHARACTERISTIC
The peer reads the characteristic.
Definition: wss.h:158
WSS_MASS_RES_200G
@ WSS_MASS_RES_200G
Resolution of 0.2kg or 0.5lb.
Definition: wss.h:128
wss_evt_t::p_data
const uint8_t * p_data
Pointer to event data.
Definition: wss.h:181
WSS_FEAT_MASS_RES_200G
@ WSS_FEAT_MASS_RES_200G
Resolution of 0.2kg or 0.5lb.
Definition: wss.h:109
WSS_EVT_MEAS_INDICATION_CPLT
@ WSS_EVT_MEAS_INDICATION_CPLT
Indicate that BC Measurement has been indicated.
Definition: wss.h:157
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_1MM
@ WSS_HEIGHT_RES_1MM
Resolution of 0.001m or 0.1in.
Definition: wss.h:141
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:111
wss_init_t::char_mask
uint8_t char_mask
Initial mask of Supported characteristics, and configured with Characteristics Mask.
Definition: wss.h:203
WSS_MEAS_FLAG_UNIT_IMPERIAL
@ WSS_MEAS_FLAG_UNIT_IMPERIAL
Flag bit for Imperial Measurement Units Present.
Definition: wss.h:93
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:156
WSS_FEAT_MASS_RES_10G
@ WSS_FEAT_MASS_RES_10G
Resolution of 0.01kg or 0.02lb.
Definition: wss.h:113
WSS_HEIGHT_RES_5MM
@ WSS_HEIGHT_RES_5MM
Resolution of 0.005m or 0.5in.
Definition: wss.h:140
wss_init_t::feature
uint32_t feature
Initial value for features.
Definition: wss.h:202
wss_height_res_t
wss_height_res_t
WSS Height Measurement resolutions.
Definition: wss.h:138
wss_meas_flag_bits
wss_meas_flag_bits
Weight Scale Measurement Flags.
Definition: wss.h:91
WSS_EVT_INVALID
@ WSS_EVT_INVALID
Indicate that invalid event.
Definition: wss.h:154
WSS_FEAT_MASS_RES_100G
@ WSS_FEAT_MASS_RES_100G
Resolution of 0.1kg or 0.2lb.
Definition: wss.h:110
WSS_MASS_RES_500G
@ WSS_MASS_RES_500G
Resolution of 0.5kg or 1lb.
Definition: wss.h:127
WSS_FEAT_HEIGHT_RES_10MM
@ WSS_FEAT_HEIGHT_RES_10MM
Resolution of 0.01m or 1in.
Definition: wss.h:117
WSS_FEAT_HEIGHT_RES_5MM
@ WSS_FEAT_HEIGHT_RES_5MM
Resolution of 0.005m or 0.5in.
Definition: wss.h:118
wss_init_t::time_stamp_present
bool time_stamp_present
Flag which indicates if time stamp is present.
Definition: wss.h:208
WSS_MASS_RES_100G
@ WSS_MASS_RES_100G
Resolution of 0.1kg or 0.2lb.
Definition: wss.h:129
WSS_FEAT_MASS_RES_500G
@ WSS_FEAT_MASS_RES_500G
Resolution of 0.5kg or 1lb.
Definition: wss.h:108
ble_prf_utils.h
Profile/Service Utilities API.
WSS_MEAS_FLAG_BMI_HEIGHT_PRESENT
@ WSS_MEAS_FLAG_BMI_HEIGHT_PRESENT
Flag bit for BMI and Height Present.
Definition: wss.h:96
wss_evt_t::evt_type
wss_evt_type_t evt_type
The WSS event type.
Definition: wss.h:179
WSS_MASS_RES_20G
@ WSS_MASS_RES_20G
Resolution of 0.02kg or 0.05lb.
Definition: wss.h:131
wss_init_t::bmi_present
bool bmi_present
Flag which indicates if bmi is present.
Definition: wss.h:209
wss_meas_val_t::weight
uint16_t weight
Weight.
Definition: wss.h:169
WSS_MASS_RES_50G
@ WSS_MASS_RES_50G
Resolution of 0.05kg or 0.1lb.
Definition: wss.h:130
wss_init_t::evt_handler
wss_evt_handler_t evt_handler
Weight Scale Service event handler.
Definition: wss.h:201
wss_meas_val_t
Weight Scale Measurement data.
Definition: wss.h:168
wss_service_init
sdk_err_t wss_service_init(wss_init_t *p_wss_init, uint16_t *p_bcs_start_handle)
Initialize a Weight Scale Service instance and add in the DB.
wss_mass_res_t
wss_mass_res_t
WSS Weight Measurement resolutions.
Definition: wss.h:126
wss_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: wss.h:180
WSS_FEAT_TIME_STAMP
@ WSS_FEAT_TIME_STAMP
Time Stamp supported.
Definition: wss.h:103
WSS_MEAS_FLAG_UNIT_SI
@ WSS_MEAS_FLAG_UNIT_SI
Flag bit for SI Measurement Units Present.
Definition: wss.h:92
WSS_UNIT_SI
@ WSS_UNIT_SI
Weight in kilograms and height in meters.
Definition: wss.h:147
wss_evt_handler_t
void(* wss_evt_handler_t)(wss_evt_t *p_evt)
Weight Scale Service event handler type.
Definition: wss.h:191
WSS_FEAT_MULTI_USER
@ WSS_FEAT_MULTI_USER
Multiple Users supported.
Definition: wss.h:104