zigbee-ezsp 0.3.0

Silicon Labs EZSP (EmberZNet Serial Protocol) frames and an async client, EmberZNet 7.4 to 8.x
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
//! An async EZSP client over an ASH link.

use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;

use tokio::io::{AsyncRead, AsyncWrite};
use tokio::sync::{mpsc, oneshot};
use zigbee_ash::{Config as AshConfig, Event as AshEvent, Link, LinkError, LinkEvent, Role};
use zigbee_primitives::wire::Reader;

use crate::callback::Callback;
use crate::command::{Command, DecodeError, Response};
use crate::frame::{self, Format, HeaderError};
use crate::ids;
use crate::types::{
    ProtocolVersion, StackVersion, Status, MAX_PROTOCOL_VERSION, MIN_PROTOCOL_VERSION,
};

/// What the NCP said about itself during start-up.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NcpInfo {
    /// Negotiated protocol version.
    pub protocol: ProtocolVersion,
    /// Stack type (2 for a Zigbee mesh stack).
    pub stack_type: u8,
    /// The `version` command's packed stack version (one nibble per part).
    pub stack_version_packed: u16,
    /// The full EmberZNet version from `VERSION_INFO`.
    pub stack_version: StackVersion,
    /// Why the NCP last reset (the RSTACK code).
    pub reset_code: u8,
}

/// Unpack the `version` command's stack version: `0x7440` is 7.4.4.0.
pub fn unpack_stack_version(packed: u16) -> (u8, u8, u8, u8) {
    (
        (packed >> 12) as u8,
        ((packed >> 8) & 0xF) as u8,
        ((packed >> 4) & 0xF) as u8,
        (packed & 0xF) as u8,
    )
}

/// Client errors.
#[derive(Debug, Clone, thiserror::Error)]
pub enum EzspError {
    /// The ASH link failed.
    #[error("ASH link: {0}")]
    Link(#[from] LinkError),
    /// The link went down (NCP reset, timeouts, port closed).
    #[error("NCP link down: {0}")]
    Down(String),
    /// No RSTACK: nothing that speaks ASH is on the port.
    #[error("no ASH reply (is this an EZSP adapter at the right baud rate?)")]
    NoReply,
    /// No response to a command in time.
    #[error("no response to frame {0:#06x}")]
    Timeout(u16),
    /// A frame header did not parse.
    #[error("bad EZSP header: {0}")]
    Header(#[from] HeaderError),
    /// A response did not parse.
    #[error("bad EZSP response: {0}")]
    Decode(#[from] DecodeError),
    /// The NCP rejected the command as invalid.
    #[error("NCP rejected frame {frame_id:#06x} as invalid (reason {reason:#04x})")]
    InvalidCommand {
        /// The command.
        frame_id: u16,
        /// `EzspStatus` reason.
        reason: u8,
    },
    /// The command ran and returned a failure status.
    #[error("frame {frame_id:#06x} failed: {status}")]
    Status {
        /// The command.
        frame_id: u16,
        /// The status.
        status: Status,
    },
    /// The NCP answered with a response that does not fit the command.
    #[error("unexpected response {0:?}")]
    Unexpected(Box<Response>),
    /// The NCP's protocol version is outside what this crate speaks.
    #[error(
        "EZSP protocol {protocol} (EmberZNet {}.{}.{}) is not supported: need {MIN_PROTOCOL_VERSION} to {MAX_PROTOCOL_VERSION} (EmberZNet 7.4 or newer)",
        unpack_stack_version(*stack_version).0, unpack_stack_version(*stack_version).1, unpack_stack_version(*stack_version).2
    )]
    Unsupported {
        /// The NCP's protocol version.
        protocol: u8,
        /// Its packed stack version.
        stack_version: u16,
    },
    /// The NCP is not a Zigbee stack.
    #[error("stack type {0} is not a Zigbee mesh stack")]
    StackType(u8),
}

/// Something the NCP sent that is not a response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EzspEvent {
    /// A callback.
    Callback(Callback),
    /// The link is down; every later call fails. Start a new client.
    Down(String),
}

/// Client settings.
#[derive(Debug, Clone)]
pub struct ClientConfig {
    /// The ASH link's settings.
    pub ash: AshConfig,
    /// How long to wait for each response.
    pub response_timeout: Duration,
}

impl Default for ClientConfig {
    fn default() -> Self {
        ClientConfig {
            ash: AshConfig::default(),
            response_timeout: Duration::from_secs(12),
        }
    }
}

