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