Merge pull request #695 from ain101/develop

update mch2022 tools

app/resources/plugins/MCH22BToolchain/mch2022-tools/README.md

@@ -3,34 +3,92 @@ This directory contains command line tools for use with your badge.
 
 To use them, you will need to `pip install pyusb`.
 
-### AppFS
+### Application management
 The AppFS contains binary ESP32 apps - standalone firmwares that can be booted and used as apps.
 
-`webusb_ls.py`  
+`app_list.py`
+
 Lists all apps on the AppFS.
 
-`webusb_push.py {target_name} {filename} [--run]`  
+`app_push.py {file} {name} {title} {version} [--run]`
+
 Installs an ESP32 app to the AppFS.
 The `--run` flag will also immediately start the app after installing.
 
-`webusb_boot.py {app_name}`  
+`app_pull.py {name} {target}`
+
+Downloads the ESP32 app binary to your computer, the file will be saved at the location provided as target.
+
+`app_run.py {name}`
+
 Boots an ESP32 app with the specified name.
 
-`webusb_rm.py {app_name}`  
+`webusb_remove.py {app_name}`
+
 Removes an ESP32 app from the AppFS.
 
-### Filesystem
-`webusb_fat_ls.py [path]`  
+### FAT filesystem
+`filesystem_list.py [path] [--recursive]`
+
 Returns a directory listing for the specified path.
 
-`webusb_fat_push.py {filename} {target_location}`  
-Uploads a local file to the FAT filesystem.  
-`target_location` should always start with `/flash` or `/sdcard` and include the target filename.
+`filesystem_push.py {name} {target}`
+
+Uploads file `{name}` to location `{target}` on the filesystem of the badge.
+`target` should always start with `/internal` or `/sd` and the target path should always end with a filename.
+
+`filesystem_pull.py {name} {target}`
+
+Downloads file `{name}` from the filesystem of the badge to location `{target}` on your computer.
+`name` should always start with `/internal` or `/sd` and the path should always end with a filename.
+
+`filesystem_remove.py {name}`
+
+Removes a file or a directory from the filesystem of the badge. In case of a directory the directory is removed recursively.
+`name` should always start with `/internal` or `/sd`.
+
+`filesystem_create_directory.py {name}`
+
+Creates a directory on the filesystem of the badge.
+`name` should always start with `/internal` or `/sd`.
+
+`filesystem_exists.py {name}`
+
+Checks if a file exists on the filesystem of the badge.
+`name` should always start with `/internal` or `/sd`.
+
+### Configuration management
+
+`configuration_list.py [namespace]`
+
+Lists all configuration entries in the NVS partition of the badge. The optional `namespace` argument allows for filtering the results, returning only the entries in the provided namespace.
+
+`configuration_read.py {namespace} {key} {type}`
+
+Reads the value of a configuration entry with key `{key}` in namespace `{namespace}`. Valid types are u8 (8-bit unsigned integer), i8 (8-bit signed integer), u16 (16-bit unsigned integer), i16 (16-bit signed integer), u32 (32-bit unsigned integer), i32 (32-bit signed integer), u64 (64-bit unsigned integer), i64 (64-bit signed integer), string (a text string) and blob (binary data).
+
+Note that reading entries of type `blob` will output raw binary data to stdout. You might want to pipe the output to another program (`python configuration_read.py example example blob | xxd`) or to a file (`python configuration_read.py example example blob > data.bin`).
+
+`configuration_write.py {namespace} {key} {type} [value]`
+
+Writes the value of a configuration entry with key `{key}` in namespace `{namespace}`. Valid types are u8 (8-bit unsigned integer), i8 (8-bit signed integer), u16 (16-bit unsigned integer), i16 (16-bit signed integer), u32 (32-bit unsigned integer), i32 (32-bit signed integer), u64 (64-bit unsigned integer), i64 (64-bit signed integer), string (a text string) and blob (binary data).
+
+The value can either be provided using optional command line argument `[value]` or by writing a value to stdin (`echo "test" | python configuration_write.py owner nickname string`). Writing to stdin can also be used for storing binary data to a configuration entry of type `blob`.
+
+`configuration_remove.py {namespace} {key}`
+
+Removes a configuration entry with key `{key}` in namespace `{namespace}` from the NVS partition.
 
 ### FPGA
