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). */
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. */
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  */
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  */
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
Definition: bas_c.h:98
bas_c_handles_t::bas_bat_level_cccd_handle
uint16_t bas_bat_level_cccd_handle
Definition: bas_c.h:99
bas_c_evt_t::bat_level
uint8_t bat_level
Definition: bas_c.h:108
BAS_C_EVT_BAT_LEVEL_NTF_SET_ERR
@ BAS_C_EVT_BAT_LEVEL_NTF_SET_ERR
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
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
Definition: bas_c.h:97
bas_c_evt_t::evt_type
bas_c_evt_type_t evt_type
Definition: bas_c.h:107
bas_c_handles_t::bas_bat_level_pres_handle
uint16_t bas_bat_level_pres_handle
Definition: bas_c.h:100
bas_c_evt_t::conn_idx
uint8_t conn_idx
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
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
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:290
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
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
Definition: bas_c.h:96
BAS_C_EVT_BAT_LEVEL_NTF_SET_SUCCESS
@ BAS_C_EVT_BAT_LEVEL_NTF_SET_SUCCESS
Definition: bas_c.h:83