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). */
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. */
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_DISCONNECT, /**< link disconnected. */
115 /** @} */
116 
117 /**
118  * @defgroup OTAS_STRUCT Structures
119  * @{
120  */
121 /**@brief OTA Service event. */
122 typedef struct
123 {
124  otas_evt_type_t evt_type; /**< The OTAS event. */
125  uint8_t conn_idx; /**< Index of connection. */
126  uint8_t *p_data; /**< Pointer to data. */
127  uint16_t length; /**< Length of data. */
128  otas_dfu_mode_t dfu_mode; /**< OTA Service dfu mode. */
129 } otas_evt_t;
130 /** @} */
131 
132 /**
133  * @defgroup OTAS_TYPEDEF Typedefs
134  * @{
135  */
136 /**@brief OTA Service event handler type. */
137 typedef void (*otas_evt_handler_t)(otas_evt_t *p_evt);
138 /** @} */
139 
140 /**
141  * @defgroup OTAS_STRUCT Structures
142  * @{
143  */
144 /**@brief OTA Service initialization variable. */
145 typedef struct
146 {
147  otas_evt_handler_t evt_handler; /**< Handler to handle otas event. */
148 } otas_init_t;
149 /** @} */
150 
151 
152 /**
153  * @defgroup OTAS_FUNCTION Functions
154  * @{
155  */
156 /**
157  *****************************************************************************************
158  * @brief Add an OTA Service instance in the DB
159  *
160  * @param[in] p_otas_init :Pointer to OTA Service environment variable
161  *
162  * @return Result of service initialization.
163  *****************************************************************************************
164  */
166 
167 /**
168  *****************************************************************************************
169  * @brief Send data to peer device
170  *
171  * @param[in] conn_idx: Connection index
172  * @param[in] p_data: The Pointer of send value
173  * @param[in] length: The Lenth of send value
174  *
175  * @return Result of notify and indicate value
176  *****************************************************************************************
177  */
178 sdk_err_t otas_notify_tx_data(uint8_t conn_idx, uint8_t *p_data,uint16_t length);
179 
180 /**
181  *****************************************************************************************
182  * @brief Provide the interface for other modules to obtain the ots service start handle .
183  *
184  * @return The ots service start handle.
185  *****************************************************************************************
186  */
188 /** @} */
189 
190 #endif
191 
192 /** @} */
193 /** @} */
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
tx notification enable event for ota service.
Definition: otas.h:105
otas_evt_t::dfu_mode
otas_dfu_mode_t dfu_mode
OTA Service dfu mode.
Definition: otas.h:128
otas_evt_handler_t
void(* otas_evt_handler_t)(otas_evt_t *p_evt)
OTA Service event handler type.
Definition: otas.h:137
otas_evt_t
OTA Service event.
Definition: otas.h:123
OTAS_EVT_INVALID
@ OTAS_EVT_INVALID
Invalid event for ota service.
Definition: otas.h:104
otas_evt_t::p_data
uint8_t * p_data
Pointer to data.
Definition: otas.h:126
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
Response code.
Definition: otas.h:98
otas_evt_t::conn_idx
uint8_t conn_idx
Index of connection.
Definition: otas.h:125
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
OTAS Copy DFU mode (Double bank, Background).
Definition: otas.h:89
OTAS_EVT_DISCONNECT
@ OTAS_EVT_DISCONNECT
link disconnected.
Definition: otas.h:113
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
Reserved for future use.
Definition: otas.h:88
OTAS_EVT_RX_RECEIVE_DATA
@ OTAS_EVT_RX_RECEIVE_DATA
rx receive data event for ota service.
Definition: otas.h:109
otas_evt_t::length
uint16_t length
Length of data.
Definition: otas.h:127
OTAS_EVT_TX_NOTIFICATION_DISABLED
@ OTAS_EVT_TX_NOTIFICATION_DISABLED
tx notification disable event for ota service.
Definition: otas.h:106
OTAS_EVT_DFU_MODE_SET
@ OTAS_EVT_DFU_MODE_SET
set dfu mode for ota service.
Definition: otas.h:112
otas_init_t
OTA Service initialization variable.
Definition: otas.h:146
OTAS_EVT_CTRL_PT_INDICATION_ENABLED
@ OTAS_EVT_CTRL_PT_INDICATION_ENABLED
control point indication enable event for ota service.
Definition: otas.h:107
OTAS_CTRL_PT_OP_RESERVED
@ OTAS_CTRL_PT_OP_RESERVED
Reserved for future use.
Definition: otas.h:96
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
OTAS_EVT_DFU_TASK_ENTER
@ OTAS_EVT_DFU_TASK_ENTER
set dfu task enter event for ota service.
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
OTAS task enter Operation Code.
Definition: otas.h:97
OTAS_EVT_CTRL_PT_INDICATION_DISABLED
@ OTAS_EVT_CTRL_PT_INDICATION_DISABLED
control point indication disable event for ota service.
Definition: otas.h:108
OTAS_DFU_MODE_NON_COPY_UPGRADE
@ OTAS_DFU_MODE_NON_COPY_UPGRADE
OTAS Non-Copy DFU mode (Single bank, Non-background).
Definition: otas.h:90
OTAS_EVT_NOTIFY_COMPLETE
@ OTAS_EVT_NOTIFY_COMPLETE
notify complete event for ota service.
Definition: otas.h:110
otas_evt_t::evt_type
otas_evt_type_t evt_type
The OTAS event.
Definition: otas.h:124
otas_init_t::evt_handler
otas_evt_handler_t evt_handler
Handler to handle otas event.
Definition: otas.h:147
otas_evt_type_t
otas_evt_type_t
OTA Service event type.
Definition: otas.h:103