micrOSDevToolKit 2.9.1__py3-none-any.whl → 2.26.1__py3-none-any.whl

micrOS/source/modules/LM_fileserver.py

@@ -0,0 +1,265 @@
+"""
+micrOS Fileserver addon for WebEngine
+"""
+
+from json import dumps
+from re import compile as recompile
+from uos import stat, rename, mkdir, statvfs
+
+from Common import web_endpoint, web_mounts, web_dir, syslog
+from Files import path_join, is_dir, remove_dir, remove_file, OSPath, abs_path, ilist_fs
+from Web import url_path_resolve
+from Auth import sudo
+
+
+class Shared:
+    ROOT_DIR = web_dir("user_data")         # Default Public WEB dir
+    TMP_DIR = path_join(ROOT_DIR, "tmp")    # Temporary directory for partial uploads
+    UPLOAD_COUNTER = 0                      # Counter for handling partial uploads
+    MOUNTS_WRITE_ACCESS = {"$modules": False, "$data": False, "$logs": False}
+    # mpy: code bytestream
+    HIDE_FEXT = ("mpy",)                    # Hide / Protect (delete/upload) files with the listed extensions
+
+    @staticmethod
+    def check_write_access(path):
+        """
+        Raw input path mount write access checker
+        """
+        if "$" in path:
+            # Mount alias in path
+            for access in Shared.MOUNTS_WRITE_ACCESS:
+                if access in path:
+                    if Shared.MOUNTS_WRITE_ACCESS[access]:
+                        return      # Writeable
+                    raise ValueError(f'ReadOnly path: {path}')
+        else:
+            # No mount alias in path
+            return      # Writeable
+        raise ValueError(f'ReadOnly path: {path}')
+
+
+#############################################
+#           Web Endpoint Callbacks          #
+#############################################
+
+def _list_file_paths_clb(root_dir=None):
+    """
+    List files shared path
+    """
+    if isinstance(root_dir, bytes)and len(root_dir.strip()) > 0:
+        # Decode input path from request body
+        root_dir = root_dir.decode("ascii")
+    else:
+        root_dir = Shared.ROOT_DIR
+
+    # Resolve and Validate path (mount aliases)
+    try:
+        root_dir = resolve_path(root_dir.replace(web_dir(), ""))
+    except Exception as e:
+        return "text/plain", str(e)
+
+    user_data = []
+    # Show file content on selected root_dir
+    # Hide: .mpy files (non-readable/non-editable)
+    for name in (f for f in ilist_fs(path=root_dir, type_filter='f') if f.split(".")[-1] not in Shared.HIDE_FEXT):
+        file_path = path_join(root_dir, name)
+        user_data.append(file_path)
+
+    response = [
+        {
+            'path': file_path.replace(web_dir(),""),
+            'size': stat(file_path)[6],
+            'created': stat(file_path)[9]
+        }
+        for file_path in user_data
+    ]
+    return 'application/json', dumps(response)
+
+
+def _delete_file_clb(file_to_delete: bytes):
+    file_to_delete = file_to_delete.decode('ascii')
+    Shared.check_write_access(file_to_delete)
+    filepath = resolve_path(file_to_delete)
+    if is_dir(filepath):
+        raise ValueError(f'File does not exist: {filepath}')
+    # File name extension based delete protection
+    if filepath.split(".")[-1] in Shared.HIDE_FEXT:
+        raise ValueError(f'Delete access denied: {filepath}')
+    verdict = remove_file(filepath)
+    return 'text/plain', verdict
+
+
+def _upload_file_clb(part_headers: dict, part_body: bytes, first=False, last=False):
+    """
+    Callback function for handling file uploads (Content-Type: multipart/form-data)
+    This callback is invoked on every part.
+    """
+    cd = part_headers.get('content-disposition', '')
+    target_filepath = None
+    filename = ""
+    cd_pattern = recompile(r'filename\*?=(?:"([^"]+)"|([^;]+))')
+
+    if match := cd_pattern.search(cd):
+        filepath = match.group(1) or match.group(2)
+        filepath = filepath.strip()
+        # Reject UTF-8 and percent-encoded UTF-8 filenames (RFC 8187)
+        if filepath.lower().startswith("utf-8'"):
+            raise ValueError("Percent encoded filenames are not supported")
+        Shared.check_write_access(filepath)
+        target_filepath = resolve_path(filepath)
+        filename = target_filepath.split("/")[-1]
+
+    # File name extension based upload protection
+    if not filename or filename.split(".")[-1] in Shared.HIDE_FEXT:
+        raise ValueError(f"Invalid filename in part headers: {filename}")
+    target_parts = target_filepath.strip("/").split("/")
+    if len(target_parts) == 2 and target_parts[-2] == "web":
+        # Write protected /web root -> redirect to user shared dir
+        target_filepath = path_join(Shared.ROOT_DIR, filename)
+
+    if first:
+        Shared.UPLOAD_COUNTER += 1
+
+    if first and last:
+        with open(target_filepath, 'wb') as f:
+            f.write(part_body)
+    elif first and not last:
+        tmp_file_path = path_join(Shared.TMP_DIR, f"{filename}.{Shared.UPLOAD_COUNTER}")
+        with open(tmp_file_path, 'wb') as f:
+            f.write(part_body)
+    else:
+        tmp_file_path = path_join(Shared.TMP_DIR, f"{filename}.{Shared.UPLOAD_COUNTER}")
+        with open(tmp_file_path, 'ab') as f:
+            f.write(part_body)
+        if last:
+            rename(tmp_file_path, target_filepath)
+
+    return 'text/plain', 'ok'
+
+
+def _disk_usage_clb():
+    """
+    Calculate disk usage
+    return {'used': <bytes used>, 'free': <bytes free>}
+    """
+    # Check root dir usage
+    fs_stat = statvfs(OSPath._ROOT)
+    fs_free = fs_stat[0] * fs_stat[3]
+    fs_size = fs_stat[0] * fs_stat[2]
+    used = fs_size - fs_free
+    return 'application/json', dumps({'used': used, 'free': fs_free})
+
+
+#############################################
+#              Public functions             #
+#############################################
+
+def load(web_data_dir:str=None):
+    """
+    Initialize fileserver.
+    :param web_data_dir: web data public directory (default: /web/<user_data>)
+    """
+    if isinstance(web_data_dir, str):
+        # Customize public web dir name
+        Shared.ROOT_DIR = web_dir(web_data_dir)
+        Shared.TMP_DIR = path_join(Shared.ROOT_DIR, 'tmp')
+    if is_dir(Shared.TMP_DIR):
+        remove_dir(Shared.TMP_DIR, force=True) # Clean existing partial uploads, is force needed?
+    if not is_dir(Shared.ROOT_DIR):
+        root_dir = web_dir()
+        base_dir = root_dir
+        for subdir in Shared.TMP_DIR.replace(root_dir, "").split('/'):
+            current_dir = path_join(base_dir, subdir)
+            if not is_dir(current_dir):
+                mkdir(current_dir)
+            base_dir = current_dir
+
+    # Register endpoints
+    #   [GET] List shared directories
+    web_endpoint('fs/dirs', lambda: ('application/json', dumps(get_shared_dirs())))
+    #   [GET] List help message
+    web_endpoint('fs/list', lambda: ('text/plain', 'USE THIS AS POST Endpoint, select dir in http body'))
+    #   [POST] List selected directory content
+    web_endpoint('fs/list', _list_file_paths_clb, 'POST')
+    #   [GET] Files - list user files
+    web_endpoint('fs/files', _list_file_paths_clb)
+    #   [DELETE] Files - delete selected file
+    web_endpoint('fs/files', _delete_file_clb, 'DELETE')
+    #   [POST] Upload file to the selected path (in filename)
+    web_endpoint('fs/files', _upload_file_clb, 'POST')
+    #   [GET] Show internal flash storage usage
+    web_endpoint('fs/usage', _disk_usage_clb)
+    #   [GET] Fileserver homepage UI
+    web_endpoint('fs', 'filesui.html')
+
+    return "Fileserver was initialized, endpoints: /fs, /fs/files, /fs/dirs, /fs/usage"
+
+
+def resolve_path(path):
+    """
+    Resolve and Validate input path
+    :param path: URL resource path or mount path string
+    """
+    # Path resolve and validation
+    path = abs_path(path)
+    err, path = url_path_resolve(path)
+    if err:
+        raise ValueError(f"Invalid path: {path}")
+    filename = path.split("/")[-1]
+    # Filename validation
+    filename_pattern = recompile(r"^[a-zA-Z0-9._-]+$")
+    if not filename_pattern.match(filename):
+        raise ValueError(f"Filename contains invalid characters: {path}")
+    return path
+
+
+def get_shared_dirs() -> list:
+    """
+    Getter for web shared dirs
+    - default: /web/Shared.ROOT_DIR
+    - extended: web_mounts()
+    """
+    web_dirs = list([a for a, p in web_mounts().items() if p is not None])
+    web_dirs.insert(0, Shared.ROOT_DIR.replace(web_dir(), ""))
+    return web_dirs
+
+
+def get_user_dir():
+    """
+    Getter for user configured shared dir
+    - used by other load modules
+    """
+    return Shared.ROOT_DIR
+
+
+def extend_mounts(modules:bool=None, data:bool=None, logs:bool=None):
+    """
+    Extend web engine shared root path list
+    :param modules: add/remove /modules to web shared path
+    :param data: add/remove /data to web shared path
+    :param logs: add/remove /logs web shared path
+    """
+    return web_mounts(modules, data, logs)
+
+
+@sudo
+def mounts_write_access(modules:bool=None, data:bool=None, logs:bool=None):
+    if modules is not None:
+        Shared.MOUNTS_WRITE_ACCESS["$modules"] = modules
+    if data is not None:
+        Shared.MOUNTS_WRITE_ACCESS["$data"] = data
+    if logs is not None:
+        Shared.MOUNTS_WRITE_ACCESS["$logs"] = logs
+    return Shared.MOUNTS_WRITE_ACCESS
+
+#######################
+# Helper LM functions #
+#######################
+
+def help(widgets=False):
+    return (f'load web_data_dir=<shared directory under {web_dir()}>',
+            'resolve_path "<str>"',
+            'get_shared_dirs',
+            'get_user_dir',
+            'extend_mounts modules:bool=None data:bool=None logs:bool=None',
+            'mounts_write_access modules:bool=None data:bool=None logs:bool=None')

