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