-`webusb_fpga.py {filename} [bindings]`  
-Loads a bit stream from a file into the FPGA.
+`fpga.py {filename} [bindings]`
+
+Loads a bit stream from a file into the FPGA. This tool also allows for uploading and presenting files to the FPGA via the SPI interface that connects the FPGA to the ESP32.
+
+### Other
+`exit.py`
+
+Reboots the badge, exiting webusb mode.
+
+`information.py`
 
-### General
-`webusb_reset.py`  
-Reboots the device.
+Returns usage information about the FAT filesystems and the AppFS filesystem

app/resources/plugins/MCH22BToolchain/mch2022-tools/app_list.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+from webusb import *
+import argparse
+import sys
+import time
+
+def listapps():
+    applist = badge.app_list()
+    if not applist == None:
+        print("\x1b[4m{: <48}\x1b[0m \x1b[4m{: <64}\x1b[0m \x1b[4m{: <8}\x1b[0m \x1b[4m{: <10}\x1b[0m".format("Name", "Title", "Version", "Size"))
+        for app in applist:
+            size = str(app["size"]) + " B"
+            if app["size"] > 1024:
+                size = str(round(app["size"] / 1024, 2)) + " KB"
+            print("{: <48} {: <64} {: <8} {: <10}".format(app["name"].decode("ascii", errors="ignore"), app["title"].decode("ascii", errors="ignore"), str(app["version"]), size))
+    else:
+        print(location.decode("ascii") + " ** Failed to load application list **")
+
+parser = argparse.ArgumentParser(description='MCH2022 badge application list tool')
+args = parser.parse_args()
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+listapps()

app/resources/plugins/MCH22BToolchain/mch2022-tools/app_pull.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+
+from webusb import *
+import argparse
+import sys
+import time
+
+parser = argparse.ArgumentParser(description='MCH2022 badge app download tool')
+parser.add_argument("name", help="Remote app")
+parser.add_argument("target", help="Local file")
+args = parser.parse_args()
+
+name = args.name
+target = args.target
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+result = badge.app_read(name.encode("ascii", "ignore"))
+
+if result:
+    with open(target, "wb") as f:
+        f.write(result)
+        f.truncate(len(result))
+    print("App downloaded succesfully")
+else:
+    print("Failed to download app")
+    sys.exit(1)

app/resources/plugins/MCH22BToolchain/mch2022-tools/app_push.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+
+from webusb import *
+import argparse
+import sys
+import time
+
+parser = argparse.ArgumentParser(description='MCH2022 badge app upload tool')
+parser.add_argument("file", help="Application binary")
+parser.add_argument("name", help="Application name")
+parser.add_argument("title", help="Application title")
+parser.add_argument("version", type=int, help="Application version")
+parser.add_argument('--run', '-r', '-R', action='store_true', help="Run application after uploading")
+args = parser.parse_args()
+
+name = args.name.encode("ascii", "ignore")
+title = args.title.encode("ascii", "ignore")
+version = args.version
+if version < 0:
+    version = 0
+
+with open(args.file, "rb") as f:
+    data = f.read()
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+result = badge.app_write(name, title, version, data)
+
+if result:
+    print("App installed succesfully")
+else:
+    print("Failed to install app")
+    sys.exit(1)
+
+if args.run:
+    result = badge.app_run(name)
+
+    if result:
+        badge.reset(False)
+        print("Started")
+    else:
+        print("Failed to start")
+        sys.exit(1)

