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. */
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. */
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. */
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. */
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. */
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  */
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  */
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  */
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
Reserved for future use.
Definition: rscs.h:137
RSCS_CTRL_PT_OP_START_CALIB
@ RSCS_CTRL_PT_OP_START_CALIB
Start Sensor Calibration Operation Code.
Definition: rscs.h:139
RSCS_EVT_CTRL_POINT_INDICATION_DISABLE
@ RSCS_EVT_CTRL_POINT_INDICATION_DISABLE
Indicate that SC Control Point indication has been disabled.
Definition: rscs.h:162
rscs_init_t
Running Speed and Cadence Service init stucture.
Definition: rscs.h:212
rscs_meas_val_t::inst_stride_length_present
bool inst_stride_length_present
If Instantaneous Stride Length is present.
Definition: rscs.h:188
RSCS_CTRL_PT_RSP_FAILED
@ RSCS_CTRL_PT_RSP_FAILED
Operation Failed.
Definition: rscs.h:152
rscs_init_t::sensor_location
rscs_sensor_loc_t sensor_location
Initial sensor location.
Definition: rscs.h:215
rscs_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: rscs.h:180
rscs_evt_t::evt_type
rscs_evt_type_t evt_type
The RSCS event type.
Definition: rscs.h:179
RSCS_SENSOR_LOC_HIP
@ RSCS_SENSOR_LOC_HIP
Sensor location: 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
Operation Code Not Supported.
Definition: rscs.h:150
RSCS_SENSOR_LOC_OTHER
@ RSCS_SENSOR_LOC_OTHER
Sensor location: 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
Sensor location: left pedal.
Definition: rscs.h:128
RSCS_EVT_CUMUL_VAL_SET
@ RSCS_EVT_CUMUL_VAL_SET
Indicate that Total Distance value needs to be set.
Definition: rscs.h:164
rscs_meas_val_t::inst_speed
uint16_t inst_speed
Instantaneous Speed.
Definition: rscs.h:191
rscs_meas_val_t::is_run_or_walk
bool is_run_or_walk
True: Running, False: Walking.
Definition: rscs.h:190
RSCS_CTRL_PT_OP_UPD_LOC
@ RSCS_CTRL_PT_OP_UPD_LOC
Update Sensor Location Operation Code.
Definition: rscs.h:140
RSCS_EVT_CTRL_POINT_RSP_CPLT
@ RSCS_EVT_CTRL_POINT_RSP_CPLT
Indicate that SC Control Point response has been indicated.
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
Indicate that Sensor calibration procedure should be initiated.
Definition: rscs.h:165
rscs_init_t::evt_handler
rscs_evt_handler_t evt_handler
Running Speed and Cadence Service event handler.
Definition: rscs.h:213
RSCS_CTRL_PT_OP_SET_CUMUL_VAL
@ RSCS_CTRL_PT_OP_SET_CUMUL_VAL
Set Cumulative value Operation Code.
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
Sensor location: inside of shoe.
Definition: rscs.h:125
RSCS_SENSOR_LOC_FRONT_HUB
@ RSCS_SENSOR_LOC_FRONT_HUB
Sensor location: front hub.
Definition: rscs.h:130
rscs_meas_val_t::inst_cadence
uint8_t inst_cadence
Instantaneous Cadence.
Definition: rscs.h:192
RSCS_CTRL_PT_OP_REQ_SUP_LOC
@ RSCS_CTRL_PT_OP_REQ_SUP_LOC
Request Supported Sensor Locations Operation Code.
Definition: rscs.h:141
RSCS_EVT_SEBSOR_LOC_UPD
@ RSCS_EVT_SEBSOR_LOC_UPD
Indicate that Sensor Location needs to be reset.
Definition: rscs.h:166
RSCS_EVT_CTRL_POINT_INDICATION_ENABLE
@ RSCS_EVT_CTRL_POINT_INDICATION_ENABLE
Indicate that SC Control Point indication has been enabled.
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
Sensor location: top of shoe.
Definition: rscs.h:124
RSCS_CTRL_PT_RSP_INVALID_PARAM
@ RSCS_CTRL_PT_RSP_INVALID_PARAM
Invalid Parameter.
Definition: rscs.h:151
RSCS_EVT_RSC_MEAS_SEND_CPLT
@ RSCS_EVT_RSC_MEAS_SEND_CPLT
Indicate that RSC Measurement has been notified.
Definition: rscs.h:163
rscs_meas_val_t::inst_stride_length
uint16_t inst_stride_length
Instantaneous Stride Length.
Definition: rscs.h:193
RSCS_EVT_INVALID
@ RSCS_EVT_INVALID
Indicate that invalid event.
Definition: rscs.h:158
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
RSCS_SENSOR_LOC_FRONT_WHEEL
@ RSCS_SENSOR_LOC_FRONT_WHEEL
Sensor location: 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
Total Distance.
Definition: rscs.h:194
RSCS_SENSOR_LOC_RIGHT_PEDAL
@ RSCS_SENSOR_LOC_RIGHT_PEDAL
Sensor location: right pedal.
Definition: rscs.h:129
RSCS_SENSOR_LOC_SUP_NB
@ RSCS_SENSOR_LOC_SUP_NB
Number of sensor location.
Definition: rscs.h:131
RSCS_CTRL_PT_RSP_RESERVED
@ RSCS_CTRL_PT_RSP_RESERVED
Reserved value.
Definition: rscs.h:148
rscs_init_t::char_mask
uint16_t char_mask
Initial mask of supported characteristics, and configured with Characteristics Mask.
Definition: rscs.h:214
RSCS_CTRL_PT_RSP_SUCCESS
@ RSCS_CTRL_PT_RSP_SUCCESS
Operation Succeeded.
Definition: rscs.h:149
RSCS_EVT_SUP_SEBSOR_LOC_REQ
@ RSCS_EVT_SUP_SEBSOR_LOC_REQ
Indicate that request supported sensor location list.
Definition: rscs.h:167
RSCS_CTRL_PT_OP_RSP_CODE
@ RSCS_CTRL_PT_OP_RSP_CODE
Response code.
Definition: rscs.h:142
rscs_evt_t::length
uint16_t length
Length of event data.
Definition: rscs.h:182
rscs_meas_val_t::total_distance_present
bool total_distance_present
If Total Distance is present.
Definition: rscs.h:189
RSCS_EVT_RSC_MEAS_NOTIFICATION_ENABLE
@ RSCS_EVT_RSC_MEAS_NOTIFICATION_ENABLE
Indicate that RSC Measurement notification has been enabled.
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
Indicate that RSC Measurement notification has been disabled.
Definition: rscs.h:160
rscs_evt_t::p_data
const uint8_t * p_data
Pointer to event 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
Initial value for features.
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.