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