bas_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file bas_c.h
5 *
6 * @brief Battery Service Client 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 */
42
43 /**
44 * @defgroup BLE_SDK_BAS_C Battery Service Client (BAS_C)
45 * @{
46 * @brief Battery Service Client module.
47 *
48 * @details The Battery Service Client contains the APIs and types, which can be used by the
49 * application to discovery of Battery Service of peer and interact with it.
50 *
51 * The application must provide an event handler to register, then call \ref bas_client_init().
52 * After Battery Service Client discoveries peer Battery Service, application can call
53 * \ref bas_c_bat_level_notify_set() and \ref bas_c_bat_level_read() to get battery
54 * data from peer.
55 */
56
57 #ifndef __BAS_C_H__
58 #define __BAS_C_H__
59
60 #include "gr_includes.h"
61 #include "ble_prf_types.h"
62 #include "custom_config.h"
63 #include <stdint.h>
64 #include <stdbool.h>
65
66 /**
67 * @defgroup BAS_C_MACRO Defines
68 * @{
69 */
70 #define BAS_C_CONNECTION_MAX 10 /**< Maximum number of BAS Client connections. */
71 /** @} */
72
73 /**
74 * @defgroup BAS_C_ENUM Enumerations
75 * @{
76 */
77 /**@brief Battery Service Client event type. */
78 typedef enum
79 {
80 BAS_C_EVT_INVALID, /**< BAS Client invalid event. */
81 BAS_C_EVT_DISCOVERY_COMPLETE, /**< BAS Client has found BAS service and its characteristics. */
82 BAS_C_EVT_DISCOVERY_FAIL, /**< BAS Client found BAS service failed because of invalid operation or no found at the peer. */
83 BAS_C_EVT_BAT_LEVEL_NTF_SET_SUCCESS, /**< BAS Client has enabled Notification of Battery Level characteristics. */
84 BAS_C_EVT_BAT_LEVEL_NTF_SET_ERR, /**< Error occured when BAS Client set Notification of Battery Level characteristics. */
85 BAS_C_EVT_BAT_LEVE_RECEIVE, /**< BAS Client has received Battery Level value (Read or Notification from peer). */
86 } bas_c_evt_type_t;
87 /** @} */
88
89 /**
90 * @defgroup BAS_C_STRUCT Structures
91 * @{
92 */
93 /**@brief Handles on the connected peer device needed to interact with it. */
94 typedef struct
95 {
96 uint16_t bas_srvc_start_handle; /**< BAS Service start handle. */
97 uint16_t bas_srvc_end_handle; /**< BAS Service end handle. */
98 uint16_t bas_bat_level_handle; /**< BAS Battery Level characteristic Value handle which has been got from peer. */
99 uint16_t bas_bat_level_cccd_handle; /**< BAS CCCD handle of Battery Level characteristic which has been got from peer. */
100 uint16_t bas_bat_level_pres_handle; /**< BAS Presentation Format Descriptor handle of Battery Level characteristic which has been got from peer. */
101 } bas_c_handles_t;
102
103 /**@brief Battery Service Client event. */
104 typedef struct
105 {
106 uint8_t conn_idx; /**< The connection index. */
107 bas_c_evt_type_t evt_type; /**< BAS Client event type. */
108 uint8_t bat_level; /**< Battery level. */
109 } bas_c_evt_t;
110 /** @} */
111
112 /**
113 * @defgroup BAS_C_TYPEDEF Typedefs
114 * @{
115 */
116 /**@brief Battery Service Client event handler type. */
117 typedef void (*bas_c_evt_handler_t)(bas_c_evt_t *p_evt);
118 /** @} */
119
120 /**
121 * @defgroup BAS_C_FUNCTION Functions
122 * @{
123 */
124 /**
125 *****************************************************************************************
126 * @brief Register BAS Client event handler.
127 *
128 * @param[in] evt_handler: Battery Service Client event handler.
129 *
130 * @return Result of initialization.
131 *****************************************************************************************
132 */
133 sdk_err_t bas_client_init(bas_c_evt_handler_t evt_handler);
134
135 /**
136 *****************************************************************************************
137 * @brief Discovery Battery Service on peer.
138 *
139 * @param[in] conn_idx: Index of connection.
140 *
141 * @return Operation result.
142 *****************************************************************************************
143 */
144 sdk_err_t bas_c_disc_srvc_start(uint8_t conn_idx);
145
146 /**
147 *****************************************************************************************
148 * @brief Enable or disable peer Battery Level characteristic notify.
149 *
150 * @param[in] conn_idx: Index of connection.
151 * @param[in] is_enable: true or false.
152 *
153 * @return Operation result.
154 *****************************************************************************************
155 */
156 sdk_err_t bas_c_bat_level_notify_set(uint8_t conn_idx, bool is_enable);
157
158 /**
159 *****************************************************************************************
160 * @brief Read Battery Level characteristic value.
161 *
162 * @param[in] conn_idx: Index of connection.
163 *
164 * @return Operation result.
165 *****************************************************************************************
166 */
167 sdk_err_t bas_c_bat_level_read(uint8_t conn_idx);
168 /** @} */
169
170 #endif
171 /** @} */
172 /** @} */
bas_c_handles_t::bas_bat_level_handle
uint16_t bas_bat_level_handle
BAS Battery Level characteristic Value handle which has been got from peer.
Definition: bas_c.h:98
bas_c_handles_t::bas_bat_level_cccd_handle
uint16_t bas_bat_level_cccd_handle
BAS CCCD handle of Battery Level characteristic which has been got from peer.
Definition: bas_c.h:99
bas_c_evt_t::bat_level
uint8_t bat_level
Battery level.
Definition: bas_c.h:108
BAS_C_EVT_BAT_LEVEL_NTF_SET_ERR
@ BAS_C_EVT_BAT_LEVEL_NTF_SET_ERR
Error occured when BAS Client set Notification of Battery Level characteristics.
Definition: bas_c.h:84
bas_c_bat_level_notify_set
sdk_err_t bas_c_bat_level_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer Battery Level characteristic notify.
BAS_C_EVT_DISCOVERY_FAIL
@ BAS_C_EVT_DISCOVERY_FAIL
BAS Client found BAS service failed because of invalid operation or no found at the peer.
Definition: bas_c.h:82
gr_includes.h
Include Files API.
bas_c_handles_t::bas_srvc_end_handle
uint16_t bas_srvc_end_handle
BAS Service end handle.
Definition: bas_c.h:97
bas_c_evt_t::evt_type
bas_c_evt_type_t evt_type
BAS Client event type.
Definition: bas_c.h:107
bas_c_handles_t::bas_bat_level_pres_handle
uint16_t bas_bat_level_pres_handle
BAS Presentation Format Descriptor handle of Battery Level characteristic which has been got from pee...
Definition: bas_c.h:100
bas_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: bas_c.h:106
bas_c_bat_level_read
sdk_err_t bas_c_bat_level_read(uint8_t conn_idx)
Read Battery Level characteristic value.
BAS_C_EVT_INVALID
@ BAS_C_EVT_INVALID
BAS Client invalid event.
Definition: bas_c.h:80
bas_c_evt_type_t
bas_c_evt_type_t
Battery Service Client event type.
Definition: bas_c.h:79
BAS_C_EVT_DISCOVERY_COMPLETE
@ BAS_C_EVT_DISCOVERY_COMPLETE
BAS Client has found BAS service and its characteristics.
Definition: bas_c.h:81
ble_prf_types.h
Profile/Service Common Types.
bas_c_disc_srvc_start
sdk_err_t bas_c_disc_srvc_start(uint8_t conn_idx)
Discovery Battery Service on peer.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
bas_c_evt_t
Battery Service Client event.
Definition: bas_c.h:105
bas_client_init
sdk_err_t bas_client_init(bas_c_evt_handler_t evt_handler)
Register BAS Client event handler.
BAS_C_EVT_BAT_LEVE_RECEIVE
@ BAS_C_EVT_BAT_LEVE_RECEIVE
BAS Client has received Battery Level value (Read or Notification from peer).
Definition: bas_c.h:85
bas_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: bas_c.h:95
bas_c_evt_handler_t
void(* bas_c_evt_handler_t)(bas_c_evt_t *p_evt)
Battery Service Client event handler type.
Definition: bas_c.h:117
bas_c_handles_t::bas_srvc_start_handle
uint16_t bas_srvc_start_handle
BAS Service start handle.
Definition: bas_c.h:96
BAS_C_EVT_BAT_LEVEL_NTF_SET_SUCCESS
@ BAS_C_EVT_BAT_LEVEL_NTF_SET_SUCCESS
BAS Client has enabled Notification of Battery Level characteristics.
Definition: bas_c.h:83