Updated API, refactored examples and App Manager.

Signed-off-by: ubi de feo <me@ubidefeo.com>

Author: ubidefeo

README.md

@@ -1,18 +1,39 @@
 # Arduino Tools for MicroPython
 
 This package adds functionalities for
+
 * MicroPython apps framework
 * file system helpers
 * WiFi network management
 
+## Installation
+
+### Using `mpremote`
+
+We must specify the target especially if the framework is already installed and a default app is present, since `mpremote mip` will use the current path to look for or create the `lib` folder.
+We want to make sure the tools are accessible from every application/location.
+
+```bash
+mpremote mip install --target=[flash]/lib github:arduino/arduino-tools-mpy
+```
+
+### Using `mip` from the board.
+
+First make sure your board is connected to a network, or `mip` will fail.
+
+```python
+import mip
+mip.install('github:arduino/arduino-tools-mpy', target='[flash]/lib')
+```
 
 ## MicroPython Apps Framework
+
 A set of tools and helpers to implement, create and manage MicroPython Apps.
 
 A new approach to enabling a MicroPython board to host/store multiple projects with the choice of running one as default, as well as have a mechanism of fallback to a default launcher.
 It does not interfere with the canonical `boot.py`  > `main.py` run paradigm, and allows users to easily activate this functionality on top of any stock MicroPython file-system.
 
-The Arduino MicroPython App framework relies on the creation of well structured projects/apps enclosed in their own folders named "app_{app-name}", which in turn contain a set of files (`main.py`, `lib/`, `app.json`, etc.).
+The Arduino MicroPython App framework relies on the creation of aptly structured projects/apps enclosed in their own folders named "app_{app-name}", which in turn contain a set of files (`main.py`, `lib/`, `app.json`, etc.).
 These are the conditions for a project/app to be considered "valid".
 Other files can be added to user's discretion, for instance to store assets or log/save data.
 
@@ -23,44 +44,50 @@ The framework exploits the standard behaviour of MicroPython at start/reset/soft
 
 The framework's boot.py only requires two lines for the following operations:
 
-- import the minimum required parts of arduino_tools (common) from the board's FileSystem (preferrably installed as a module in /lib/arduino_tools)
-- call a method to enter the default app's path and apply some temporary settings to configure the running environment (search paths and launch configuration changes) which will be reset at the next start.
+* import the minimum required parts of arduino_tools (common) from the board's File System (installed as a package in [flash]/lib/arduino_tools)
+* invoke the method `load_app()` to enter the default app's path and apply some temporary settings to configure the running environment (search paths and launch configuration changes) which will be reset at the next start.
 
 If no default app is set, it will fall back to the `main.py` in the board's root if present.
-No error condition will be generated, as MicroPython is capable of handling the absence of `boot.py` and/or `main.py`.
+No error condition will be generated, as MicroPython is capable of handling the absence of `boot.py` and/or `main.py` at C level.
 
-If a default app is set, the `enter_default_app()` will issue an `os.chdir()` command and enter the app's folder.
+If a default app is set, the `load_app()` will issue an `os.chdir()` command and enter the app's folder.
 MicroPython will automatically run the main.py it finds in its Current Working Directory.
 
 **NOTES:**
 
-- each app can contain a `.hidden` file that will hide the app from AMP, effectively preventing listing or deletion.
+* each app can contain a `.hidden` file that will hide the app from AMP, effectively preventing listing or deletion.
 The `list_apps()` command accepts a `skip_hidden = False` parameter to return every app, not just the visible ones.
 
-- each app should contain a metadata file named `app.json`
-  {
-    "name": "",
-    "author": "",
-    "created": 0,
-    "modified": 0,
-    "version": "x.y.z",
-    "origin_url": "",  
-    "tools_version": "x.y.z"
-  }
-- while some fields should be mandatory ("name", "hidden") others could not be a requirement, especially for students apps who do not care about versions or source URL.
-We should also handle if extra fields are added not to break legacy
-
-- AMP can replace/update an app with the content of a `.tar` archive.
-This is useful for updating versions of apps/launcher/demos.
+* each app should contain a metadata file named `app.json`
+
+  ```json
+    {
+      "name": "",
+      "friendly_name": "",
+      "author": "", 
+      "created": 0, 
+      "modified": 0, 
+      "version": "M.m.p", 
+      "origin_url": "https://arduino.cc", 
+      "tools_version": "M.m.p"
+    }
+  ```
+
+* while some fields should be mandatory ("name", "tools_version") others could not be required, especially for students apps who do not care about versions or source URL.
+We should also handle if extra fields are added not to break legacy.
+Still WIP.
+
+* AMP can replace/update an app with the contents of a properly structured `.tar` archive.
+This is useful for updating versions of apps/launcher.
 An app launcher could be delegated to checking for available updates to any of the other apps it manages.
 
 ### How to setup
 
 **NOTE:** The API is not yet final, hence subject to changes.
-Same goes for the name of the module(s)
+Same goes for the name of modules.
 
 The only requirement is that all the files in `arduino_tools` should be transferred to the board using one's preferred method.
