1 /** 2 **************************************************************************************** 3 * 4 * @file uds.h 5 * 6 * @brief User Data 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_UDS User Data Service (UDS) 46 * @{ 47 * @brief User Data Service module. 48 * 49 * @details The User Data Service (UDS) exposes user-related data in a sports and fitness, home, or healthcare 50 * environment. This allows remote access and update of user data by a client as well as the 51 * synchronization of user data between a server and a client. 52 * 53 * After \ref uds_init_t variable is intialized, the application must call \ref uds_service_init() 54 * to add User Data Service and UDS Characteristic, Database Change Increment, User Index, User 55 * Control Point and Registered User characteristics to the BLE Stack database according to 56 * \ref uds_init_t.char_mask. 57 */ 58 59 #ifndef __UDS_H__ 60 #define __UDS_H__ 61 62 #include <stdint.h> 63 #include <stdbool.h> 64 #include "gr55xx_sys.h" 65 #include "custom_config.h" 66 #include "ble_prf_utils.h" 67 68 /** 69 * @defgroup UDS_MACRO Defines 70 * @{ 71 */ 72 #define UDS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 73 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of UDS connections. */ 74 75 #define UDS_AGE_VAL_LEN_MAX 2 /**< Maximum length of Age Characteristic value. */ 76 #define UDS_DATE_OF_BIRTH_VAL_LEN_MAX 4 /**< Maximum length of Date of Birth Characteristic value. */ 77 #define UDS_FIRST_NAME_VAL_LEN_MAX 50 /**< Maximum length of First Name Characteristic value. */ 78 #define UDS_HEIGHT_VAL_LEN_MAX 2 /**< Maximum length of Height Characteristic value. */ 79 #define UDS_GENDER_VAL_LEN_MAX 2 /**< Maximum length of Gender Characteristic value. */ 80 #define UDS_DB_CHANGE_INCR_VAL_LEN_MAX 4 /**< Maximum length of Database Change Increment value. */ 81 #define UDS_USER_INDEX_VAL_LEN_MAX 1 /**< Maximum length of User Index value. */ 82 #define UDS_CTRL_PT_RSP_LEN_MIN 3 /**< Mimimum length of User Control Point response value. */ 83 #define UDS_CTRL_PT_RSP_LEN_MAX 20 /**< Maximum length of User Control Point response value. */ 84 #define UDS_CTRL_PT_VAL_LEN_MAX 19 /**< Maximum length of User Control Point value. */ 85 #define UDS_REGI_USER_DATA_LEN_MAX 19 /**< Maximum length of Registered User Data value. */ 86 #define UDS_REGI_USER_VAL_LEN_MAX 20 /**< Maximum length of Registered User Characteristic value. */ 87 88 #define UDS_ERROR_UD_ACCESS_NOT_PERMIT 0x80 /**< Error code: The user data access is not permitted. */ 89 #define UDS_ERROR_PROC_IN_PROGRESS 0xFE /**< Error code: A previously triggered User Control Point operation \ 90 is still in progress. */ 91 #define UDS_ERROR_CCCD_INVALID 0xFD /**< Error code: The Client Characteristic Configuration descriptor \ 92 is not configured. */ 93 94 #define UDS_DB_CHANGE_INCR_DEFAULT_VAL 0x00 /**< Database Change Increment default value. */ 95 #define UDS_UNKNOWN_USER 0xFF /**< Unknown User. */ 96 #define UDS_CONSENT_CODE_VAL_MAX 0x270F /**< Maximum value of Consent Code. */ 97 #define UDS_CONSENT_TRY_NUM_MAX 0x04 /**< Maximum number of consent tries. */ 98 99 #define UDS_MIDDLE_REGI_USER_SEGM 0x00 /**< The middle segment of Registered User Characterristic value. */ 100 #define UDS_FIRST_REGI_USER_SEGM 0x01 /**< The first segment of Registered User Characterristic value. */ 101 #define UDS_LAST_REGI_USER_SEGM 0x02 /**< The last segment of Registered User Characterristic value. */ 102 #define UDS_ONLY_REGI_USER_SEGM 0x03 /**< The only segment of Registered User Characterristic value. */ 103 104 /** 105 * @defgroup UDS_CHAR_MASK Characteristics Mask 106 * @{ 107 * @brief Bit masks for the initialization of \ref uds_init_t.char_mask. 108 */ 109 #define UDS_CHAR_MANDATORY 0x000001FF /**< Bit mask for mandatory characteristic in UDS.*/ 110 #define UDS_CHAR_AGE_SUP 0x00000600 /**< Bit mask for Age characteristic that is optional.*/ 111 #define UDS_CHAR_DATE_OF_BIRTH_SUP 0x00001800 /**< Bit mask for date of birth characteristic that is optional.*/ 112 #define UDS_CHAR_FIRST_NAME_SUP 0x00006000 /**< Bit mask for first name characteristic that is optional. */ 113 #define UDS_CHAR_HEIGHT_SUP 0x00018000 /**< Bit mask for height characteristic that is optional.*/ 114 #define UDS_CHAR_GENDER_SUP 0x00060000 /**< Bit mask for gender characteristic that is optional.*/ 115 #define UDS_CHAR_REGIST_USER_SUP 0x00380000 /**< Bit mask for Registered User characteristic that is optional.*/ 116 #define UDS_CHAR_FULL 0x003FFFFF /**< Bit mask of the full characteristic.*/ 117 /** @} */ 118 /** @} */ 119 120 /** 121 * @defgroup UDS_ENUM Enumerations 122 * @{ 123 */ 124 /**@brief User Data Service Control Point Operation Code.*/ 125 typedef enum { 126 UDS_CTRL_PT_OP_RESERVED, /**< Reserved for future use. */ 127 UDS_CTRL_PT_OP_REGIST_NEW_USER, /**< Register New User Operation Code.*/ 128 UDS_CTRL_PT_OP_CONSENT, /**< Consent Operation Code.*/ 129 UDS_CTRL_PT_OP_DEL_USER_DATA, /**< Delete User Data Operation Code.*/ 130 UDS_CTRL_PT_OP_LIST_ALL_USERS, /**< List All Users Operation Code.*/ 131 UDS_CTRL_PT_OP_DEL_USERS, /**< Delete User(s) Operation code. */ 132 UDS_CTRL_PT_OP_RSP_CODE = 0x20, /**< Response code. */ 133 } uds_ctrl_pt_op_code_t; 134 135 /**@brief User Data Service Control Point Response value.*/ 136 typedef enum { 137 UDS_CTRL_PT_RSP_RESERVED, /**< Reserved value. */ 138 UDS_CTRL_PT_RSP_SUCCESS, /**< Operation Success. */ 139 UDS_CTRL_PT_RSP_NOT_SUP, /**< Operation Code Not Supported. */ 140 UDS_CTRL_PT_RSP_INVALID_PARAM, /**< Invalid Parameter. */ 141 UDS_CTRL_PT_RSP_FAILED, /**< Operation Failed. */ 142 UDS_CTRL_PT_RSP_USER_NOT_AUTH, /**< User Not Authorized. */ 143 } uds_ctrl_pt_rsp_t; 144 145 /**@brief User Data Service event type. */ 146 typedef enum { 147 UDS_EVT_INVALID = 0x00, /**< Invalid event. */ 148 UDS_EVT_DB_CHANGE_INCR_NOTIFICATION_ENABLE, /**< Database Change Increment Notification is enabled. */ 149 UDS_EVT_DB_CHANGE_INCR_NOTIFICATION_DISABLE, /**< Database Change Increment Notification is disabled. */ 150 UDS_EVT_CTRL_POINT_INDICATION_ENABLE, /**< Indicate that User Control Point indication has been enabled.*/ 151 UDS_EVT_CTRL_POINT_INDICATION_DISABLE, /**< Indicate that User Control Point indication has been disabled.*/ 152 UDS_EVT_REGIST_USER_INDICATION_ENABLE, /**< Indicate that Registered User indication has been enabled. */ 153 UDS_EVT_REGIST_USER_INDICATION_DISABLE, /**< Indicate that Registered User indication has been disabled. */ 154 UDS_EVT_DB_CHANGE_INCR_SEND_CPLT, /**< Indicate that Database Change Increment has been notified. */ 155 UDS_EVT_CTRL_POINT_RSP_CPLT, /**< Indicate that User Control Point response has been indicated. */ 156 UDS_EVT_REGIST_USER_RSP_CPLT, /**< Indicate that Registered User response has been indicated. */ 157 UDS_EVT_AGE_SET_BY_PEER, /**< Age has been set by peer. */ 158 UDS_EVT_DATE_OF_BIRTH_SET_BY_PEER, /**< Date of Birth has been set by peer. */ 159 UDS_EVT_FIRST_NAME_SET_BY_PEER, /**< First Name has been set by peer. */ 160 UDS_EVT_HEIGHT_SET_BY_PEER, /**< Height has been set by peer. */ 161 UDS_EVT_GENDER_SET_BY_PEER, /**< Gender has been set by peer. */ 162 UDS_EVT_DB_CHANGE_INCR_SET_BY_PEER, /**< Database Change Increment has been set by peer. */ 163 UDS_EVT_CTRL_POINT_SET_BY_PEER, /**< User Control Point has been set by peer. */ 164 UDS_EVT_USER_GRANT_ACCESS, /**< Indicate that User is waiting to be granted access. */ 165 UDS_EVT_REGIST_NEW_USER, /**< Indicate that User is waiting to be granted access. */ 166 UDS_EVT_DEL_USER_DATA, 167 UDS_EVT_DEL_USERS, 168 } uds_evt_type_t; 169 170 /**@brief UDS Characteristics Flags. */ 171 enum uds_chars_flag_bits { 172 UDS_CHARS_WEIGHT_PRESENT = 0x01, /**< Flag bit for Weight Present. */ 173 UDS_CHARS_AGE_PRESENT = 0x02, /**< Flag bit for Age Present. */ 174 UDS_CHARS_BIRTH_DATE_PRESENT = 0x04, /**< Flag bit for Date of Birth Present. */ 175 UDS_CHARS_FIRST_NAME_PRESENT = 0x08, /**< Flag bit for First Name Present. */ 176 UDS_CHARS_HEIGHT_PRESENT = 0x10, /**< Flag bit for Height Present. */ 177 UDS_CHARS_GENDER_PRESENT = 0X20, /**< Flag bit for Gender Present. */ 178 }; 179 180 /**@brief Registered User Data Flags. */ 181 enum uds_regi_user_data_flag_bits { 182 UDS_REGI_USER_NAME_PRESENT = 0x01, /**< Flag bit for Registered User Name Present. */ 183 UDS_USER_NAME_TRUNCATED = 0x02, /**< Flag bit for User Name is truncated. */ 184 }; 185 /** @} */ 186 187 /** 188 * @defgroup UDS_STRUCT Structures 189 * @{ 190 */ 191 /**@brief UDS Characteristic - birthdate's structure. */ 192 typedef struct { 193 uint16_t year; /**< year time element of birth date. */ 194 uint8_t month; /**< month time element of birth date. */ 195 uint8_t day; /**< day time element of birth date. */ 196 } birth_date_t; 197 198 /**@brief UDS Characteristics Flags structure. */ 199 typedef struct { 200 uint8_t weight_present : 1; /**< Weight Present. */ 201 uint8_t age_present : 1; /**< Age Present. */ 202 uint8_t birth_date_present : 1; /**< Date of Birth Present. */ 203 uint8_t first_name_present : 1; /**< First Name Present. */ 204 uint8_t height_present : 1; /**< Height Present. */ 205 uint8_t gender_present : 1; /**< Gender Present. */ 206 } uds_chars_flag_t; 207 208 /**@brief UDS Characteristics value structure. */ 209 typedef struct { 210 uint16_t weight; /**< User's weight. */ 211 uint8_t age; /**< User's age. */ 212 birth_date_t date_of_birth; /**< User's birth date. */ 213 uint16_t height; /**< User's height. */ 214 uint8_t gender; /**< User's gender. */ 215 uint8_t *p_first_name; /**< User's first name. */ 216 uint16_t name_length; /**< Length of User's first name. */ 217 } uds_chars_val_t; 218 219 /**@brief Registered User Data Flags structure. */ 220 typedef struct { 221 uint8_t regi_user_name_present : 1; /**< Registered User Name Present. */ 222 uint8_t user_name_truncated : 1; /**< User Name is truncated. */ 223 uint8_t reserved : 6; /**< Reserved for Future Use. */ 224 } uds_regi_user_data_flag_t; 225 226 /**@brief User Data Service event. */ 227 typedef struct { 228 uint8_t conn_idx; /**< The index of the connection. */ 229 uds_evt_type_t evt_type; /**< The UDS event type. */ 230 const uint8_t *p_data; /**< Pointer to event data. */ 231 uint16_t length; /**< Length of event data. */ 232 uint16_t consent_code; /**< Consent Code data. */ 233 uds_chars_val_t uds_chars_val; /**< UDS Characteristics value set by peer. */ 234 uint32_t db_change_incr_val; /**< Database Change Increment value set by peer. */ 235 } uds_evt_t; 236 /** @} */ 237 238 /** 239 * @defgroup UDS_TYPEDEF Typedefs 240 * @{ 241 */ 242 /**@brief User Data Service event handler type. */ 243 typedef void (*uds_evt_handler_t)(uds_evt_t *p_evt); 244 /** @} */ 245 246 /** 247 * @defgroup UDS_STRUCT Structures 248 * @{ 249 */ 250 /**@brief UDS Registered User Data stream. */ 251 typedef struct { 252 uint8_t *p_data; /**< Pointer to Registered User Data stream. */ 253 uint16_t length; /**< Length of Registered User Data stream. */ 254 uint16_t offset; /**< Offset of Registered User Data stream. */ 255 uint16_t *p_segm_length; /**< Pointer to each segmentation length of Registered User Data stream. */ 256 uint16_t segm_num; /**< Registered User Data segmentations' number. */ 257 uint16_t segm_offset; /**< Offset of Registered User Data segmentations' number. */ 258 } uds_regi_user_data_stream_t; 259 260 /**@brief User Data Service init structure. 261 * This contains all option and data needed for initialization of the service. */ 262 typedef struct { 263 uds_evt_handler_t evt_handler; /**< User Data Service event handler. */ 264 uint32_t 265 char_mask; /**< Initialize the mask of supported characteristics, \ 266 and configured with \ref UDS_CHAR_MASK. */ 267 uint8_t user_index; /**< Initialize the user index. */ 268 uint8_t db_change_incr_val; /**< Initialize the Database Change Increment value. */ 269 uds_regi_user_data_flag_t uds_regi_user_data_flag; /**< Initialize the Registered User Data Flags structure. */ 270 uds_chars_flag_t uds_chars_flag; /**< Initialize the UDS Characteristics Flags structure. */ 271 } uds_init_t; 272 /** @} */ 273 274 /** 275 * @defgroup UDS_FUNCTION Functions 276 * @{ 277 */ 278 /** 279 ***************************************************************************************** 280 * @brief Initialize a User Data Service instance and add in the DB. 281 * 282 * @param[in] p_uds_init: Pointer to UDS Service initialization variable. 283 * 284 * @return Result of service initialization. 285 ***************************************************************************************** 286 */ 287 sdk_err_t uds_service_init(uds_init_t *p_uds_init); 288 289 /** 290 ***************************************************************************************** 291 * @brief Send Registered User Characteristic value. 292 * 293 * @param[in] conn_idx: Connnection index. 294 * 295 * @return Result of sending Registered User Characteristic value. 296 ***************************************************************************************** 297 */ 298 sdk_err_t uds_regi_user_val_send(uint8_t conn_idx); 299 300 /** 301 ***************************************************************************************** 302 * @brief Send Database Change Increment Characteristic value if UDS Characteristics value has been changed. 303 * 304 * @param[in] conn_idx: Connnection index. 305 * @param[in] user_idx: Current user index. 306 * 307 * @return Result of sending Database Change Increment Characteristic value. 308 ***************************************************************************************** 309 */ 310 sdk_err_t uds_db_change_incr_val_send(uint8_t conn_idx, uint8_t user_idx); 311 312 /** 313 ***************************************************************************************** 314 * @brief Send User Control Point response if it's indication has been enabled. 315 * 316 * @param[in] conn_idx: Connnection index. 317 * @param[in] p_data: Pointer to data. 318 * @param[in] length: Length of data. 319 * 320 * @return Result of indicate value. 321 ***************************************************************************************** 322 */ 323 sdk_err_t uds_ctrl_pt_rsp_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length); 324 325 /** 326 ***************************************************************************************** 327 * @brief Get current user index. 328 * 329 * @param[in] conn_idx: Connnection index. 330 * 331 * @return Result of current user index. 332 ***************************************************************************************** 333 */ 334 uint8_t uds_get_cur_user_index(uint8_t conn_idx); 335 336 /** 337 ***************************************************************************************** 338 * @brief Set current user index. 339 * 340 * @param[in] conn_idx: Connnection index. 341 * @param[in] user_index: current user index. 342 ***************************************************************************************** 343 */ 344 void uds_set_cur_user_index(uint8_t conn_idx, uint8_t user_index); 345 346 #if defined(PTS_AUTO_TEST) 347 void uds_regist_new_user(uint8_t conn_idx); 348 #endif 349 350 /** @} */ 351 352 #endif 353 /** @} */ 354 /** @} */ 355 356