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