Skip to main content

zwave_host/
firmware.rs

1//! Firmware updates over the air (Firmware Update Meta Data command class).
2//!
3//! The controller offers an image; the node asks for it in numbered
4//! fragments, each carrying a CRC-16, checks the whole image's CRC-16, and
5//! reports the outcome. Images may need activation afterwards.
6
7use crate::controller::{Controller, Inbound};
8use crate::{Error, Event, NodeId};
9use std::time::Duration;
10use tracing::{debug, info};
11use zwave_cc::{crc16, firmware_update_md as fw, Command};
12
13/// How long the node may take between fragment requests.
14pub const FRAGMENT_TIMEOUT: Duration = Duration::from_secs(60);
15/// How long the node may take to report the result after the last fragment.
16pub const STATUS_TIMEOUT: Duration = Duration::from_secs(120);
17/// Largest image accepted.
18pub const MAX_IMAGE: usize = 8 * 1024 * 1024;
19
20/// How an update ended.
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub struct FirmwareUpdateResult {
23    /// The node's status: `0xFF` done and restarting, `0xFE` done without
24    /// restart, `0xFD` waiting for activation; below `0x10` an error.
25    pub status: u8,
26    /// Seconds until the node is back, if it says.
27    pub wait_time: Option<u16>,
28    /// Whether activation succeeded, if it was needed.
29    pub activated: Option<bool>,
30}
31
32impl FirmwareUpdateResult {
33    /// Whether the node accepted the image.
34    pub fn success(&self) -> bool {
35        self.status >= 0xfd && self.activated != Some(false)
36    }
37}
38
39/// Reads a firmware file: Intel HEX (`.hex`, or text starting with `:`) is
40/// turned into a binary image from its lowest address with gaps filled with
41/// `0xFF`; anything else (`.gbl`, `.bin`, `.ota`) is sent as it is.
42pub fn read_image(name: &str, bytes: &[u8]) -> Result<Vec<u8>, String> {
43    if bytes.len() > MAX_IMAGE * 3 {
44        return Err("file too large".into());
45    }
46    let is_hex = name.to_ascii_lowercase().ends_with(".hex") || bytes.first() == Some(&b':');
47    if !is_hex {
48        if bytes.is_empty() || bytes.len() > MAX_IMAGE {
49            return Err("image empty or too large".into());
50        }
51        return Ok(bytes.to_vec());
52    }
53    let text = std::str::from_utf8(bytes).map_err(|_| "Intel HEX file is not text".to_string())?;
54    let mut chunks: Vec<(u32, Vec<u8>)> = Vec::new();
55    let mut base: u32 = 0;
56    for rec in ihex::Reader::new(text) {
57        match rec.map_err(|e| e.to_string())? {
58            ihex::Record::Data { offset, value } => chunks.push((base + u32::from(offset), value)),
59            ihex::Record::ExtendedLinearAddress(a) => base = u32::from(a) << 16,
60            ihex::Record::ExtendedSegmentAddress(a) => base = u32::from(a) << 4,
61            ihex::Record::EndOfFile => break,
62            _ => {}
63        }
64    }
65    let start = chunks
66        .iter()
67        .map(|c| c.0)
68        .min()
69        .ok_or("no data in Intel HEX file")?;
70    let end = chunks
71        .iter()
72        .map(|c| c.0 as usize + c.1.len())
73        .max()
74        .unwrap_or(0);
75    let len = end - start as usize;
76    if len > MAX_IMAGE {
77        return Err("image too large".into());
78    }
79    let mut image = vec![0xffu8; len];
80    for (addr, data) in chunks {
81        let o = (addr - start) as usize;
82        image[o..o + data.len()].copy_from_slice(&data);
83    }
84    Ok(image)
85}
86
87/// A Firmware Update Meta Data Report command (a fragment) with its CRC.
88pub fn fragment(number: u16, last: bool, data: &[u8]) -> Vec<u8> {
89    let header = (number & 0x7fff) | if last { 0x8000 } else { 0 };
90    let mut v = Command::from(fw::Report {
91        header,
92        data: data.to_vec(),
93    })
94    .encode();
95    let crc = crc16::checksum(&v);
96    v.extend_from_slice(&crc.to_be_bytes());
97    v
98}
99
100/// Splits a received fragment command into number, last flag and data,
101/// checking its CRC; `None` if it does not check out.
102pub fn parse_fragment(frame: &[u8]) -> Option<(u16, bool, &[u8])> {
103    if frame.len() < 6 || frame[0] != 0x7a || frame[1] != 0x06 {
104        return None;
105    }
106    let (body, crc) = frame.split_at(frame.len() - 2);
107    if crc16::checksum(body) != u16::from_be_bytes([crc[0], crc[1]]) {
108        return None;
109    }
110    let header = u16::from_be_bytes([body[2], body[3]]);
111    Some((header & 0x7fff, header & 0x8000 != 0, &body[4..]))
112}
113
114async fn next_fw(
115    node: NodeId,
116    rx: &mut tokio::sync::mpsc::UnboundedReceiver<Inbound>,
117    t: Duration,
118) -> Result<fw::Command, Error> {
119    match tokio::time::timeout(t, rx.recv()).await {
120        Ok(Some(Inbound::Command {
121            command: Command::FirmwareUpdateMd(c),
122            ..
123        })) => Ok(c),
124        Ok(_) => Err(Error::Stopped),
125        Err(_) => Err(Error::Timeout(node)),
126    }
127}
128
129impl Controller {
130    /// Updates a node's firmware target (0 is the main firmware) with `image`.
131    /// Emits [`Event::FirmwareUpdateProgress`] as fragments go out.
132    pub async fn update_firmware(
133        &self,
134        node: NodeId,
135        image: &[u8],
136        target: u8,
137    ) -> Result<FirmwareUpdateResult, Error> {
138        if image.is_empty() || image.len() > MAX_IMAGE {
139            return Err(Error::Controller(
140                "firmware image empty or too large".into(),
141            ));
142        }
143        let (version, security) = self
144            .with_node(node, |r| {
145                (
146                    r.root().version(fw::ID),
147                    r.highest_s2().map(|_| 2).or(r.s0_only().then_some(0)),
148                )
149            })
150            .ok_or(Error::UnknownNode(node))?;
151        if version == 0 {
152            return Err(Error::Controller(format!(
153                "node {node} does not support firmware updates"
154            )));
155        }
156        let _a = self.activity(node);
157        self.wait_awake(node).await;
158        let (_g, mut rx) = self.subscribe(node, |i| {
159            matches!(
160                i,
161                Inbound::Command {
162                    command: Command::FirmwareUpdateMd(_),
163                    ..
164                }
165            )
166        });
167        let send = |c: Command| self.send_encoded(node, 0, fw::ID, c.encode());
168
169        send(fw::MetaDataGet {}.into()).await?;
170        let md = loop {
171            if let fw::Command::MetaDataReport(r) =
172                next_fw(node, &mut rx, self.inner.cfg.request_timeout).await?
173            {
174                break r;
175            }
176        };
177        if md.upgradable == Some(0) {
178            return Err(Error::Controller(format!(
179                "node {node} says its firmware is not upgradable"
180            )));
181        }
182        let firmware_id = if target == 0 {
183            md.firmware_id
184        } else {
185            let i = 2 * usize::from(target - 1);
186            md.rest
187                .get(i..i + 2)
188                .map(|b| u16::from_be_bytes([b[0], b[1]]))
189                .ok_or(Error::Controller(format!(
190                    "node {node} has no firmware target {target}"
191                )))?
192        };
193        // Fragment data per frame: what fits a frame after the report header
194        // and CRC, and the security encapsulation.
195        let budget: u16 = match security {
196            Some(2) => 28,
197            Some(_) => 20,
198            None => 40,
199        };
200        let size = match (version >= 3, md.max_fragment_size) {
201            (true, Some(m)) if m > 0 => budget.min(m),
202            _ => budget,
203        };
204        let checksum = crc16::checksum(image);
205        let mut req = fw::RequestGet {
206            manufacturer_id: md.manufacturer_id,
207            firmware_id,
208            checksum,
209            ..Default::default()
210        };
211        if version >= 3 {
212            req.target = Some(target);
213            req.fragment_size = Some(size);
214        }
215        if version >= 4 {
216            req.resume = Some(false);
217            req.non_secure = Some(false);
218            req.activation = Some(false);
219        }
220        send(req.into()).await?;
221        let status = loop {
222            if let fw::Command::RequestReport(r) =
223                next_fw(node, &mut rx, self.inner.cfg.request_timeout).await?
224            {
225                break r.status;
226            }
227        };
228        if status != 0xff {
229            return Err(Error::Controller(format!(
230                "node {node} refused the update (status {status})"
231            )));
232        }
233        info!(node, bytes = image.len(), size, "firmware transfer started");
234        let total = image.len().div_ceil(usize::from(size)) as u16;
235        let result = loop {
236            let t = FRAGMENT_TIMEOUT.max(STATUS_TIMEOUT);
237            match next_fw(node, &mut rx, t).await? {
238                fw::Command::Get(g) => {
239                    let first = g.report & 0x7fff;
240                    for n in first..first.saturating_add(u16::from(g.count.max(1))) {
241                        if n == 0 || n > total {
242                            break;
243                        }
244                        let start = usize::from(n - 1) * usize::from(size);
245                        let end = (start + usize::from(size)).min(image.len());
246                        let frame = fragment(n, n == total, &image[start..end]);
247                        self.send_encoded(node, 0, fw::ID, frame).await?;
248                        self.emit(Event::FirmwareUpdateProgress {
249                            node,
250                            sent: n,
251                            total,
252                        });
253                    }
254                }
255                fw::Command::StatusReport(s) => {
256                    break FirmwareUpdateResult {
257                        status: s.status,
258                        wait_time: s.wait_time,
259                        activated: None,
260                    }
261                }
262                other => debug!(node, "firmware update: {}", other.name()),
263            }
264        };
265        let mut result = result;
266        if result.status == 0xfd {
267            send(
268                fw::ActivationSet {
269                    manufacturer_id: md.manufacturer_id,
270                    firmware_id,
271                    checksum,
272                    target,
273                    hardware_version: None,
274                }
275                .into(),
276            )
277            .await?;
278            loop {
279                if let fw::Command::ActivationReport(a) =
280                    next_fw(node, &mut rx, STATUS_TIMEOUT).await?
281                {
282                    result.activated = Some(a.status == 0xff);
283                    break;
284                }
285            }
286        }
287        info!(node, status = result.status, "firmware update finished");
288        self.emit(Event::FirmwareUpdateFinished {
289            node,
290            status: result.status,
291            success: result.success(),
292        });
293        Ok(result)
294    }
295}
296
297#[cfg(test)]
298mod tests {
299    use super::*;
300
301    #[test]
302    fn fragments_roundtrip_and_crc() {
303        let f = fragment(3, true, &[1, 2, 3]);
304        assert_eq!(parse_fragment(&f), Some((3, true, &[1u8, 2, 3][..])));
305        let mut bad = f.clone();
306        bad[5] ^= 1;
307        assert_eq!(parse_fragment(&bad), None);
308    }
309
310    #[test]
311    fn intel_hex_images() {
312        // Two records with a gap, then end of file.
313        let hex = ":0400000001020304F2\n:02000600AABB93\n:00000001FF\n";
314        assert_eq!(
315            read_image("fw.hex", hex.as_bytes()).unwrap(),
316            vec![1, 2, 3, 4, 0xff, 0xff, 0xaa, 0xbb]
317        );
318        assert!(
319            read_image("fw.hex", b":0400000001020304F3\n").is_err(),
320            "bad checksum"
321        );
322        assert_eq!(read_image("fw.gbl", &[9, 9]).unwrap(), vec![9, 9]);
323    }
324}