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

micrOS/source/modules/LM_distance.py

@@ -0,0 +1,135 @@
+from machine import Pin, time_pulse_us
+from utime import sleep_us
+from microIO import bind_pin, pinmap_search
+from Common import micro_task
+from Types import resolve
+
+__TRIGGER_OBJ = None
+__ECHO_OBJ = None
+
+
+def __init_HCSR04():
+    """
+    HCSR04 Ultrasonic distance sensor
+    """
+    global __TRIGGER_OBJ, __ECHO_OBJ
+    if __TRIGGER_OBJ is None or __ECHO_OBJ is None:
+        trigger_pin = bind_pin('hcsrtrig')
+        echo_pin = bind_pin('hcsrecho')
+        # Init trigger pin (out)
+        __TRIGGER_OBJ = Pin(trigger_pin, mode=Pin.OUT, pull=None)
+        __TRIGGER_OBJ.value(0)
+        # Init echo pin (in)
+        __ECHO_OBJ = Pin(echo_pin, mode=Pin.IN, pull=None)
+    return __TRIGGER_OBJ, __ECHO_OBJ
+
+
+def __send_pulse_and_wait(echo_timeout_us=1000000):
+    trigger_pin, echo_pin = __init_HCSR04()
+    trigger_pin.value(0) # Stabilize the sensor
+    sleep_us(5)
+    trigger_pin.value(1)
+    # Send a 10us pulse.
+    sleep_us(10)
+    trigger_pin.value(0)
+    try:
+        pulse_time = time_pulse_us(echo_pin, 1, echo_timeout_us)
+        return pulse_time
+    except OSError as ex:
+        if ex.args[0] == 110: # 110 = ETIMEDOUT
+            raise OSError('Out of range')
+        raise ex
+
+
+async def __task(period_ms, dimmer, idle_cm):
+    average = None
+    with micro_task(tag="distance.visual") as my_task:
+        while True:
+            brightness_max_cm = 200
+            brightness_min_cm = 5
+            dist = int(measure_cm()["cm"])
+            if dist > idle_cm+100:
+                await my_task.feed(sleep_ms=50)
+                continue
+            dist = brightness_max_cm if dist > brightness_max_cm else dist   # Limit max
+            dist = 0 if dist < brightness_min_cm else dist                   # Limit min
+            average = dist if average is None else (average + dist) / 2
+            brightness = int(600 * (average/(brightness_max_cm)))
+            if dist >= idle_cm:
+                dimmer(5)
+            else:
+                dimmer(brightness)
+
+            # Store data in task cache (task show mytask)
+            my_task.out = f'Dist: {dist} br: {brightness}'
+            # Async sleep - feed event loop
+            await my_task.feed(sleep_ms=period_ms)
+
+
+def start_dimmer_indicator(idle_distance=180):
+    """Distance visualization on LED brightness (LM_dimmer)"""
+    from LM_dimmer import set_value
+    # [!] ASYNC TASK CREATION [1*] with async task callback + taskID (TAG) handling
+    return micro_task(tag="distance.visual", task=__task(period_ms=200, dimmer=set_value, idle_cm=idle_distance))
+
+
+#########################
+# Application functions #
+#########################
+
+def load():
+    """
+    Initialize HCSR04 ultrasonic distance sensor module
+    """
+    __init_HCSR04()
+    return "HCSR04 Ultrasonic distance sensor - loaded"
+
+
+def measure_mm():
+    """
+    To calculate the distance we get the pulse_time and divide it by 2
+    (the pulse walk the distance twice) and by 29.1 becasue
+    the sound speed on air (343.2 m/s), that It's equivalent to
+    0.34320 mm/us that is 1mm each 2.91us
+    pulse_time // 2 // 2.91 -> pulse_time // 5.82 -> pulse_time * 100 // 582
+    """
+    return {'mm': __send_pulse_and_wait() * 100 // 582}
+
+
+def measure_cm():
+    return {'cm': (__send_pulse_and_wait() / 2) / 29.1}
+
+
+def deinit():
+    global __TRIGGER_OBJ, __ECHO_OBJ
+    trigger_pin, echo_pin = __init_HCSR04()
+    trigger_pin.deinit()
+    echo_pin.deinit()
+    __TRIGGER_OBJ = None
+    __ECHO_OBJ = None
+
+
+#######################
+# LM helper functions #
+#######################
+
+def pinmap():
+    """
+    [i] micrOS LM naming convention
+    Shows logical pins - pin number(s) used by this Load module
+    - info which pins to use for this application
+    :return dict: pin name (str) - pin value (int) pairs
+    """
+    return pinmap_search(['hcsrtrig', 'hcsrecho', 'dimmer'])
+
+
+def help(widgets=False):
+    """
+    [i] micrOS LM naming convention - built-in help message
+    :return tuple:
+        (widgets=False) list of functions implemented by this application
+        (widgets=True) list of widget json for UI generation
+    """
+    return resolve(('measure_mm', 'TEXTBOX measure_cm', 'deinit', 'pinmap',
+                             'load', 'start_dimmer_indicator idle_distance=180',
+                             '[info] HCSR04 Ultrasonic distance sensor'), widgets=widgets)

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

@@ -1,5 +1,6 @@
 import machine, onewire, ds18x20, time
-from microIO import physical_pin, pinmap_dump
+from microIO import bind_pin, pinmap_search
+from Types import resolve
 
 DS_OBJ = None
 
@@ -7,7 +8,7 @@ DS_OBJ = None
 def __init_DS18():
     global DS_OBJ
     if DS_OBJ is None:
-        ds_pin = machine.Pin(physical_pin('ds18'))
+        ds_pin = machine.Pin(bind_pin('ds18'))
         DS_OBJ = ds18x20.DS18X20(onewire.OneWire(ds_pin))
     return DS_OBJ
 
@@ -16,6 +17,13 @@ def __init_DS18():
 # Application functions #
 #########################
 
+def load():
+    """
+    Initialize DS18 temp sensor module
+    """
+    __init_DS18()
+    return "DS18 temp sensor module - loaded"
+
 def measure():
     """
     Measure with digital onewire temperature sensor
@@ -53,7 +61,7 @@ def pinmap():
     - info which pins to use for this application
     :return dict: pin name (str) - pin value (int) pairs
     """
-    return pinmap_dump('ds18')
+    return pinmap_search('ds18')
 
 
 def help(widgets=False):
@@ -63,4 +71,4 @@ def help(widgets=False):
         (widgets=False) list of functions implemented by this application
         (widgets=True) list of widget json for UI generation
     """
-    return 'measure', 'pinmap'
+    return resolve(('TEXTBOX measure', 'load', 'pinmap'), widgets=widgets)

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

@@ -1,4 +1,5 @@
 import esp32
+from Common import syslog
 
 #########################
 # Application functions #
@@ -17,8 +18,19 @@ def temp():
     """
     Measure CPU temperature
     """
+    try:
+        cpu_temp = esp32.mcu_temperature()
+        return {'MCU temp [C]': int(cpu_temp)}
+    except:
+        pass
+    try:
+        raw_temp =  esp32.raw_temperature()
+    except Exception as e:
+        syslog(f"[WARN] cpu temp: {e}")
+        return {'CPU temp [C]': -1.0}
     # read the internal temperature of the MCU, in Farenheit
-    return {'CPU temp [ºC]': '{:.1f}'.format((esp32.raw_temperature() - 32) / 1.8)}
+    cpu_temp = round((raw_temp - 32) / 1.8, 1)
+    return {'CPU temp [C]': cpu_temp}
 
 
 def touch(triglvl=300):
@@ -28,8 +40,8 @@ def touch(triglvl=300):
     :return dict: verdict isTouched and value
     """
     from machine import TouchPad, Pin
-    from microIO import physical_pin
-    t = TouchPad(Pin(physical_pin('touch_0')))
+    from microIO import resolve_pin
+    t = TouchPad(Pin(resolve_pin('touch_0')))
     value = t.read()  # Returns a smaller number when touched
     return {'isTouched': True if value < triglvl else False, 'value': value}
 
@@ -49,7 +61,7 @@ def battery():
 
 def help(widgets=False):
     """
-    [i] micrOS LM naming convention - built-in help message
+    [BETA][i] micrOS LM naming convention - built-in help message
     :return tuple:
         (widgets=False) list of functions implemented by this application
         (widgets=True) list of widget json for UI generation

micrOS/source/modules/LM_espnow.py

@@ -0,0 +1,53 @@
+from Espnow import ESPNowSS
+ESPNOW = ESPNowSS()
+
+
+def send(peer:bytes|str, cmd:str='modules'):
+    """
+    Send message to peer (by mac address)
+    :param peer: mac address of espnow device
+    :param cmd: message string/load module call
+    """
+    return ESPNOW.send(peer, cmd)
+
+def stats():
+    """
+    Get ESPNOW stats
+    """
+    return ESPNOW.stats()
+
+
+def members():
+    """
+    Get ESPNow devices
+    """
+    return ESPNOW.members()
+
+
+def handshake(peer:bytes|str):
+    """
+    Handshake with ESPNow Peer
+    :param peer: mac address of espnow device
+    - device name detection
+    - address:name caching
+    """
+    return ESPNOW.handshake(peer)
+
+
+def remove(peer:bytes):
+    """
+    Remove peer by binary mac address
+    :param peer: binary mac address of espnow device
+    """
+    return ESPNOW.remove_peer(peer)
+
+
+def help():
+    """
+    ESPNOW sender/receiver with LM execution
+    """
+    return ('handshake peer=<mac-address>',
+            'send peer=<peer-name> cmd="hello"',
+            'remove peer=<binary-mac-address>',
+            'stats',
+            'members')

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_gameOfLife.py → modules/LM_gameOfLife.py}

@@ -145,7 +145,7 @@ Custom config usage:
 def my_config(add_cells):
     # custom cells
     cells = ((10,10),(1,0,0),(0,1,1),(0,0,1))
-    load_n_init(w=32, h=16, custom=cells)
+    load(w=32, h=16, custom=cells)
     
     matrix = []
     while matrix is not None:
@@ -153,7 +153,7 @@ def my_config(add_cells):
         print(matrix)
 """
 
-def load_n_init(w=32, h=16, custom=None):
+def load(w=32, h=16, custom=None):
     """
     Init Conway's Game of Life
     :param w: width of display (pixel)
@@ -171,14 +171,14 @@ def load_n_init(w=32, h=16, custom=None):
 def next_gen(raw=False, w=32, h=16):
     """
     Main Game of Life function
-        Get Next Generation of cells (with auto load_n_init and GoL reinit)
+        Get Next Generation of cells (with auto load and GoL reinit)
     :param raw: Output type (raw:True -> matrix), (raw:False formatted output)
     :param w: width of display (pixel) - auto init
     :param h: height of display (pixel) - auto init
     return change of life matrix or None if there is no change (on None, restart feature: call reset())
     """
     if GoL.GOL is None:
-        load_n_init(w=w, h=h)
+        load(w=w, h=h)
     matrix = GoL.GOL.next_gen()
     if raw:
         return matrix               # Matrix / None (no change)
@@ -205,4 +205,4 @@ def help(widgets=False):
         (widgets=False) list of functions implemented by this application
         (widgets=True) list of widget json for UI generation
     """
-    return 'load_n_init w=32 h=16 custom=None', 'next_gen w=32 h=16 raw=False', 'reset'
+    return 'load w=32 h=16 custom=None', 'next_gen w=32 h=16 raw=False', 'reset'