micrOS/source/{LM_genIO.py → modules/LM_genIO.py}

@@ -1,5 +1,5 @@
 from machine import Pin, PWM
-from microIO import resolve_pin, register_pin, PinMap
+from microIO import bind_pin, PinMap
 from Common import SmartADC
 from random import randint
 
@@ -10,15 +10,25 @@ from random import randint
 
 class IObjects:
     PIN_OBJS = {}
+    DENY_TAG_INPUT = True
 
     @staticmethod
-    def store_obj(pin, obj):
+    def store_obj(pin:int, obj:object) -> None:
         IObjects.PIN_OBJS[pin] = obj
 
     @staticmethod
-    def get_obj(pin):
+    def get_obj(pin:int) -> object:
         return IObjects.PIN_OBJS[pin]
 
+    @staticmethod
+    def is_unassigned(pin_number):
+        return IObjects.PIN_OBJS.get(pin_number, None) is None
+
+    @staticmethod
+    def protect_builtins(pin_num, tag):
+        if pin_num is None and IObjects.DENY_TAG_INPUT:
+            raise Exception(f"pin must be integer not {type(tag)}: {tag}")
+
 
 ##################################
 #     INTERNAL INIT FUNCTIONS    #
@@ -28,48 +38,39 @@ def __digital_out_init(pin):
     """
     Init Digital output
     """
