1 /** 2 ***************************************************************************************** 3 * 4 * @file rscs.h 5 * 6 * @brief Running Speed and Cadence 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_RSCS Running Speed and Cadence Service (RSCS) 46 * @{ 47 * @brief Definitions and prototypes for the RSCS interface. 48 * 49 * @details The Running Speed and Cadence (RSC) Service exposes speed, cadence and other data related to 50 * fitness applications such as the stride length and the total distance the user has traveled 51 * while using the Running Speed and Cadence sensor (Server). This module implements the Running 52 * Speed and Cadence Service with RSC Measurement, RSC Feature, Sensor Location and SC Control 53 * Point characteristics. 54 * 55 * After \ref rscs_init_t variable is initialized, the application must call \ref rscs_service_init() 56 * to add the Running Speed and Cadence Service and RSC Measurement, RSC Feature, Sensor Location and 57 * SC Control Point characteristics to the BLE Stack database according to \ref rscs_init_t.char_mask. 58 */ 59 60 #ifndef __RSCS_H__ 61 #define __RSCS_H__ 62 63 #include <stdint.h> 64 #include <stdbool.h> 65 #include "gr55xx_sys.h" 66 #include "custom_config.h" 67 68 /** 69 * @defgroup RSCS_MACRO Defines 70 * @{ 71 */ 72 #define RSCS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 73 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Running Speed and \ 74 Cadence Service connections. */ 75 #define RSCS_MEAS_VAL_LEN_MAX 20 /**< Maximum length of RSC measurement value. */ 76 #define RSCS_FEAT_VAL_LEN_MAX 2 /**< Maximum length of RSC Feature value. */ 77 #define RSCS_SENSOR_LOC_VAL_LEN_MAX 1 /**< Maximum length of RSC Sensor Location value. */ 78 #define RSCS_CTRL_PT_RSP_LEN_MIN 3 /**< Mimimum length of SC Control Point responce value. */ 79 /**< Maximum length of SC Control Point value. */ 80 #define RSCS_CTRL_PT_VAL_LEN_MAX (RSCS_CTRL_PT_RSP_LEN_MIN + RSCS_SENSOR_LOC_SUP_NB) 81 82 #define RSCS_ERROR_PROC_IN_PROGRESS 0x80 /**< Error code: A previously triggered SC Control Point operation \ 83 is still in progress. */ 84 #define RSCS_ERROR_CCCD_INVALID 0x81 /**< Error code: The Client Characteristic Configuration descriptor \ 85 is not configured. */ 86 87 /** 88 * @defgroup RSCS_CHAR_MASK Characteristics Mask 89 * @{ 90 * @brief Bit masks for the initialization of \ref rscs_init_t.char_mask. 91 */ 92 #define RSCS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in RSCS.*/ 93 #define RSCS_CHAR_SENSOR_LOC_SUP 0x00c0 /**< Bit mask for Sensor Location characteristic that is optional.*/ 94 #define RSCS_CHAR_SC_CTRL_POINT 0x0700 /**< Bit mask for SC Control Point characteristic that is optional.*/ 95 #define RSCS_CHAR_FULL 0x07ff /**< Bit mask of the full characteristic.*/ 96 /** @} */ 97 98 /** 99 * @defgroup RSCS_MEAS_FLAG_BIT Measurement Flag Bits 100 * @{ 101 * @brief Running Speed and Cadence Measurement Flags. 102 */ 103 #define RSCS_MEAS_FLAG_INST_STRIDE_LEN_BIT (0x01 << 0) /**< Flag bit for Instantaneous Stride Length Measurement.*/ 104 #define RSCS_MEAS_FLAG_TOTAL_DISTANCE_BIT (0x01 << 1) /**< Flag bit for Total Distance Measurement.*/ 105 #define RSCS_MEAS_FLAG_RUNNING_OR_WALKING_BIT (0x01 << 2) /**< Flag bit for Running or Walking.*/ 106 /** @} */ 107 108 /** 109 * @defgroup RSCS_FEAT_BIT Feature Bits 110 * @{ 111 * @brief Running Speed and Cadence Service feature bits. 112 */ 113 /**< Bit for Instantaneous Stride Length Measurement Supported.*/ 114 #define RSCS_FEAT_INSTANT_STRIDE_LEN_BIT (0x01 << 0) 115 #define RSCS_FEAT_TOTAL_DISTANCE_BIT (0x01 << 1) /**< Bit for Total Distance Measurement Supported. */ 116 #define RSCS_FEAT_RUNNING_OR_WALKING_STATUS_BIT (0x01 << 2) /**< Bit for Running or Walking Status Supported. */ 117 #define RSCS_FEAT_CALIBRATION_PROCEDURE_BIT (0x01 << 3) /**< Bit for Calibration Procedure Supported. */ 118 #define RSCS_FEAT_MULTIPLE_SENSORS_BIT (0x01 << 4) /**< Bit for Multiple Sensor Locations Supported. */ 119 #define RSCS_FEAR_FULL_BIT (0x1f) /**< Bit for all RSC features Supported. */ 120 /** @} */ 121 /** @} */ 122 123 /** 124 * @defgroup RSCS_ENUM Enumerations 125 * @{ 126 */ 127 /**@brief Running Speed and Cadence Service Sensor Location. */ 128 typedef enum { 129 RSCS_SENSOR_LOC_OTHER, /**< Sensor location: other. */ 130 RSCS_SENSOR_LOC_SHOE_TOP, /**< Sensor location: top of shoe. */ 131 RSCS_SENSOR_LOC_SHOE_IN, /**< Sensor location: inside of shoe. */ 132 RSCS_SENSOR_LOC_HIP, /**< Sensor location: hip. */ 133 RSCS_SENSOR_LOC_FRONT_WHEEL, /**< Sensor location: front wheel. */ 134 RSCS_SENSOR_LOC_LEFT_PEDAL, /**< Sensor location: left pedal. */ 135 RSCS_SENSOR_LOC_RIGHT_PEDAL, /**< Sensor location: right pedal. */ 136 RSCS_SENSOR_LOC_FRONT_HUB, /**< Sensor location: front hub. */ 137 RSCS_SENSOR_LOC_SUP_NB /**< Number of sensor location. */ 138 } rscs_sensor_loc_t; 139 140 /**@brief Running Speed and Cadence Service Control Point Operation Code.*/ 141 typedef enum { 142 RSCS_CTRL_PT_OP_RESERVED, /**< Reserved for future use. */ 143 RSCS_CTRL_PT_OP_SET_CUMUL_VAL, /**< Set Cumulative value Operation Code.*/ 144 RSCS_CTRL_PT_OP_START_CALIB, /**< Start Sensor Calibration Operation Code.*/ 145 RSCS_CTRL_PT_OP_UPD_LOC, /**< Update Sensor Location Operation Code.*/ 146 RSCS_CTRL_PT_OP_REQ_SUP_LOC, /**< Request Supported Sensor Locations Operation Code.*/ 147 RSCS_CTRL_PT_OP_RSP_CODE = 0x10, /**< Response code. */ 148 } rscs_ctrl_pt_op_code_t; 149 150 /**@brief Running Speed and Cadence Service Control Point Response value.*/ 151 typedef enum { 152 RSCS_CTRL_PT_RSP_RESERVED, /**< Reserved value. */ 153 RSCS_CTRL_PT_RSP_SUCCESS, /**< Operation Succeeded. */ 154 RSCS_CTRL_PT_RSP_NOT_SUP, /**< Operation Code Not Supported. */ 155 RSCS_CTRL_PT_RSP_INVALID_PARAM, /**< Invalid Parameter. */ 156 RSCS_CTRL_PT_RSP_FAILED /**< Operation Failed. */ 157 } rscs_ctrl_pt_rsp_t; 158 159 /**@brief Running Speed and Cadence Service event type.*/ 160 typedef enum { 161 RSCS_EVT_INVALID, /**< Indicate that invalid event. */ 162 RSCS_EVT_RSC_MEAS_NOTIFICATION_ENABLE, /**< Indicate that RSC Measurement notification has been enabled. */ 163 RSCS_EVT_RSC_MEAS_NOTIFICATION_DISABLE, /**< Indicate that RSC Measurement notification has been disabled. */ 164 RSCS_EVT_CTRL_POINT_INDICATION_ENABLE, /**< Indicate that SC Control Point indication has been enabled. */ 165 RSCS_EVT_CTRL_POINT_INDICATION_DISABLE, /**< Indicate that SC Control Point indication has been disabled. */ 166 RSCS_EVT_RSC_MEAS_SEND_CPLT, /**< Indicate that RSC Measurement has been notified. */ 167 RSCS_EVT_CUMUL_VAL_SET, /**< Indicate that Total Distance value needs to be set. */ 168 RSCS_EVT_SEBSOR_CALIBRATION, /**< Indicate that Sensor calibration procedure should be initiated. */ 169 RSCS_EVT_SEBSOR_LOC_UPD, /**< Indicate that Sensor Location needs to be reset. */ 170 RSCS_EVT_SUP_SEBSOR_LOC_REQ, /**< Indicate that request supported sensor location list. */ 171 RSCS_EVT_CTRL_POINT_RSP_CPLT /**< Indicate that SC Control Point response has been indicated. */ 172 } rscs_evt_type_t; 173 /** @} */ 174 175 /** 176 * @defgroup RSCS_STRUCT Structures 177 * @{ 178 */ 179 /**@brief Running Speed and Cadence Service event. */ 180 typedef struct { 181 rscs_evt_type_t evt_type; /**< The RSCS event type. */ 182 uint8_t conn_idx; /**< The index of the connection. */ 183 const uint8_t *p_data; /**< Pointer to event data. */ 184 uint16_t length; /**< Length of event data. */ 185 } rscs_evt_t; 186 187 /**@brief Running Speed and Cadence Measurement Character value structure. */ 188 typedef struct { 189 bool inst_stride_length_present; /**< If Instantaneous Stride Length is present. */ 190 bool total_distance_present; /**< If Total Distance is present. */ 191 bool is_run_or_walk; /**< True: Running, False: Walking. */ 192 uint16_t inst_speed; /**< Instantaneous Speed. */ 193 uint8_t inst_cadence; /**< Instantaneous Cadence. */ 194 uint16_t inst_stride_length; /**< Instantaneous Stride Length. */ 195 uint32_t total_distance; /**< Total Distance. */ 196 } rscs_meas_val_t; 197 /** @} */ 198 199 /** 200 * @defgroup RSCS_TYPEDEF Typedefs 201 * @{ 202 */ 203 /**@brief Running Speed and Cadence Service event handler type.*/ 204 typedef void (*rscs_evt_handler_t)(rscs_evt_t *p_evt); 205 /** @} */ 206 207 /** 208 * @defgroup RSCS_STRUCT Structures 209 * @{ 210 */ 211 /**@brief Running Speed and Cadence Service init stucture. 212 * This contains all option and data needed for initialization of the service. */ 213 typedef struct { 214 rscs_evt_handler_t evt_handler; /**< Running Speed and Cadence Service event handler. */ 215 uint16_t 216 char_mask; /**< Initial mask of supported characteristics, and configured with \ref RSCS_CHAR_MASK. */ 217 rscs_sensor_loc_t sensor_location; /**< Initial sensor location. */ 218 uint16_t feature; /**< Initial value for features. */ 219 } rscs_init_t; 220 /** @} */ 221 222 223 /** 224 * @defgroup RSCS_FUNCTION Functions 225 * @{ 226 */ 227 /** 228 ***************************************************************************************** 229 * @brief Initialize a Running Speed and Cadence Service instance and add in the DB. 230 * 231 * @param[in] p_rscs_init: Pointer to rscs_init_t Service initialization variable 232 * 233 * @return Result of service initialization. 234 ***************************************************************************************** 235 */ 236 sdk_err_t rscs_service_init(rscs_init_t *p_rscs_init); 237 238 /** 239 ***************************************************************************************** 240 * @brief Send RSC measurement if notification has been enabled. 241 * 242 * @param[in] conn_idx: Connnection index. 243 * @param[in] p_meas: The pointer to new Running Speed and Cadence measurement. 244 * 245 * @return Result of notify value 246 ***************************************************************************************** 247 */ 248 sdk_err_t rscs_measurement_send(uint8_t conn_idx, rscs_meas_val_t *p_meas); 249 250 /** 251 ***************************************************************************************** 252 * @brief Send SC Control Point responce if indication has been enabled. 253 * 254 * @param[in] conn_idx: Connnection index. 255 * @param[in] p_data: Pointer to data. 256 * @param[in] length: Length of data. 257 * 258 * @return Result of indicate value 259 ***************************************************************************************** 260 */ 261 sdk_err_t rscs_ctrl_pt_rsp_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length); 262 263 /** 264 ***************************************************************************************** 265 * @brief Update Sensor Location if Multiple Sensor Locations Supported \ref rscs_init_t.feature. 266 * 267 * @param[in] sensor_loc: New sensor location. 268 * 269 * @return Result of update. 270 ***************************************************************************************** 271 */ 272 sdk_err_t rscs_sensor_loc_update(rscs_sensor_loc_t sensor_loc); 273 274 /** @} */ 275 276 #endif 277 /** @} */ 278 279 /** @} */ 280 281