app/resources/plugins/MCH22BToolchain/mch2022-tools/app_remove.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+
+from webusb import *
+import argparse
+import sys
+import time
+
+parser = argparse.ArgumentParser(description='MCH2022 badge app removal tool')
+parser.add_argument("name", help="Name of app to be removed")
+args = parser.parse_args()
+
+name = args.name
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+result = badge.app_remove(name.encode('ascii', "ignore"))
+
+if result:
+    print("Removed")
+else:
+    print("Failed to remove")
+    sys.exit(1)

app/resources/plugins/MCH22BToolchain/mch2022-tools/app_run.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+
+from webusb import *
+import argparse
+import sys
+import time
+
+parser = argparse.ArgumentParser(description='MCH2022 badge app run tool')
+parser.add_argument("name", help="Name of app to be started")
+parser.add_argument("--command", "-c", help="String to be stored in memory", required=False)
+args = parser.parse_args()
+
+name = args.name
+command = args.command
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+result = badge.app_run(name.encode('ascii', "ignore"), command.encode('ascii', "ignore") if command else None)
+
+if result:
+    badge.reset(False)
+    print("Started")
+else:
+    print("Failed to start")
+    sys.exit(1)

app/resources/plugins/MCH22BToolchain/mch2022-tools/configuration_list.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+from webusb import *
+import argparse
+import sys
+import time
+
+parser = argparse.ArgumentParser(description='MCH2022 badge NVS list tool')
+parser.add_argument("namespace", help="Namespace", nargs='?', default=None)
+args = parser.parse_args()
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+print("\x1b[4m{: <32}\x1b[0m \x1b[4m{: <32}\x1b[0m \x1b[4m{: <8}\x1b[0m \x1b[4m{: <10}\x1b[0m \x1b[4m{: <32}\x1b[0m".format("Namespace", "Key", "Type", "Size", "Value"))
+badge.printGarbage = True
+if args.namespace:
+    entries = badge.nvs_list(args.namespace)
+else:
+    entries = badge.nvs_list()
+
+if not entries:
+    print("Failed to read data")
+else:
+    for namespace in entries:
+        for entry in entries[namespace]:
+            value = "(skipped)"
+            if entry["size"] < 64 and badge.nvs_should_read(entry["type"]):
+                value = str(badge.nvs_read(namespace, entry["key"], entry["type"]))
+            print("{: <32} {: <32} {: <8} {:10d} {}".format(namespace, entry["key"], badge.nvs_type_to_name(entry["type"]), entry["size"], value))

app/resources/plugins/MCH22BToolchain/mch2022-tools/configuration_read.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+from webusb import *
+import argparse
+import sys
+import time
+import sys
+
+parser = argparse.ArgumentParser(description='MCH2022 badge NVS read tool')
+parser.add_argument("namespace", help="Namespace")
+parser.add_argument("key", help="Key")
+parser.add_argument("type", help="Type, one of u8, i8, u16, i16, u32, i32, u64, i64, string or blob")
+args = parser.parse_args()
+
+badge = Badge()
+
+type_name = args.type.lower()
+type_number = badge.nvs_name_to_type(type_name)
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+value = badge.nvs_read(args.namespace, args.key, type_number)
+
+if type_name == "blob":
+    sys.stdout.buffer.write(value)
+else:
+    print(value)

app/resources/plugins/MCH22BToolchain/mch2022-tools/configuration_remove.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+from webusb import *
+import argparse
+import sys
+import time
+import sys
+
+parser = argparse.ArgumentParser(description='MCH2022 badge NVS remove tool')
+parser.add_argument("namespace", help="Namespace")
+parser.add_argument("key", help="Key")
+args = parser.parse_args()
+
+badge = Badge()
+
+if not badge.begin():
+    print("Failed to connect")
+    sys.exit(1)
+
+result = badge.nvs_remove(args.namespace, args.key)
+
+if result:
+    print("Entry removed")
+else:
+    print("Failed to remove entry")
+    sys.exit(1)