-    if not isinstance(pin, int):
-        pin = resolve_pin(pin)
-
-    # Register pin in microIO (drops exception if pin already booked)
-    pin_tag = f"OUT{pin}"
-    if PinMap.IO_USE_DICT.get(pin_tag, None) is None:
-        pin = register_pin(pin_tag, pin)
-        pin_obj = Pin(pin, Pin.OUT)
-        IObjects.store_obj(pin, pin_obj)
-    return IObjects.get_obj(pin)
+    pin_tag, pin = (pin, None) if isinstance(pin, str) else (f"OUT{pin}", pin)
+    IObjects.protect_builtins(pin, pin_tag)
+    pin_num = bind_pin(pin_tag, pin)
+    if IObjects.is_unassigned(pin_number=pin_num):
+        pin_obj = Pin(pin_num, Pin.OUT)
+        IObjects.store_obj(pin_num, pin_obj)
+    return IObjects.get_obj(pin_num)
 
 
 def __digital_in_init(pin):
     """
     Init Digital output
     """
-    if not isinstance(pin, int):
-        pin = resolve_pin(pin)
-
-    # Register pin in microIO (drops exception if pin already booked)
-    pin_tag = f"IN{pin}"
-    if PinMap.IO_USE_DICT.get(pin_tag, None) is None:
-        pin = register_pin(pin_tag, pin)
-        pin_obj = Pin(pin, Pin.IN, Pin.PULL_UP)
-        IObjects.store_obj(pin, pin_obj)
-    return IObjects.get_obj(pin)
+    pin_tag, pin = (pin, None) if isinstance(pin, str) else (f"IN{pin}", pin)
+    IObjects.protect_builtins(pin, pin_tag)
+    pin_num = bind_pin(pin_tag, pin)
+    if IObjects.is_unassigned(pin_number=pin_num):
+        pin_obj = Pin(pin_num, Pin.IN, Pin.PULL_UP)
+        IObjects.store_obj(pin_num, pin_obj)
+    return IObjects.get_obj(pin_num)
 
 
 def __pwm_init(pin, freq):
     """
     Init PWM signal
     """
