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