1 /** 2 ***************************************************************************************** 3 * 4 * @file bas.h 5 * 6 * @brief Battery 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_BAS Battery Service (BAS) 46 * @{ 47 * @brief Definitions and prototypes for the BAS interface. 48 * 49 * @details The Battery Service exposes the state of a battery within a device. 50 * This module implements the Battery Service with the Battery Level characteristic. 51 * 52 * After \ref bas_init_t variable is initialized, the application must call \ref bas_service_init() 53 * to add the Battery Service(s) and Battery Level characteristic(s) to the BLE Stack database. 54 * However the value of Battery Level characteristic is stored within \ref bas_init_t.batt_lvl 55 * which locates in user space. 56 * 57 * The module supports more than one instance of the Battery service with \ref bas_service_init(). 58 * When the device has more than one instance, each Battery Level characteristic shall include 59 * a Characteristic Presentation Format descriptor to identify the instance. \ref bas_init_t.char_mask 60 * shall be set with the mask \ref BAS_CHAR_FORMAT_SUP to add the descriptor to the BLE stack database. 61 * 62 * If \ref bas_init_t.char_mask is set with the mask \ref BAS_CHAR_LVL_NTF_SUP, the module will 63 * support notification of the Battery Level characteristic through the bas_batt_lvl_update() function. 64 * If an event handler is provided by the application, the Battery Service will pass Battery Service 65 * events to the application. 66 * 67 */ 68 69 #ifndef __BAS_H__ 70 #define __BAS_H__ 71 72 #include <stdbool.h> 73 #include <stdint.h> 74 #include "gr55xx_sys.h" 75 #include "custom_config.h" 76 77 /** 78 * @defgroup BAS_MACRO Defines 79 * @{ 80 */ 81 #define BAS_INSTANCE_MAX 1 /**< Maximum number of Battery Service instances. \ 82 The value is configurable. */ 83 #define BAS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ? \ 84 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of BAS connections. 85 The value is configurable. */ 86 #define BAS_LVL_MAX_LEN 1 /**< Maximun length of battery level value. */ 87 88 /** 89 * @defgroup BAS_CHAR_MASK Characteristics Mask 90 * @{ 91 * @brief Bit masks for the initialization of \ref bas_init_t.char_mask. 92 */ 93 #define BAS_CHAR_MANDATORY 0x07 /**< Bit mask of the mandatory characteristics in BAS. */ 94 #define BAS_CHAR_LVL_NTF_SUP 0x08 /**< Bit mask of Battery Level notification. */ 95 #define BAS_CHAR_FORMAT_SUP 0x10 /**< Bit mask of the Presentation Format descriptor. */ 96 #define BAS_CHAR_FULL 0x1f /**< Bit mask of the full characteristic. */ 97 /** @} */ 98 /** @} */ 99 100 /** 101 * @defgroup BAS_ENUM Enumerations 102 * @{ 103 */ 104 /**@brief Battery Service event types. */ 105 typedef enum { 106 BAS_EVT_INVALID, /**< Indicate that it's an invalid event. */ 107 BAS_EVT_NOTIFICATION_ENABLED, /**< Indicate that notification has been enabled. */ 108 BAS_EVT_NOTIFICATION_DISABLED, /**< Indicate that notification has been disabled. */ 109 } bas_evt_type_t; 110 /** @} */ 111 112 /** 113 * @defgroup BAS_STRUCT Structures 114 * @{ 115 */ 116 /**@brief Battery Service event. */ 117 typedef struct { 118 bas_evt_type_t evt_type; /**< The BAS event type. */ 119 uint8_t conn_idx; /**< The index of the connection. */ 120 } bas_evt_t; 121 /** @} */ 122 123 /** 124 * @defgroup BAS_TYPEDEF Typedefs 125 * @{ 126 */ 127 /**@brief Battery Service event handler type. */ 128 typedef void (*bas_evt_handler_t)(bas_evt_t *p_evt); 129 /** @} */ 130 131 /** 132 * @defgroup BAS_STRUCT Structures 133 * @{ 134 */ 135 /**@brief Battery Service init structure. 136 * This contains all options and data needed for initialization of the service. */ 137 typedef struct { 138 bas_evt_handler_t evt_handler; /**< Battery Service event handler. */ 139 uint8_t 140 char_mask; /**< Initial mask of supported characteristics, and configured with \ref BAS_CHAR_MASK */ 141 uint8_t batt_lvl; /**< Initial value of Battery Level characteristic. */ 142 } bas_init_t; 143 /** @} */ 144 145 /** 146 * @defgroup BAS_FUNCTION Functions 147 * @{ 148 */ 149 /** 150 ***************************************************************************************** 151 * @brief Initialize Battery Service instances and add to the DB. 152 * 153 * @param[in] ins_num: The number of Battery Service instances. 154 * @param[in] bas_init: The array of Battery Service initialization variables. 155 * 156 * @return Result of service initialization. 157 ***************************************************************************************** 158 */ 159 sdk_err_t bas_service_init(bas_init_t bas_init[], uint8_t ins_num); 160 161 /** 162 ***************************************************************************************** 163 * @brief Update a Battery Level value. If notification is enabled, send it. 164 * 165 * @param[in] conn_idx: Connection index. 166 * @param[in] ins_idx: Battery Service instance index. 167 * @param[in] batt_lvl: Battery Level value. 168 * 169 * @return Result of battery level updating. 170 ***************************************************************************************** 171 */ 172 sdk_err_t bas_batt_lvl_update(uint8_t conn_idx, uint8_t ins_idx, uint8_t batt_lvl); 173 /** @} */ 174 175 #endif 176 /** @} */ 177 /** @} */ 178