Implement backup and restore

Author: puddly

README.md

@@ -25,15 +25,21 @@ custom_zha_radios:
    description: TI CC13x2, CC26x2, and ZZH
 ```
 
+# Backup and restore
+A complete radio NVRAM backup can be performed to migrate between different radios **based on the same chip** (i.e. between the zig-a-zig-ah! and the LAUNCHXL-CC26X2R1 will work). Anything else is untested.
+
+```shell
+(venv) $ python -m zigpy_znp.tools.backup /dev/serial/by-id/old_radio -o backup.json
+(venv) $ python -m zigpy_znp.tools.restore /dev/serial/by-id/new_radio -i backup.json
+```
+
 # Hardware requirements
 USB-adapters, GPIO-modules, and development-boards running recent TI Z-Stack releases (i.e. CC13x2 and CC26x2) are supported. Reference hardware for this project includes:
 
  - [TI LAUNCHXL-CC26X2R1](https://www.ti.com/tool/LAUNCHXL-CC26X2R1) running [Z-Stack 3.30.00.03](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/Z-Stack_3.x.0/bin). You can flash `CC26X2R1_20191106.hex` using [TI's UNIFLASH](https://www.ti.com/tool/download/UNIFLASH).
  - [Electrolama's zig-a-zig-ah!](https://electrolama.com/projects/zig-a-zig-ah/) running [Z-Stack 4.10.00.78](https://github.com/Koenkk/Z-Stack-firmware/tree/develop/coordinator/Z-Stack_3.x.0/bin). You can flash `CC26X2R1_20200417.hex` using [cc2538-bsl](https://github.com/JelmerT/cc2538-bsl).
 
- Z-Stack versions 3.x and above are currently required and all communication with the radio module is done over the the Z-Stack Monitor and Test (MT) interface via a serial port.
-
-Texas Instruments CC13x2 and CC26x2 based adapters/boards already come with a bootloader so can be flashed over USB using the official "Flash Programmer v2" from Texas Instruments. The zig-a-zig-ah! 
+Z-Stack versions 3.x and above are currently required and all communication with the radio module is done over the the Z-Stack Monitor and Test (MT) interface via a serial port.
 
 ## Texas Instruments Chip Part Numbers
 Texas Instruments (TI) has quite a few different wireless MCU chips and they are all used/mentioned in open-source Zigbee world which can be daunting if you are just starting out. Here is a quick summary of part numbers and key features.

zigpy_znp/tools/__init__.py

@@ -0,0 +1,85 @@
+import sys
+import json
+import asyncio
+import logging
+import argparse
+import coloredlogs
+
+import zigpy_znp.types as t
+import zigpy_znp.commands as c
+
+from zigpy_znp.api import ZNP
+from zigpy_znp.config import CONFIG_SCHEMA
+from zigpy_znp.exceptions import InvalidCommandResponse
+from zigpy_znp.types.nvids import NwkNvIds, OsalExNvIds
+
+coloredlogs.install(level=logging.DEBUG)
+logging.getLogger("zigpy_znp").setLevel(logging.DEBUG)
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def backup(radio_path):
+    znp = ZNP(CONFIG_SCHEMA({"device": {"path": radio_path}}))
+
+    await znp.connect()
+
+    data = {
+        "osal": {},
+        "nwk": {},
+    }
+
+    for nwk_nvid in NwkNvIds:
+        try:
+            value = await znp.nvram_read(nwk_nvid)
+            LOGGER.info("%s = %s", nwk_nvid, value)
+
+            data["nwk"][nwk_nvid.name] = value.hex()
+        except InvalidCommandResponse:
+            LOGGER.warning("Read failed for %s", nwk_nvid)
+            continue
+
+    for osal_nvid in OsalExNvIds:
+        length_rsp = await znp.request(
+            c.SYS.NVLength.Req(SysId=1, ItemId=osal_nvid, SubId=0)
+        )
+        length = length_rsp.Length
+
+        if length == 0:
+            LOGGER.warning("Read failed for %s", osal_nvid)
+            continue
+
+        value = (
+            await znp.request(
+                c.SYS.NVRead.Req(
+                    SysId=1, ItemId=osal_nvid, SubId=0, Offset=0, Length=length
+                ),
+                RspStatus=t.Status.SUCCESS,
+            )
+        ).Value
+        LOGGER.info("%s = %s", osal_nvid, value)
+
+        data["osal"][osal_nvid.name] = value.hex()
+
+    return data
+
+
+async def main(argv):
+    parser = argparse.ArgumentParser(description="Backup a radio's NVRAM")
+    parser.add_argument("serial", type=argparse.FileType("rb"), help="Serial port path")
+    parser.add_argument(
+        "--output", "-o", type=argparse.FileType("w"), help="Output file", default="-"
+    )
+
+    args = parser.parse_args(argv)
+
+    # We just want to make sure it exists
+    args.serial.close()
+
+    obj = await backup(args.serial.name)
+
+    args.output.write(json.dumps(obj, indent=4))
+
+
+if __name__ == "__main__":
+    asyncio.run(main(sys.argv[1:]))

zigpy_znp/tools/backup.py

@@ -0,0 +1,80 @@
+import sys
+import json
+import asyncio
+import logging
+import argparse
+import coloredlogs
+
+import zigpy_znp.types as t
+import zigpy_znp.commands as c
+
+from zigpy_znp.api import ZNP
+from zigpy_znp.config import CONFIG_SCHEMA
+from zigpy_znp.exceptions import InvalidCommandResponse
+from zigpy_znp.types.nvids import NwkNvIds, OsalExNvIds
+
+coloredlogs.install(level=logging.DEBUG)
+logging.getLogger("zigpy_znp").setLevel(logging.DEBUG)
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def restore(radio_path, backup):
+    znp = ZNP(CONFIG_SCHEMA({"device": {"path": radio_path}}))
+
+    await znp.connect()
+
+    for nwk_nvid, value in backup["nwk"].items():
+        nvid = NwkNvIds[nwk_nvid]
+        value = bytes.fromhex(value)
+
+        # XXX: are any NVIDs not filled all the way?
+        init_rsp = await znp.request(
+            c.SYS.OSALNVItemInit.Req(Id=nvid, ItemLen=len(value), Value=value)
+        )
+        assert init_rsp.Status in (t.Status.SUCCESS, t.Status.NV_ITEM_UNINIT)
+
+        try:
+            await znp.nvram_write(nvid, value)
+        except InvalidCommandResponse:
+            LOGGER.warning("Write failed for %s = %s", nvid, value)
+
+    for osal_nvid, value in backup["osal"].items():
+        nvid = OsalExNvIds[osal_nvid]
+        value = bytes.fromhex(value)
+
+        try:
+            await znp.request(
+                c.SYS.NVWrite.Req(SysId=1, ItemId=nvid, SubId=0, Offset=0, Value=value),
+                RspStatus=t.Status.SUCCESS,
+            )
+        except InvalidCommandResponse:
+            LOGGER.warning("Write failed for %s = %s", nvid, value)
+
+    # Reset afterwards to have the new values take effect
+    await znp.request_callback_rsp(
+        request=c.SYS.ResetReq.Req(Type=t.ResetType.Soft),
+        callback=c.SYS.ResetInd.Callback(partial=True),
+    )
+
+
+async def main(argv):
+    parser = argparse.ArgumentParser(
+        description="Restore a radio's NVRAM from a previous backup"
+    )
+    parser.add_argument("serial", type=argparse.FileType("rb"), help="Serial port path")
+    parser.add_argument(
+        "--input", "-i", type=argparse.FileType("r"), help="Input file", required=True
+    )
+
+    args = parser.parse_args(argv)
+
+    # We just want to make sure it exists
+    args.serial.close()
+
+    backup = json.load(args.input)
+    await restore(args.serial.name, backup)
+
+
+if __name__ == "__main__":
+    asyncio.run(main(sys.argv[1:]))