ble_cscs.h

00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  *
00011  */
00012 
00013 /** @file
00014  *
00015  * @defgroup ble_sdk_srv_csc Cycling Speed and Cadence Service
00016  * @{
00017  * @ingroup ble_sdk_srv
00018  * @brief Cycling Speed and Cadence Service module.
00019  *
00020  * @details This module implements the Cycling Speed and Cadence Service. If enabled, notification
00021  *          of the Cycling Speead and Candence Measurement is performed when the application
00022  *          calls ble_cscs_measurement_send().
00023  *
00024  *          To use this service, you need to provide the the supported features (@ref BLE_CSCS_FEATURES).
00025  *          If you choose to support Wheel revolution data (feature bit @ref BLE_CSCS_FEATURE_WHEEL_REV_BIT), 
00026  *          you then need to support the 'setting of cumulative value' operation by the supporting the 
00027  *          Speed and Cadence Control Point (@ref ble_sdk_srv_sc_ctrlpt) by setting the @ref BLE_SRV_SC_CTRLPT_CUM_VAL_OP_SUPPORTED
00028  *          bit of the ctrplt_supported_functions in the @ref ble_cscs_init_t structure.
00029  *          If you want to support the 'start autocalibration' control point feature, you need, after the @ref BLE_SC_CTRLPT_EVT_START_CALIBRATION
00030  *          has been received and the auto calibration is finished, to call the @ref ble_sc_ctrlpt_rsp_send to indicate that the operation is finished
00031  *          and thus be able to receive new control point operations.
00032  *          If you want to support the 'sensor location' related operation, you need to provide a list of supported location in the 
00033  *          @ref ble_cscs_init_t structure.
00034  *          
00035  *
00036  * @note The application or the service using this module must propagate BLE stack events to the 
00037  *       Cycling Speead and Candence Service module by calling ble_cscs_on_ble_evt() from the 
00038  *       from the @ref ble_stack_handler function. This service will forward the event to the @ref ble_sdk_srv_sc_ctrlpt module.
00039  *
00040  * @note Attention! 
00041  *  To maintain compliance with Nordic Semiconductor ASA Bluetooth profile 
00042  *  qualification listings, this section of source code must not be modified.
00043  */
00044 
00045 #ifndef BLE_CSCS_H__
00046 #define BLE_CSCS_H__
00047 
00048 #include <stdint.h>
00049 #include <stdbool.h>
00050 #include "ble.h"
00051 #include "ble_srv_common.h "
00052 #include "ble_sc_ctrlpt.h "
00053 #include "ble_sensor_location.h"
00054 
00055 /** @defgroup BLE_CSCS_FEATURES Cycling Speed and Cadence Service feature bits
00056  * @{ */
00057 #define BLE_CSCS_FEATURE_WHEEL_REV_BIT                  (0x01 << 0)     /**< Wheel Revolution Data Supported bit. */
00058 #define BLE_CSCS_FEATURE_CRANK_REV_BIT                  (0x01 << 1)     /**< Crank Revolution Data Supported bit. */
00059 #define BLE_CSCS_FEATURE_MULTIPLE_SENSORS_BIT           (0x01 << 2)     /**< Multiple Sensor Locations Supported bit. */
00060 /** @} */
00061 
00062 /**@brief Cycling Speed and Cadence Service event type. */
00063 typedef enum
00064 {
00065     BLE_CSCS_EVT_NOTIFICATION_ENABLED,                                  /**< Cycling Speed and Cadence value notification enabled event. */
00066     BLE_CSCS_EVT_NOTIFICATION_DISABLED                                  /**< Cycling Speed and Cadence value notification disabled event. */
00067 } ble_cscs_evt_type_t;
00068 
00069 /**@brief Cycling Speed and Cadence Service event. */
00070 typedef struct
00071 {
00072     ble_cscs_evt_type_t evt_type;                                       /**< Type of event. */
00073 } ble_cscs_evt_t;
00074 
00075 // Forward declaration of the ble_csc_t type. 
00076 typedef struct ble_cscs_s ble_cscs_t;
00077 
00078 /**@brief Cycling Speed and Cadence Service event handler type. */
00079 typedef void (*ble_cscs_evt_handler_t) (ble_cscs_t * p_cscs, ble_cscs_evt_t * p_evt);
00080 
00081 /**@brief Cycling Speed and Cadence Service init structure. This contains all options and data
00082 *         needed for initialization of the service. */
00083 typedef struct
00084 {
00085     ble_cscs_evt_handler_t       evt_handler;                           /**< Event handler to be called for handling events in the Cycling Speed and Cadence Service. */
00086     ble_srv_cccd_security_mode_t csc_meas_attr_md;                      /**< Initial security level for cycling speed and cadence measurement attribute */
00087     ble_srv_cccd_security_mode_t csc_ctrlpt_attr_md;                    /**< Initial security level for cycling speed and cadence control point attribute */
00088     ble_srv_security_mode_t      csc_feature_attr_md;                   /**< Initial security level for feature attribute */
00089     uint16_t                     feature;                               /**< Initial value for features of sensor @ref BLE_CSCS_FEATURES. */
00090     uint8_t                      ctrplt_supported_functions;            /**< Supported control point functionnalities see @ref BLE_SRV_SC_CTRLPT_SUPP_FUNC. */
00091     ble_sc_ctrlpt_evt_handler_t  ctrlpt_evt_handler;                    /**< Event handler */
00092     ble_sensor_location_t        *list_supported_locations;             /**< List of supported sensor locations.*/
00093     uint8_t                      size_list_supported_locations;         /**< Number of supported sensor locations in the list.*/
00094     ble_srv_error_handler_t      error_handler;                         /**< Function to be called in case of an error. */
00095     ble_sensor_location_t        *sensor_location;                      /**< Initial Sensor Location, if NULL, sensor_location characteristic is not added*/
00096     ble_srv_cccd_security_mode_t csc_sensor_loc_attr_md;                /**< Initial security level for sensor location attribute */
00097 } ble_cscs_init_t;
00098 
00099 /**@brief Cycling Speed and Cadence Service structure. This contains various status information for
00100  *        the service. */
00101 typedef struct ble_cscs_s
00102 {
00103     ble_cscs_evt_handler_t       evt_handler;                           /**< Event handler to be called for handling events in the Cycling Speed and Cadence Service. */
00104     uint16_t                     service_handle;                        /**< Handle of Cycling Speed and Cadence Service (as provided by the BLE stack). */
00105     ble_gatts_char_handles_t     meas_handles;                          /**< Handles related to the Cycling Speed and Cadence Measurement characteristic. */
00106     ble_gatts_char_handles_t     feature_handles;                       /**< Handles related to the Cycling Speed and Cadence feature characteristic. */
00107     ble_gatts_char_handles_t     sensor_loc_handles;                    /**< Handles related to the Cycling Speed and Cadence Sensor Location characteristic. */
00108     uint16_t                     conn_handle;                           /**< Handle of the current connection (as provided by the BLE stack, is BLE_CONN_HANDLE_INVALID if not in a connection). */
00109     uint16_t                     feature;                               /**< Bit mask of features available on sensor. */
00110     ble_sc_ctrlpt_t              ctrl_pt;                               /**< data for speed and cadence control point */
00111 } ble_cscs_t;
00112 
00113 /**@brief Cycling Speed and Cadence Service measurement structure. This contains a Cycling Speed and
00114  *        Cadence Service measurement. */
00115 typedef struct ble_cscs_meas_s
00116 {
00117     bool        is_wheel_rev_data_present;                              /**< True if Wheel Revolution Data is present in the measurement. */
00118     bool        is_crank_rev_data_present;                              /**< True if Crank Revolution Data is present in the measurement. */
00119     uint32_t    cumulative_wheel_revs;                                  /**< Cumulative Wheel Revolutions. */
00120     uint16_t    last_wheel_event_time;                                  /**< Last Wheel Event Time. */
00121     uint16_t    cumulative_crank_revs;                                  /**< Cumulative Crank Revolutions. */
00122     uint16_t    last_crank_event_time;                                  /**< Last Crank Event Time. */
00123 } ble_cscs_meas_t;
00124 
00125 /**@brief Function for initializing the Cycling Speed and Cadence Service.
00126  *
00127  * @param[out]  p_cscs      Cycling Speed and Cadence Service structure. This structure will have to
00128  *                          be supplied by the application. It will be initialized by this function,
00129  *                          and will later be used to identify this particular service instance.
00130  * @param[in]   p_cscs_init Information needed to initialize the service.
00131  *
00132  * @return      NRF_SUCCESS on successful initialization of service, otherwise an error code.
00133  */
00134 uint32_t ble_cscs_init(ble_cscs_t * p_cscs, const ble_cscs_init_t * p_cscs_init);
00135 
00136 /**@brief Function for handling the Application's BLE Stack events.
00137  *
00138  * @details Handles all events from the BLE stack of interest to the Cycling Speed and Cadence
00139  *          Service.
00140  *
00141  * @param[in]   p_cscs     Cycling Speed and Cadence Service structure.
00142  * @param[in]   p_ble_evt  Event received from the BLE stack.
00143  */
00144 void ble_cscs_on_ble_evt(ble_cscs_t * p_cscs, ble_evt_t * p_ble_evt);
00145 
00146 /**@brief Function for sending cycling speed and cadence measurement if notification has been enabled.
00147  *
00148  * @details The application calls this function after having performed a Cycling Speed and Cadence
00149  *          Service measurement. If notification has been enabled, the measurement data is encoded
00150  *          and sent to the client.
00151  *
00152  * @param[in]   p_cscs         Cycling Speed and Cadence Service structure.
00153  * @param[in]   p_measurement  Pointer to new cycling speed and cadence measurement.
00154  *
00155  * @return      NRF_SUCCESS on success, otherwise an error code.
00156  */
00157 uint32_t ble_cscs_measurement_send(ble_cscs_t * p_cscs, ble_cscs_meas_t * p_measurement);
00158 
00159 #endif // BLE_CSCS_H__
00160 
00161 /** @} */