Merge pull request #11 from puddly/puddly/energy-scans

Implement an `energy-scan` tool

Author: puddly

.pre-commit-config.yaml

@@ -1,16 +1,16 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 22.3.0
     hooks:
       - id: black
         args:
           - --safe
           - --quiet
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.3
+    rev: 4.0.1
     hooks:
       - id: flake8
   - repo: https://github.com/PyCQA/isort
-    rev: 5.5.2
+    rev: 5.10.1
     hooks:
       - id: isort

README.md

@@ -67,6 +67,36 @@ Network key sequence:  0
 2021-07-12 13:25:15.316 host zigpy_znp.uart DEBUG Closing serial port
 ```
 
+Performing an energy scan (using a router device instead of the coordinator):
+
+```console
+$ zigpy radio znp /dev/cu.usbserial-1420 energy-scan --nwk 0xbc6a
+
+Channel energy (mean of 1 / 5):
+------------------------------------------------
+ + Lower energy is better
+ + Active Zigbee networks on a channel may still cause congestion
+ + TX on 26 in North America may be with lower power due to regulations
+ + Zigbee channels 15, 20, 25 fall between WiFi channels 1, 6, 11
+ + Some Zigbee devices only join networks on channels 15, 20, and 25
+------------------------------------------------
+ - 11    80.00%  ################################################################################
+ - 12    83.53%  ###################################################################################
+ - 13    83.14%  ###################################################################################
+ - 14    78.82%  ##############################################################################
+ - 15    76.47%  ############################################################################
+ - 16    72.16%  ########################################################################
+ - 17    76.47%  ############################################################################
+ - 18    75.69%  ###########################################################################
+ - 19    72.16%  ########################################################################
+ - 20    65.49%  #################################################################
+ - 21    66.67%  ##################################################################
+ - 22    70.59%  ######################################################################
+ - 23    80.00%  ################################################################################
+ - 24    64.31%  ################################################################
+ - 25    77.25%  #############################################################################
+ - 26*   81.96%  #################################################################################
+```
 
 # OTA
 Display basic information about OTA files:

zigpy_cli/common.py

@@ -1,5 +1,7 @@
 import logging
 
+import click
+
 TRACE = logging.DEBUG - 5
 logging.addLevelName(TRACE, "TRACE")
 
@@ -69,3 +71,22 @@
 }
 
 RADIO_TO_PYPI = {name: mod.replace("_", "-") for name, mod in RADIO_TO_PACKAGE.items()}
+
+
+class HexOrDecIntParamType(click.ParamType):
+    name = "integer"
+
+    def convert(self, value, param, ctx):
+        if isinstance(value, int):
+            return value
+
+        try:
+            if value[:2].lower() == "0x":
+                return int(value[2:], 16)
+            else:
+                return int(value, 10)
+        except ValueError:
+            self.fail(f"{value!r} is not a valid integer", param, ctx)
+
+
+HEX_OR_DEC_INT = HexOrDecIntParamType()

zigpy_cli/radio.py

@@ -2,13 +2,22 @@
 
 import logging
 import importlib
+import collections
 
 import click
+import zigpy.state
+import zigpy.types
 import zigpy.config as conf
+import zigpy.zdo.types
 
 from zigpy_cli.cli import cli, click_coroutine
 from zigpy_cli.utils import format_bytes
-from zigpy_cli.common import RADIO_TO_PYPI, RADIO_TO_PACKAGE, RADIO_LOGGING_CONFIGS
+from zigpy_cli.common import (
+    RADIO_TO_PYPI,
+    HEX_OR_DEC_INT,
+    RADIO_TO_PACKAGE,
+    RADIO_LOGGING_CONFIGS,
+)
 
 LOGGER = logging.getLogger(__name__)
 
@@ -96,3 +105,59 @@ async def form(app):
     await app.startup(auto_form=True)
     await app.form_network()
     dump_app_info(app)
+
+
+@radio.command()
+@click.pass_obj
+@click.option("--nwk", type=HEX_OR_DEC_INT, default=0x0000)
+@click_coroutine
+async def energy_scan(app, nwk):
+    await app.startup()
+    LOGGER.info("Running scan...")
+
+    # Temporarily create a zigpy device for scans not using the coordinator itself
+    if nwk != 0x0000:
+        app.add_device(
+            nwk=nwk,
+            ieee=zigpy.types.EUI64.convert("AA:AA:AA:AA:AA:AA:AA:AA"),
+        )
+
+    # We compute an average over the last 5 scans
+    channel_energies = collections.defaultdict(lambda: collections.deque([], maxlen=5))
+
+    while True:
+        rsp = await app.get_device(nwk=nwk).zdo.Mgmt_NWK_Update_req(
+            zigpy.zdo.types.NwkUpdate(
+                ScanChannels=zigpy.types.Channels.ALL_CHANNELS,
+                ScanDuration=0x02,
+                ScanCount=1,
+            )
+        )
+
+        _, scanned_channels, _, _, energy_values = rsp
+
+        for channel, energy in zip(scanned_channels, energy_values):
+            energies = channel_energies[channel]
+            energies.append(energy)
+
+        total = 0xFF * len(energies)
+
+        print(f"Channel energy (mean of {len(energies)} / {energies.maxlen}):")
+        print("------------------------------------------------")
+        print(" + Lower energy is better")
+        print(" + Active Zigbee networks on a channel may still cause congestion")
+        print(" + TX on 26 in North America may be with lower power due to regulations")
+        print(" + Zigbee channels 15, 20, 25 fall between WiFi channels 1, 6, 11")
+        print(" + Some Zigbee devices only join networks on channels 15, 20, and 25")
+        print("------------------------------------------------")
+
+        for channel, energies in channel_energies.items():
+            count = sum(energies)
+            asterisk = "*" if channel == 26 else " "
+
+            print(
+                f" - {channel:>02}{asterisk}  {count / total:>7.2%}  "
+                + "#" * int(100 * count / total)
+            )
+
+        print()