Skip to main content

zigbee_deconz/
message.rs

1//! Typed requests and responses, both directions, so the client, the
2//! simulator and the fuzz targets share one definition of each layout.
3
4use zigbee_primitives::wire::{Reader, Truncated, Writer};
5use zigbee_primitives::{Ieee, NodeId};
6
7use crate::frame::Frame;
8use crate::ids::command as cmd;
9
10/// A frame did not decode.
11#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
12pub enum DecodeError {
13    /// Too short.
14    #[error(transparent)]
15    Truncated(#[from] Truncated),
16    /// A command this crate does not know.
17    #[error("unknown deCONZ command {0:#04x}")]
18    Unknown(u8),
19    /// An address mode this crate does not know.
20    #[error("unknown deCONZ address mode {0:#04x}")]
21    AddressMode(u8),
22}
23
24/// An APS address.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum Address {
27    /// A group (mode 1).
28    Group(u16),
29    /// A network address (mode 2).
30    Nwk(NodeId),
31    /// An IEEE address (mode 3).
32    Ieee(Ieee),
33    /// Both (mode 4).
34    NwkIeee(NodeId, Ieee),
35}
36
37impl Address {
38    fn read(r: &mut Reader<'_>) -> Result<Address, DecodeError> {
39        Ok(match r.u8()? {
40            1 => Address::Group(r.u16()?),
41            2 => Address::Nwk(r.u16()?),
42            3 => Address::Ieee(r.ieee()?),
43            4 => Address::NwkIeee(r.u16()?, r.ieee()?),
44            m => return Err(DecodeError::AddressMode(m)),
45        })
46    }
47
48    fn write(&self, w: &mut Vec<u8>) {
49        match self {
50            Address::Group(g) => {
51                w.put_u8(1);
52                w.put_u16(*g);
53            }
54            Address::Nwk(n) => {
55                w.put_u8(2);
56                w.put_u16(*n);
57            }
58            Address::Ieee(i) => {
59                w.put_u8(3);
60                w.put_ieee(*i);
61            }
62            Address::NwkIeee(n, i) => {
63                w.put_u8(4);
64                w.put_u16(*n);
65                w.put_ieee(*i);
66            }
67        }
68    }
69
70    /// The network address, when the address has one.
71    pub fn nwk(&self) -> Option<NodeId> {
72        match self {
73            Address::Nwk(n) | Address::NwkIeee(n, _) => Some(*n),
74            _ => None,
75        }
76    }
77
78    /// The IEEE address, when the address has one.
79    pub fn ieee(&self) -> Option<Ieee> {
80        match self {
81            Address::Ieee(i) | Address::NwkIeee(_, i) => Some(*i),
82            _ => None,
83        }
84    }
85
86    fn is_group(&self) -> bool {
87        matches!(self, Address::Group(_))
88    }
89}
90
91/// An APS data request.
92#[derive(Debug, Clone, PartialEq, Eq)]
93pub struct ApsRequest {
94    /// Request id, named again in the confirm.
95    pub request_id: u8,
96    /// Destination.
97    pub destination: Address,
98    /// Destination endpoint (absent for a group).
99    pub destination_endpoint: Option<u8>,
100    /// Profile.
101    pub profile: u16,
102    /// Cluster.
103    pub cluster: u16,
104    /// Source endpoint.
105    pub source_endpoint: u8,
106    /// Payload.
107    pub asdu: Vec<u8>,
108    /// Transmit options ([`crate::ids::tx_option`]).
109    pub tx_options: u8,
110    /// Radius.
111    pub radius: u8,
112}
113
114/// An APS data confirm.
115#[derive(Debug, Clone, PartialEq, Eq)]
116pub struct ApsConfirm {
117    /// Device state.
118    pub device_state: u8,
119    /// The request's id.
120    pub request_id: u8,
121    /// Destination.
122    pub destination: Address,
123    /// Destination endpoint (absent for a group).
124    pub destination_endpoint: Option<u8>,
125    /// Source endpoint.
126    pub source_endpoint: u8,
127    /// Delivery status: 0 delivered.
128    pub status: u8,
129}
130
131/// An APS data indication: a received frame.
132#[derive(Debug, Clone, PartialEq, Eq)]
133pub struct ApsIndication {
134    /// Device state.
135    pub device_state: u8,
136    /// Destination.
137    pub destination: Address,
138    /// Destination endpoint.
139    pub destination_endpoint: u8,
140    /// Source.
141    pub source: Address,
142    /// Source endpoint.
143    pub source_endpoint: u8,
144    /// Profile.
145    pub profile: u16,
146    /// Cluster.
147    pub cluster: u16,
148    /// Payload.
149    pub asdu: Vec<u8>,
150    /// Link quality, when reported.
151    pub lqi: Option<u8>,
152    /// Signal strength, dBm, when reported.
153    pub rssi: Option<i8>,
154}
155
156/// A request from the host.
157#[derive(Debug, Clone, PartialEq, Eq)]
158pub enum Request {
159    /// `VERSION`.
160    Version,
161    /// `READ_PARAMETER`, with a qualifier for keyed parameters (the key
162    /// index, or the IEEE address of a link key).
163    ReadParameter {
164        /// Parameter.
165        param: u8,
166        /// Qualifier.
167        extra: Vec<u8>,
168    },
169    /// `WRITE_PARAMETER`.
170    WriteParameter {
171        /// Parameter.
172        param: u8,
173        /// Value.
174        value: Vec<u8>,
175    },
176    /// `DEVICE_STATE`.
177    DeviceState,
178    /// `CHANGE_NETWORK_STATE`.
179    ChangeNetworkState {
180        /// [`crate::ids::net_state`].
181        state: u8,
182    },
183    /// `APS_DATA_REQUEST`.
184    ApsDataRequest(Box<ApsRequest>),
185    /// `APS_DATA_CONFIRM`: read the next confirm.
186    ApsDataConfirm,
187    /// `APS_DATA_INDICATION`: read the next received frame.
188    ApsDataIndication,
189}
190
191impl Request {
192    /// The command id.
193    pub fn command(&self) -> u8 {
194        match self {
195            Request::Version => cmd::VERSION,
196            Request::ReadParameter { .. } => cmd::READ_PARAMETER,
197            Request::WriteParameter { .. } => cmd::WRITE_PARAMETER,
198            Request::DeviceState => cmd::DEVICE_STATE,
199            Request::ChangeNetworkState { .. } => cmd::CHANGE_NETWORK_STATE,
200            Request::ApsDataRequest(_) => cmd::APS_DATA_REQUEST,
201            Request::ApsDataConfirm => cmd::APS_DATA_CONFIRM,
202            Request::ApsDataIndication => cmd::APS_DATA_INDICATION,
203        }
204    }
205
206    /// The frame, with sequence number `seq`.
207    pub fn encode(&self, seq: u8) -> Frame {
208        let mut w = Vec::new();
209        match self {
210            Request::Version => w.put_u32(0),
211            Request::ReadParameter { param, extra } => {
212                w.put_u16((1 + extra.len()) as u16);
213                w.put_u8(*param);
214                w.put_bytes(extra);
215            }
216            Request::WriteParameter { param, value } => {
217                w.put_u16((1 + value.len()) as u16);
218                w.put_u8(*param);
219                w.put_bytes(value);
220            }
221            Request::DeviceState => w.put_bytes(&[0, 0, 0]),
222            Request::ChangeNetworkState { state } => w.put_u8(*state),
223            Request::ApsDataRequest(a) => {
224                let mut body = Vec::new();
225                body.put_u8(a.request_id);
226                body.put_u8(0); // flags
227                a.destination.write(&mut body);
228                if let (false, Some(ep)) = (a.destination.is_group(), a.destination_endpoint) {
229                    body.put_u8(ep);
230                }
231                body.put_u16(a.profile);
232                body.put_u16(a.cluster);
233                body.put_u8(a.source_endpoint);
234                body.put_u16(a.asdu.len() as u16);
235                body.put_bytes(&a.asdu);
236                body.put_u8(a.tx_options);
237                body.put_u8(a.radius);
238                w.put_u16(body.len() as u16);
239                w.put_bytes(&body);
240            }
241            Request::ApsDataConfirm => w.put_u16(0),
242            Request::ApsDataIndication => {
243                // Flags 1: report link quality and signal strength.
244                w.put_u16(1);
245                w.put_u8(1);
246            }
247        }
248        Frame::new(self.command(), seq, 0, w)
249    }
250
251    /// Decode a request (the simulator's side).
252    pub fn decode(frame: &Frame) -> Result<Request, DecodeError> {
253        let mut r = Reader::new(&frame.payload);
254        Ok(match frame.command {
255            cmd::VERSION => Request::Version,
256            cmd::READ_PARAMETER => {
257                let len = usize::from(r.u16()?);
258                let body = r.bytes(len)?;
259                let mut b = Reader::new(body);
260                Request::ReadParameter {
261                    param: b.u8()?,
262                    extra: b.rest().to_vec(),
263                }
264            }
265            cmd::WRITE_PARAMETER => {
266                let len = usize::from(r.u16()?);
267                let body = r.bytes(len)?;
268                let mut b = Reader::new(body);
269                Request::WriteParameter {
270                    param: b.u8()?,
271                    value: b.rest().to_vec(),
272                }
273            }
274            cmd::DEVICE_STATE => Request::DeviceState,
275            cmd::CHANGE_NETWORK_STATE => Request::ChangeNetworkState { state: r.u8()? },
276            cmd::APS_DATA_REQUEST => {
277                let len = usize::from(r.u16()?);
278                let mut b = Reader::new(r.bytes(len)?);
279                let request_id = b.u8()?;
280                let _flags = b.u8()?;
281                let destination = Address::read(&mut b)?;
282                let destination_endpoint = if destination.is_group() {
283                    None
284                } else {
285                    Some(b.u8()?)
286                };
287                let profile = b.u16()?;
288                let cluster = b.u16()?;
289                let source_endpoint = b.u8()?;
290                let n = usize::from(b.u16()?);
291                let asdu = b.bytes(n)?.to_vec();
292                Request::ApsDataRequest(Box::new(ApsRequest {
293                    request_id,
294                    destination,
295                    destination_endpoint,
296                    profile,
297                    cluster,
298                    source_endpoint,
299                    asdu,
300                    tx_options: b.u8()?,
301                    radius: b.u8()?,
302                }))
303            }
304            cmd::APS_DATA_CONFIRM => Request::ApsDataConfirm,
305            cmd::APS_DATA_INDICATION => Request::ApsDataIndication,
306            other => return Err(DecodeError::Unknown(other)),
307        })
308    }
309}
310
311/// A frame from the NCP: a response or an unsolicited notice.
312#[derive(Debug, Clone, PartialEq, Eq)]
313pub enum Response {
314    /// `VERSION`: `0xMMmmPP00` (major, minor, platform).
315    Version {
316        /// The packed firmware version.
317        version: u32,
318    },
319    /// `READ_PARAMETER`.
320    ReadParameter {
321        /// Parameter.
322        param: u8,
323        /// Value.
324        value: Vec<u8>,
325    },
326    /// `WRITE_PARAMETER`.
327    WriteParameter {
328        /// Parameter.
329        param: u8,
330    },
331    /// `DEVICE_STATE`.
332    DeviceState {
333        /// Device state.
334        device_state: u8,
335    },
336    /// `CHANGE_NETWORK_STATE`.
337    ChangeNetworkState {
338        /// The requested state.
339        state: u8,
340    },
341    /// `APS_DATA_REQUEST`.
342    ApsDataRequest {
343        /// Device state.
344        device_state: u8,
345        /// The request's id.
346        request_id: u8,
347    },
348    /// `APS_DATA_CONFIRM`.
349    ApsDataConfirm(Box<ApsConfirm>),
350    /// `APS_DATA_INDICATION`.
351    ApsDataIndication(Box<ApsIndication>),
352    /// `DEVICE_STATE_CHANGED` (unsolicited).
353    DeviceStateChanged {
354        /// Device state.
355        device_state: u8,
356    },
357    /// `MAC_POLL` (unsolicited): a child polled.
358    MacPoll {
359        /// The child.
360        source: Address,
361    },
362}
363
364impl Response {
365    /// The command id.
366    pub fn command(&self) -> u8 {
367        match self {
368            Response::Version { .. } => cmd::VERSION,
369            Response::ReadParameter { .. } => cmd::READ_PARAMETER,
370            Response::WriteParameter { .. } => cmd::WRITE_PARAMETER,
371            Response::DeviceState { .. } => cmd::DEVICE_STATE,
372            Response::ChangeNetworkState { .. } => cmd::CHANGE_NETWORK_STATE,
373            Response::ApsDataRequest { .. } => cmd::APS_DATA_REQUEST,
374            Response::ApsDataConfirm(_) => cmd::APS_DATA_CONFIRM,
375            Response::ApsDataIndication(_) => cmd::APS_DATA_INDICATION,
376            Response::DeviceStateChanged { .. } => cmd::DEVICE_STATE_CHANGED,
377            Response::MacPoll { .. } => cmd::MAC_POLL,
378        }
379    }
380
381    /// The device state the frame carries, if it carries one.
382    pub fn device_state(&self) -> Option<u8> {
383        match self {
384            Response::DeviceState { device_state }
385            | Response::DeviceStateChanged { device_state }
386            | Response::ApsDataRequest { device_state, .. } => Some(*device_state),
387            Response::ApsDataConfirm(c) => Some(c.device_state),
388            Response::ApsDataIndication(i) => Some(i.device_state),
389            _ => None,
390        }
391    }
392
393    /// Decode a frame from the NCP. A frame with a failure status decodes
394    /// to nothing useful; check [`Frame::status`] first.
395    pub fn decode(frame: &Frame) -> Result<Response, DecodeError> {
396        let mut r = Reader::new(&frame.payload);
397        Ok(match frame.command {
398            cmd::VERSION => Response::Version { version: r.u32()? },
399            cmd::READ_PARAMETER => {
400                let len = usize::from(r.u16()?);
401                let mut b = Reader::new(r.bytes(len)?);
402                Response::ReadParameter {
403                    param: b.u8()?,
404                    value: b.rest().to_vec(),
405                }
406            }
407            cmd::WRITE_PARAMETER => {
408                let _len = r.u16()?;
409                Response::WriteParameter { param: r.u8()? }
410            }
411            cmd::DEVICE_STATE => Response::DeviceState {
412                device_state: r.u8()?,
413            },
414            cmd::CHANGE_NETWORK_STATE => Response::ChangeNetworkState { state: r.u8()? },
415            cmd::APS_DATA_REQUEST => {
416                let _len = r.u16()?;
417                Response::ApsDataRequest {
418                    device_state: r.u8()?,
419                    request_id: r.u8()?,
420                }
421            }
422            cmd::APS_DATA_CONFIRM => {
423                let len = usize::from(r.u16()?);
424                let mut b = Reader::new(r.bytes(len)?);
425                let device_state = b.u8()?;
426                let request_id = b.u8()?;
427                let destination = Address::read(&mut b)?;
428                let destination_endpoint = if destination.is_group() {
429                    None
430                } else {
431                    Some(b.u8()?)
432                };
433                Response::ApsDataConfirm(Box::new(ApsConfirm {
434                    device_state,
435                    request_id,
436                    destination,
437                    destination_endpoint,
438                    source_endpoint: b.u8()?,
439                    status: b.u8()?,
440                }))
441            }
442            cmd::APS_DATA_INDICATION => {
443                let len = usize::from(r.u16()?);
444                let mut b = Reader::new(r.bytes(len)?);
445                let device_state = b.u8()?;
446                let destination = Address::read(&mut b)?;
447                let destination_endpoint = b.u8()?;
448                let source = Address::read(&mut b)?;
449                let source_endpoint = b.u8()?;
450                let profile = b.u16()?;
451                let cluster = b.u16()?;
452                let n = usize::from(b.u16()?);
453                let asdu = b.bytes(n)?.to_vec();
454                // Two reserved bytes, link quality, four reserved, RSSI.
455                let tail = b.rest();
456                Response::ApsDataIndication(Box::new(ApsIndication {
457                    device_state,
458                    destination,
459                    destination_endpoint,
460                    source,
461                    source_endpoint,
462                    profile,
463                    cluster,
464                    asdu,
465                    lqi: tail.get(2).copied(),
466                    rssi: tail.get(7).map(|b| *b as i8),
467                }))
468            }
469            cmd::DEVICE_STATE_CHANGED => Response::DeviceStateChanged {
470                device_state: r.u8()?,
471            },
472            cmd::MAC_POLL => {
473                let _len = r.u16()?;
474                Response::MacPoll {
475                    source: Address::read(&mut r)?,
476                }
477            }
478            other => return Err(DecodeError::Unknown(other)),
479        })
480    }
481
482    /// Encode with sequence number `seq` and status `status` (the
483    /// simulator's side).
484    pub fn encode(&self, seq: u8, status: u8) -> Frame {
485        let mut w = Vec::new();
486        let with_len = |w: &mut Vec<u8>, body: Vec<u8>| {
487            w.put_u16(body.len() as u16);
488            w.put_bytes(&body);
489        };
490        match self {
491            Response::Version { version } => w.put_u32(*version),
492            Response::ReadParameter { param, value } => {
493                let mut body = vec![*param];
494                body.put_bytes(value);
495                with_len(&mut w, body);
496            }
497            Response::WriteParameter { param } => with_len(&mut w, vec![*param]),
498            Response::DeviceState { device_state } => w.put_bytes(&[*device_state, 0, 0]),
499            Response::ChangeNetworkState { state } => w.put_u8(*state),
500            Response::ApsDataRequest {
501                device_state,
502                request_id,
503            } => with_len(&mut w, vec![*device_state, *request_id]),
504            Response::ApsDataConfirm(c) => {
505                let mut body = vec![c.device_state, c.request_id];
506                c.destination.write(&mut body);
507                if let (false, Some(ep)) = (c.destination.is_group(), c.destination_endpoint) {
508                    body.put_u8(ep);
509                }
510                body.put_u8(c.source_endpoint);
511                body.put_u8(c.status);
512                body.put_u32(0);
513                with_len(&mut w, body);
514            }
515            Response::ApsDataIndication(i) => {
516                let mut body = vec![i.device_state];
517                i.destination.write(&mut body);
518                body.put_u8(i.destination_endpoint);
519                i.source.write(&mut body);
520                body.put_u8(i.source_endpoint);
521                body.put_u16(i.profile);
522                body.put_u16(i.cluster);
523                body.put_u16(i.asdu.len() as u16);
524                body.put_bytes(&i.asdu);
525                if let Some(lqi) = i.lqi {
526                    body.put_bytes(&[0, 0, lqi]);
527                    if let Some(rssi) = i.rssi {
528                        body.put_bytes(&[0, 0, 0, 0, rssi as u8]);
529                    }
530                }
531                with_len(&mut w, body);
532            }
533            Response::DeviceStateChanged { device_state } => w.put_bytes(&[*device_state, 0]),
534            Response::MacPoll { source } => {
535                let mut body = Vec::new();
536                source.write(&mut body);
537                with_len(&mut w, body);
538            }
539        }
540        Frame::new(self.command(), seq, status, w)
541    }
542}
543
544#[cfg(test)]
545mod tests {
546    use super::*;
547
548    #[test]
549    fn requests_and_responses_round_trip() {
550        let aps = ApsRequest {
551            request_id: 7,
552            destination: Address::Nwk(0x1234),
553            destination_endpoint: Some(1),
554            profile: 0x0104,
555            cluster: 6,
556            source_endpoint: 1,
557            asdu: vec![1, 2, 3],
558            tx_options: 4,
559            radius: 0,
560        };
561        for r in [
562            Request::ReadParameter {
563                param: 0x18,
564                extra: vec![0],
565            },
566            Request::ApsDataRequest(Box::new(aps)),
567            Request::ApsDataRequest(Box::new(ApsRequest {
568                destination: Address::Group(5),
569                destination_endpoint: None,
570                request_id: 1,
571                profile: 0x0104,
572                cluster: 6,
573                source_endpoint: 1,
574                asdu: vec![],
575                tx_options: 0,
576                radius: 30,
577            })),
578        ] {
579            assert_eq!(Request::decode(&r.encode(3)), Ok(r));
580        }
581        let ind = Response::ApsDataIndication(Box::new(ApsIndication {
582            device_state: 0x22,
583            destination: Address::Nwk(0),
584            destination_endpoint: 1,
585            source: Address::NwkIeee(0x1234, Ieee(9)),
586            source_endpoint: 1,
587            profile: 0x0104,
588            cluster: 0x0402,
589            asdu: vec![0x18, 1, 0x0A],
590            lqi: Some(200),
591            rssi: Some(-60),
592        }));
593        assert_eq!(Response::decode(&ind.encode(1, 0)), Ok(ind));
594    }
595}