struct Pending {
    seq: u8,
    frame_id: u16,
    reply: oneshot::Sender<Result<Response, EzspError>>,
}

struct Inner {
    link: Link,
    version: AtomicU8,
    extended: AtomicBool,
    down: Mutex<Option<String>>,
    seq: tokio::sync::Mutex<u8>,
    pending: Mutex<Option<Pending>>,
    timeout: Duration,
}

/// An EZSP client. Clones share one connection; commands are sent one at a
/// time, as EZSP requires.
#[derive(Clone)]
pub struct Ezsp {
    inner: Arc<Inner>,
}

impl std::fmt::Debug for Ezsp {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Ezsp")
            .field("version", &self.version())
            .finish_non_exhaustive()
    }
}

/// Reset the link (RST) and wait for RSTACK. Returns the reset code.
async fn connect_link(
    link: &Link,
    events: &mut mpsc::Receiver<LinkEvent>,
    config: &AshConfig,
) -> Result<u8, EzspError> {
    link.reset().await?;
    let wait = config.rst_timeout * config.rst_attempts + Duration::from_millis(500);
    let deadline = tokio::time::Instant::now() + wait;
    loop {
        match tokio::time::timeout_at(deadline, events.recv()).await {
            Err(_) => return Err(EzspError::NoReply),
            Ok(None) => return Err(EzspError::Down("link task stopped".into())),
            Ok(Some(LinkEvent::Ash(AshEvent::Connected { reset_code }))) => return Ok(reset_code),
            Ok(Some(LinkEvent::Ash(AshEvent::Down(zigbee_ash::DownReason::ResetTimeout)))) => {
                return Err(EzspError::NoReply)
            }
            Ok(Some(LinkEvent::Ash(AshEvent::Down(reason)))) => {
                return Err(EzspError::Down(format!("{reason:?}")))
            }
            Ok(Some(LinkEvent::Closed(why))) => return Err(EzspError::Down(why)),
            Ok(Some(LinkEvent::Ash(AshEvent::Data(_)))) => {}
        }
    }
}

/// Reset the NCP's ASH layer and report the RSTACK code: the one frame
/// [`Ezsp::start`] begins with, and the cheapest proof that an EZSP NCP is on
/// the port. Returns [`EzspError::NoReply`] when nothing answers.
pub async fn ash_reset<T>(io: T, config: &AshConfig) -> Result<u8, EzspError>
where
    T: AsyncRead + AsyncWrite + Send + 'static,
{
    let (link, mut events) = Link::spawn(io, Role::Host, config.clone());
    connect_link(&link, &mut events, config).await
}

impl Ezsp {
    /// Connect over `io`: reset the link, negotiate the protocol version
    /// and read the stack version. Callbacks arrive on the receiver; it is
    /// unbounded so a slow consumer never stalls command responses.
    pub async fn start<T>(
        io: T,
        config: ClientConfig,
    ) -> Result<(Ezsp, NcpInfo, mpsc::UnboundedReceiver<EzspEvent>), EzspError>
    where
        T: AsyncRead + AsyncWrite + Send + 'static,
    {
        let (link, mut link_events) = Link::spawn(io, Role::Host, config.ash.clone());
        let reset_code = connect_link(&link, &mut link_events, &config.ash).await?;
        let inner = Arc::new(Inner {
            link,
            version: AtomicU8::new(MAX_PROTOCOL_VERSION),
            extended: AtomicBool::new(false),
            down: Mutex::new(None),
            seq: tokio::sync::Mutex::new(0),
            pending: Mutex::new(None),
            timeout: config.response_timeout,
        });
        let (event_tx, event_rx) = mpsc::unbounded_channel();
        // The reader holds the client weakly: dropping the last `Ezsp` drops
        // the link, which ends the link task and closes the port.
        tokio::spawn(reader(Arc::downgrade(&inner), link_events, event_tx));
        let ezsp = Ezsp { inner };

        // First `version` in the legacy format, asking for the newest we speak.
        let (protocol, stack_type, packed) = ezsp.version_command(MAX_PROTOCOL_VERSION).await?;
        if stack_type != ids::STACK_TYPE_MESH {
            return Err(EzspError::StackType(stack_type));
        }
        if !ProtocolVersion(protocol).is_supported() {
            return Err(EzspError::Unsupported {
                protocol,
                stack_version: packed,
            });
        }
        ezsp.inner.version.store(protocol, Ordering::SeqCst);
        ezsp.inner.extended.store(true, Ordering::SeqCst);
        // Again in the extended format, now at the NCP's version.
        let (agreed, _, packed) = ezsp.version_command(protocol).await?;
        if agreed != protocol {
            return Err(EzspError::Unsupported {
                protocol: agreed,
                stack_version: packed,
            });
        }
        let stack_version = ezsp
            .get_value(ids::value::VERSION_INFO)
            .await
            .and_then(|bytes| {
                StackVersion::read(&mut Reader::new(&bytes))
                    .map_err(|e| EzspError::Decode(DecodeError::Truncated(e)))
            })?;
        let info = NcpInfo {
            protocol: ProtocolVersion(protocol),
            stack_type,
            stack_version_packed: packed,
            stack_version,
            reset_code,
        };
        Ok((ezsp, info, event_rx))
    }

