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 #define OTAS_C_CTRL_PT_OP_DFU_ENTER 0x474f4f44
86 /** @} */
87
88 /**
89 * @defgroup OTAS_C_ENUM Enumerations
90 * @{
91 */
92 /**@brief OTA Service Client event type. */
93 typedef enum
94 {
95 OTAS_C_EVT_INVALID, /**< OTA Client invalid event. */
96 OTAS_C_EVT_DISCOVERY_COMPLETE, /**< OTA Client has found THS service and its characteristics. */
97 OTAS_C_EVT_DISCOVERY_FAIL, /**< OTA Client found THS service failed because of invalid operation or no found at the peer. */
98 OTAS_C_EVT_TX_NTF_SET_SUCCESS, /**< OTA Client has set peer Tx notify. */
99 OTAS_C_EVT_CTRL_SUCCESS, /**< OTA Client has set control info. */
100 OTAS_C_EVT_PEER_DATA_RECEIVE, /**< OTA Client has received data from peer. */
101 OTAS_C_EVT_TX_CPLT, /**< OTA Client has sent something to a peer successfully. */
102 OTAS_C_EVT_WRITE_OP_ERR, /**< Error occured when OTA Client writen to peer. */
103 } otas_c_evt_type_t;
104 /** @} */
105
106 /**
107 * @defgroup OTAS_C_STRUCT Structures
108 * @{
109 */
110 /**@brief Handles on the connected peer device needed to interact with it. */
111 typedef struct
112 {
113 uint16_t otas_srvc_start_handle; /**< OTA Service start handle. */
114 uint16_t otas_srvc_end_handle; /**< OTA Service end handle. */
115 uint16_t otas_tx_handle; /**< OTA tx characteristic handle which has been got from peer. */
116 uint16_t otas_tx_cccd_handle; /**< OTA tx characteristic CCCD handle which has been got from peer. */
117 uint16_t otas_rx_handle; /**< OTA rx characteristic handle which has been got from peer. */
118 uint16_t otas_ctrl_handle; /**< OTA control characteristic handle which has been got from peer. */
119 } otas_c_handles_t;
120
121 /**@brief OTA Service Client event. */
122 typedef struct
123 {
124 uint8_t conn_idx; /**< The connection index. */
125 otas_c_evt_type_t evt_type; /**< OTA client event type. */
126 uint8_t *p_data; /**< Pointer to event data. */
127 uint16_t length; /**< Length of event data. */
128 } otas_c_evt_t;
129 /** @} */
130
131 /**
132 * @defgroup OTAS_C_TYPEDEF Typedefs
133 * @{
134 */
135 /**@brief OTA Service Client event handler type. */
136 typedef void (*otas_c_evt_handler_t)(otas_c_evt_t *p_evt);
137 /** @} */
138
139 /**
140 * @defgroup OTAS_C_FUNCTION Functions
141 * @{
142 */
143 /**
144 *****************************************************************************************
145 * @brief Register THS Client event handler.
146 *
147 * @param[in] evt_handler: OTA Service Client event handler.
148 *
149 * @return Result of initialization.
150 *****************************************************************************************
151 */
152 sdk_err_t otas_client_init(otas_c_evt_handler_t evt_handler);
153
154 /**
155 *****************************************************************************************
156 * @brief Discovery OTAS on peer.
157 *
158 * @param[in] conn_idx: Index of connection.
159 *
160 * @return Operation result.
161 *****************************************************************************************
162 */
163 sdk_err_t otas_c_disc_srvc_start(uint8_t conn_idx);
164
165 /**
166 *****************************************************************************************
167 * @brief Enable or disable peer OTA tx characteristic notify.
168 *
169 * @param[in] conn_idx: Connection index.
170 * @param[in] is_enable: Enable or disable OTA tx notify.
171 *
172 * @return Operation result.
173 *****************************************************************************************
174 */
175 sdk_err_t otas_c_tx_notify_set(uint8_t conn_idx, bool is_enable);
176
177 /**
178 *****************************************************************************************
179 * @brief Send control data to peer.
180 *
181 * @param[in] conn_idx: Connection index.
182 * @param[in] data: Control data.
183 *
184 * @return Operation result.
185 *****************************************************************************************
186 */
187 sdk_err_t otas_c_ctrl_data_send(uint8_t conn_idx, uint32_t data);
188
189 /**
190 *****************************************************************************************
191 * @brief Send data to peer.
192 *
193 * @param[in] conn_idx: Connection index.
194 * @param[in] p_data: Pointer to data to be sent.
195 * @param[in] length: Length of data to be sent.
196 *
197 * @return Operation result.
198 *****************************************************************************************
199 */
200 sdk_err_t otas_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
201 /** @} */
202 #endif
203
204 /** @} */
205 /** @} */
OTAS_C_EVT_CTRL_SUCCESS
@ OTAS_C_EVT_CTRL_SUCCESS
OTA Client has set control info.
Definition: otas_c.h:99
otas_c_evt_t::length
uint16_t length
Length of event data.
Definition: otas_c.h:127
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:117
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:118
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:97
OTAS_C_EVT_INVALID
@ OTAS_C_EVT_INVALID
OTA Client invalid event.
Definition: otas_c.h:95
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:112
otas_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: otas_c.h:124
otas_c_handles_t::otas_srvc_start_handle
uint16_t otas_srvc_start_handle
OTA Service start handle.
Definition: otas_c.h:113
OTAS_C_EVT_WRITE_OP_ERR
@ OTAS_C_EVT_WRITE_OP_ERR
Error occured when OTA Client writen to peer.
Definition: otas_c.h:102
otas_c_evt_t
OTA Service Client event.
Definition: otas_c.h:123
OTAS_C_EVT_DISCOVERY_COMPLETE
@ OTAS_C_EVT_DISCOVERY_COMPLETE
OTA Client has found THS service and its characteristics.
Definition: otas_c.h:96
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:274
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:115
otas_c_evt_type_t
otas_c_evt_type_t
OTA Service Client event type.
Definition: otas_c.h:94
OTAS_C_EVT_TX_CPLT
@ OTAS_C_EVT_TX_CPLT
OTA Client has sent something to a peer successfully.
Definition: otas_c.h:101
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:126
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:116
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:125
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:114
OTAS_C_EVT_PEER_DATA_RECEIVE
@ OTAS_C_EVT_PEER_DATA_RECEIVE
OTA Client has received data from peer.
Definition: otas_c.h:100
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:98
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:136