1 /** 2 ***************************************************************************************** 3 * 4 * @file cscs.h 5 * 6 * @brief Cycling 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_CSCS Cycling Speed and Cadence Service (CSCS) 46 * @{ 47 * @brief Definitions and prototypes for the CSCS interface. 48 * 49 * @details The Cycling Speed and Cadence (CSC) Service exposes speed-related data and/or cadence-related data 50 * while using the Cycling Speed and Cadence sensor(Server). This module implements the Cycling Speed 51 * and Cadence Service with CSC Measurement, CSC Feature, Sensor Location and SC Control Point characteristics. 52 * 53 * After \ref cscs_init_t variable is initialized, the application must call \ref cscs_service_init() 54 * to add the Cycling Speed and Cadence Service and CSC Measurement, CSC Feature, Sensor Location and 55 * SC Control Point characteristics to the BLE Stack database according to \ref cscs_init_t.char_mask. 56 */ 57 58 #ifndef __CSCS_H__ 59 #define __CSCS_H__ 60 61 #include <stdint.h> 62 #include <stdbool.h> 63 #include "gr55xx_sys.h" 64 #include "custom_config.h" 65 66 /** 67 * @defgroup CSCS_MACRO Defines 68 * @{ 69 */ 70 #define CSCS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 71 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of CSCS connections. */ 72 #define CSCS_MEAS_VAL_LEN_MAX 20 /**< Maximum length of CSC Measurment value. */ 73 #define CSCS_FEAT_VAL_LEN_MAX 2 /**< Maximum length of CSC Feature value. */ 74 #define CSCS_SENSOR_LOC_VAL_LEN_MAX 1 /**< Maximum length of Sensor Location value. */ 75 #define CSCS_CTRL_PT_RSP_LEN_MIN 3 /**< Mimimum length of SC Control Point response value. */ 76 /**< Maximum length of SC Control Point value. */ 77 #define CSCS_CTRL_PT_VAL_LEN_MAX (CSCS_CTRL_PT_RSP_LEN_MIN + CSCS_SENSOR_LOC_SUP_NB) 78 79 #define CSCS_ERROR_PROC_IN_PROGRESS 0x80 /**< Error code: A previously triggered SC Control Point operation \ 80 is still in progress. */ 81 #define CSCS_ERROR_CCCD_INVALID 0x81 /**< Error code: The Client Characteristic Configuration descriptor \ 82 is not configured. */ 83 84 /** 85 * @defgroup CSCS_CHAR_MASK Characteristics Mask 86 * @{ 87 * @brief Bit masks for the initialization of \ref cscs_init_t.char_mask. 88 */ 89 #define CSCS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in CSCS. */ 90 #define CSCS_CHAR_SENSOR_LOC_SUP 0x00c0 /**< Bit mask for Sensor Location characteristic that is optional. */ 91 #define CSCS_CHAR_SC_CTRL_POINT 0x0700 /**< Bit mask for SC Control Point characteristic that is optional. */ 92 #define CSCS_CHAR_FULL 0x07ff /**< Bit mask of the full characteristic. */ 93 /** @} */ 94 95 /** 96 * @defgroup CSCS_MEAS_FLAG_BIT Measurement Flag Bits 97 * @{ 98 * @brief Cycling Speed and Cadence Measurement Flags. 99 */ 100 #define CSCS_MEAS_FLAG_WHEEL_REVOLUTION_BIT (0x01 << 0) /**< Flag bit for Wheel Revolution Data Present. */ 101 #define CSCS_MEAS_FLAG_CRANK_REVOLUTION_BIT (0x01 << 1) /**< Flag bit for Crank Revolution Data Present. */ 102 /** @} */ 103 104 /** 105 * @defgroup CSCS_FEAT_BIT Feature Bits 106 * @{ 107 * @brief Cycling Speed and Cadence Service feature bits. 108 */ 109 #define CSCS_FEAT_WHEEL_REVOLUTION_SUP_BIT (0x01 << 0) /**< Bit for Wheel Revolution Data Supported. */ 110 #define CSCS_FEAT_CRANK_REVOLUTION_SUP_BIT (0x01 << 1) /**< Bit for Crank Revolution Data Supported. */ 111 #define CSCS_FEAT_MULTIPLE_SENSORS_BIT (0x01 << 2) /**< Bit for Multiple Sensor Locations Supported. */ 112 #define CSCS_FEAR_FULL_BIT (0x07) /**< Bit for all CSC features Supported. */ 113 /** @} */ 114 /** @} */ 115 116 /** 117 * @defgroup CSCS_ENUM Enumerations 118 * @{ 119 */ 120 /**@brief Cycling Speed and Cadence Service Sensor Location. */ 121 typedef enum { 122 CSCS_SENSOR_LOC_OTHER, /**< Sensor location: other. */ 123 CSCS_SENSOR_LOC_SHOE_TOP, /**< Sensor location: top of shoe. */ 124 CSCS_SENSOR_LOC_SHOE_IN, /**< Sensor location: inside of shoe. */ 125 CSCS_SENSOR_LOC_HIP, /**< Sensor location: hip. */ 126 CSCS_SENSOR_LOC_FRONT_WHEEL, /**< Sensor location: front wheel. */ 127 CSCS_SENSOR_LOC_LEFT_PEDAL, /**< Sensor location: left pedal. */ 128 CSCS_SENSOR_LOC_RIGHT_PEDAL, /**< Sensor location: right pedal. */ 129 CSCS_SENSOR_LOC_FRONT_HUB, /**< Sensor location: front hub. */ 130 CSCS_SENSOR_LOC_SUP_NB /**< Number of sensor location. */ 131 } cscs_sensor_loc_t; 132 133 /**@brief Cycling Speed and Cadence Service Control Point Operation Code.*/ 134 typedef enum { 135 CSCS_CTRL_PT_OP_RESERVED, /**< Reserved for future use. */ 136 CSCS_CTRL_PT_OP_SET_CUMUL_VAL, /**< Set Cumulative value Operation Code.*/ 137 CSCS_CTRL_PT_OP_START_CALIB, /**< Start Sensor Calibration Operation Code.*/ 138 CSCS_CTRL_PT_OP_UPD_LOC, /**< Update Sensor Location Operation Code.*/ 139 CSCS_CTRL_PT_OP_REQ_SUP_LOC, /**< Request Supported Sensor Locations Operation Code.*/ 140 CSCS_CTRL_PT_OP_RSP_CODE = 0x10, /**< Response code. */ 141 } cscs_ctrl_pt_op_code_t; 142 143 /**@brief Cycling Speed and Cadence Service Control Point Response value.*/ 144 typedef enum { 145 CSCS_CTRL_PT_RSP_RESERVED, /**< Reserved value. */ 146 CSCS_CTRL_PT_RSP_SUCCESS, /**< Operation Success. */ 147 CSCS_CTRL_PT_RSP_NOT_SUP, /**< Operation Code Not Supported. */ 148 CSCS_CTRL_PT_RSP_INVALID_PARAM, /**< Invalid Parameter. */ 149 CSCS_CTRL_PT_RSP_FAILED /**< Operation Failed. */ 150 } cscs_ctrl_pt_rsp_t; 151 152 /**@brief Cycling Speed and Cadence Service event type.*/ 153 typedef enum { 154 CSCS_EVT_INVALID, /**< Indicate that invalid event. */ 155 CSCS_EVT_CSC_MEAS_NOTIFICATION_ENABLE, /**< Indicate that CSC Measurement notification has been enabled. */ 156 CSCS_EVT_CSC_MEAS_NOTIFICATION_DISABLE, /**< Indicate that CSC Measurement notification has been disabled. */ 157 CSCS_EVT_CTRL_POINT_INDICATION_ENABLE, /**< Indicate that SC Control Point indication has been enabled. */ 158 CSCS_EVT_CTRL_POINT_INDICATION_DISABLE, /**< Indicate that SC Control Point indication has been disabled. */ 159 CSCS_EVT_CSC_MEAS_SEND_CPLT, /**< Indicate that CSC Measurement has been notified. */ 160 CSCS_EVT_CUMUL_VAL_SET, /**< Indicate that Wheel Revolution Data needs to be set. */ 161 CSCS_EVT_SEBSOR_CALIBRATION, /**< Indicate that Sensor calibration procedure should be initiated. */ 162 CSCS_EVT_SEBSOR_LOC_UPD, /**< Indicate that Sensor Location needs to be reset. */ 163 CSCS_EVT_SUP_SEBSOR_LOC_REQ, /**< Indicate that request supported sensor location list. */ 164 CSCS_EVT_CTRL_POINT_RSP_CPLT /**< Indicate that SC Control Point response has been indicated. */ 165 } cscs_evt_type_t; 166 /** @} */ 167 168 /** 169 * @defgroup CSCS_STRUCT Structures 170 * @{ 171 */ 172 /**@brief Cycling Speed and Cadence Service event. */ 173 typedef struct { 174 cscs_evt_type_t evt_type; /**< The CSCS event type. */ 175 uint8_t conn_idx; /**< The index of the connection. */ 176 const uint8_t *p_data; /**< Pointer to event data. */ 177 uint16_t length; /**< Length of event data. */ 178 } cscs_evt_t; 179 /** @} */ 180 181 /** 182 * @defgroup CSCS_TYPEDEF Typedefs 183 * @{ 184 */ 185 /**@brief Cycling Speed and Cadence Service event handler type.*/ 186 typedef void (*cscs_evt_handler_t)(cscs_evt_t *p_evt); 187 /** @} */ 188 189 /** 190 * @defgroup CSCS_STRUCT Structures 191 * @{ 192 */ 193 /**@brief Cycling Speed and Cadence Measurement Character value structure. */ 194 typedef struct { 195 bool wheel_rev_data_present; /**< If Wheel Revolution Data is present. */ 196 bool crank_rev_data_present; /**< If Crank Revolution Data is present. */ 197 uint32_t cumulative_wheel_revs; /**< Cumulative Wheel Revolutions. */ 198 uint16_t last_wheel_event_time; /**< Last Wheel Event Time. */ 199 uint16_t cumulative_crank_revs; /**< Cumulative Crank Revolutions. */ 200 uint16_t last_crank_event_time; /**< Last Crank Event Time. */ 201 } cscs_meas_val_t; 202 203 /**@brief Cycling Speed and Cadence Service init stucture. 204 * This contains all option and data needed for initialization of the service. */ 205 typedef struct { 206 cscs_evt_handler_t evt_handler; /**< Cycling Speed and Cadence Service event handler. */ 207 uint16_t 208 char_mask; /**< Initial mask of supported characteristics, \ 209 and configured with \ref CSCS_CHAR_MASK. */ 210 cscs_sensor_loc_t sensor_location; /**< Initial sensor location. */ 211 uint16_t feature; /**< Initial value for features. */ 212 } cscs_init_t; 213 /** @} */ 214 215 /** 216 * @defgroup RSCS_FUNCTION Functions 217 * @{ 218 */ 219 /** 220 ***************************************************************************************** 221 * @brief Initialize a Cycling Speed and Cadence Service instance and add in the DB. 222 * 223 * @param[in] p_cscs_init: Pointer to cscs_init_t Service initialization variable 224 * 225 * @return Result of service initialization. 226 ***************************************************************************************** 227 */ 228 sdk_err_t cscs_service_init(cscs_init_t *p_cscs_init); 229 230 /** 231 ***************************************************************************************** 232 * @brief Send CSC measurement if notification has been enabled. 233 * 234 * @param[in] conn_idx: Connnection index. 235 * @param[in] p_meas: The pointer to new Cycling Speed and Cadence measurement. 236 * 237 * @return Result of notify value 238 ***************************************************************************************** 239 */ 240 sdk_err_t cscs_measurement_send(uint8_t conn_idx, cscs_meas_val_t *p_meas); 241 242 /** 243 ***************************************************************************************** 244 * @brief Send SC Control Point responce if indication has been enabled. 245 * 246 * @param[in] conn_idx: Connnection index. 247 * @param[in] p_data: Pointer to data. 248 * @param[in] length: Length of data. 249 * 250 * @return Result of indicate value 251 ***************************************************************************************** 252 */ 253 sdk_err_t cscs_ctrl_pt_rsp_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length); 254 255 /** 256 ***************************************************************************************** 257 * @brief Update Sensor Location if Multiple Sensor Locations Supported \ref cscs_init_t.feature. 258 * 259 * @param[in] sensor_loc: New sensor location. 260 * 261 * @return Result of update. 262 ***************************************************************************************** 263 */ 264 sdk_err_t cscs_sensor_loc_update(cscs_sensor_loc_t sensor_loc); 265 /** @} */ 266 267 #endif 268 /** @} */ 269 /** @} */ 270 271