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