otas.h
Go to the documentation of this file.
1 /**
2 ****************************************************************************************
3 *
4 * @file otas.h
5 *
6 * @brief Over The Air Service 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 * @brief Definitions and prototypes for the BLE Service interface.
42 */
43
44 /**
45 * @defgroup BLE_SDK_OTA OTA Service (OTAS)
46 * @{
47 * @brief Definitions and prototypes for the OTAS interface.
48 *
49 * @details The OTA Service is a customized service with Tx, Rx and Flow Control
50 * characteristics. This module implements the Battery Service with the Battery Level
51 * characteristic. After @ref otas_init_t variable is initialized, the
52 * developer shall call @ref otas_service_init() to add the OTA
53 * Service and RX, TX, Control characteristic to the BLE stack database.
54 *
55 * This module also provides \ref otas_notify_tx_data() function to the application
56 * to send data to peer.
57 */
58
59 #ifndef _OTAS_H_
60 #define _OTAS_H_
61
62 /*
63 * INCLUDE FILES
64 ****************************************************************************************
65 */
66 #include "gr_includes.h"
67 #include "custom_config.h"
68 #include "flash_scatter_config.h"
69
70 /**
71 * @defgroup OTAS_MACRO Defines
72 * @{
73 */
74 #define OTAS_CONNECTION_MAX 10 /**< Maximum number of OTA Service connections. */
75 #define OTAS_MAX_DATA_LEN 244 /**< Maximum length of OTAS characteristic. */
76 #define OTAS_VERSION 0x02 /**< The OTA VERSION. */
77 #define BLE_UUID_OTA_SERVICE 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
78 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x04, 0xED, 0xA6 /**< The UUID of OTA Service for setting advertising data. */
79 /** @} */
80
81 /**
82 * @defgroup OTA_ENUM Enumerations
83 * @{
84 */
85 /**@brief OTA Service dfu mode.*/
86 typedef enum
87 {
88 OTAS_DFU_MODE_RESERVED, /**< Reserved for future use. */
89 OTAS_DFU_MODE_COPY_UPGRADE, /**< OTAS Copy DFU mode (Double bank, Background). */
90 OTAS_DFU_MODE_NON_COPY_UPGRADE, /**< OTAS Non-Copy DFU mode (Single bank, Non-background). */
91 } otas_dfu_mode_t;
92
93 /**@brief OTA Service Control Point Operation Code.*/
94 typedef enum
95 {
96 OTAS_CTRL_PT_OP_RESERVED, /**< Reserved for future use. */
97 OTAS_CTRL_PT_OP_DFU_ENTER = 0x474f4f44, /**< OTAS task enter Operation Code.*/
98 OTAS_CTRL_PT_OP_RSP_CODE = 0x10, /**< Response code. */
99 } otas_ctrl_pt_op_code_t;
100
101 /**@brief OTA Service event type. */
102 typedef enum
103 {
104 OTAS_EVT_INVALID, /**< Invalid event for ota service. */
105 OTAS_EVT_TX_NOTIFICATION_ENABLED, /**< tx notification enable event for ota service. */
106 OTAS_EVT_TX_NOTIFICATION_DISABLED, /**< tx notification disable event for ota service. */
107 OTAS_EVT_CTRL_PT_INDICATION_ENABLED, /**< control point indication enable event for ota service. */
108 OTAS_EVT_CTRL_PT_INDICATION_DISABLED, /**< control point indication disable event for ota service. */
109 OTAS_EVT_RX_RECEIVE_DATA, /**< rx receive data event for ota service. */
110 OTAS_EVT_NOTIFY_COMPLETE, /**< notify complete event for ota service. */
111 OTAS_EVT_DFU_TASK_ENTER, /**< set dfu task enter event for ota service. */
112 OTAS_EVT_DFU_MODE_SET, /**< set dfu mode for ota service. */
113 } otas_evt_type_t;
114 /** @} */
115
116 /**
117 * @defgroup OTAS_STRUCT Structures
118 * @{
119 */
120 /**@brief OTA Service event. */
121 typedef struct
122 {
123 otas_evt_type_t evt_type; /**< The OTAS event. */
124 uint8_t conn_idx; /**< Index of connection. */
125 uint8_t *p_data; /**< Pointer to data. */
126 uint16_t length; /**< Length of data. */
127 otas_dfu_mode_t dfu_mode; /**< OTA Service dfu mode. */
128 } otas_evt_t;
129 /** @} */
130
131 /**
132 * @defgroup OTAS_TYPEDEF Typedefs
133 * @{
134 */
135 /**@brief OTA Service event handler type. */
136 typedef void (*otas_evt_handler_t)(otas_evt_t *p_evt);
137 /** @} */
138
139 /**
140 * @defgroup OTAS_STRUCT Structures
141 * @{
142 */
143 /**@brief OTA Service initialization variable. */
144 typedef struct
145 {
146 otas_evt_handler_t evt_handler; /**< Handler to handle otas event. */
147 } otas_init_t;
148 /** @} */
149
150
151 /**
152 * @defgroup OTAS_FUNCTION Functions
153 * @{
154 */
155 /**
156 *****************************************************************************************
157 * @brief Add an OTA Service instance in the DB
158 *
159 * @param[in] p_otas_init :Pointer to OTA Service environment variable
160 *
161 * @return Result of service initialization.
162 *****************************************************************************************
163 */
164 sdk_err_t otas_service_init(otas_init_t *p_otas_init);
165
166 /**
167 *****************************************************************************************
168 * @brief Send data to peer device
169 *
170 * @param[in] conn_idx: Connection index
171 * @param[in] p_data: The Pointer of send value
172 * @param[in] length: The Lenth of send value
173 *
174 * @return Result of notify and indicate value
175 *****************************************************************************************
176 */
177 sdk_err_t otas_notify_tx_data(uint8_t conn_idx, uint8_t *p_data,uint16_t length);
178
179 /**
180 *****************************************************************************************
181 * @brief Provide the interface for other modules to obtain the ots service start handle .
182 *
183 * @return The ots service start handle.
184 *****************************************************************************************
185 */
186 uint16_t otas_service_start_handle_get(void);
187 /** @} */
188
189 #endif
190
191 /** @} */
192 /** @} */
otas_notify_tx_data
sdk_err_t otas_notify_tx_data(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer device.
OTAS_EVT_TX_NOTIFICATION_ENABLED
@ OTAS_EVT_TX_NOTIFICATION_ENABLED
Definition: otas.h:105
otas_evt_t::dfu_mode
otas_dfu_mode_t dfu_mode
Definition: otas.h:127
otas_evt_handler_t
void(* otas_evt_handler_t)(otas_evt_t *p_evt)
OTA Service event handler type.
Definition: otas.h:136
otas_evt_t
OTA Service event.
Definition: otas.h:122
OTAS_EVT_INVALID
@ OTAS_EVT_INVALID
Definition: otas.h:104
otas_evt_t::p_data
uint8_t * p_data
Definition: otas.h:125
otas_service_start_handle_get
uint16_t otas_service_start_handle_get(void)
Provide the interface for other modules to obtain the ots service start handle .
OTAS_CTRL_PT_OP_RSP_CODE
@ OTAS_CTRL_PT_OP_RSP_CODE
Definition: otas.h:98
otas_evt_t::conn_idx
uint8_t conn_idx
Definition: otas.h:124
gr_includes.h
Include Files API.
otas_dfu_mode_t
otas_dfu_mode_t
OTA Service dfu mode.
Definition: otas.h:87
OTAS_DFU_MODE_COPY_UPGRADE
@ OTAS_DFU_MODE_COPY_UPGRADE
Definition: otas.h:89
otas_ctrl_pt_op_code_t
otas_ctrl_pt_op_code_t
OTA Service Control Point Operation Code.
Definition: otas.h:95
OTAS_DFU_MODE_RESERVED
@ OTAS_DFU_MODE_RESERVED
Definition: otas.h:88
OTAS_EVT_RX_RECEIVE_DATA
@ OTAS_EVT_RX_RECEIVE_DATA
Definition: otas.h:109
otas_evt_t::length
uint16_t length
Definition: otas.h:126
OTAS_EVT_TX_NOTIFICATION_DISABLED
@ OTAS_EVT_TX_NOTIFICATION_DISABLED
Definition: otas.h:106
OTAS_EVT_DFU_MODE_SET
@ OTAS_EVT_DFU_MODE_SET
Definition: otas.h:112
otas_init_t
OTA Service initialization variable.
Definition: otas.h:145
OTAS_EVT_CTRL_PT_INDICATION_ENABLED
@ OTAS_EVT_CTRL_PT_INDICATION_ENABLED
Definition: otas.h:107
OTAS_CTRL_PT_OP_RESERVED
@ OTAS_CTRL_PT_OP_RESERVED
Definition: otas.h:96
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:257
OTAS_EVT_DFU_TASK_ENTER
@ OTAS_EVT_DFU_TASK_ENTER
Definition: otas.h:111
otas_service_init
sdk_err_t otas_service_init(otas_init_t *p_otas_init)
Add an OTA Service instance in the DB.
OTAS_CTRL_PT_OP_DFU_ENTER
@ OTAS_CTRL_PT_OP_DFU_ENTER
Definition: otas.h:97
OTAS_EVT_CTRL_PT_INDICATION_DISABLED
@ OTAS_EVT_CTRL_PT_INDICATION_DISABLED
Definition: otas.h:108
OTAS_DFU_MODE_NON_COPY_UPGRADE
@ OTAS_DFU_MODE_NON_COPY_UPGRADE
Definition: otas.h:90
OTAS_EVT_NOTIFY_COMPLETE
@ OTAS_EVT_NOTIFY_COMPLETE
Definition: otas.h:110
otas_evt_t::evt_type
otas_evt_type_t evt_type
Definition: otas.h:123
otas_init_t::evt_handler
otas_evt_handler_t evt_handler
Definition: otas.h:146
otas_evt_type_t
otas_evt_type_t
OTA Service event type.
Definition: otas.h:103