use serde::{Deserialize, Serialize};
use zigbee_primitives::{ExtPanId, Ieee, Key, PanId};
pub const FORMAT: &str = "zigpy/open-coordinator-backup";
pub const RESTORE_FRAME_COUNTER_MARGIN: u32 = 100_000;
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Backup {
pub metadata: Metadata,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub stack_specific: Option<StackSpecific>,
pub coordinator_ieee: Ieee,
#[serde(with = "pan_hex")]
pub pan_id: PanId,
pub extended_pan_id: ExtPanId,
pub nwk_update_id: u8,
pub security_level: u8,
pub channel: u8,
pub channel_mask: Vec<u8>,
pub network_key: NetworkKey,
pub devices: Vec<BackupDevice>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Metadata {
pub format: String,
pub version: u32,
pub source: String,
#[serde(default)]
pub internal: Internal,
}
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct Internal {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub created_unix: Option<u64>,
#[serde(
default,
rename = "ezspVersion",
skip_serializing_if = "Option::is_none"
)]
pub ezsp_version: Option<u8>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub firmware: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct StackSpecific {
#[serde(default, skip_serializing_if = "Option::is_none")]
pub ezsp: Option<EzspSpecific>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub zstack: Option<ZstackSpecific>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ZstackSpecific {
pub tclk_seed: Key,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct EzspSpecific {
pub hashed_tclk: Key,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NetworkKey {
pub key: Key,
pub sequence_number: u8,
pub frame_counter: u32,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BackupDevice {
#[serde(default, with = "opt_pan_hex")]
pub nwk_address: Option<u16>,
pub ieee_address: Ieee,
#[serde(default)]
pub is_child: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub link_key: Option<LinkKey>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LinkKey {
pub key: Key,
pub tx_counter: u32,
pub rx_counter: u32,
}
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum BackupError {
#[error("not an open coordinator backup (format {0:?})")]
Format(String),
#[error("unsupported backup format version {0}")]
Version(u32),
#[error("channel {0} is not a 2.4 GHz Zigbee channel")]
Channel(u8),
#[error("backup JSON: {0}")]
Json(String),
}
impl Backup {
pub fn from_json(text: &str) -> Result<Backup, BackupError> {
let backup: Backup =
serde_json::from_str(text).map_err(|e| BackupError::Json(e.to_string()))?;
backup.validate()?;
Ok(backup)
}
pub fn validate(&self) -> Result<(), BackupError> {
if self.metadata.format != FORMAT {
return Err(BackupError::Format(self.metadata.format.clone()));
}
if self.metadata.version != 1 {
return Err(BackupError::Version(self.metadata.version));
}
if !(11..=26).contains(&self.channel) {
return Err(BackupError::Channel(self.channel));
}
Ok(())
}
pub fn to_json(&self) -> String {
serde_json::to_string_pretty(self).unwrap_or_default()
}
pub fn restore_frame_counter(&self) -> u32 {
self.network_key
.frame_counter
.saturating_add(RESTORE_FRAME_COUNTER_MARGIN)
}
}
mod pan_hex {
use serde::{de::Error, Deserialize, Deserializer, Serializer};
pub fn serialize<S: Serializer>(v: &u16, s: S) -> Result<S::Ok, S::Error> {
s.serialize_str(&format!("{v:04x}"))
}
pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<u16, D::Error> {
let text = String::deserialize(d)?;
u16::from_str_radix(text.trim_start_matches("0x"), 16).map_err(D::Error::custom)
}
}
mod opt_pan_hex {
use serde::{de::Error, Deserialize, Deserializer, Serializer};
pub fn serialize<S: Serializer>(v: &Option<u16>, s: S) -> Result<S::Ok, S::Error> {
match v {
Some(v) => s.serialize_str(&format!("{v:04x}")),
None => s.serialize_none(),
}
}
pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Option<u16>, D::Error> {
match Option::<String>::deserialize(d)? {
None => Ok(None),
Some(text) => u16::from_str_radix(text.trim_start_matches("0x"), 16)
.map(Some)
.map_err(D::Error::custom),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn round_trips_and_validates() {
let backup = Backup {
metadata: Metadata {
format: FORMAT.into(),
version: 1,
source: "zigbee-bridge@0.1.0".into(),
internal: Internal {
created_unix: Some(1),
ezsp_version: Some(13),
firmware: Some("7.4.4.0".into()),
},
},
stack_specific: Some(StackSpecific {
ezsp: Some(EzspSpecific {
hashed_tclk: Key([1; 16]),
}),
zstack: None,
}),
coordinator_ieee: Ieee(0x00124B0001020304),
pan_id: 0x1A62,
extended_pan_id: ExtPanId(0xDDDDDDDDDDDDDDDD),
nwk_update_id: 0,
security_level: 5,
channel: 15,
channel_mask: vec![15],
network_key: NetworkKey {
key: Key([2; 16]),
sequence_number: 0,
frame_counter: 4242,
},
devices: vec![BackupDevice {
nwk_address: Some(0x1234),
ieee_address: Ieee(5),
is_child: true,
link_key: Some(LinkKey {
key: Key([3; 16]),
tx_counter: 1,
rx_counter: 2,
}),
}],
};
let json = backup.to_json();
assert!(json.contains("\"pan_id\": \"1a62\""));
assert!(json.contains("\"coordinator_ieee\": \"00124b0001020304\""));
assert_eq!(Backup::from_json(&json).unwrap(), backup);
assert_eq!(
backup.restore_frame_counter(),
4242 + RESTORE_FRAME_COUNTER_MARGIN
);
let bad = json.replace("\"channel\": 15", "\"channel\": 30");
assert_eq!(Backup::from_json(&bad), Err(BackupError::Channel(30)));
}
#[test]
fn reads_backups_from_other_hosts() {
let text = r#"{
"metadata": {"format": "zigpy/open-coordinator-backup", "version": 1,
"source": "another-host@1.2.3",
"internal": {"date": "2026-01-02T03:04:05Z", "znpVersion": 1}},
"stack_specific": {"zstack": {"tclk_seed": "0102030405060708090a0b0c0d0e0f10"}},
"coordinator_ieee": "00124b0012345678",
"pan_id": "1a62",
"extended_pan_id": "dddddddddddddddd",
"nwk_update_id": 3,
"security_level": 5,
"channel": 15,
"channel_mask": [15],
"network_key": {"key": "01030507090b0d0f00020406080a0c0d",
"sequence_number": 1, "frame_counter": 123456},
"devices": [
{"nwk_address": "ddb4", "ieee_address": "00158d0001020304", "is_child": true,
"link_key": {"key": "f1f2f3f4f5f6f7f8f9fafbfcfdfeff00", "rx_counter": 7, "tx_counter": 9}},
{"nwk_address": null, "ieee_address": "00158d0001020305", "is_child": false}
]
}"#;
let b = Backup::from_json(text).unwrap();
assert_eq!(b.coordinator_ieee, Ieee(0x00124B0012345678));
assert_eq!((b.pan_id, b.channel, b.nwk_update_id), (0x1A62, 15, 3));
assert_eq!(b.network_key.frame_counter, 123_456);
let seed = b
.stack_specific
.as_ref()
.and_then(|s| s.zstack.as_ref())
.unwrap();
assert_eq!(seed.tclk_seed.0[0], 0x01);
assert_eq!(b.devices.len(), 2);
assert_eq!(b.devices[0].nwk_address, Some(0xDDB4));
assert_eq!(
b.devices[0].link_key.as_ref().map(|k| k.tx_counter),
Some(9)
);
assert_eq!(b.devices[1].nwk_address, None);
let again = Backup::from_json(&b.to_json()).unwrap();
assert_eq!(again, b);
}
}