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}