Expand description
rsezsp is a hardware-driven Rust implementation of Silicon Labs EZSP for
Ember NCP devices.
The project intentionally implements EZSP incrementally. Command coverage is based on real hardware and application requirements rather than protocol completeness.
§Layering
Application / Zigbee runtime
│
typed EZSP API ezsp::command, ezsp::callback
│
EZSP codec + correlation ezsp::codec, ezsp::frame, ezsp::correlation
│
ASH transport ash::
│
serial transport::
│
Silicon Labs Ember NCPEach layer is usable on its own and none reaches past its neighbours. This crate owns the host-to-NCP conversation and nothing above it: no ZCL, no ZDO interview logic, no device definitions.
§Usage
use rsezsp::Ncp;
use rsezsp::ezsp::command::GetEui64;
use rsezsp::transport::serial::{SerialSettings, SerialTransport};
// Opening the port performs no I/O with the NCP; connecting does the ASH
// reset handshake and EZSP version negotiation.
let transport = SerialTransport::open("/dev/ttyUSB0", SerialSettings::default())?;
let mut ncp = Ncp::connect(transport).await?;
println!("EZSP {}, firmware {:#06x}", ncp.version(), ncp.stack_version());
let response = ncp.command(GetEui64).await?;
println!("coordinator {}", response.eui64);examples/startup.rs is the full version: bringup, opening the network for
joining, and sending a command to a device that joined.
§Adding a command this crate does not have
Coverage grows from real need rather than from working through the
specification, so at any moment there are commands nobody has needed yet.
That is only a reasonable design if it does not block you, so
Command is an ordinary public trait: you can implement it in your
crate, for a command this one has never heard of, and send it with
Ncp::command today.
use rsezsp::ezsp::codec::{EzspDecode, EzspEncode, Reader, Writer};
use rsezsp::ezsp::{Command, EzspError, FrameId};
use rsezsp::types::status::SlStatus;
/// `setRadioPower` — frame id `0x0099`.
struct SetRadioPower {
dbm: i8,
}
impl EzspEncode for SetRadioPower {
fn encode(&self, out: &mut Writer) -> Result<(), EzspError> {
out.u8(self.dbm as u8);
Ok(())
}
}
struct SetRadioPowerResponse {
status: SlStatus,
}
impl EzspDecode for SetRadioPowerResponse {
fn decode(input: &mut Reader<'_>) -> Result<Self, EzspError> {
// Applies the version boundary for you: a status is one byte below
// EZSP 14 and four at or above it.
Ok(Self { status: SlStatus::decode(input)? })
}
}
impl Command for SetRadioPower {
type Response = SetRadioPowerResponse;
const ID: FrameId = FrameId(0x0099);
}tests/extending_from_outside.rs proves this works from a separate crate
and drives such a command through the whole runtime. If you write one worth
sharing, please send it back – see CONTRIBUTING.md.
§Two properties the design is built around
The protocol version is part of the wire format. Field widths change
between EZSP versions – a status is one byte below version 14 and four at
or above it – so the negotiated version is threaded through every codec
rather than stored once. See ezsp::version.
Parsing is sans-I/O. Bytes in, typed values out, no runtime involved. That is what makes the parsers deterministic to test, cheap to fuzz, and able to replay a captured wire trace as a regression test.
§Protocol references
Silicon Labs’ EZSP documentation is the authority. Behaviour, command ids,
field widths and version boundaries were cross-checked against
zigbee-herdsman’s Ember adapter (MIT, © Koen Kanters and contributors),
which is a mature behavioural reference, and against wire traces captured
from real hardware. Nothing here is a translation of that source; where the
references disagreed, the wire trace decided.
Re-exports§
pub use ncp::Ncp;pub use ash::AshError;pub use ezsp::Command;pub use ezsp::EzspError;pub use ezsp::FrameId;pub use ezsp::ProtocolVersion;pub use types::network::Eui64;pub use types::network::NodeId;pub use types::status::SlStatus;