-Best practice is to copy all the files in the board's `/lib/arduino_tools`, which is what happens when installing with the `mip` tool.
+Best practice is to copy all the files in the board's `[flash]/lib/arduino_tools`, which is what happens when installing with the `mip` tool (or `mpremote mip`).
 
 Enter a REPL session
 
@@ -101,7 +128,7 @@ Note: creating an app and giving it a name with unallowed characters will replac
 Enable AMP and create a few apps
 
 ```shell
->>> from arduino_tools.app_manager import *
+>>> from arduino_tools.apps_manager import *
 >>> enable_apps()
 
 >>> create_app('abc')
@@ -138,7 +165,7 @@ Type "help()" for more information.
 
 ### Advanced Usage
 
-#### Restore script
+#### Restore script (very experimental)
 
 The restore script allows to have a way of restoring a default app at boot.
 This script may respond to a hardware condition such as a pressed pin in order to set the default app to run.

arduino_tools/__init__.py

@@ -1,5 +1,6 @@
 from .constants import TOOLS_VERSION
 from .loader import *
+from .helpers import show_commands
 __author__ = "Ubi de Feo"
 __credits__ = ["Ubi de Feo", "Sebastian Romero"]
 __license__ = "MPL 2.0"

arduino_tools/app.py

@@ -1,6 +1,7 @@
 from .common import validate_app
 from .loader import enter_app
 from .properties import get_app_properties, update_app_properties
+from .apps_manager import import_app
 import os
 
 class App:
@@ -26,8 +27,10 @@ def save_properties(self):
   def get_path(self):
     return self.get_property('path')
 
-  def update_app(self):
-    self.app_updater = __import__('arduino_tools.updater')
-    updater = __import__('arduino_tools.updater')
-    updater.updater.check_for_updates(self.app_name)
-    
+  def update_app(self, path = None):
+    if path is not None:
+      self.app_updater = __import__('arduino_tools.updater')
+      updater = __import__('arduino_tools.updater')
+      updater.updater.check_for_updates(self.app_name)
+    else:
+      import_app(path)

arduino_tools/apps_manager.py

@@ -92,7 +92,7 @@ def install_package(package = None, app = None, url = None):
 # Managing apps
 
 def create_app(app_name = None, friendly_name = None, set_default = False, hidden = False):
-  a_name = app_name or 'untitled'
+  a_name = app_name or f'py_{tm()}'
   a_name = "".join(c for c in a_name if c.isalpha() or c.isdigit() or c==' ' or c == '_').rstrip()
   a_name = a_name.replace(' ', '_')
   if validate_app(app_name):
@@ -250,7 +250,6 @@ def set_required_app_properties(app_name, **keys):
   if not validate_app(app_name) :
     raise ValueError(f'Invalid app: {app_name}')
 
-
 def list_apps(return_list = False, include_hidden = False):
   apps_list = []
   for app in get_apps():

arduino_tools/boot_apps.tpl

@@ -34,23 +34,23 @@ def validate_app(app_name):
   else:
     return False
 
-def default_app(app = None, fall_back = None):
-  default_app = '' if app == None else app
-  if app != None:
-    if (not validate_app(default_app)) and default_app != '':
-      return(OSError(9, f'Project {default_app} does not exist'))
+def default_app(app_name = None, fall_back = None):
+  default_app_name = '' if app_name == None else app_name
+  if app_name != None:
+    if (not validate_app(default_app_name)) and default_app_name != '':
+      return(OSError(9, f'Project {default_app_name} does not exist'))
     with open(APPS_ROOT + BOOT_CONFIG_FILE, 'w') as a_cfg:
-      a_cfg.write(default_app)
+      a_cfg.write(default_app_name)
       if fall_back != None:
         a_cfg.write('\n')
         a_cfg.write(fall_back)
   else:
     if fs_item_exists(APPS_ROOT + BOOT_CONFIG_FILE):
       with open(APPS_ROOT + BOOT_CONFIG_FILE, 'r') as a_cfg:
-        default_app = a_cfg.readline().strip()
+        default_app_name = a_cfg.readline().strip()
     else:
-      default_app = None
-    return default_app if default_app != None else None
+      default_app_name = ''
+    return default_app_name if default_app_name != '' else None
 
 # more targeted approach
 def get_app(app_name):  

arduino_tools/common.py

@@ -1,11 +1,10 @@
 from time import time as tm
 import os
-
+from .common import get_root
 def get_template_path(file_name):
-  template_path = '/'.join(__file__.split('/')[:-1]) + f'/{file_name}'
+  template_path = get_root().join(__file__.split('/')[:-1]) + f'/templates/{file_name}'
   return template_path
 
-
 def template_to_file(template_name, destination_file, **variables):
   template_path = get_template_path(template_name)
   try:
@@ -20,7 +19,6 @@ def template_to_file(template_name, destination_file, **variables):
     return False, f'{destination_file} not created', e 
   return True, f'{destination_file} created', None
 
-
 ### UNUSED UNTIL EXAMPLES LOADING IS IMPLEMENTED
 def new_file_from_source(file_name = None, destination_path = '.', overwrite = False, source_path = None):
   if file_name is None:

arduino_tools/files.py

@@ -4,13 +4,13 @@ enable_apps():
 disable_apps():
   Disable support for Arduino MicroPython Apps.
 
-create_app('{app name}', set_default = False, hidden = False):
-  Creates a app with the given name. No special characters allowed. Spaces will be converted to '_'
+create_app('{app name}', friendly_name = '{friendly_name}', set_default = False, hidden = False):
+  Creates an app with the given name. No special characters allowed. Spaces will be converted to '_'
   Setting the app as default will make it run at boot/reset.
   Making the app hidden will prevent its listing.
   Useful for launchers and other management utilities not to be messed with.
 
-delete_app([force_confirm = 'n']):
+delete_app('{app_name}', force_confirm = False):
   Deletes the app with the given name.
   If force_confirm is set to 'Y' no confirmation will be required to delete the whole tree.
 
@@ -29,31 +29,97 @@ get_apps_list(include_hidden = False)
   Path, name, default, hidden.
   Hidden apps are excluded by default.
 
-default_app():
-  Displays the app currently set as default (if any)
+default_app(app name = '', fall_back = None):
+  If app name is '' (empty string) or not passed at all, no default will be set.
+  If fall_back is set (and is a valid app based on name), at the next reset/boot that will become the default app to run.
+  When no parameter is passed, the function returns the current default app or `None`
 
-default_app('{app name}', fall_back = None):
-  If app name is '' (empty string), no default will be set.
-  If fall_back is set (and is a valid app), at the next reset/boot that will become the default app to run.
-
-export_app('{app name}'):
+export_app('{app name}') - requires `tarfile-write` to be installed:
   Creates a .tar archive of the app with the given name if valid.
-  The archive file will be named appending a timestamp to the app name.
-  The archive will be saved in '/amp_exports/filename.tar'
+  The archive file will be named appending a timestamp to the app's name.
+  The archive will be saved in '/__ampexports/filename.tar'
 
 import_app('{archive path}', force_overwrite = False):
   Expands the .tar archive into a app folder.
   Requires confirmation if app exists unless force_overwrite is True.
 
-delete_folder('{folder path}', [force_confirm = 'n']):
+delete_folder('{folder path}', [force_confirm = False]):
   Will attempt to delete the folder and all its content recursively.
   If force_confirm is set to True it will not ask for confirmation at each file/folder.
 
-list_directory('{folder path}'):
-  [helper] Will recursively list through the path specified, indicationg if the item is a directory (d:) or a file (f:)
+read_file('{file path}'):
+ Will read the content of the file and output it to REPL
+
+--- WiFi Utilities ---
+
+auto_connect(progress_callback = None):
+  Automatically connects to known networks. Returns True on success.
+  Optional progress_callback function for connection updates.
+
+connect(ssid = None, key = None, interface = None, timeout = 10, display_progress = False, progress_callback = None):
+  Connect to WiFi network. If no params provided, tries auto_connect then interactive mode.
+  Returns network interface on success, None on failure.
+
+connect_to_network(id = None):
+  Interactive WiFi connection. Lists available networks if no id provided.
+  Prompts for password and saves credentials on successful connection.
+
+wifi_scan(force_scan = False):
+  Scans for available WiFi networks. Uses cache unless force_scan=True.
+  Returns list of network tuples (ssid, mac, channel, rssi, security, hidden).
+
+list_networks(rescan = False):
+  Lists available WiFi networks with formatted output.
+  Rescans if rescan=True.
+
+print_scan_results():
+  Pretty prints all scanned networks (or stored one if within `_NETWORK_CACHE_LIFE`)
+
+get_network_qrcode_string(ssid, password, security):
+  Returns QR code string for WiFi network sharing.
+
+print_network_details(interface = _net_if):
+  Prints network connection details (IP, MAC, gateway, etc.).
+  `interface` defaults to `_net_if` which is `None` when not initialised.
+
+--- Access Point Mode ---
+
+init_ap(ssid, key):
+  Initializes device as WiFi Access Point with given credentials.
+
+get_ap_settings():
+  retrieves Access Point configuration
+
+
+--- File System Helpers ---
 
 fs_root():
-  [helper] Will change the current directory to root ('/')
+  Changes current directory to filesystem root ('/').
 
-read_file('{file path}'):
- Will read the content of the file and output it to REPL
+fs_getpath():
+  Returns current working directory path.
+
+print_directory(path = '.'):
+  Prints formatted directory tree structure.
+
+get_directory_tree(path = '.', order = -1):
+  Returns directory tree as list of tuples (depth, path, name, is_folder).
+
+is_directory(path):
+  Returns True if path is a directory, False if file.
+
+--- Console Utilities ---
+
+show_cursor(show = True):
+  Show or hide terminal cursor.
+
+clear_terminal(cursor_visible = True):
+  Clear terminal screen and optionally set cursor visibility.
+
+show_commands():
+  Display this help text in terminal.
+
+--- Hash Utilities ---
+
+get_hash(file_path):
+  Calculate SHA256 hash of file content.