-    if not isinstance(pin, int):
-        pin = resolve_pin(pin)
-
-    # Register pin in microIO (drops exception if pin already booked)
-    pin_tag = f"PWM{pin}"
-    if PinMap.IO_USE_DICT.get(pin_tag, None) is None:
-        pin = register_pin(pin_tag, pin)
-        pin_obj = PWM(Pin(pin), freq=freq)
-        IObjects.store_obj(pin, pin_obj)
-    return IObjects.get_obj(pin)
+    pin_tag, pin = (pin, None) if isinstance(pin, str) else (f"PWM{pin}", pin)
+    IObjects.protect_builtins(pin, pin_tag)
+    pin_num = bind_pin(pin_tag, pin)
+    if IObjects.is_unassigned(pin_number=pin_num):
+        pin_obj = PWM(Pin(pin_num), freq=freq)
+        IObjects.store_obj(pin_num, pin_obj)
+    return IObjects.get_obj(pin_num)
 
 
 ##################################
@@ -121,9 +122,9 @@ def get_adc(pin, key=None):
     :param key: select adc parameter by key
     :return dict: adc volt, percent, raw
     """
-    if isinstance(pin, int):
-        pin_tag = f"ADC{pin}"
-        pin = register_pin(pin_tag, pin)
+    pin_tag, pin = (pin, None) if isinstance(pin, str) else (f"ADC{pin}", pin)
+    IObjects.protect_builtins(pin, pin_tag)
+    pin = bind_pin(pin_tag, pin)
     data = SmartADC.get_instance(pin).get()
     data["pin"] = pin
     if key is None:
@@ -140,6 +141,19 @@ def get_in(pin):
     return {'pin': pin, 'state': __digital_in_init(pin).value()}
 
 
+def load(allow_tags=False):
+    """
+    Optional load function to set
+    tag input besides pin numbers.
+    [WARNING] allow_tag=True can be dangerous
+    - it can overwrite existing I/O based on
+    the provided tag
+    :param allow_tag: default False
+    """
+    IObjects.DENY_TAG_INPUT = not allow_tags
+    return "[WARNING] allow_tag=True can be dangerous, use it consciously!!!" if allow_tags else "Loaded"
+
+
 #######################
 # LM helper functions #
 #######################
@@ -155,4 +169,5 @@ def help(widgets=False):
            'set_random_pwm pin min_duty max_duty freq=20480)',\
            'set_out pin=<int> state=<None/True/False>',\
            'get_adc pin key=None',\
-           'get_in pin'
+           'get_in pin',\
+           'load allow_tags=False'

micrOS/source/{LM_haptic.py → modules/LM_haptic.py}

@@ -1,4 +1,4 @@
-from microIO import resolve_pin, pinmap_search
+from microIO import bind_pin, pinmap_search
 from Types import resolve
 from machine import Pin, PWM
 from utime import sleep_ms
@@ -18,7 +18,7 @@ def load(intensity=None):
     :param intensity: low / high / None haptic feedback intensity
     """
     if Haptic.HAPTIC_OBJ is None:
