Interval loop support for obstruction maps

Tracked on issue #27

README.md

@@ -26,11 +26,13 @@ The scripts that use [MQTT](https://mqtt.org/) for output require the `paho-mqtt
 
 The scripts that use [InfluxDB](https://www.influxdata.com/products/influxdb/) for output require the `influxdb` Python package. Information about how to install that can be found at https://github.com/influxdata/influxdb-python. Note that this is the (slightly) older version of the InfluxDB client Python module, not the InfluxDB 2.0 client. It can still be made to work with an InfluxDB 2.0 server, but doing so requires using `influx v1` [CLI commands](https://docs.influxdata.com/influxdb/v2.0/reference/cli/influx/v1/) on the server to map the 1.x username, password, and database names to their 2.0 equivalents.
 
+The `dish_obstruction_map.py` script requires the `pypng` Python package. Information about how to install that can be found at https://pypng.readthedocs.io/en/latest/png.html#installation-and-overview
+
 Note that the Python package versions available from various Linux distributions (ie: installed via `apt-get` or similar) tend to run a bit behind those available to install via `pip`. While the distro packages should work OK as long as they aren't extremely old, they may not work as well as the later versions.
 
 ### Generating the gRPC protocol modules
 
-This step is no longer required, as the grpc scripts can now get the protocol module classes at run time via reflection, but generating the protocol modules will improve script startup time, and it would be a good idea to at least stash away the protoset file emitted by `grpcurl` in case SpaceX ever turns off server reflection in the dish software.
+This step is no longer required, as the grpc scripts can now get the protocol module classes at run time via reflection, but generating the protocol modules will improve script startup time, and it would be a good idea to at least stash away the protoset file emitted by `grpcurl` in case SpaceX ever turns off server reflection in the dish software. That being said, it's probably less error prone to use the run time reflection support rather than using the files generated in this step, so use your own judgement as to whether or not to proceed with this.
 
 The grpc scripts require some generated code to support the specific gRPC protocol messages used. These would normally be generated from .proto files that specify those messages, but to date (2020-Dec), SpaceX has not publicly released such files. The gRPC service running on the dish appears to have [server reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) enabled, though. `grpcurl` can use that to extract a protoset file, and the `protoc` compiler can use that to make the necessary generated code:
 ```shell script
@@ -86,6 +88,19 @@ python3 dish_grpc_text.py -t 60 -o 60 ping_drop
 ```
 will poll history data once per minute, but compute statistics only once per hour. This also reduces data loss due to a dish reboot, since the `-o` option will aggregate across reboots, too.
 
+### The obstruction map script
+
+`dish_obstruction_map.py` is a little different in that it doesn't write to a database, but rather writes PNG images to the local filesystem. To get a single image of the current obstruction map using the default colors, you can do the following:
+```shell script
+python3 dish_obstruction_map.py obstructions.png
+```
+or to run in a loop writing a sequence of images once per hour, you can do the following:
+```shell script
+python3 dish_obstruction_map.py -t 3600 obstructions_%s.png
+```
+
+Run it with the `-h` command line option for full usage details, including control of the map colors and color modes.
+
 ### The JSON parser script
 
 `dish_json_text.py` is similar to `dish_grpc_text.py`, but it takes JSON format input from a file instead of pulling it directly from the dish via grpc call. It also does not support the status info modes, because those are easy enough to interpret directly from the JSON data. The easiest way to use it is to pipe the `grpcurl` command directly into it. For example:

dish_obstruction_map.py

@@ -6,10 +6,12 @@ reachable on the local network and writes a PNG image based on that data.
 """
 
 import argparse
+from datetime import datetime
 import logging
 import os
 import png
 import sys
+import time
 
 import starlink_grpc
 
@@ -19,9 +21,10 @@ DEFAULT_NO_DATA_COLOR = "00000000"
 DEFAULT_OBSTRUCTED_GREYSCALE = "FF00"
 DEFAULT_UNOBSTRUCTED_GREYSCALE = "FFFF"
 DEFAULT_NO_DATA_GREYSCALE = "0000"
+LOOP_TIME_DEFAULT = 0
 
 
-def run_loop(opts, context):
+def loop_body(opts, context):
     snr_data = starlink_grpc.obstruction_map(context)
 
     def pixel_bytes(row):
@@ -58,7 +61,12 @@ def run_loop(opts, context):
         # Open new stdout file to get binary mode
         out_file = os.fdopen(sys.stdout.fileno(), "wb", closefd=False)
     else:
-        out_file = open(opts.filename, "wb")
+        now = int(time.time())
+        filename = opts.filename.replace("%u", str(now))
+        filename = filename.replace("%d",
+                                    datetime.utcfromtimestamp(now).strftime("%Y_%m_%d_%H_%M_%S"))
+        filename = filename.replace("%s", str(opts.sequence))
+        out_file = open(filename, "wb")
     if not snr_data or not snr_data[0]:
         logging.error("Invalid SNR map data: Zero-length")
         return 1
@@ -68,16 +76,20 @@ def run_loop(opts, context):
                         greyscale=opts.greyscale)
     writer.write(out_file, (bytes(pixel_bytes(row)) for row in snr_data))
     out_file.close()
+
+    opts.sequence += 1
     return 0
 
 
-def main():
+def parse_args():
-    logging.basicConfig(format="%(levelname)s: %(message)s")
-
     parser = argparse.ArgumentParser(
         description="Collect directional obstruction map data from a Starlink user terminal and "
         "emit it as a PNG image")
-    parser.add_argument("filename", help="The image file to write, or - to write to stdout")
+    parser.add_argument(
+        "filename",
+        help="The image file to write, or - to write to stdout; may be a template with the "
+        "following to be filled in per loop iteration: %%s for sequence number, %%d for UTC date "
+        "and time, %%u for seconds since Unix epoch.")
     parser.add_argument(
         "-o",
         "--obstructed-color",
@@ -97,20 +109,29 @@ def main():
         "-g",
         "--greyscale",
         action="store_true",
-        help=
+        help="Emit a greyscale image instead of the default full color image; greyscale images "
-        "Emit a greyscale image instead of the default full color image; greyscale images use L or AL hex notation for the color options"
+        "use L or AL hex notation for the color options")
-    )
     parser.add_argument(
         "-z",
         "--no-alpha",
         action="store_true",
-        help=
+        help="Emit an image without alpha (transparency) channel instead of the default that "
-        "Emit an image without alpha (transparency) channel instead of the default that includes alpha channel"
+        "includes alpha channel")
-    )
+    parser.add_argument("-e",
-    parser.add_argument("-t",
                         "--target",
                         help="host:port of dish to query, default is the standard IP address "
                         "and port (192.168.100.1:9200)")
+    parser.add_argument("-t",
+                        "--loop-interval",
+                        type=float,
+                        default=float(LOOP_TIME_DEFAULT),
+                        help="Loop interval in seconds or 0 for no loop, default: " +
+                        str(LOOP_TIME_DEFAULT))
+    parser.add_argument("-s",
+                        "--sequence",
+                        type=int,
+                        default=1,
+                        help="Starting sequence number for templatized filenames, default: 1")
     opts = parser.parse_args()
 
     if opts.obstructed_color is None:
@@ -135,11 +156,26 @@ def main():
             logging.error("Invalid hex number for %s", option)
             sys.exit(1)
 
+    return opts
+
+
+def main():
+    opts = parse_args()
+
+    logging.basicConfig(format="%(levelname)s: %(message)s")
+
     context = starlink_grpc.ChannelContext(target=opts.target)
 
     try:
-        # XXX: make this actually run in a loop...
+        next_loop = time.monotonic()
-        rc = run_loop(opts, context)
+        while True:
+            rc = loop_body(opts, context)
+            if opts.loop_interval > 0.0:
+                now = time.monotonic()
+                next_loop = max(next_loop + opts.loop_interval, now)
+                time.sleep(next_loop - now)
+            else:
+                break
     finally:
         context.close()