Skip to main content

zigbee_host/
adapter.rs

1//! The boundary between the host and a network co-processor family.
2//!
3//! The host does formation policy, the trust center's decisions, interviews
4//! and everything above APS; an [`Adapter`] does what only the NCP can: start
5//! or form the network, open it for joining, carry APS frames, and export
6//! or import keys. EZSP is the first implementation
7//! ([`crate::ezsp_adapter`]).
8
9use std::future::Future;
10
11use zigbee_primitives::{ExtPanId, Ieee, Key, NodeId, PanId};
12
13use crate::backup::Backup;
14use crate::error::HostError;
15
16/// The network a coordinator should run.
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub struct NetworkSettings {
19    /// Channel, 11 to 26.
20    pub channel: u8,
21    /// PAN id.
22    pub pan_id: PanId,
23    /// Extended PAN id.
24    pub extended_pan_id: ExtPanId,
25    /// Network key.
26    pub network_key: Key,
27    /// Transmit power, dBm, if not the firmware's default.
28    pub tx_power: Option<i8>,
29}
30
31/// How to start.
32#[derive(Debug, Clone)]
33pub enum StartMode {
34    /// Resume the NCP's network if it is `settings`; form `settings` if the
35    /// NCP has none. A different network on the NCP is an error unless
36    /// `replace_other` (which leaves it, losing its devices).
37    Normal {
38        /// The network to run.
39        settings: NetworkSettings,
40        /// Replace a different network found on the NCP.
41        replace_other: bool,
42    },
43    /// Leave whatever the NCP has and restore a backup onto it.
44    Restore(Box<Backup>),
45}
46
47/// What [`Adapter::start`] did.
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub enum StartOutcome {
50    /// The NCP already ran the network.
51    Resumed,
52    /// A new network was formed.
53    Formed,
54    /// A backup was restored.
55    Restored,
56}
57
58/// The running network.
59#[derive(Debug, Clone, PartialEq, Eq)]
60pub struct NetworkInfo {
61    /// The coordinator's IEEE address.
62    pub ieee: Ieee,
63    /// The coordinator's network address (0).
64    pub nwk: NodeId,
65    /// Channel.
66    pub channel: u8,
67    /// PAN id.
68    pub pan_id: PanId,
69    /// Extended PAN id.
70    pub extended_pan_id: ExtPanId,
71    /// Network update id.
72    pub nwk_update_id: u8,
73}
74
75/// The NCP.
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct AdapterInfo {
78    /// Family, such as `ezsp`.
79    pub kind: &'static str,
80    /// Firmware version.
81    pub firmware: String,
82    /// Serial protocol version.
83    pub protocol: u8,
84    /// The NCP reports each device's link key exchange
85    /// ([`AdapterEvent::KeyExchange`]), so the host can remove devices
86    /// that never do one. Without it the NCP enforces
87    /// [`JoinPolicy::allow_legacy`] itself, or cannot.
88    pub reports_key_exchange: bool,
89}
90
91/// Trust center join policy.
92#[derive(Debug, Clone, PartialEq, Eq)]
93pub struct JoinPolicy {
94    /// Only devices with an install code may join.
95    pub install_code_only: bool,
96    /// Accept devices that never request a unique link key (pre-Zigbee 3.0
97    /// devices keep the well-known key). When false they are removed.
98    pub allow_legacy: bool,
99}
100
101impl Default for JoinPolicy {
102    fn default() -> Self {
103        JoinPolicy {
104            install_code_only: false,
105            allow_legacy: true,
106        }
107    }
108}
109
110/// APS addressing for a frame.
111#[derive(Debug, Clone, Copy, PartialEq, Eq)]
112pub struct Aps {
113    /// Profile.
114    pub profile: u16,
115    /// Cluster.
116    pub cluster: u16,
117    /// Source endpoint.
118    pub source_endpoint: u8,
119    /// Destination endpoint.
120    pub destination_endpoint: u8,
121}
122
123/// A network heard during an active scan.
124#[derive(Debug, Clone, PartialEq, Eq)]
125pub struct Beacon {
126    /// Channel.
127    pub channel: u8,
128    /// PAN id.
129    pub pan_id: PanId,
130    /// Extended PAN id.
131    pub extended_pan_id: ExtPanId,
132    /// It accepts joins now.
133    pub permit_joining: bool,
134    /// Its network update id.
135    pub nwk_update_id: u8,
136    /// Link quality of the beacon.
137    pub lqi: u8,
138    /// Signal strength of the beacon, dBm, when the NCP reports it.
139    pub rssi: Option<i8>,
140}
141
142/// Something the NCP reported.
143#[derive(Debug, Clone, PartialEq, Eq)]
144pub enum AdapterEvent {
145    /// An APS frame for the host.
146    Message {
147        /// Sender's network address.
148        source: NodeId,
149        /// Sender's IEEE address, when the frame carried it.
150        source_ieee: Option<Ieee>,
151        /// APS addressing.
152        aps: Aps,
153        /// Sent as a broadcast or multicast.
154        broadcast: bool,
155        /// The group, for a multicast.
156        group: Option<u16>,
157        /// Last hop link quality.
158        lqi: u8,
159        /// Last hop signal strength, dBm, when the NCP reports it.
160        rssi: Option<i8>,
161        /// The APS payload.
162        payload: Vec<u8>,
163    },
164    /// A device joined or rejoined.
165    Joined {
166        /// Network address.
167        nwk: NodeId,
168        /// IEEE address.
169        ieee: Ieee,
170        /// Its parent.
171        parent: NodeId,
172        /// A rejoin (the device was on the network before).
173        rejoin: bool,
174    },
175    /// A device left.
176    Left {
177        /// Network address.
178        nwk: NodeId,
179        /// IEEE address.
180        ieee: Ieee,
181    },
182    /// Trust center link key exchange with a device finished.
183    KeyExchange {
184        /// The device.
185        ieee: Ieee,
186        /// It now has a unique link key.
187        success: bool,
188    },
189    /// A route record arrived.
190    RouteRecord {
191        /// The originator.
192        source: NodeId,
193        /// Its IEEE address, when the NCP reports it.
194        ieee: Option<Ieee>,
195        /// Relays, nearest the source first.
196        relays: Vec<NodeId>,
197        /// Last hop link quality, when the NCP reports it.
198        lqi: Option<u8>,
199        /// Last hop signal strength, when the NCP reports it.
200        rssi: Option<i8>,
201    },
202    /// A frame given to [`Adapter::send_unicast`] was delivered (APS
203    /// acknowledged) or not.
204    Delivery {
205        /// The tag `send_unicast` returned.
206        tag: u16,
207        /// Delivered.
208        delivered: bool,
209    },
210    /// The network went down.
211    NetworkDown,
212    /// The network came up.
213    NetworkUp,
214    /// The adapter failed (NCP reset or port lost); restart the host.
215    Failed(String),
216}
217
218/// A network co-processor family. Every method's future is `Send` so the
219/// host can call it from any task.
220pub trait Adapter: Send + Sync + 'static {
221    /// The NCP's identity.
222    fn info(&self) -> AdapterInfo;
223
224    /// Configure the NCP and bring the network up.
225    fn start(
226        &self,
227        mode: StartMode,
228    ) -> impl Future<Output = Result<(StartOutcome, NetworkInfo), HostError>> + Send;
229
230    /// Open (seconds > 0) or close (0) the coordinator for joining.
231    fn permit_join(
232        &self,
233        seconds: u8,
234        policy: &JoinPolicy,
235    ) -> impl Future<Output = Result<(), HostError>> + Send;
236
237    /// Let the device `ieee` join with `key` (from its install code).
238    fn add_join_key(
239        &self,
240        ieee: Ieee,
241        key: Key,
242    ) -> impl Future<Output = Result<(), HostError>> + Send;
243
244    /// Send an APS unicast. Returns a tag that a later
245    /// [`AdapterEvent::Delivery`] names.
246    fn send_unicast(
247        &self,
248        nwk: NodeId,
249        aps: Aps,
250        payload: Vec<u8>,
251    ) -> impl Future<Output = Result<u16, HostError>> + Send;
252
253    /// Send an APS broadcast to 0xFFFF, 0xFFFD or 0xFFFC.
254    fn send_broadcast(
255        &self,
256        destination: NodeId,
257        aps: Aps,
258        payload: Vec<u8>,
259    ) -> impl Future<Output = Result<(), HostError>> + Send;
260
261    /// Read the running network's parameters again (after a channel
262    /// change).
263    fn network_info(&self) -> impl Future<Output = Result<NetworkInfo, HostError>> + Send;
264
265    /// Export everything a restore needs.
266    fn backup(&self) -> impl Future<Output = Result<Backup, HostError>> + Send;
267
268    /// Listen for other networks' beacons on the channels in the mask
269    /// (an active scan). Works before a network is formed. An NCP family
270    /// that cannot scan returns none.
271    fn active_scan(
272        &self,
273        channel_mask: u32,
274    ) -> impl Future<Output = Result<Vec<Beacon>, HostError>> + Send;
275
276    /// Leave the NCP's network and erase it (keys, PAN ids, frame counter)
277    /// from the NCP, whether or not it was started.
278    fn leave(&self) -> impl Future<Output = Result<(), HostError>> + Send;
279
280    /// Measure each channel's energy; returns (channel, max RSSI dBm).
281    fn energy_scan(
282        &self,
283        channel_mask: u32,
284    ) -> impl Future<Output = Result<Vec<(u8, i8)>, HostError>> + Send;
285}