cscs.h
Go to the documentation of this file.
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 "gr_includes.h"
62 #include "custom_config.h"
63 #include <stdint.h>
64 #include <stdbool.h>
65
66 /**
67 * @defgroup CSCS_MACRO Defines
68 * @{
69 */
70 #define CSCS_CONNECTION_MAX 10 /**< Maximum number of CSCS connections. */
71 #define CSCS_MEAS_VAL_LEN_MAX 20 /**< Maximum length of CSC Measurment value. */
72 #define CSCS_FEAT_VAL_LEN_MAX 2 /**< Maximum length of CSC Feature value. */
73 #define CSCS_SENSOR_LOC_VAL_LEN_MAX 1 /**< Maximum length of Sensor Location value. */
74 #define CSCS_CTRL_PT_RSP_LEN_MIN 3 /**< Mimimum length of SC Control Point response value. */
75 #define CSCS_CTRL_PT_VAL_LEN_MAX (CSCS_CTRL_PT_RSP_LEN_MIN + CSCS_SENSOR_LOC_SUP_NB) /**< Maximum length of SC Control Point value. */
76
77 #define CSCS_ERROR_PROC_IN_PROGRESS 0x80 /**< Error code: A previously triggered SC Control Point operation is still in progress. */
78 #define CSCS_ERROR_CCCD_INVALID 0x81 /**< Error code: The Client Characteristic Configuration descriptor is not configured. */
79
80 /**
81 * @defgroup CSCS_CHAR_MASK Characteristics Mask
82 * @{
83 * @brief Bit masks for the initialization of \ref cscs_init_t.char_mask.
84 */
85 #define CSCS_CHAR_MANDATORY 0x003f /**< Bit mask for mandatory characteristic in CSCS. */
86 #define CSCS_CHAR_SENSOR_LOC_SUP 0x00c0 /**< Bit mask for Sensor Location characteristic that is optional. */
87 #define CSCS_CHAR_SC_CTRL_POINT 0x0700 /**< Bit mask for SC Control Point characteristic that is optional. */
88 #define CSCS_CHAR_FULL 0x07ff /**< Bit mask of the full characteristic. */
89 /** @} */
90
91 /**
92 * @defgroup CSCS_MEAS_FLAG_BIT Measurement Flag Bits
93 * @{
94 * @brief Cycling Speed and Cadence Measurement Flags.
95 */
96 #define CSCS_MEAS_FLAG_WHEEL_REVOLUTION_BIT (0x01 << 0) /**< Flag bit for Wheel Revolution Data Present. */
97 #define CSCS_MEAS_FLAG_CRANK_REVOLUTION_BIT (0x01 << 1) /**< Flag bit for Crank Revolution Data Present. */
98 /** @} */
99
100 /**
101 * @defgroup CSCS_FEAT_BIT Feature Bits
102 * @{
103 * @brief Cycling Speed and Cadence Service feature bits.
104 */
105 #define CSCS_FEAT_WHEEL_REVOLUTION_SUP_BIT (0x01 << 0) /**< Bit for Wheel Revolution Data Supported. */
106 #define CSCS_FEAT_CRANK_REVOLUTION_SUP_BIT (0x01 << 1) /**< Bit for Crank Revolution Data Supported. */
107 #define CSCS_FEAT_MULTIPLE_SENSORS_BIT (0x01 << 2) /**< Bit for Multiple Sensor Locations Supported. */
108 #define CSCS_FEAR_FULL_BIT (0x07) /**< Bit for all CSC features Supported. */
109 /** @} */
110 /** @} */
111
112 /**
113 * @defgroup CSCS_ENUM Enumerations
114 * @{
115 */
116 /**@brief Cycling Speed and Cadence Service Sensor Location. */
117 typedef enum
118 {
119 CSCS_SENSOR_LOC_OTHER, /**< Sensor location: other. */
120 CSCS_SENSOR_LOC_SHOE_TOP, /**< Sensor location: top of shoe. */
121 CSCS_SENSOR_LOC_SHOE_IN, /**< Sensor location: inside of shoe. */
122 CSCS_SENSOR_LOC_HIP, /**< Sensor location: hip. */
123 CSCS_SENSOR_LOC_FRONT_WHEEL, /**< Sensor location: front wheel. */
124 CSCS_SENSOR_LOC_LEFT_PEDAL, /**< Sensor location: left pedal. */
125 CSCS_SENSOR_LOC_RIGHT_PEDAL, /**< Sensor location: right pedal. */
126 CSCS_SENSOR_LOC_FRONT_HUB, /**< Sensor location: front hub. */
127 CSCS_SENSOR_LOC_SUP_NB /**< Number of sensor location. */
128 } cscs_sensor_loc_t;
129
130 /**@brief Cycling Speed and Cadence Service Control Point Operation Code.*/
131 typedef enum
132 {
133 CSCS_CTRL_PT_OP_RESERVED, /**< Reserved for future use. */
134 CSCS_CTRL_PT_OP_SET_CUMUL_VAL, /**< Set Cumulative value Operation Code.*/
135 CSCS_CTRL_PT_OP_START_CALIB, /**< Start Sensor Calibration Operation Code.*/
136 CSCS_CTRL_PT_OP_UPD_LOC, /**< Update Sensor Location Operation Code.*/
137 CSCS_CTRL_PT_OP_REQ_SUP_LOC, /**< Request Supported Sensor Locations Operation Code.*/
138 CSCS_CTRL_PT_OP_RSP_CODE = 0x10, /**< Response code. */
139 } cscs_ctrl_pt_op_code_t;
140
141 /**@brief Cycling Speed and Cadence Service Control Point Response value.*/
142 typedef enum
143 {
144 CSCS_CTRL_PT_RSP_RESERVED, /**< Reserved value. */
145 CSCS_CTRL_PT_RSP_SUCCESS, /**< Operation Success. */
146 CSCS_CTRL_PT_RSP_NOT_SUP, /**< Operation Code Not Supported. */
147 CSCS_CTRL_PT_RSP_INVALID_PARAM, /**< Invalid Parameter. */
148 CSCS_CTRL_PT_RSP_FAILED /**< Operation Failed. */
149 } cscs_ctrl_pt_rsp_t;
150
151 /**@brief Cycling Speed and Cadence Service event type.*/
152 typedef enum
153 {
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 {
175 cscs_evt_type_t evt_type; /**< The CSCS event type. */
176 uint8_t conn_idx; /**< The index of the connection. */
177 const uint8_t *p_data; /**< Pointer to event data. */
178 uint16_t length; /**< Length of event data. */
179 } cscs_evt_t;
180 /** @} */
181
182 /**
183 * @defgroup CSCS_TYPEDEF Typedefs
184 * @{
185 */
186 /**@brief Cycling Speed and Cadence Service event handler type.*/
187 typedef void (*cscs_evt_handler_t)(cscs_evt_t *p_evt);
188 /** @} */
189
190 /**
191 * @defgroup CSCS_STRUCT Structures
192 * @{
193 */
194 /**@brief Cycling Speed and Cadence Measurement Character value structure. */
195 typedef struct
196 {
197 bool wheel_rev_data_present; /**< If Wheel Revolution Data is present. */
198 bool crank_rev_data_present; /**< If Crank Revolution Data is present. */
199 uint32_t cumulative_wheel_revs; /**< Cumulative Wheel Revolutions. */
200 uint16_t last_wheel_event_time; /**< Last Wheel Event Time. */
201 uint16_t cumulative_crank_revs; /**< Cumulative Crank Revolutions. */
202 uint16_t last_crank_event_time; /**< Last Crank Event Time. */
203 } cscs_meas_val_t;
204
205 /**@brief Cycling Speed and Cadence Service init stucture. This contains all option and data needed for initialization of the service. */
206 typedef struct
207 {
208 cscs_evt_handler_t evt_handler; /**< Cycling Speed and Cadence Service event handler. */
209 uint16_t char_mask; /**< Initial mask of supported characteristics, 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
CSCS_SENSOR_LOC_SHOE_TOP
@ CSCS_SENSOR_LOC_SHOE_TOP
Sensor location: top of shoe.
Definition: cscs.h:120
CSCS_CTRL_PT_RSP_RESERVED
@ CSCS_CTRL_PT_RSP_RESERVED
Reserved value.
Definition: cscs.h:144
cscs_evt_t::p_data
const uint8_t * p_data
Pointer to event data.
Definition: cscs.h:177
CSCS_EVT_CSC_MEAS_NOTIFICATION_ENABLE
@ CSCS_EVT_CSC_MEAS_NOTIFICATION_ENABLE
Indicate that CSC Measurement notification has been enabled.
Definition: cscs.h:155
cscs_meas_val_t::cumulative_wheel_revs
uint32_t cumulative_wheel_revs
Cumulative Wheel Revolutions.
Definition: cscs.h:199
cscs_init_t::char_mask
uint16_t char_mask
Initial mask of supported characteristics, and configured with Characteristics Mask.
Definition: cscs.h:209
CSCS_CTRL_PT_RSP_SUCCESS
@ CSCS_CTRL_PT_RSP_SUCCESS
Operation Success.
Definition: cscs.h:145
cscs_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: cscs.h:176
CSCS_SENSOR_LOC_RIGHT_PEDAL
@ CSCS_SENSOR_LOC_RIGHT_PEDAL
Sensor location: right pedal.
Definition: cscs.h:125
CSCS_CTRL_PT_RSP_NOT_SUP
@ CSCS_CTRL_PT_RSP_NOT_SUP
Operation Code Not Supported.
Definition: cscs.h:146
cscs_ctrl_pt_op_code_t
cscs_ctrl_pt_op_code_t
Cycling Speed and Cadence Service Control Point Operation Code.
Definition: cscs.h:132
cscs_ctrl_pt_rsp_send
sdk_err_t cscs_ctrl_pt_rsp_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send SC Control Point responce if indication has been enabled.
cscs_measurement_send
sdk_err_t cscs_measurement_send(uint8_t conn_idx, cscs_meas_val_t *p_meas)
Send CSC measurement if notification has been enabled.
cscs_meas_val_t::crank_rev_data_present
bool crank_rev_data_present
If Crank Revolution Data is present.
Definition: cscs.h:198
cscs_meas_val_t
Cycling Speed and Cadence Measurement Character value structure.
Definition: cscs.h:196
gr_includes.h
Include Files API.
cscs_evt_type_t
cscs_evt_type_t
Cycling Speed and Cadence Service event type.
Definition: cscs.h:153
CSCS_CTRL_PT_OP_REQ_SUP_LOC
@ CSCS_CTRL_PT_OP_REQ_SUP_LOC
Request Supported Sensor Locations Operation Code.
Definition: cscs.h:137
CSCS_CTRL_PT_RSP_INVALID_PARAM
@ CSCS_CTRL_PT_RSP_INVALID_PARAM
Invalid Parameter.
Definition: cscs.h:147
CSCS_SENSOR_LOC_HIP
@ CSCS_SENSOR_LOC_HIP
Sensor location: hip.
Definition: cscs.h:122
cscs_meas_val_t::cumulative_crank_revs
uint16_t cumulative_crank_revs
Cumulative Crank Revolutions.
Definition: cscs.h:201
cscs_init_t::sensor_location
cscs_sensor_loc_t sensor_location
Initial sensor location.
Definition: cscs.h:210
CSCS_SENSOR_LOC_FRONT_HUB
@ CSCS_SENSOR_LOC_FRONT_HUB
Sensor location: front hub.
Definition: cscs.h:126
CSCS_CTRL_PT_RSP_FAILED
@ CSCS_CTRL_PT_RSP_FAILED
Operation Failed.
Definition: cscs.h:148
CSCS_SENSOR_LOC_FRONT_WHEEL
@ CSCS_SENSOR_LOC_FRONT_WHEEL
Sensor location: front wheel.
Definition: cscs.h:123
cscs_ctrl_pt_rsp_t
cscs_ctrl_pt_rsp_t
Cycling Speed and Cadence Service Control Point Response value.
Definition: cscs.h:143
cscs_sensor_loc_update
sdk_err_t cscs_sensor_loc_update(cscs_sensor_loc_t sensor_loc)
Update Sensor Location if Multiple Sensor Locations Supported cscs_init_t::feature.
cscs_evt_handler_t
void(* cscs_evt_handler_t)(cscs_evt_t *p_evt)
Cycling Speed and Cadence Service event handler type.
Definition: cscs.h:187
cscs_init_t::feature
uint16_t feature
Initial value for features.
Definition: cscs.h:211
CSCS_CTRL_PT_OP_RESERVED
@ CSCS_CTRL_PT_OP_RESERVED
Reserved for future use.
Definition: cscs.h:133
CSCS_SENSOR_LOC_LEFT_PEDAL
@ CSCS_SENSOR_LOC_LEFT_PEDAL
Sensor location: left pedal.
Definition: cscs.h:124
CSCS_EVT_CTRL_POINT_INDICATION_DISABLE
@ CSCS_EVT_CTRL_POINT_INDICATION_DISABLE
Indicate that SC Control Point indication has been disabled.
Definition: cscs.h:158
cscs_init_t::evt_handler
cscs_evt_handler_t evt_handler
Cycling Speed and Cadence Service event handler.
Definition: cscs.h:208
cscs_sensor_loc_t
cscs_sensor_loc_t
Cycling Speed and Cadence Service Sensor Location.
Definition: cscs.h:118
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
CSCS_EVT_CTRL_POINT_INDICATION_ENABLE
@ CSCS_EVT_CTRL_POINT_INDICATION_ENABLE
Indicate that SC Control Point indication has been enabled.
Definition: cscs.h:157
CSCS_CTRL_PT_OP_RSP_CODE
@ CSCS_CTRL_PT_OP_RSP_CODE
Response code.
Definition: cscs.h:138
CSCS_EVT_INVALID
@ CSCS_EVT_INVALID
Indicate that invalid event.
Definition: cscs.h:154
cscs_init_t
Cycling Speed and Cadence Service init stucture.
Definition: cscs.h:207
CSCS_EVT_CTRL_POINT_RSP_CPLT
@ CSCS_EVT_CTRL_POINT_RSP_CPLT
Indicate that SC Control Point response has been indicated.
Definition: cscs.h:164
CSCS_EVT_CSC_MEAS_SEND_CPLT
@ CSCS_EVT_CSC_MEAS_SEND_CPLT
Indicate that CSC Measurement has been notified.
Definition: cscs.h:159
cscs_meas_val_t::last_wheel_event_time
uint16_t last_wheel_event_time
Last Wheel Event Time.
Definition: cscs.h:200
cscs_evt_t::evt_type
cscs_evt_type_t evt_type
The CSCS event type.
Definition: cscs.h:175
cscs_meas_val_t::last_crank_event_time
uint16_t last_crank_event_time
Last Crank Event Time.
Definition: cscs.h:202
CSCS_SENSOR_LOC_SUP_NB
@ CSCS_SENSOR_LOC_SUP_NB
Number of sensor location.
Definition: cscs.h:127
cscs_service_init
sdk_err_t cscs_service_init(cscs_init_t *p_cscs_init)
Initialize a Cycling Speed and Cadence Service instance and add in the DB.
cscs_evt_t::length
uint16_t length
Length of event data.
Definition: cscs.h:178
CSCS_EVT_CSC_MEAS_NOTIFICATION_DISABLE
@ CSCS_EVT_CSC_MEAS_NOTIFICATION_DISABLE
Indicate that CSC Measurement notification has been disabled.
Definition: cscs.h:156
CSCS_SENSOR_LOC_SHOE_IN
@ CSCS_SENSOR_LOC_SHOE_IN
Sensor location: inside of shoe.
Definition: cscs.h:121
CSCS_EVT_SEBSOR_CALIBRATION
@ CSCS_EVT_SEBSOR_CALIBRATION
Indicate that Sensor calibration procedure should be initiated.
Definition: cscs.h:161
cscs_meas_val_t::wheel_rev_data_present
bool wheel_rev_data_present
If Wheel Revolution Data is present.
Definition: cscs.h:197
CSCS_CTRL_PT_OP_START_CALIB
@ CSCS_CTRL_PT_OP_START_CALIB
Start Sensor Calibration Operation Code.
Definition: cscs.h:135
CSCS_EVT_CUMUL_VAL_SET
@ CSCS_EVT_CUMUL_VAL_SET
Indicate that Wheel Revolution Data needs to be set.
Definition: cscs.h:160
CSCS_SENSOR_LOC_OTHER
@ CSCS_SENSOR_LOC_OTHER
Sensor location: other.
Definition: cscs.h:119
CSCS_EVT_SEBSOR_LOC_UPD
@ CSCS_EVT_SEBSOR_LOC_UPD
Indicate that Sensor Location needs to be reset.
Definition: cscs.h:162
CSCS_CTRL_PT_OP_UPD_LOC
@ CSCS_CTRL_PT_OP_UPD_LOC
Update Sensor Location Operation Code.
Definition: cscs.h:136
CSCS_EVT_SUP_SEBSOR_LOC_REQ
@ CSCS_EVT_SUP_SEBSOR_LOC_REQ
Indicate that request supported sensor location list.
Definition: cscs.h:163
CSCS_CTRL_PT_OP_SET_CUMUL_VAL
@ CSCS_CTRL_PT_OP_SET_CUMUL_VAL
Set Cumulative value Operation Code.
Definition: cscs.h:134
cscs_evt_t
Cycling Speed and Cadence Service event.
Definition: cscs.h:174