Skip to main content

zigbee_host/host/
ota_server.rs

1//! The OTA Upgrade cluster server: devices download images from the
2//! directory in [`HostConfig::ota_dir`].
3//!
4//! Nothing is offered unless asked: a device's own queries are answered
5//! "no image" (and reported, with what the directory holds for it), and a
6//! download starts only after [`Host::ota_update`] for that device.
7
8use super::*;
9use crate::ota::{self, command as oc, status as os, OtaImage, OtaStore};
10
11/// The largest block the server sends, whatever a device asks for; small
12/// enough for every coordinator family's APS payload.
13const MAX_BLOCK: u8 = 64;
14
15pub(super) struct OtaSession {
16    /// The device may download.
17    update: bool,
18    /// The image it is downloading.
19    image: Option<OtaImage>,
20    /// The version it runs.
21    from: u32,
22    /// Whoever waits for the device's query.
23    waiter: Option<oneshot::Sender<OtaOffer>>,
24    last_percent: u8,
25}
26
27/// A device's firmware and what the image directory has for it.
28#[derive(Debug, Clone, PartialEq, Eq)]
29pub struct OtaOffer {
30    /// Manufacturer code.
31    pub manufacturer: u16,
32    /// Image type.
33    pub image_type: u16,
34    /// The file version it runs.
35    pub current_version: u32,
36    /// The newest newer version in the directory.
37    pub available: Option<u32>,
38    /// That image's size.
39    pub size: Option<u32>,
40}
41
42fn u16_at(p: &[u8], i: usize) -> Option<u16> {
43    Some(u16::from_le_bytes(p.get(i..i + 2)?.try_into().ok()?))
44}
45
46fn u32_at(p: &[u8], i: usize) -> Option<u32> {
47    Some(u32::from_le_bytes(p.get(i..i + 4)?.try_into().ok()?))
48}
49
50impl<A: Adapter> Host<A> {
51    fn ota_store(&self) -> Result<OtaStore, HostError> {
52        self.inner
53            .config
54            .ota_dir
55            .as_ref()
56            .map(OtaStore::new)
57            .ok_or_else(|| HostError::Invalid("no OTA image directory is configured".into()))
58    }
59
60    /// Ask a device which firmware it runs and whether the image directory
61    /// has a newer one. The device is told to query (Image Notify) and
62    /// answered "no image"; sleepy devices answer when they next wake.
63    pub async fn ota_check(&self, ieee: Ieee) -> Result<OtaOffer, HostError> {
64        self.ota_ask(ieee, false).await
65    }
66
67    /// Start upgrading a device from the image directory. Returns once the
68    /// device took the offer; [`HostEvent::OtaProgress`] and
69    /// [`HostEvent::OtaFinished`] follow.
70    pub async fn ota_update(&self, ieee: Ieee) -> Result<OtaOffer, HostError> {
71        let offer = self.ota_ask(ieee, true).await?;
72        if offer.available.is_none() {
73            return Err(HostError::Invalid(format!(
74                "no newer image for {ieee} (manufacturer {:#06x}, image type {:#06x}, version {:#010x})",
75                offer.manufacturer, offer.image_type, offer.current_version
76            )));
77        }
78        Ok(offer)
79    }
80
81    async fn ota_ask(&self, ieee: Ieee, update: bool) -> Result<OtaOffer, HostError> {
82        self.ota_store()?;
83        let device = self.device(ieee).ok_or(HostError::UnknownDevice(ieee))?;
84        let endpoint = device
85            .endpoints
86            .iter()
87            .find(|e| e.output_clusters.contains(&ota::CLUSTER))
88            .ok_or_else(|| HostError::Invalid(format!("{ieee} has no OTA Upgrade client")))?;
89        let (tx, rx) = oneshot::channel();
90        {
91            let mut state = self.state();
92            if state.ota.get(&ieee).is_some_and(|s| s.image.is_some()) {
93                return Err(HostError::Invalid(format!(
94                    "{ieee} is already downloading an image"
95                )));
96            }
97            state.ota.insert(
98                ieee,
99                OtaSession {
100                    update,
101                    image: None,
102                    from: 0,
103                    waiter: Some(tx),
104                    last_percent: 0,
105                },
106            );
107        }
108        let mut notify = Frame::cluster(
109            Direction::ServerToClient,
110            self.next_seq(),
111            oc::IMAGE_NOTIFY,
112            // Payload type 0 (jitter only), jitter 100: query now.
113            vec![0x00, 100],
114        );
115        notify.header.disable_default_response = true;
116        let aps = Aps {
117            profile: endpoint.profile_id,
118            cluster: ota::CLUSTER,
119            source_endpoint: HOST_ENDPOINT,
120            destination_endpoint: endpoint.endpoint,
121        };
122        if let Err(e) = self
123            .inner
124            .adapter
125            .send_unicast(device.nwk, aps, notify.encode())
126            .await
127        {
128            self.state().ota.remove(&ieee);
129            return Err(e);
130        }
131        match tokio::time::timeout(self.inner.config.ota_query_timeout, rx).await {
132            Ok(Ok(offer)) => Ok(offer),
133            _ => {
134                let mut state = self.state();
135                if state.ota.get(&ieee).is_some_and(|s| s.image.is_none()) {
136                    state.ota.remove(&ieee);
137                }
138                Err(HostError::Timeout(device.nwk))
139            }
140        }
141    }
142
143    fn ota_reply(&self, source: NodeId, aps: Aps, seq: u8, command: u8, payload: Vec<u8>) {
144        let mut f = Frame::cluster(Direction::ServerToClient, seq, command, payload);
145        f.header.disable_default_response = true;
146        self.send_reply(source, aps, f);
147    }
148
149    /// A client-to-server OTA command from a device.
150    pub(super) fn on_ota(
151        &self,
152        ieee: Ieee,
153        source: NodeId,
154        aps: Aps,
155        seq: u8,
156        command: u8,
157        p: &[u8],
158    ) {
159        match command {
160            oc::QUERY_NEXT_IMAGE_REQUEST => self.ota_query(ieee, source, aps, seq, p),
161            oc::IMAGE_BLOCK_REQUEST => {
162                let (Some(offset), Some(&max)) = (u32_at(p, 9), p.get(13)) else {
163                    return;
164                };
165                self.ota_blocks(ieee, source, aps, seq, p, offset, max, 1, 0);
166            }
167            oc::IMAGE_PAGE_REQUEST => {
168                let (Some(offset), Some(&max), Some(page), Some(spacing)) =
169                    (u32_at(p, 9), p.get(13), u16_at(p, 14), u16_at(p, 16))
170                else {
171                    return;
172                };
173                let blocks = u32::from(page).div_ceil(u32::from(max.clamp(1, MAX_BLOCK)));
174                self.ota_blocks(ieee, source, aps, seq, p, offset, max, blocks, spacing);
175            }
176            oc::UPGRADE_END_REQUEST => self.ota_end(ieee, source, aps, seq, p),
177            _ => {}
178        }
179    }
180
181    fn ota_query(&self, ieee: Ieee, source: NodeId, aps: Aps, seq: u8, p: &[u8]) {
182        let (Some(&fc), Some(manufacturer), Some(image_type), Some(current)) =
183            (p.first(), u16_at(p, 1), u16_at(p, 3), u32_at(p, 5))
184        else {
185            return;
186        };
187        let hardware = if fc & 0x01 != 0 { u16_at(p, 9) } else { None };
188        let image = self
189            .ota_store()
190            .ok()
191            .and_then(|s| s.newer(manufacturer, image_type, current, hardware, ieee));
192        let offer = OtaOffer {
193            manufacturer,
194            image_type,
195            current_version: current,
196            available: image.as_ref().map(|i| i.header.file_version),
197            size: image.as_ref().map(|i| i.header.total_size),
198        };
199        let accept = {
200            let mut state = self.state();
201            let accept = match (state.ota.get_mut(&ieee), &image) {
202                (Some(session), Some(image)) if session.update => {
203                    session.image = Some(image.clone());
204                    session.from = current;
205                    session.last_percent = 0;
206                    true
207                }
208                _ => false,
209            };
210            if let Some(session) = state.ota.get_mut(&ieee) {
211                if let Some(waiter) = session.waiter.take() {
212                    let _ = waiter.send(offer.clone());
213                }
214            }
215            if !accept {
216                state.ota.remove(&ieee);
217            }
218            accept
219        };
220        self.emit(HostEvent::OtaQuery {
221            ieee,
222            current_version: current,
223            available: offer.available,
224        });
225        let payload = match (&image, accept) {
226            (Some(image), true) => {
227                tracing::info!(%ieee, from = format!("{current:#010x}"), to = format!("{:#010x}", image.header.file_version), "OTA upgrade starting");
228                let mut v = vec![os::SUCCESS];
229                v.extend_from_slice(&manufacturer.to_le_bytes());
230                v.extend_from_slice(&image_type.to_le_bytes());
231                v.extend_from_slice(&image.header.file_version.to_le_bytes());
232                v.extend_from_slice(&image.header.total_size.to_le_bytes());
233                v
234            }
235            _ => vec![os::NO_IMAGE_AVAILABLE],
236        };
237        self.ota_reply(source, aps, seq, oc::QUERY_NEXT_IMAGE_RESPONSE, payload);
238    }
239
240    #[allow(clippy::too_many_arguments)]
241    fn ota_blocks(
242        &self,
243        ieee: Ieee,
244        source: NodeId,
245        aps: Aps,
246        seq: u8,
247        p: &[u8],
248        offset: u32,
249        max: u8,
250        blocks: u32,
251        spacing_ms: u16,
252    ) {
253        let (Some(manufacturer), Some(image_type), Some(version)) =
254            (u16_at(p, 1), u16_at(p, 3), u32_at(p, 5))
255        else {
256            return;
257        };
258        let image = self
259            .state()
260            .ota
261            .get(&ieee)
262            .and_then(|s| s.image.clone())
263            .filter(|i| {
264                i.header.manufacturer == manufacturer
265                    && i.header.image_type == image_type
266                    && i.header.file_version == version
267            });
268        let Some(image) = image else {
269            // Nothing offered (or the host restarted): stop the download.
270            self.ota_reply(source, aps, seq, oc::IMAGE_BLOCK_RESPONSE, vec![os::ABORT]);
271            return;
272        };
273        let size = image.header.total_size;
274        let block = usize::from(max.clamp(1, MAX_BLOCK));
275        let host = self.clone();
276        tokio::spawn(async move {
277            let mut offset = offset;
278            for i in 0..blocks.min(256) {
279                if offset >= size {
280                    break;
281                }
282                if i > 0 && spacing_ms > 0 {
283                    tokio::time::sleep(Duration::from_millis(u64::from(spacing_ms.min(1000))))
284                        .await;
285                }
286                let data = match image.read(offset, block).await {
287                    Ok(d) => d,
288                    Err(e) => {
289                        tracing::warn!(%ieee, error = %e, "reading the OTA image");
290                        host.ota_reply(source, aps, seq, oc::IMAGE_BLOCK_RESPONSE, vec![os::ABORT]);
291                        return;
292                    }
293                };
294                let mut v = vec![os::SUCCESS];
295                v.extend_from_slice(&manufacturer.to_le_bytes());
296                v.extend_from_slice(&image_type.to_le_bytes());
297                v.extend_from_slice(&version.to_le_bytes());
298                v.extend_from_slice(&offset.to_le_bytes());
299                v.push(data.len() as u8);
300                v.extend_from_slice(&data);
301                host.ota_reply(source, aps, seq, oc::IMAGE_BLOCK_RESPONSE, v);
302                offset += data.len() as u32;
303                host.ota_progress(ieee, offset, size);
304            }
305        });
306    }
307
308    fn ota_progress(&self, ieee: Ieee, done: u32, size: u32) {
309        let percent = (u64::from(done) * 100 / u64::from(size.max(1))).min(100) as u8;
310        let report = {
311            let mut state = self.state();
312            match state.ota.get_mut(&ieee) {
313                Some(s)
314                    if percent >= s.last_percent.saturating_add(10)
315                        || (percent == 100 && s.last_percent < 100) =>
316                {
317                    s.last_percent = percent;
318                    true
319                }
320                _ => false,
321            }
322        };
323        if report {
324            self.emit(HostEvent::OtaProgress { ieee, percent });
325        }
326    }
327
328    fn ota_end(&self, ieee: Ieee, source: NodeId, aps: Aps, seq: u8, p: &[u8]) {
329        let (Some(&status), Some(manufacturer), Some(image_type), Some(version)) =
330            (p.first(), u16_at(p, 1), u16_at(p, 3), u32_at(p, 5))
331        else {
332            return;
333        };
334        let Some(session) = self.state().ota.remove(&ieee) else {
335            return;
336        };
337        let success = status == os::SUCCESS;
338        if success {
339            let mut v = Vec::with_capacity(16);
340            v.extend_from_slice(&manufacturer.to_le_bytes());
341            v.extend_from_slice(&image_type.to_le_bytes());
342            v.extend_from_slice(&version.to_le_bytes());
343            // Current time 0, upgrade time 0: apply now.
344            v.extend_from_slice(&0u32.to_le_bytes());
345            v.extend_from_slice(&0u32.to_le_bytes());
346            self.ota_reply(source, aps, seq, oc::UPGRADE_END_RESPONSE, v);
347            tracing::info!(%ieee, version = format!("{version:#010x}"), "OTA upgrade finished");
348            // The new firmware may report and bind differently: interview
349            // again once it has restarted.
350            let host = self.clone();
351            tokio::spawn(async move {
352                tokio::time::sleep(Duration::from_secs(30)).await;
353                let _ = host.reinterview(ieee);
354            });
355        } else {
356            tracing::warn!(%ieee, status, "OTA upgrade failed on the device");
357        }
358        self.emit(HostEvent::OtaFinished {
359            ieee,
360            from: session.from,
361            to: version,
362            success,
363            status,
364        });
365    }
366}