bas.h
Go to the documentation of this file.
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 "gr55xx_sys.h"
73 #include "custom_config.h"
74 #include <stdbool.h>
75 #include <stdint.h>
76
77 /**
78 * @defgroup BAS_MACRO Defines
79 * @{
80 */
81 #define BAS_INSTANCE_MAX 1 /**< Maximum number of Battery Service instances. The value is configurable. */
82 #define BAS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
83 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of BAS connections.
84 The value is configurable. */
85 #define BAS_LVL_MAX_LEN 1 /**< Maximun length of battery level value. */
86
87 /**
88 * @defgroup BAS_CHAR_MASK Characteristics Mask
89 * @{
90 * @brief Bit masks for the initialization of \ref bas_init_t.char_mask.
91 */
92 #define BAS_CHAR_MANDATORY 0x07 /**< Bit mask of the mandatory characteristics in BAS. */
93 #define BAS_CHAR_LVL_NTF_SUP 0x08 /**< Bit mask of Battery Level notification. */
94 #define BAS_CHAR_FORMAT_SUP 0x10 /**< Bit mask of the Presentation Format descriptor. */
95 #define BAS_CHAR_FULL 0x1f /**< Bit mask of the full characteristic. */
96 /** @} */
97 /** @} */
98
99 /**
100 * @defgroup BAS_ENUM Enumerations
101 * @{
102 */
103 /**@brief Battery Service event types. */
104 typedef enum
105 {
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 {
119 bas_evt_type_t evt_type; /**< The BAS event type. */
120 uint8_t conn_idx; /**< The index of the connection. */
121 } bas_evt_t;
122 /** @} */
123
124 /**
125 * @defgroup BAS_TYPEDEF Typedefs
126 * @{
127 */
128 /**@brief Battery Service event handler type. */
129 typedef void (*bas_evt_handler_t)(bas_evt_t *p_evt);
130 /** @} */
131
132 /**
133 * @defgroup BAS_STRUCT Structures
134 * @{
135 */
136 /**@brief Battery Service init structure. This contains all options and data needed for initialization of the service. */
137 typedef struct
138 {
139 bas_evt_handler_t evt_handler; /**< Battery Service event handler. */
140 uint8_t 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 /** @} */
BAS_EVT_NOTIFICATION_DISABLED
@ BAS_EVT_NOTIFICATION_DISABLED
Indicate that notification has been disabled.
Definition: bas.h:108
bas_init_t::batt_lvl
uint8_t batt_lvl
Initial value of Battery Level characteristic.
Definition: bas.h:141
bas_evt_t
Battery Service event.
Definition: bas.h:118
bas_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: bas.h:120
gr55xx_sys.h
GR55XX System API.
BAS_EVT_INVALID
@ BAS_EVT_INVALID
Indicate that it's an invalid event.
Definition: bas.h:106
bas_evt_handler_t
void(* bas_evt_handler_t)(bas_evt_t *p_evt)
Battery Service event handler type.
Definition: bas.h:129
bas_evt_t::evt_type
bas_evt_type_t evt_type
The BAS event type.
Definition: bas.h:119
BAS_EVT_NOTIFICATION_ENABLED
@ BAS_EVT_NOTIFICATION_ENABLED
Indicate that notification has been enabled.
Definition: bas.h:107
bas_service_init
sdk_err_t bas_service_init(bas_init_t bas_init[], uint8_t ins_num)
Initialize Battery Service instances and add to the DB.
bas_init_t
Battery Service init structure.
Definition: bas.h:138
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
bas_init_t::evt_handler
bas_evt_handler_t evt_handler
Battery Service event handler.
Definition: bas.h:139
bas_batt_lvl_update
sdk_err_t bas_batt_lvl_update(uint8_t conn_idx, uint8_t ins_idx, uint8_t batt_lvl)
Update a Battery Level value.
bas_init_t::char_mask
uint8_t char_mask
Initial mask of supported characteristics, and configured with Characteristics Mask.
Definition: bas.h:140
bas_evt_type_t
bas_evt_type_t
Battery Service event types.
Definition: bas.h:105