ble_bas.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_bas Battery Service
00016  * @{
00017  * @ingroup ble_sdk_srv
00018  * @brief Battery Service module.
00019  *
00020  * @details This module implements the Battery Service with the Battery Level characteristic.
00021  *          During initialization it adds the Battery Service and Battery Level characteristic
00022  *          to the BLE stack database. Optionally it can also add a Report Reference descriptor
00023  *          to the Battery Level characteristic (used when including the Battery Service in
00024  *          the HID service).
00025  *
00026  *          If specified, the module will support notification of the Battery Level characteristic
00027  *          through the ble_bas_battery_level_update() function.
00028  *          If an event handler is supplied by the application, the Battery Service will
00029  *          generate Battery Service events to the application.
00030  *
00031  * @note The application must propagate BLE stack events to the Battery Service module by calling
00032  *       ble_bas_on_ble_evt() from the from the @ref ble_stack_handler callback.
00033  *
00034  * @note Attention! 
00035  *  To maintain compliance with Nordic Semiconductor ASA Bluetooth profile 
00036  *  qualification listings, this section of source code must not be modified.
00037  */
00038 
00039 #ifndef BLE_BAS_H__
00040 #define BLE_BAS_H__
00041 
00042 #include <stdint.h>
00043 #include <stdbool.h>
00044 #include "ble.h"
00045 #include "ble_srv_common.h "
00046 
00047 /**@brief Battery Service event type. */
00048 typedef enum
00049 {
00050     BLE_BAS_EVT_NOTIFICATION_ENABLED,                             /**< Battery value notification enabled event. */
00051     BLE_BAS_EVT_NOTIFICATION_DISABLED                             /**< Battery value notification disabled event. */
00052 } ble_bas_evt_type_t;
00053 
00054 /**@brief Battery Service event. */
00055 typedef struct
00056 {
00057     ble_bas_evt_type_t evt_type;                                  /**< Type of event. */
00058 } ble_bas_evt_t;
00059 
00060 // Forward declaration of the ble_bas_t type. 
00061 typedef struct ble_bas_s ble_bas_t;
00062 
00063 /**@brief Battery Service event handler type. */
00064 typedef void (*ble_bas_evt_handler_t) (ble_bas_t * p_bas, ble_bas_evt_t * p_evt);
00065 
00066 /**@brief Battery Service init structure. This contains all options and data needed for
00067  *        initialization of the service.*/
00068 typedef struct
00069 {
00070     ble_bas_evt_handler_t         evt_handler;                    /**< Event handler to be called for handling events in the Battery Service. */
00071     bool                          support_notification;           /**< TRUE if notification of Battery Level measurement is supported. */
00072     ble_srv_report_ref_t *        p_report_ref;                   /**< If not NULL, a Report Reference descriptor with the specified value will be added to the Battery Level characteristic */
00073     uint8_t                       initial_batt_level;             /**< Initial battery level */
00074     ble_srv_cccd_security_mode_t  battery_level_char_attr_md;     /**< Initial security level for battery characteristics attribute */
00075     ble_gap_conn_sec_mode_t       battery_level_report_read_perm; /**< Initial security level for battery report read attribute */
00076 } ble_bas_init_t;
00077 
00078 /**@brief Battery Service structure. This contains various status information for the service. */
00079 typedef struct ble_bas_s
00080 {
00081     ble_bas_evt_handler_t         evt_handler;                    /**< Event handler to be called for handling events in the Battery Service. */
00082     uint16_t                      service_handle;                 /**< Handle of Battery Service (as provided by the BLE stack). */
00083     ble_gatts_char_handles_t      battery_level_handles;          /**< Handles related to the Battery Level characteristic. */
00084     uint16_t                      report_ref_handle;              /**< Handle of the Report Reference descriptor. */
00085     uint8_t                       battery_level_last;             /**< Last Battery Level measurement passed to the Battery Service. */
00086     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). */
00087     bool                          is_notification_supported;      /**< TRUE if notification of Battery Level is supported. */
00088 } ble_bas_t;
00089 
00090 /**@brief Function for initializing the Battery Service.
00091  *
00092  * @param[out]  p_bas       Battery Service structure. This structure will have to be supplied by
00093  *                          the application. It will be initialized by this function, and will later
00094  *                          be used to identify this particular service instance.
00095  * @param[in]   p_bas_init  Information needed to initialize the service.
00096  *
00097  * @return      NRF_SUCCESS on successful initialization of service, otherwise an error code.
00098  */
00099 uint32_t ble_bas_init(ble_bas_t * p_bas, const ble_bas_init_t * p_bas_init);
00100 
00101 /**@brief Function for handling the Application's BLE Stack events.
00102  *
00103  * @details Handles all events from the BLE stack of interest to the Battery Service.
00104  *
00105  * @note For the requirements in the BAS specification to be fulfilled,
00106  *       ble_bas_battery_level_update() must be called upon reconnection if the
00107  *       battery level has changed while the service has been disconnected from a bonded
00108  *       client.
00109  *
00110  * @param[in]   p_bas      Battery Service structure.
00111  * @param[in]   p_ble_evt  Event received from the BLE stack.
00112  */
00113 void ble_bas_on_ble_evt(ble_bas_t * p_bas, ble_evt_t * p_ble_evt);
00114 
00115 /**@brief Function for updating the battery level.
00116  *
00117  * @details The application calls this function after having performed a battery measurement. If
00118  *          notification has been enabled, the battery level characteristic is sent to the client.
00119  *
00120  * @note For the requirements in the BAS specification to be fulfilled,
00121  *       this function must be called upon reconnection if the battery level has changed
00122  *       while the service has been disconnected from a bonded client.
00123  *
00124  * @param[in]   p_bas          Battery Service structure.
00125  * @param[in]   battery_level  New battery measurement value (in percent of full capacity).
00126  *
00127  * @return      NRF_SUCCESS on success, otherwise an error code.
00128  */
00129 uint32_t ble_bas_battery_level_update(ble_bas_t * p_bas, uint8_t battery_level);
00130 
00131 #endif // BLE_BAS_H__
00132 
00133 /** @} */