otas_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file otas_c.h
5 *
6 * @brief OTAS 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_OTAS_C OTA Service Client (OTAS_C)
45 * @{
46 * @brief OTAS Client Interface module.
47 *
48 * @details The OTA Service Client contains the APIs and types, which can be used by the
49 * application to perform discovery of OTA Service at peer and interact with it.
50 *
51 * The application must provide to register, then call \ref otas_client_init().
52 * The module can send firmware information data to peer.
53 */
54
55 #ifndef __OTAS_C_H__
56 #define __OTAS_C_H__
57
58 #include "ble_prf_types.h"
59 #include "gr55xx_sys.h"
60 #include "custom_config.h"
61 #include <stdint.h>
62 #include <stdbool.h>
63
64 /**
65 * @defgroup OTAS_C_MACRO Defines
66 * @{
67 */
68 #define OTAS_C_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
69 10 : CFG_MAX_CONNECTIONS) /**< Maximum number of OTAS Client connections. */
70
71 /**
72 * @defgroup OTAS_UUID OTAS UUIDs
73 * @{
74 * @brief OTAS service and characteristcs UUID.
75 */
76 #define OTAS_SVC_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80, \
77 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x04, 0xED, 0xA6} /**< UUID of OTA Service. */
78 #define OTAS_TX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80, \
79 0x0A, 0x46, 0x44, 0xD3, 0x02, 0x04, 0xED, 0xA6} /**< UUID of OTA TX Characteristic. */
80 #define OTAS_RX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80, \
81 0x0A, 0x46, 0x44, 0xD3, 0x03, 0x04, 0xED, 0xA6} /**< UUID of OTA RX Characteristic. */
82 #define OTAS_CTRL_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80, \
83 0x0A, 0x46, 0x44, 0xD3, 0x04, 0x04, 0xED, 0xA6} /**< UUID of OTA Control Characteristic. */
84 /** @} */
85 /** @} */
86
87 /**
88 * @defgroup OTAS_C_ENUM Enumerations
89 * @{
90 */
91 /**@brief OTA Service Client event type. */
92 typedef enum
93 {
94 OTAS_C_EVT_INVALID, /**< OTA Client invalid event. */
95 OTAS_C_EVT_DISCOVERY_COMPLETE, /**< OTA Client has found THS service and its characteristics. */
96 OTAS_C_EVT_DISCOVERY_FAIL, /**< OTA Client found THS service failed because of invalid operation or no found at the peer. */
97 OTAS_C_EVT_TX_NTF_SET_SUCCESS, /**< OTA Client has set peer Tx notify. */
98 OTAS_C_EVT_CTRL_SUCCESS, /**< OTA Client has set control info. */
99 OTAS_C_EVT_PEER_DATA_RECEIVE, /**< OTA Client has received data from peer. */
100 OTAS_C_EVT_TX_CPLT, /**< OTA Client has sent something to a peer successfully. */
101 OTAS_C_EVT_WRITE_OP_ERR, /**< Error occured when OTA Client writen to peer. */
102 } otas_c_evt_type_t;
103 /** @} */
104
105 /**
106 * @defgroup OTAS_C_STRUCT Structures
107 * @{
108 */
109 /**@brief Handles on the connected peer device needed to interact with it. */
110 typedef struct
111 {
112 uint16_t otas_srvc_start_handle; /**< OTA Service start handle. */
113 uint16_t otas_srvc_end_handle; /**< OTA Service end handle. */
114 uint16_t otas_tx_handle; /**< OTA tx characteristic handle which has been got from peer. */
115 uint16_t otas_tx_cccd_handle; /**< OTA tx characteristic CCCD handle which has been got from peer. */
116 uint16_t otas_rx_handle; /**< OTA rx characteristic handle which has been got from peer. */
117 uint16_t otas_ctrl_handle; /**< OTA control characteristic handle which has been got from peer. */
118 } otas_c_handles_t;
119
120 /**@brief OTA Service Client event. */
121 typedef struct
122 {
123 uint8_t conn_idx; /**< The connection index. */
124 otas_c_evt_type_t evt_type; /**< OTA client event type. */
125 uint8_t *p_data; /**< Pointer to event data. */
126 uint16_t length; /**< Length of event data. */
127 } otas_c_evt_t;
128 /** @} */
129
130 /**
131 * @defgroup OTAS_C_TYPEDEF Typedefs
132 * @{
133 */
134 /**@brief OTA Service Client event handler type. */
135 typedef void (*otas_c_evt_handler_t)(otas_c_evt_t *p_evt);
136 /** @} */
137
138 /**
139 * @defgroup OTAS_C_FUNCTION Functions
140 * @{
141 */
142 /**
143 *****************************************************************************************
144 * @brief Register THS Client event handler.
145 *
146 * @param[in] evt_handler: OTA Service Client event handler.
147 *
148 * @return Result of initialization.
149 *****************************************************************************************
150 */
151 sdk_err_t otas_client_init(otas_c_evt_handler_t evt_handler);
152
153 /**
154 *****************************************************************************************
155 * @brief Discovery OTAS on peer.
156 *
157 * @param[in] conn_idx: Index of connection.
158 *
159 * @return Operation result.
160 *****************************************************************************************
161 */
162 sdk_err_t otas_c_disc_srvc_start(uint8_t conn_idx);
163
164 /**
165 *****************************************************************************************
166 * @brief Enable or disable peer OTA tx characteristic notify.
167 *
168 * @param[in] conn_idx: Connection index.
169 * @param[in] is_enable: Enable or disable OTA tx notify.
170 *
171 * @return Operation result.
172 *****************************************************************************************
173 */
174 sdk_err_t otas_c_tx_notify_set(uint8_t conn_idx, bool is_enable);
175
176 /**
177 *****************************************************************************************
178 * @brief Send control data to peer.
179 *
180 * @param[in] conn_idx: Connection index.
181 * @param[in] data: Control data.
182 *
183 * @return Operation result.
184 *****************************************************************************************
185 */
186 sdk_err_t otas_c_ctrl_data_send(uint8_t conn_idx, uint32_t data);
187
188 /**
189 *****************************************************************************************
190 * @brief Send data to peer.
191 *
192 * @param[in] conn_idx: Connection index.
193 * @param[in] p_data: Pointer to data to be sent.
194 * @param[in] length: Length of data to be sent.
195 *
196 * @return Operation result.
197 *****************************************************************************************
198 */
199 sdk_err_t otas_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
200 /** @} */
201 #endif
202
203 /** @} */
204 /** @} */
OTAS_C_EVT_CTRL_SUCCESS
@ OTAS_C_EVT_CTRL_SUCCESS
OTA Client has set control info.
Definition: otas_c.h:98
otas_c_evt_t::length
uint16_t length
Length of event data.
Definition: otas_c.h:126
otas_c_handles_t::otas_rx_handle
uint16_t otas_rx_handle
OTA rx characteristic handle which has been got from peer.
Definition: otas_c.h:116
otas_c_handles_t::otas_ctrl_handle
uint16_t otas_ctrl_handle
OTA control characteristic handle which has been got from peer.
Definition: otas_c.h:117
OTAS_C_EVT_DISCOVERY_FAIL
@ OTAS_C_EVT_DISCOVERY_FAIL
OTA Client found THS service failed because of invalid operation or no found at the peer.
Definition: otas_c.h:96
OTAS_C_EVT_INVALID
@ OTAS_C_EVT_INVALID
OTA Client invalid event.
Definition: otas_c.h:94
gr55xx_sys.h
GR55XX System API.
otas_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: otas_c.h:111
otas_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: otas_c.h:123
otas_c_handles_t::otas_srvc_start_handle
uint16_t otas_srvc_start_handle
OTA Service start handle.
Definition: otas_c.h:112
OTAS_C_EVT_WRITE_OP_ERR
@ OTAS_C_EVT_WRITE_OP_ERR
Error occured when OTA Client writen to peer.
Definition: otas_c.h:101
otas_c_evt_t
OTA Service Client event.
Definition: otas_c.h:122
OTAS_C_EVT_DISCOVERY_COMPLETE
@ OTAS_C_EVT_DISCOVERY_COMPLETE
OTA Client has found THS service and its characteristics.
Definition: otas_c.h:95
ble_prf_types.h
Profile/Service Common Types.
otas_c_tx_data_send
sdk_err_t otas_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
otas_client_init
sdk_err_t otas_client_init(otas_c_evt_handler_t evt_handler)
Register THS Client event handler.
otas_c_handles_t::otas_tx_handle
uint16_t otas_tx_handle
OTA tx characteristic handle which has been got from peer.
Definition: otas_c.h:114
otas_c_evt_type_t
otas_c_evt_type_t
OTA Service Client event type.
Definition: otas_c.h:93
OTAS_C_EVT_TX_CPLT
@ OTAS_C_EVT_TX_CPLT
OTA Client has sent something to a peer successfully.
Definition: otas_c.h:100
otas_c_disc_srvc_start
sdk_err_t otas_c_disc_srvc_start(uint8_t conn_idx)
Discovery OTAS on peer.
otas_c_evt_t::p_data
uint8_t * p_data
Pointer to event data.
Definition: otas_c.h:125
otas_c_handles_t::otas_tx_cccd_handle
uint16_t otas_tx_cccd_handle
OTA tx characteristic CCCD handle which has been got from peer.
Definition: otas_c.h:115
otas_c_tx_notify_set
sdk_err_t otas_c_tx_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer OTA tx characteristic notify.
otas_c_evt_t::evt_type
otas_c_evt_type_t evt_type
OTA client event type.
Definition: otas_c.h:124
otas_c_ctrl_data_send
sdk_err_t otas_c_ctrl_data_send(uint8_t conn_idx, uint32_t data)
Send control data to peer.
otas_c_handles_t::otas_srvc_end_handle
uint16_t otas_srvc_end_handle
OTA Service end handle.
Definition: otas_c.h:113
OTAS_C_EVT_PEER_DATA_RECEIVE
@ OTAS_C_EVT_PEER_DATA_RECEIVE
OTA Client has received data from peer.
Definition: otas_c.h:99
OTAS_C_EVT_TX_NTF_SET_SUCCESS
@ OTAS_C_EVT_TX_NTF_SET_SUCCESS
OTA Client has set peer Tx notify.
Definition: otas_c.h:97
otas_c_evt_handler_t
void(* otas_c_evt_handler_t)(otas_c_evt_t *p_evt)
OTA Service Client event handler type.
Definition: otas_c.h:135