pcs.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file pcs.h
5  *
6  * @brief Power Consumption 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_PCS Power Consumption Service (PCS)
46  * @{
47  * @brief Definitions and prototypes for the PCS interface.
48  *
49  * @details The Power Consumption Service is a customized GATT-based service with TX and Setting
50  * characteristics. The application uses the service to notify data to peer and receive
51  * some BLE parameters such as advertising interval, connect interval, PHY and so on,
52  * which can simulate different application scenes for power consumption test.
53  *
54  * After \ref pcs_init_t variable is initialized , the application must call \ref pcs_service_init()
55  * to add the ower Consumption Service and TX, Setting characteristics to the BLE Stack database.
56  */
57 
58 #ifndef __PCS_H__
59 #define __PCS_H__
60 
61 #include "gr55xx_sys.h"
62 #include "custom_config.h"
63 
64 /**
65  * @defgroup PCS_MACRO Defines
66  * @{
67  */
68 #define PCS_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
69  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of Power Consumption Service connections. */
70 #define PCS_MAX_DATA_LEN 244 /**< Maximum length of application data packet which is transmitted via PCS. */
71 #define PCS_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
72  0x0A, 0x46, 0x44, 0xD3, 0x01, 0x05, 0xED, 0xA6 /**< The UUID of Power Consumption Service for setting advertising data. */
73 
74 #define PCS_SET_PARAM_SUCCESS 0x00 /**< PCS parameters set successfully. */
75 #define PCS_SET_PARAM_FAIL 0x81 /**< PCS parameters set unsuccessfully. */
76 
77 #define PCS_SET_ADV_DATA_3B 0x03 /**< Set 3 byte advertising data. */
78 #define PCS_SET_ADV_DATA_10B 0x0a /**< Set 10 byte advertising data. */
79 #define PCS_SET_ADV_DATA_17B 0x11 /**< Set 17 byte advertising data. */
80 #define PCS_SET_ADV_DATA_24B 0x18 /**< Set 24 byte advertising data. */
81 #define PCS_SET_ADV_DATA_31B 0x1f /**< Set 31 byte advertising data. */
82 /** @} */
83 
84 /**
85  * @defgroup PCS_ENUM Enumerations
86  * @{
87  */
88 /**@brief PCS Service event types. */
89 typedef enum
90 {
91  PCS_EVT_INVALID, /**< Invalid PCS event. */
92  PCS_EVT_TX_ENABLE, /**< TX notify has been enabled. */
93  PCS_EVT_TX_DISABLE, /**< TX notify has been disabled. */
94  PCS_EVT_SETTING_ENABLE, /**< Setting notify has been enabled. */
95  PCS_EVT_SETTING_DISABLE, /**< Setting notify has been disabled. */
96  PCS_EVT_TX_DATA_SENT, /**< Data has been notitied completely. */
97  PCS_EVT_PARAM_SET, /**< BLE parameters set. */
98  PCS_EVT_DISCONNECTED, /**< Disconnected. */
100 
101 /**@brief PCS Service settings types. */
102 typedef enum
103 {
104  PCS_SETTING_TYPE_ADV_INTERVAL, /**< BLE Advertising Interval parameter. */
105  PCS_SETTING_TYPE_CONN_PARAM, /**< BLE Connection parameter. */
106  PCS_SETTING_TYPE_PHY, /**< Radio Phy mode, 1M, 2M, Encoded. */
107  PCS_SETTING_TYPE_ADV_DATA, /**< BLE advertising data. */
108  PCS_SETTING_TYPE_TX_POWER, /**< Tx Power. */
110 /** @} */
111 
112 /**
113  * @defgroup PCS_STRUCT Structures
114  * @{
115  */
116 /**@brief PCS Service event. */
117 typedef struct
118 {
119  uint8_t conn_idx; /**< The index of the connection. */
120  pcs_evt_type_t evt_type; /**< The PCS event type. */
121  uint8_t *p_data; /**< Pointer to data. */
122  uint16_t length; /**< Length of data. */
123 } pcs_evt_t;
124 /** @} */
125 
126 /**
127  * @defgroup pPCS_TYPEDEF Typedefs
128  * @{
129  */
130 /**@brief PCS Service event handler type. */
131 typedef void (*pcs_evt_handler_t)(pcs_evt_t *p_evt);
132 /** @} */
133 
134 /**
135  * @addtogroup PCS_STRUCT Structures
136  * @{
137  */
138 /**@brief PCS Service init stucture. This contains all option and data needed for initialization of the service. */
139 typedef struct
140 {
141  pcs_evt_handler_t evt_handler; /**< PCS Service event handler. */
142 } pcs_init_t;
143 /** @} */
144 
145 /**
146  * @defgroup PCS_FUNCTION Functions
147  * @{
148  */
149 /**
150  *****************************************************************************************
151  * @brief Initialize a PCS Service instance and add in the database.
152  *
153  * @param[in] p_pcs_init: Pointer to PCS Service initialization variables.
154  *
155  * @return Result of service initialization.
156  *****************************************************************************************
157  */
159 
160 /**
161  *****************************************************************************************
162  * @brief Send data to peer device.
163  *
164  * @param[in] conn_idx: Index of the connection.
165  * @param[in] p_data: Pointer to sent data.
166  * @param[in] length: Length of sent data.
167  *
168  * @return Result of sending data.
169  *****************************************************************************************
170  */
171 sdk_err_t pcs_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
172 
173 /**
174  *****************************************************************************************
175  * @brief Reply parameters set result.
176  *
177  * @param[in] conn_idx: Index of the connection.
178  * @param[in] p_data: Pointer to sent data.
179  * @param[in] length: Length of sent data.
180  *
181  * @return Result of sending data.
182  *****************************************************************************************
183  */
184 sdk_err_t pcs_setting_reply(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
185 /** @} */
186 
187 #endif
188 /** @} */
189 /** @} */
PCS_SETTING_TYPE_ADV_DATA
@ PCS_SETTING_TYPE_ADV_DATA
BLE advertising data.
Definition: pcs.h:107
PCS_EVT_SETTING_DISABLE
@ PCS_EVT_SETTING_DISABLE
Setting notify has been disabled.
Definition: pcs.h:95
pcs_evt_t::conn_idx
uint8_t conn_idx
The index of the connection.
Definition: pcs.h:119
PCS_SETTING_TYPE_ADV_INTERVAL
@ PCS_SETTING_TYPE_ADV_INTERVAL
BLE Advertising Interval parameter.
Definition: pcs.h:104
PCS_EVT_INVALID
@ PCS_EVT_INVALID
Invalid PCS event.
Definition: pcs.h:91
PCS_EVT_DISCONNECTED
@ PCS_EVT_DISCONNECTED
Disconnected.
Definition: pcs.h:98
pcs_evt_t::length
uint16_t length
Length of data.
Definition: pcs.h:122
pcs_setting_type_t
pcs_setting_type_t
PCS Service settings types.
Definition: pcs.h:103
pcs_evt_t::evt_type
pcs_evt_type_t evt_type
The PCS event type.
Definition: pcs.h:120
PCS_EVT_TX_DISABLE
@ PCS_EVT_TX_DISABLE
TX notify has been disabled.
Definition: pcs.h:93
gr55xx_sys.h
GR55XX System API.
PCS_EVT_TX_ENABLE
@ PCS_EVT_TX_ENABLE
TX notify has been enabled.
Definition: pcs.h:92
PCS_EVT_SETTING_ENABLE
@ PCS_EVT_SETTING_ENABLE
Setting notify has been enabled.
Definition: pcs.h:94
PCS_SETTING_TYPE_CONN_PARAM
@ PCS_SETTING_TYPE_CONN_PARAM
BLE Connection parameter.
Definition: pcs.h:105
pcs_evt_t
PCS Service event.
Definition: pcs.h:118
pcs_init_t::evt_handler
pcs_evt_handler_t evt_handler
PCS Service event handler.
Definition: pcs.h:141
PCS_EVT_TX_DATA_SENT
@ PCS_EVT_TX_DATA_SENT
Data has been notitied completely.
Definition: pcs.h:96
PCS_EVT_PARAM_SET
@ PCS_EVT_PARAM_SET
BLE parameters set.
Definition: pcs.h:97
pcs_evt_handler_t
void(* pcs_evt_handler_t)(pcs_evt_t *p_evt)
PCS Service event handler type.
Definition: pcs.h:131
pcs_init_t
PCS Service init stucture.
Definition: pcs.h:140
pcs_evt_t::p_data
uint8_t * p_data
Pointer to data.
Definition: pcs.h:121
pcs_setting_reply
sdk_err_t pcs_setting_reply(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Reply parameters set result.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
PCS_SETTING_TYPE_TX_POWER
@ PCS_SETTING_TYPE_TX_POWER
Tx Power.
Definition: pcs.h:108
pcs_service_init
sdk_err_t pcs_service_init(pcs_init_t *p_pcs_init)
Initialize a PCS Service instance and add in the database.
PCS_SETTING_TYPE_PHY
@ PCS_SETTING_TYPE_PHY
Radio Phy mode, 1M, 2M, Encoded.
Definition: pcs.h:106
pcs_tx_data_send
sdk_err_t pcs_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer device.
pcs_evt_type_t
pcs_evt_type_t
PCS Service event types.
Definition: pcs.h:90