    async fn version_command(&self, desired: u8) -> Result<(u8, u8, u16), EzspError> {
        match self.call(Command::Version { desired }).await? {
            Response::Version {
                protocol_version,
                stack_type,
                stack_version,
            } => Ok((protocol_version, stack_type, stack_version)),
            other => Err(EzspError::Unexpected(Box::new(other))),
        }
    }

    /// The negotiated protocol version.
    pub fn version(&self) -> ProtocolVersion {
        ProtocolVersion(self.inner.version.load(Ordering::SeqCst))
    }

    /// Send a command and wait for its response.
    pub async fn call(&self, command: Command) -> Result<Response, EzspError> {
        let frame_id = command.frame_id();
        let mut seq = self.inner.seq.lock().await;
        if let Some(why) = self.inner.down.lock().ok().and_then(|d| d.clone()) {
            return Err(EzspError::Down(why));
        }
        let this_seq = *seq;
        *seq = seq.wrapping_add(1);
        let format = if self.inner.extended.load(Ordering::SeqCst) {
            Format::Extended
        } else {
            Format::Legacy
        };
        let bytes = frame::encode(
            format,
            this_seq,
            0x00,
            frame_id,
            &command.encode(self.version()),
        );
        let (tx, rx) = oneshot::channel();
        if let Ok(mut pending) = self.inner.pending.lock() {
            *pending = Some(Pending {
                seq: this_seq,
                frame_id,
                reply: tx,
            });
        }
        tracing::trace!(frame_id, seq = this_seq, "ezsp tx");
        self.inner.link.send(bytes).await?;
        let result = match tokio::time::timeout(self.inner.timeout, rx).await {
            Ok(Ok(result)) => result,
            Ok(Err(_)) => Err(EzspError::Down(self.down_reason())),
            Err(_) => Err(EzspError::Timeout(frame_id)),
        };
        if let Ok(mut pending) = self.inner.pending.lock() {
            *pending = None;
        }
        drop(seq);
        match result? {
            Response::InvalidCommand { reason } => {
                Err(EzspError::InvalidCommand { frame_id, reason })
            }
            response => Ok(response),
        }
    }

    fn down_reason(&self) -> String {
        self.inner
            .down
            .lock()
            .ok()
            .and_then(|d| d.clone())
            .unwrap_or_else(|| "link closed".into())
    }

    /// Send a command whose response is a status and require success.
    pub async fn call_ok(&self, command: Command) -> Result<(), EzspError> {
        let frame_id = command.frame_id();
        let response = self.call(command).await?;
        match response.status() {
            Some(status) if status.is_ok() => Ok(()),
            Some(status) => Err(EzspError::Status { frame_id, status }),
            None => Ok(()),
        }
    }

    /// `getValue`, requiring success.
    pub async fn get_value(&self, value_id: u8) -> Result<Vec<u8>, EzspError> {
        match self.call(Command::GetValue { value_id }).await? {
            Response::GetValue { status, value } if status.is_ok() => Ok(value),
            Response::GetValue { status, .. } => Err(EzspError::Status {
                frame_id: ids::frame::GET_VALUE,
                status,
            }),
            other => Err(EzspError::Unexpected(Box::new(other))),
        }
    }

    /// `setValue`, requiring success.
    pub async fn set_value(&self, value_id: u8, value: Vec<u8>) -> Result<(), EzspError> {
        self.call_ok(Command::SetValue { value_id, value }).await
    }

    /// `setConfigurationValue`, requiring success.
    pub async fn set_config(&self, config_id: u8, value: u16) -> Result<(), EzspError> {
        self.call_ok(Command::SetConfigurationValue { config_id, value })
            .await
    }

