Line data Source code
1 0 : /*
2 : * Copyright (c) 2020 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @defgroup bt_mesh_dfu_srv Firmware Update Server model
10 : * @ingroup bt_mesh_dfu
11 : * @{
12 : * @brief API for the Bluetooth Mesh Firmware Update Server model
13 : */
14 :
15 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_DFU_SRV_H__
16 : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_DFU_SRV_H__
17 :
18 : #include <zephyr/bluetooth/mesh/dfu.h>
19 : #include <zephyr/bluetooth/mesh/blob_srv.h>
20 : #include <zephyr/bluetooth/mesh/access.h>
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : struct bt_mesh_dfu_srv;
27 :
28 : /**
29 : *
30 : * @brief Initialization parameters for @ref bt_mesh_dfu_srv.
31 : *
32 : * @param _handlers DFU handler function structure.
33 : * @param _imgs List of @ref bt_mesh_dfu_img managed by this Server.
34 : * @param _img_count Number of DFU images managed by this Server.
35 : */
36 1 : #define BT_MESH_DFU_SRV_INIT(_handlers, _imgs, _img_count) \
37 : { \
38 : .blob = { .cb = &_bt_mesh_dfu_srv_blob_cb }, .cb = _handlers, \
39 : .imgs = _imgs, .img_count = _img_count, \
40 : }
41 :
42 : /**
43 : *
44 : * @brief Firmware Update Server model entry.
45 : *
46 : * @param _srv Pointer to a @ref bt_mesh_dfu_srv instance.
47 : */
48 1 : #define BT_MESH_MODEL_DFU_SRV(_srv) \
49 : BT_MESH_MODEL_BLOB_SRV(&(_srv)->blob), \
50 : BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_DFU_SRV, _bt_mesh_dfu_srv_op, NULL, \
51 : _srv, &_bt_mesh_dfu_srv_cb)
52 :
53 : /** @brief Firmware Update Server event callbacks. */
54 1 : struct bt_mesh_dfu_srv_cb {
55 : /** @brief Transfer check callback.
56 : *
57 : * The transfer check can be used to validate the incoming transfer
58 : * before it starts. The contents of the metadata is implementation
59 : * specific, and should contain all the information the application
60 : * needs to determine whether this image should be accepted, and what
61 : * the effect of the transfer would be.
62 : *
63 : * If applying the image will have an effect on the provisioning state
64 : * of the mesh stack, this can be communicated through the @c effect
65 : * return parameter.
66 : *
67 : * The metadata check can be performed both as part of starting a new
68 : * transfer and as a separate procedure.
69 : *
70 : * This handler is optional.
71 : *
72 : * @param srv Firmware Update Server instance.
73 : * @param img DFU image the metadata check is performed on.
74 : * @param metadata Image metadata.
75 : * @param effect Return parameter for the image effect on the
76 : * provisioning state of the mesh stack.
77 : *
78 : * @return 0 on success, or (negative) error code otherwise.
79 : */
80 1 : int (*check)(struct bt_mesh_dfu_srv *srv,
81 : const struct bt_mesh_dfu_img *img,
82 : struct net_buf_simple *metadata,
83 : enum bt_mesh_dfu_effect *effect);
84 :
85 : /** @brief Transfer start callback.
86 : *
87 : * Called when the Firmware Update Server is ready to start a new DFU transfer.
88 : * The application must provide an initialized BLOB stream to be used
89 : * during the DFU transfer.
90 : *
91 : * The following error codes are treated specially, and should be used
92 : * to communicate these issues:
93 : * - @c -ENOMEM: The device cannot fit this image.
94 : * - @c -EBUSY: The application is temporarily unable to accept the
95 : * transfer.
96 : * - @c -EALREADY: The device has already received and verified this
97 : * image, and there's no need to transfer it again. The Firmware Update model
98 : * will skip the transfer phase, and mark the image as verified.
99 : *
100 : * This handler is mandatory.
101 : *
102 : * @param srv Firmware Update Server instance.
103 : * @param img DFU image being updated.
104 : * @param metadata Image metadata.
105 : * @param io BLOB stream return parameter. Must be set to a
106 : * valid BLOB stream by the callback.
107 : *
108 : * @return 0 on success, or (negative) error code otherwise. Return
109 : * codes @c -ENOMEM, @c -EBUSY @c -EALREADY will be passed to
110 : * the updater, other error codes are reported as internal
111 : * errors.
112 : */
113 1 : int (*start)(struct bt_mesh_dfu_srv *srv,
114 : const struct bt_mesh_dfu_img *img,
115 : struct net_buf_simple *metadata,
116 : const struct bt_mesh_blob_io **io);
117 :
118 : /** @brief Transfer end callback.
119 : *
120 : * This handler is optional.
121 : *
122 : * If the transfer is successful, the application should verify the
123 : * firmware image, and call either @ref bt_mesh_dfu_srv_verified or
124 : * @ref bt_mesh_dfu_srv_rejected depending on the outcome.
125 : *
126 : * If the transfer fails, the Firmware Update Server will be available for new
127 : * transfers immediately after this function returns.
128 : *
129 : * @param srv Firmware Update Server instance.
130 : * @param img DFU image that failed the update.
131 : * @param success Whether the DFU transfer was successful.
132 : */
133 1 : void (*end)(struct bt_mesh_dfu_srv *srv,
134 : const struct bt_mesh_dfu_img *img, bool success);
135 :
136 : /** @brief Transfer recovery callback.
137 : *
138 : * If the device reboots in the middle of a transfer, the Firmware Update Server
139 : * calls this function when the Bluetooth Mesh subsystem is started.
140 : *
141 : * This callback is optional, but transfers will not be recovered after
142 : * a reboot without it.
143 : *
144 : * @param srv Firmware Update Server instance.
145 : * @param img DFU image being updated.
146 : * @param io BLOB stream return parameter. Must be set to a valid BLOB
147 : * stream by the callback.
148 : *
149 : * @return 0 on success, or (negative) error code to abandon the
150 : * transfer.
151 : */
152 1 : int (*recover)(struct bt_mesh_dfu_srv *srv,
153 : const struct bt_mesh_dfu_img *img,
154 : const struct bt_mesh_blob_io **io);
155 :
156 : /** @brief Transfer apply callback.
157 : *
158 : * Called after a transfer has been validated, and the updater sends an
159 : * apply message to the Target nodes.
160 : *
161 : * This handler is optional.
162 : *
163 : * @param srv Firmware Update Server instance.
164 : * @param img DFU image that should be applied.
165 : *
166 : * @return 0 on success, or (negative) error code otherwise.
167 : */
168 1 : int (*apply)(struct bt_mesh_dfu_srv *srv,
169 : const struct bt_mesh_dfu_img *img);
170 : };
171 :
172 : /** @brief Firmware Update Server instance.
173 : *
174 : * Should be initialized with @ref BT_MESH_DFU_SRV_INIT.
175 : */
176 1 : struct bt_mesh_dfu_srv {
177 : /** Underlying BLOB Transfer Server. */
178 1 : struct bt_mesh_blob_srv blob;
179 : /** Callback structure. */
180 1 : const struct bt_mesh_dfu_srv_cb *cb;
181 : /** List of updatable images. */
182 1 : const struct bt_mesh_dfu_img *imgs;
183 : /** Number of updatable images. */
184 1 : size_t img_count;
185 :
186 : /* Runtime state */
187 0 : const struct bt_mesh_model *mod;
188 : struct {
189 : /* Effect of transfer, @see bt_mesh_dfu_effect. */
190 0 : uint8_t effect;
191 : /* Current phase, @see bt_mesh_dfu_phase. */
192 0 : uint8_t phase;
193 0 : uint8_t ttl;
194 0 : uint8_t idx;
195 0 : uint16_t timeout_base;
196 0 : uint16_t meta;
197 0 : } update;
198 : };
199 :
200 : /** @brief Accept the received DFU transfer.
201 : *
202 : * Should be called at the end of a successful DFU transfer.
203 : *
204 : * If the DFU transfer completes successfully, the application should verify
205 : * the image validity (including any image authentication or integrity checks),
206 : * and call this function if the image is ready to be applied.
207 : *
208 : * @param srv Firmware Update Server instance.
209 : */
210 1 : void bt_mesh_dfu_srv_verified(struct bt_mesh_dfu_srv *srv);
211 :
212 : /** @brief Reject the received DFU transfer.
213 : *
214 : * Should be called at the end of a successful DFU transfer.
215 : *
216 : * If the DFU transfer completes successfully, the application should verify
217 : * the image validity (including any image authentication or integrity checks),
218 : * and call this function if one of the checks fail.
219 : *
220 : * @param srv Firmware Update Server instance.
221 : */
222 1 : void bt_mesh_dfu_srv_rejected(struct bt_mesh_dfu_srv *srv);
223 :
224 : /** @brief Cancel the ongoing DFU transfer.
225 : *
226 : * @param srv Firmware Update Server instance.
227 : */
228 1 : void bt_mesh_dfu_srv_cancel(struct bt_mesh_dfu_srv *srv);
229 :
230 : /** @brief Confirm that the received DFU transfer was applied.
231 : *
232 : * Should be called as a result of the @ref bt_mesh_dfu_srv_cb.apply callback.
233 : *
234 : * @param srv Firmware Update Server instance.
235 : */
236 1 : void bt_mesh_dfu_srv_applied(struct bt_mesh_dfu_srv *srv);
237 :
238 : /** @brief Check if the Firmware Update Server is busy processing a transfer.
239 : *
240 : * @param srv Firmware Update Server instance.
241 : *
242 : * @return true if a DFU procedure is in progress, false otherwise.
243 : */
244 1 : bool bt_mesh_dfu_srv_is_busy(const struct bt_mesh_dfu_srv *srv);
245 :
246 : /** @brief Get the progress of the current DFU procedure, in percent.
247 : *
248 : * @param srv Firmware Update Server instance.
249 : *
250 : * @return The current transfer progress in percent.
251 : */
252 1 : uint8_t bt_mesh_dfu_srv_progress(const struct bt_mesh_dfu_srv *srv);
253 :
254 : /** @cond INTERNAL_HIDDEN */
255 : extern const struct bt_mesh_model_op _bt_mesh_dfu_srv_op[];
256 : extern const struct bt_mesh_model_cb _bt_mesh_dfu_srv_cb;
257 : extern const struct bt_mesh_blob_srv_cb _bt_mesh_dfu_srv_blob_cb;
258 : /** @endcond */
259 :
260 : #ifdef __cplusplus
261 : }
262 : #endif
263 :
264 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_DFU_SRV_H__ */
265 :
266 : /** @} */
|