-        dimmer_pin = Pin(resolve_pin('haptic'))
+        dimmer_pin = Pin(bind_pin('haptic'))
         Haptic.HAPTIC_OBJ = PWM(dimmer_pin, freq=20480)
         Haptic.HAPTIC_OBJ.duty(0)
     if intensity in ("high", "low"):

{toolkit/workspace/precompiled → micrOS/source/modules}/LM_i2c.py

@@ -1,4 +1,4 @@
-from microIO import resolve_pin, pinmap_search
+from microIO import bind_pin, pinmap_search
 
 __I2C = None
 
@@ -7,7 +7,7 @@ def __init():
     global __I2C
     if __I2C is None:
         from machine import Pin, I2C
-        __I2C = I2C(-1, Pin(resolve_pin('i2c_scl')), Pin(resolve_pin('i2c_sda')))
+        __I2C = I2C(-1, Pin(bind_pin('i2c_scl')), Pin(bind_pin('i2c_sda')))
     return __I2C
 
 
@@ -24,8 +24,9 @@ def discover():
     """
     Discover devices
     """
-    known_addresses = {hex(0x0A): "trackball", hex(0x3c): "oled",
-                       hex(0x76): "bme280", hex(0x10): 'veml7700'}
+    known_addresses = {hex(0x0A): "TRACKBALL", hex(0x3c): "OLED",
+                       hex(0x76): "BME280", hex(0x10): 'VEML7700',
+                       hex(0x6b): "QMI8658", hex(0x29): 'TCS3472'}
     devices = scan()
     output = {"unknown": []}
     for k in devices:

micrOS/source/{LM_i2s_mic.py → modules/LM_i2s_mic.py}

@@ -1,14 +1,14 @@
 from ustruct import unpack
-from microIO import resolve_pin, pinmap_search
+from microIO import bind_pin, pinmap_search
 from Common import micro_task, web_endpoint, manage_task
 from machine import I2S, Pin
 import uasyncio as asyncio
 
 
 class Data:
-    SCK_PIN = Pin(resolve_pin('i2s_sck'))  # Serial clock
-    WS_PIN = Pin(resolve_pin('i2s_ws'))    # Word select
-    SD_PIN = Pin(resolve_pin('i2s_sd'))    # Serial data
+    SCK_PIN = Pin(bind_pin('i2s_sck'))  # Serial clock
+    WS_PIN = Pin(bind_pin('i2s_ws'))    # Word select
+    SD_PIN = Pin(bind_pin('i2s_sd'))    # Serial data
     I2S_CHANNEL = 1
     FORMAT = I2S.STEREO
     SAMPLING_RATE = 8000
@@ -94,8 +94,7 @@ def background_capture():
     if not Data.MIC_ENABLED:
         return "Microphone is disabled"
 
