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. */
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. */
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  */
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  */
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
Definition: otas_c.h:99
otas_c_evt_t::length
uint16_t length
Definition: otas_c.h:127
otas_c_handles_t::otas_rx_handle
uint16_t otas_rx_handle
Definition: otas_c.h:117
otas_c_handles_t::otas_ctrl_handle
uint16_t otas_ctrl_handle
Definition: otas_c.h:118
OTAS_C_EVT_DISCOVERY_FAIL
@ OTAS_C_EVT_DISCOVERY_FAIL
Definition: otas_c.h:97
OTAS_C_EVT_INVALID
@ OTAS_C_EVT_INVALID
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
Definition: otas_c.h:124
otas_c_handles_t::otas_srvc_start_handle
uint16_t otas_srvc_start_handle
Definition: otas_c.h:113
OTAS_C_EVT_WRITE_OP_ERR
@ OTAS_C_EVT_WRITE_OP_ERR
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
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:290
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
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
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
Definition: otas_c.h:126
otas_c_handles_t::otas_tx_cccd_handle
uint16_t otas_tx_cccd_handle
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
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
Definition: otas_c.h:114
OTAS_C_EVT_PEER_DATA_RECEIVE
@ OTAS_C_EVT_PEER_DATA_RECEIVE
Definition: otas_c.h:100
OTAS_C_EVT_TX_NTF_SET_SUCCESS
@ OTAS_C_EVT_TX_NTF_SET_SUCCESS
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