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. */
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. */
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. */
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. */
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. */
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  */
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  */
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  */
265 /** @} */
266 
267 #endif
268 /** @} */
269 /** @} */
270 
CSCS_SENSOR_LOC_SHOE_TOP
@ CSCS_SENSOR_LOC_SHOE_TOP
Definition: cscs.h:120
CSCS_CTRL_PT_RSP_RESERVED
@ CSCS_CTRL_PT_RSP_RESERVED
Definition: cscs.h:144
cscs_evt_t::p_data
const uint8_t * p_data
Definition: cscs.h:177
CSCS_EVT_CSC_MEAS_NOTIFICATION_ENABLE
@ CSCS_EVT_CSC_MEAS_NOTIFICATION_ENABLE
Definition: cscs.h:155
cscs_meas_val_t::cumulative_wheel_revs
uint32_t cumulative_wheel_revs
Definition: cscs.h:199
cscs_init_t::char_mask
uint16_t char_mask
Definition: cscs.h:209
CSCS_CTRL_PT_RSP_SUCCESS
@ CSCS_CTRL_PT_RSP_SUCCESS
Definition: cscs.h:145
cscs_evt_t::conn_idx
uint8_t conn_idx
Definition: cscs.h:176
CSCS_SENSOR_LOC_RIGHT_PEDAL
@ CSCS_SENSOR_LOC_RIGHT_PEDAL
Definition: cscs.h:125
CSCS_CTRL_PT_RSP_NOT_SUP
@ CSCS_CTRL_PT_RSP_NOT_SUP
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
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
Definition: cscs.h:137
CSCS_CTRL_PT_RSP_INVALID_PARAM
@ CSCS_CTRL_PT_RSP_INVALID_PARAM
Definition: cscs.h:147
CSCS_SENSOR_LOC_HIP
@ CSCS_SENSOR_LOC_HIP
Definition: cscs.h:122
cscs_meas_val_t::cumulative_crank_revs
uint16_t cumulative_crank_revs
Definition: cscs.h:201
cscs_init_t::sensor_location
cscs_sensor_loc_t sensor_location
Definition: cscs.h:210
CSCS_SENSOR_LOC_FRONT_HUB
@ CSCS_SENSOR_LOC_FRONT_HUB
Definition: cscs.h:126
CSCS_CTRL_PT_RSP_FAILED
@ CSCS_CTRL_PT_RSP_FAILED
Definition: cscs.h:148
CSCS_SENSOR_LOC_FRONT_WHEEL
@ CSCS_SENSOR_LOC_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
Definition: cscs.h:211
CSCS_CTRL_PT_OP_RESERVED
@ CSCS_CTRL_PT_OP_RESERVED
Definition: cscs.h:133
CSCS_SENSOR_LOC_LEFT_PEDAL
@ CSCS_SENSOR_LOC_LEFT_PEDAL
Definition: cscs.h:124
CSCS_EVT_CTRL_POINT_INDICATION_DISABLE
@ CSCS_EVT_CTRL_POINT_INDICATION_DISABLE
Definition: cscs.h:158
cscs_init_t::evt_handler
cscs_evt_handler_t evt_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:257
CSCS_EVT_CTRL_POINT_INDICATION_ENABLE
@ CSCS_EVT_CTRL_POINT_INDICATION_ENABLE
Definition: cscs.h:157
CSCS_CTRL_PT_OP_RSP_CODE
@ CSCS_CTRL_PT_OP_RSP_CODE
Definition: cscs.h:138
CSCS_EVT_INVALID
@ CSCS_EVT_INVALID
Definition: cscs.h:154
cscs_init_t
Cycling Speed and Cadence Service init stucture. This contains all option and data needed for initial...
Definition: cscs.h:207
CSCS_EVT_CTRL_POINT_RSP_CPLT
@ CSCS_EVT_CTRL_POINT_RSP_CPLT
Definition: cscs.h:164
CSCS_EVT_CSC_MEAS_SEND_CPLT
@ CSCS_EVT_CSC_MEAS_SEND_CPLT
Definition: cscs.h:159
cscs_meas_val_t::last_wheel_event_time
uint16_t last_wheel_event_time
Definition: cscs.h:200
cscs_evt_t::evt_type
cscs_evt_type_t evt_type
Definition: cscs.h:175
cscs_meas_val_t::last_crank_event_time
uint16_t last_crank_event_time
Definition: cscs.h:202
CSCS_SENSOR_LOC_SUP_NB
@ CSCS_SENSOR_LOC_SUP_NB
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
Definition: cscs.h:178
CSCS_EVT_CSC_MEAS_NOTIFICATION_DISABLE
@ CSCS_EVT_CSC_MEAS_NOTIFICATION_DISABLE
Definition: cscs.h:156
CSCS_SENSOR_LOC_SHOE_IN
@ CSCS_SENSOR_LOC_SHOE_IN
Definition: cscs.h:121
CSCS_EVT_SEBSOR_CALIBRATION
@ CSCS_EVT_SEBSOR_CALIBRATION
Definition: cscs.h:161
cscs_meas_val_t::wheel_rev_data_present
bool wheel_rev_data_present
Definition: cscs.h:197
CSCS_CTRL_PT_OP_START_CALIB
@ CSCS_CTRL_PT_OP_START_CALIB
Definition: cscs.h:135
CSCS_EVT_CUMUL_VAL_SET
@ CSCS_EVT_CUMUL_VAL_SET
Definition: cscs.h:160
CSCS_SENSOR_LOC_OTHER
@ CSCS_SENSOR_LOC_OTHER
Definition: cscs.h:119
CSCS_EVT_SEBSOR_LOC_UPD
@ CSCS_EVT_SEBSOR_LOC_UPD
Definition: cscs.h:162
CSCS_CTRL_PT_OP_UPD_LOC
@ CSCS_CTRL_PT_OP_UPD_LOC
Definition: cscs.h:136
CSCS_EVT_SUP_SEBSOR_LOC_REQ
@ CSCS_EVT_SUP_SEBSOR_LOC_REQ
Definition: cscs.h:163
CSCS_CTRL_PT_OP_SET_CUMUL_VAL
@ CSCS_CTRL_PT_OP_SET_CUMUL_VAL
Definition: cscs.h:134
cscs_evt_t
Cycling Speed and Cadence Service event.
Definition: cscs.h:174