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. */
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  uint32_t dfu_fw_save_addr; /**< Address of bank1 for dfu firmware save. */
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 DFU Firmware save address set.
170  *
171  * @param[in] dfu_fw_save_addr: DFU firmware save addrss..
172  *****************************************************************************************
173  */
174 void ota_fw_save_addr_set(uint32_t dfu_fw_save_addr);
175 
176 /**
177  *****************************************************************************************
178  * @brief Send data to peer device
179  *
180  * @param[in] conn_idx: Connection index
181  * @param[in] p_data: The Pointer of send value
182  * @param[in] length: The Lenth of send value
183  *
184  * @return Result of notify and indicate value
185  *****************************************************************************************
186  */
187 sdk_err_t otas_notify_tx_data(uint8_t conn_idx, uint8_t *p_data,uint16_t length);
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
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
ota_fw_save_addr_set
void ota_fw_save_addr_set(uint32_t dfu_fw_save_addr)
DFU Firmware save address set.
OTAS_EVT_INVALID
@ OTAS_EVT_INVALID
Definition: otas.h:104
otas_evt_t::p_data
uint8_t * p_data
Definition: otas.h:125
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_init_t::dfu_fw_save_addr
uint32_t dfu_fw_save_addr
Definition: otas.h:146
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:273
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:147
otas_evt_type_t
otas_evt_type_t
OTA Service event type.
Definition: otas.h:103