Skip to main content

zwave_cc/
transport_service.rs

1//! Transport Service: frames longer than one radio frame, split into
2//! segments of a datagram with a CRC-16 each.
3//!
4//! The command byte carries data: the top five bits are the command, the
5//! low three are the top of the datagram size (or, in Segment Request, the
6//! offset). Hence this module is written by hand.
7
8use crate::crc16;
9use std::collections::HashMap;
10use std::time::{Duration, Instant};
11
12/// The Transport Service command class id.
13pub const CC: u8 = 0x55;
14/// First Segment.
15pub const FIRST_SEGMENT: u8 = 0xc0;
16/// Segment Complete.
17pub const SEGMENT_COMPLETE: u8 = 0xe8;
18/// Segment Request.
19pub const SEGMENT_REQUEST: u8 = 0xc8;
20/// Segment Wait.
21pub const SEGMENT_WAIT: u8 = 0xf0;
22/// Subsequent Segment.
23pub const SUBSEQUENT_SEGMENT: u8 = 0xe0;
24
25/// Largest datagram the 11-bit size field can describe.
26pub const MAX_DATAGRAM: usize = 0x7ff;
27/// Segment payload bytes per frame that fit any Z-Wave data rate with room for security.
28pub const DEFAULT_SEGMENT: usize = 39;
29/// How long a reassembly waits for the next segment.
30pub const SEGMENT_TIMEOUT: Duration = Duration::from_secs(1);
31/// Reassemblies kept at once (per stack); older ones are dropped.
32pub const MAX_SESSIONS: usize = 16;
33
34/// A parsed Transport Service frame.
35#[derive(Debug, Clone, PartialEq, Eq)]
36pub enum Segment {
37    /// The first segment of a datagram.
38    First {
39        /// Total datagram size.
40        size: u16,
41        /// Session id (0 to 15).
42        session: u8,
43        /// Payload bytes.
44        data: Vec<u8>,
45    },
46    /// A later segment.
47    Subsequent {
48        /// Total datagram size.
49        size: u16,
50        /// Session id.
51        session: u8,
52        /// Where this payload goes in the datagram.
53        offset: u16,
54        /// Payload bytes.
55        data: Vec<u8>,
56    },
57    /// The receiver asks for the segment at `offset` again.
58    Request {
59        /// Session id.
60        session: u8,
61        /// Missing offset.
62        offset: u16,
63    },
64    /// The receiver has the whole datagram.
65    Complete {
66        /// Session id.
67        session: u8,
68    },
69    /// The receiver is busy; wait.
70    Wait {
71        /// Segments still pending at the receiver.
72        pending: u8,
73    },
74}
75
76/// Why a frame was rejected.
77#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
78pub enum Error {
79    /// Too short or a wrong command.
80    #[error("malformed transport service frame")]
81    Malformed,
82    /// The segment's CRC did not match.
83    #[error("transport service CRC mismatch")]
84    Crc,
85    /// A segment points outside its datagram.
86    #[error("segment outside the datagram")]
87    OutOfBounds,
88}
89
90/// Parses a Transport Service frame (starting at `0x55`).
91pub fn parse(frame: &[u8]) -> Result<Segment, Error> {
92    if frame.len() < 2 || frame[0] != CC {
93        return Err(Error::Malformed);
94    }
95    let cmd = frame[1] & 0xf8;
96    let hi = u16::from(frame[1] & 0x07);
97    match cmd {
98        FIRST_SEGMENT | SUBSEQUENT_SEGMENT => {
99            let header = if cmd == FIRST_SEGMENT { 4 } else { 5 };
100            if frame.len() < header + 2 {
101                return Err(Error::Malformed);
102            }
103            let (body, crc) = frame.split_at(frame.len() - 2);
104            if crc16::checksum(body) != u16::from_be_bytes([crc[0], crc[1]]) {
105                return Err(Error::Crc);
106            }
107            let size = (hi << 8) | u16::from(frame[2]);
108            let session = frame[3] >> 4;
109            let ext = frame[3] & 0x08 != 0;
110            let mut at = header;
111            if ext {
112                // Header extension: a length byte and that many bytes, skipped.
113                let n = usize::from(*body.get(at).ok_or(Error::Malformed)?);
114                at += 1 + n;
115                if at > body.len() {
116                    return Err(Error::Malformed);
117                }
118            }
119            let data = body[at..].to_vec();
120            if cmd == FIRST_SEGMENT {
121                Ok(Segment::First {
122                    size,
123                    session,
124                    data,
125                })
126            } else {
127                let offset = (u16::from(frame[3] & 0x07) << 8) | u16::from(frame[4]);
128                Ok(Segment::Subsequent {
129                    size,
130                    session,
131                    offset,
132                    data,
133                })
134            }
135        }
136        SEGMENT_REQUEST => {
137            if frame.len() < 4 {
138                return Err(Error::Malformed);
139            }
140            Ok(Segment::Request {
141                session: frame[2] >> 4,
142                offset: (u16::from(frame[2] & 0x07) << 8) | u16::from(frame[3]),
143            })
144        }
145        SEGMENT_COMPLETE => Ok(Segment::Complete {
146            session: *frame.get(2).ok_or(Error::Malformed)? >> 4,
147        }),
148        SEGMENT_WAIT => Ok(Segment::Wait {
149            pending: *frame.get(2).ok_or(Error::Malformed)?,
150        }),
151        _ => Err(Error::Malformed),
152    }
153}
154
155fn with_crc(mut v: Vec<u8>) -> Vec<u8> {
156    let c = crc16::checksum(&v);
157    v.extend_from_slice(&c.to_be_bytes());
158    v
159}
160
161/// Splits `datagram` into Transport Service frames of at most `segment` payload bytes.
162pub fn segment(datagram: &[u8], session: u8, segment: usize) -> Vec<Vec<u8>> {
163    assert!(datagram.len() <= MAX_DATAGRAM, "datagram too long");
164    let segment = segment.max(1);
165    let size = datagram.len() as u16;
166    let mut out = Vec::new();
167    for (i, chunk) in datagram.chunks(segment).enumerate() {
168        let offset = (i * segment) as u16;
169        let mut v = vec![CC];
170        if i == 0 {
171            v.push(FIRST_SEGMENT | ((size >> 8) as u8 & 0x07));
172            v.push(size as u8);
173            v.push((session & 0x0f) << 4);
174        } else {
175            v.push(SUBSEQUENT_SEGMENT | ((size >> 8) as u8 & 0x07));
176            v.push(size as u8);
177            v.push(((session & 0x0f) << 4) | ((offset >> 8) as u8 & 0x07));
178            v.push(offset as u8);
179        }
180        v.extend_from_slice(chunk);
181        out.push(with_crc(v));
182    }
183    out
184}
185
186/// Builds a Segment Complete.
187pub fn complete(session: u8) -> Vec<u8> {
188    vec![CC, SEGMENT_COMPLETE, (session & 0x0f) << 4]
189}
190
191/// Builds a Segment Request for the segment at `offset`.
192pub fn request(session: u8, offset: u16) -> Vec<u8> {
193    vec![
194        CC,
195        SEGMENT_REQUEST,
196        ((session & 0x0f) << 4) | ((offset >> 8) as u8 & 0x07),
197        offset as u8,
198    ]
199}
200
201struct Partial {
202    size: usize,
203    data: Vec<u8>,
204    have: Vec<bool>,
205    last: Instant,
206}
207
208/// What the reassembler did with a segment.
209#[derive(Debug, Clone, PartialEq, Eq)]
210pub enum Reassembly {
211    /// More segments are needed.
212    Pending,
213    /// The datagram is whole; answer the sender with [`complete`].
214    Done(Vec<u8>),
215}
216
217/// Reassembles datagrams from any number of peers.
218#[derive(Default)]
219pub struct Reassembler {
220    sessions: HashMap<(u16, u8), Partial>,
221}
222
223impl std::fmt::Debug for Reassembler {
224    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
225        write!(f, "Reassembler({} sessions)", self.sessions.len())
226    }
227}
228
229impl Reassembler {
230    /// Feeds a First or Subsequent segment from `peer`.
231    pub fn push(&mut self, peer: u16, seg: Segment) -> Result<Reassembly, Error> {
232        let now = Instant::now();
233        self.sessions
234            .retain(|_, p| now.duration_since(p.last) < SEGMENT_TIMEOUT * 4);
235        let (size, session, offset, data) = match seg {
236            Segment::First {
237                size,
238                session,
239                data,
240            } => {
241                if self.sessions.len() >= MAX_SESSIONS {
242                    if let Some(k) = self
243                        .sessions
244                        .iter()
245                        .min_by_key(|(_, p)| p.last)
246                        .map(|(k, _)| *k)
247                    {
248                        self.sessions.remove(&k);
249                    }
250                }
251                let size = usize::from(size);
252                self.sessions.insert(
253                    (peer, session),
254                    Partial {
255                        size,
256                        data: vec![0; size],
257                        have: vec![false; size],
258                        last: now,
259                    },
260                );
261                (size, session, 0usize, data)
262            }
263            Segment::Subsequent {
264                size,
265                session,
266                offset,
267                data,
268            } => (usize::from(size), session, usize::from(offset), data),
269            _ => return Err(Error::Malformed),
270        };
271        let p = self
272            .sessions
273            .get_mut(&(peer, session))
274            .ok_or(Error::OutOfBounds)?;
275        if p.size != size || offset + data.len() > p.size {
276            self.sessions.remove(&(peer, session));
277            return Err(Error::OutOfBounds);
278        }
279        p.data[offset..offset + data.len()].copy_from_slice(&data);
280        p.have[offset..offset + data.len()]
281            .iter_mut()
282            .for_each(|h| *h = true);
283        p.last = now;
284        if p.have.iter().all(|&h| h) {
285            let p = self.sessions.remove(&(peer, session)).expect("present");
286            return Ok(Reassembly::Done(p.data));
287        }
288        Ok(Reassembly::Pending)
289    }
290
291    /// The first missing offset of a session that has gone quiet, to ask for again.
292    pub fn missing(&self, peer: u16, session: u8) -> Option<u16> {
293        let p = self.sessions.get(&(peer, session))?;
294        p.have.iter().position(|h| !h).map(|i| i as u16)
295    }
296}
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    #[test]
303    fn segment_and_reassemble() {
304        let datagram: Vec<u8> = (0..100u8).collect();
305        let frames = segment(&datagram, 3, 39);
306        assert_eq!(frames.len(), 3);
307        let mut r = Reassembler::default();
308        // Out of order: last first, after the first segment.
309        assert_eq!(
310            r.push(7, parse(&frames[0]).unwrap()).unwrap(),
311            Reassembly::Pending
312        );
313        assert_eq!(
314            r.push(7, parse(&frames[2]).unwrap()).unwrap(),
315            Reassembly::Pending
316        );
317        assert_eq!(r.missing(7, 3), Some(39));
318        assert_eq!(
319            r.push(7, parse(&frames[1]).unwrap()).unwrap(),
320            Reassembly::Done(datagram)
321        );
322    }
323
324    #[test]
325    fn crc_and_bounds() {
326        let mut f = segment(&[1, 2, 3], 1, 39).remove(0);
327        f[5] ^= 1;
328        assert_eq!(parse(&f), Err(Error::Crc));
329        let mut r = Reassembler::default();
330        let bogus = Segment::Subsequent {
331            size: 4,
332            session: 1,
333            offset: 3,
334            data: vec![1, 2],
335        };
336        assert!(r.push(1, bogus).is_err());
337        r.push(
338            1,
339            Segment::First {
340                size: 4,
341                session: 1,
342                data: vec![1],
343            },
344        )
345        .unwrap();
346        assert_eq!(
347            r.push(
348                1,
349                Segment::Subsequent {
350                    size: 4,
351                    session: 1,
352                    offset: 3,
353                    data: vec![1, 2]
354                }
355            ),
356            Err(Error::OutOfBounds)
357        );
358        assert_eq!(
359            parse(&request(2, 300)).unwrap(),
360            Segment::Request {
361                session: 2,
362                offset: 300
363            }
364        );
365        assert_eq!(
366            parse(&complete(5)).unwrap(),
367            Segment::Complete { session: 5 }
368        );
369    }
370}