    /// `getConfigurationValue`, requiring success.
    pub async fn get_config(&self, config_id: u8) -> Result<u16, EzspError> {
        match self
            .call(Command::GetConfigurationValue { config_id })
            .await?
        {
            Response::GetConfigurationValue { status, value } if status.is_ok() => Ok(value),
            Response::GetConfigurationValue { status, .. } => Err(EzspError::Status {
                frame_id: ids::frame::GET_CONFIGURATION_VALUE,
                status,
            }),
            other => Err(EzspError::Unexpected(Box::new(other))),
        }
    }

    /// `setPolicy`, requiring success.
    pub async fn set_policy(&self, policy_id: u8, decision: u8) -> Result<(), EzspError> {
        self.call_ok(Command::SetPolicy {
            policy_id,
            decision,
        })
        .await
    }
}

async fn reader(
    weak: std::sync::Weak<Inner>,
    mut link_events: mpsc::Receiver<LinkEvent>,
    events: mpsc::UnboundedSender<EzspEvent>,
) {
    let reason = loop {
        let Some(event) = link_events.recv().await else {
            break "link task stopped".to_string();
        };
        let Some(inner) = weak.upgrade() else { return };
        let data = match event {
            LinkEvent::Ash(AshEvent::Data(data)) => data,
            LinkEvent::Ash(AshEvent::Connected { .. }) => continue,
            LinkEvent::Ash(AshEvent::Down(reason)) => break format!("{reason:?}"),
            LinkEvent::Closed(why) => break why,
        };
        let format = if inner.extended.load(Ordering::SeqCst) {
            Format::Extended
        } else {
            Format::Legacy
        };
        let version = ProtocolVersion(inner.version.load(Ordering::SeqCst));
        let header = match frame::parse(&data, format) {
            Ok(h) => h,
            Err(e) => {
                tracing::warn!(error = %e, "dropping malformed EZSP frame");
                continue;
            }
        };
        if !header.is_response() {
            tracing::warn!(
                frame_id = header.frame_id,
                "dropping EZSP command frame from the NCP"
            );
            continue;
        }
        if header.overflow() {
            tracing::warn!("NCP reports it ran out of memory (overflow)");
        }
        if header.is_callback() {
            match Callback::decode(version, header.frame_id, header.params) {
                Ok(cb) => {
                    tracing::trace!(?cb, "ezsp callback");
                    let _ = events.send(EzspEvent::Callback(cb));
                }
                Err(e) => {
                    tracing::warn!(frame_id = header.frame_id, error = %e, "dropping malformed EZSP callback")
                }
            }
            continue;
        }
        let pending = inner.pending.lock().ok().and_then(|mut p| p.take());
        let Some(pending) = pending else {
            tracing::warn!(
                frame_id = header.frame_id,
                seq = header.seq,
                "EZSP response with no command waiting"
            );
            continue;
        };
        if header.seq != pending.seq {
            tracing::warn!(
                want = pending.seq,
                got = header.seq,
                "EZSP response out of sequence"
            );
            if let Ok(mut p) = inner.pending.lock() {
                *p = Some(pending);
            }
            continue;
        }
        let result = if header.truncated() {
            Err(EzspError::Decode(DecodeError::Truncated(
                zigbee_primitives::wire::Truncated {
                    offset: 0,
                    needed: 0,
                },
            )))
        } else if header.frame_id == ids::frame::INVALID_COMMAND
            || header.frame_id == pending.frame_id
        {
            Response::decode(version, header.frame_id, header.params).map_err(EzspError::from)
        } else {
            Err(EzspError::Decode(DecodeError::UnknownFrame(
                header.frame_id,
            )))
        };
        let _ = pending.reply.send(result);
    };
    tracing::warn!(%reason, "EZSP link down");
    let Some(inner) = weak.upgrade() else { return };
    if let Ok(mut down) = inner.down.lock() {
        *down = Some(reason.clone());
    }
    if let Some(p) = inner.pending.lock().ok().and_then(|mut p| p.take()) {
        let _ = p.reply.send(Err(EzspError::Down(reason.clone())));
    }
    let _ = events.send(EzspEvent::Down(reason));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn unpacks_stack_versions() {
        assert_eq!(unpack_stack_version(0x7440), (7, 4, 4, 0));
        assert_eq!(unpack_stack_version(0x6A30), (6, 10, 3, 0));
    }
}