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 "gr_includes.h"
73 #include <stdbool.h>
74 #include <stdint.h>
75 
76 /**
77  * @defgroup BAS_MACRO Defines
78  * @{
79  */
80 #define BAS_INSTANCE_MAX 1 /**< Maximum number of Battery Service instances. The value is configurable. */
81 #define BAS_CONNECTION_MAX 10 /**< Maximum number of BAS connections.The value is configurable. */
82 #define BAS_LVL_MAX_LEN 1 /**< Maximun length of battery level value. */
83 
84 /**
85  * @defgroup BAS_CHAR_MASK Characteristics Mask
86  * @{
87  * @brief Bit masks for the initialization of \ref bas_init_t.char_mask.
88  */
89 #define BAS_CHAR_MANDATORY 0x07 /**< Bit mask of the mandatory characteristics in BAS. */
90 #define BAS_CHAR_LVL_NTF_SUP 0x08 /**< Bit mask of Battery Level notification. */
91 #define BAS_CHAR_FORMAT_SUP 0x10 /**< Bit mask of the Presentation Format descriptor. */
92 #define BAS_CHAR_FULL 0x1f /**< Bit mask of the full characteristic. */
93 /** @} */
94 /** @} */
95 
96 /**
97  * @defgroup BAS_ENUM Enumerations
98  * @{
99  */
100 /**@brief Battery Service event types. */
101 typedef enum
102 {
103  BAS_EVT_INVALID, /**< Indicate that it's an invalid event. */
104  BAS_EVT_NOTIFICATION_ENABLED, /**< Indicate that notification has been enabled. */
105  BAS_EVT_NOTIFICATION_DISABLED, /**< Indicate that notification has been disabled. */
107 /** @} */
108 
109 /**
110  * @defgroup BAS_STRUCT Structures
111  * @{
112  */
113 /**@brief Battery Service event. */
114 typedef struct
115 {
116  bas_evt_type_t evt_type; /**< The BAS event type. */
117  uint8_t conn_idx; /**< The index of the connection. */
118 } bas_evt_t;
119 /** @} */
120 
121 /**
122  * @defgroup BAS_TYPEDEF Typedefs
123  * @{
124  */
125 /**@brief Battery Service event handler type. */
126 typedef void (*bas_evt_handler_t)(bas_evt_t *p_evt);
127 /** @} */
128 
129 /**
130  * @defgroup BAS_STRUCT Structures
131  * @{
132  */
133 /**@brief Battery Service init structure. This contains all options and data needed for initialization of the service. */
134 typedef struct
135 {
136  bas_evt_handler_t evt_handler; /**< Battery Service event handler. */
137  uint8_t char_mask; /**< Initial mask of supported characteristics, and configured with \ref BAS_CHAR_MASK */
138  uint8_t batt_lvl; /**< Initial value of Battery Level characteristic. */
139 } bas_init_t;
140 /** @} */
141 
142 /**
143  * @defgroup BAS_FUNCTION Functions
144  * @{
145  */
146 /**
147  *****************************************************************************************
148  * @brief Initialize Battery Service instances and add to the DB.
149  *
150  * @param[in] ins_num: The number of Battery Service instances.
151  * @param[in] bas_init: The array of Battery Service initialization variables.
152  *
153  * @return Result of service initialization.
154  *****************************************************************************************
155  */
156 sdk_err_t bas_service_init(bas_init_t bas_init[],uint8_t ins_num);
157 
158 /**
159  *****************************************************************************************
160  * @brief Update a Battery Level value. If notification is enabled, send it.
161  *
162  * @param[in] conn_idx: Connection index.
163  * @param[in] ins_idx: Battery Service instance index.
164  * @param[in] batt_lvl: Battery Level value.
165  *
166  * @return Result of battery level updating.
167  *****************************************************************************************
168  */
169 sdk_err_t bas_batt_lvl_update(uint8_t conn_idx, uint8_t ins_idx, uint8_t batt_lvl);
170 
171 /**
172  *****************************************************************************************
173  * @brief Provide the interface for other modules to obtain the bas service start handle .
174  *
175  * @return The bas service start handle.
176  *****************************************************************************************
177  */
179 
180 /** @} */
181 
182 #endif
183 /** @} */
184 /** @} */
BAS_EVT_NOTIFICATION_DISABLED
@ BAS_EVT_NOTIFICATION_DISABLED
Definition: bas.h:105
bas_init_t::batt_lvl
uint8_t batt_lvl
Definition: bas.h:138
bas_evt_t
Battery Service event.
Definition: bas.h:115
bas_evt_t::conn_idx
uint8_t conn_idx
Definition: bas.h:117
gr_includes.h
Include Files API.
BAS_EVT_INVALID
@ BAS_EVT_INVALID
Definition: bas.h:103
bas_evt_handler_t
void(* bas_evt_handler_t)(bas_evt_t *p_evt)
Battery Service event handler type.
Definition: bas.h:126
bas_evt_t::evt_type
bas_evt_type_t evt_type
Definition: bas.h:116
BAS_EVT_NOTIFICATION_ENABLED
@ BAS_EVT_NOTIFICATION_ENABLED
Definition: bas.h:104
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. This contains all options and data needed for initialization of the s...
Definition: bas.h:135
bas_service_start_handle_get
uint16_t bas_service_start_handle_get(void)
Provide the interface for other modules to obtain the bas service start handle .
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
bas_init_t::evt_handler
bas_evt_handler_t evt_handler
Definition: bas.h:136
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. If notification is enabled, send it.
bas_init_t::char_mask
uint8_t char_mask
Definition: bas.h:137
bas_evt_type_t
bas_evt_type_t
Battery Service event types.
Definition: bas.h:102