-    state = micro_task(tag=Data.TASK_TAG, task=__task(ms_period=1))
-    return "Starting" if state else "Already running"
+    return micro_task(tag=Data.TASK_TAG, task=__task(ms_period=1))
 
 
 def get_from_buffer(capture_duration=Data.CAPTURE_DURATION,
@@ -276,7 +275,7 @@ def load(buf_length=Data.BUF_LENGTH, sampling_rate=Data.SAMPLING_RATE,
     
     if control_button:
         micro_task(tag=Data.CONTROL_TASK_TAG, task=__control_task())
-        Data.CONTROL_BUTTON_PIN = Pin(resolve_pin(control_button), Pin.IN)
+        Data.CONTROL_BUTTON_PIN = Pin(bind_pin(control_button), Pin.IN)
 
     Data.BUF_LENGTH = buf_length
     Data.SAMPLING_RATE = sampling_rate

micrOS/source/{LM_ld2410.py → modules/LM_ld2410.py}

@@ -17,9 +17,9 @@
 
 from machine import Pin, UART
 import utime
-from microIO import resolve_pin, pinmap_search
+from microIO import bind_pin, pinmap_search
 
-ser = UART(1, baudrate = 256000, tx=Pin(resolve_pin('tx')), rx=Pin(resolve_pin('rx')), timeout = 1)
+ser = UART(1, baudrate = 256000, tx=Pin(bind_pin('tx')), rx=Pin(bind_pin('rx')), timeout = 1)
 HEADER = bytes([0xfd, 0xfc, 0xfb, 0xfa])
 TERMINATOR = bytes([0x04, 0x03, 0x02, 0x01])
 NULLDATA = bytes([])

micrOS/source/{LM_light_sensor.py → modules/LM_light_sensor.py}

@@ -5,13 +5,9 @@ ADC.ATTN_2_5DB — the full range voltage: 1.5V
 ADC.ATTN_6DB — the full range voltage: 2.0V
 ADC.ATTN_11DB — the full range voltage: 3.3V
 """
-from Common import SmartADC, micro_task
+from Common import SmartADC, micro_task, exec_cmd
 from Types import resolve
-try:
-    import LM_intercon as InterCon
-except:
-    InterCon = None
-from microIO import resolve_pin, pinmap_search
+from microIO import bind_pin, pinmap_search
 
 
 ADC = None
@@ -23,7 +19,7 @@ def __init_tempt6000():
     """
     global ADC
     if ADC is None:
-        ADC = SmartADC(resolve_pin('temp6000'))
+        ADC = SmartADC(bind_pin('temp6000'))
     return ADC
 
 
@@ -76,19 +72,15 @@ async def _task(on, off, threshold, tolerance=2, check_ms=5000):
             # TURN ON
             if percent <= threshold:
                 if on != last_ev:
-                    if InterCon is not None:
-                        host = on[0]
-                        cmd = ' '.join(on[1:])
-                        InterCon.send_cmd(host, cmd)
-                    my_task.out = f"{percent}% <= threshold: {threshold}% - ON"
+                    host = on[0]
+                    state, _ = exec_cmd(on[1:] + [f">>{host}"], jsonify=True)
+                    my_task.out = f"{percent}% <= threshold: {threshold}% - ON [{'OK' if state else 'NOK'}]"
                     last_ev = on
             elif percent > threshold+tolerance:     # +tolerance to avoid "on/off/on/off" on threshold limit
                 if off != last_ev:
-                    if InterCon is not None:
-                        host = off[0]
-                        cmd = ' '.join(off[1:])
-                        InterCon.send_cmd(host, cmd)
-                    my_task.out = f"{percent}% > threshold: {threshold+tolerance}% - OFF"
+                    host = off[0]
+                    state, _ = exec_cmd(off[1:] + [f">>{host}"], jsonify=True)
+                    my_task.out = f"{percent}% > threshold: {threshold+tolerance}% - OFF [{'OK' if state else 'NOK'}]"
                     last_ev = off
             await my_task.feed(sleep_ms=check_ms)   # Sample every <check_ms> sec
 
@@ -104,11 +96,8 @@ def subscribe_intercon(on, off, threshold=4, tolerance=2, sample_sec=60):
     """
     # Start play - servo XY in async task
     # [!] ASYNC TASK CREATION [1*] with async task callback + taskID (TAG) handling
-    state = micro_task(tag="light_sensor.intercon", task=_task(on, off, threshold, tolerance=tolerance,
+    return micro_task(tag="light_sensor.intercon", task=_task(on, off, threshold, tolerance=tolerance,
                                                                check_ms=sample_sec*1000))
-    if state:
-        return 'Light sensor remote trigger starts'
-    return 'Light sensor remote trigger - already running'
 
 
 #######################