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. */
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. */
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  */
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  */
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
Definition: otas_c.h:97
otas_c_evt_t::length
uint16_t length
Definition: otas_c.h:125
otas_c_handles_t::otas_rx_handle
uint16_t otas_rx_handle
Definition: otas_c.h:115
otas_c_handles_t::otas_ctrl_handle
uint16_t otas_ctrl_handle
Definition: otas_c.h:116
OTAS_C_EVT_DISCOVERY_FAIL
@ OTAS_C_EVT_DISCOVERY_FAIL
Definition: otas_c.h:95
OTAS_C_EVT_INVALID
@ OTAS_C_EVT_INVALID
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
Definition: otas_c.h:122
otas_c_handles_t::otas_srvc_start_handle
uint16_t otas_srvc_start_handle
Definition: otas_c.h:111
OTAS_C_EVT_WRITE_OP_ERR
@ OTAS_C_EVT_WRITE_OP_ERR
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
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
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
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
Definition: otas_c.h:124
otas_c_handles_t::otas_tx_cccd_handle
uint16_t otas_tx_cccd_handle
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
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
Definition: otas_c.h:112
OTAS_C_EVT_PEER_DATA_RECEIVE
@ OTAS_C_EVT_PEER_DATA_RECEIVE
Definition: otas_c.h:98
OTAS_C_EVT_TX_NTF_SET_SUCCESS
@ OTAS_C_EVT_TX_NTF_SET_SUCCESS
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