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