replx 1.22.2__tar.gz → 1.30.3__tar.gz

{replx-1.22.2/replx.egg-info → replx-1.30.3}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: replx
-Version: 1.22.2
+Version: 1.30.3
 Summary: replx is a fast, modern MicroPython CLI: turbo REPL, robust file sync (put/get), project install, mpy-cross integration, and smart port discovery.
 Author-email: "chanmin.park" <devcamp@planxlab.com>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/PlanXLab/replx
+Project-URL: Homepage, https://planxlab.com
 Project-URL: Repository, https://github.com/PlanXLab/replx
 Project-URL: Issues, https://github.com/PlanXLab/replx/issues
 Keywords: micropython,repl,serial,pyserial,typer,mpy-cross,deploy,gpio,i2c,spi,uart,pwm,adc,i2s,ws2812
@@ -17,12 +17,13 @@ Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB)
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: click>=8.4.2
-Requires-Dist: typer>=0.27.0
-Requires-Dist: rich>=13.0
+Requires-Dist: click>=8.5.0
+Requires-Dist: typer>=0.27.3
+Requires-Dist: rich>=15.0.0
 Requires-Dist: pyserial>=3.5
-Requires-Dist: mpy-cross>=1.27.0
+Requires-Dist: mpy-cross>=1.29.0
 Requires-Dist: psutil>=7.2.2
+Requires-Dist: esptool<6,>=5.6.0
 Dynamic: license-file
 
 # replx
@@ -33,6 +34,8 @@ Dynamic: license-file
 
 `replx` is a CLI tool for MicroPython development. It uses a single local agent process to manage multiple CLI sessions and multiple boards in a consistent workflow.
 
+It runs on Windows, macOS, and Linux and targets standard MicroPython 1.29 or newer, with a separate source-based legacy compatibility path for Digi XBee3 Zigbee. Hardware commands are platform-dependent; see the detailed manual's board compatibility table. Actual board testing has been completed on Raspberry Pi Pico 2 W and Waveshare ESP32-P4-WIFI6; Digi XBee3 compatibility still requires physical board validation.
+
 ## What replx provides
 
 - Shared connection management across terminal sessions
@@ -59,6 +62,7 @@ pip install replx
 - `whoami`: Show the current foreground device.
 - `disconnect`: Close a device connection.
 - `shutdown`: Stop the agent and clear active sessions.
+- `theme`: Show or customize UI panel colors and box style.
 
 ### Execution and interaction
 
@@ -77,7 +81,7 @@ pip install replx
 - `mv`: Move or rename files or directories on device.
 - `rm`: Remove files or directories on device.
 - `mkdir`: Create directories on device.
-- `touch`: Create an empty file or update timestamps.
+- `touch`: Create a file if missing; preserve existing contents.
 
 ### Device management
 
@@ -101,6 +105,8 @@ pip install replx
 - `uart`: Open, write, read, and monitor UART.
 - `spi`: Open, write, read, and transfer SPI data.
 - `i2c`: Scan, read, write, and dump I2C devices.
+- `i2s`: Play I2S tones and capture or monitor an I2S microphone.
+- `ws2812`: Write pixels and regions on WS2812 LED matrices.
 
 ### Connectivity
 

{replx-1.22.2 → replx-1.30.3}/README.md

@@ -6,6 +6,8 @@
 
 `replx` is a CLI tool for MicroPython development. It uses a single local agent process to manage multiple CLI sessions and multiple boards in a consistent workflow.
 
+It runs on Windows, macOS, and Linux and targets standard MicroPython 1.29 or newer, with a separate source-based legacy compatibility path for Digi XBee3 Zigbee. Hardware commands are platform-dependent; see the detailed manual's board compatibility table. Actual board testing has been completed on Raspberry Pi Pico 2 W and Waveshare ESP32-P4-WIFI6; Digi XBee3 compatibility still requires physical board validation.
+
 ## What replx provides
 
 - Shared connection management across terminal sessions
@@ -32,6 +34,7 @@ pip install replx
 - `whoami`: Show the current foreground device.
 - `disconnect`: Close a device connection.
 - `shutdown`: Stop the agent and clear active sessions.
+- `theme`: Show or customize UI panel colors and box style.
 
 ### Execution and interaction
 
@@ -50,7 +53,7 @@ pip install replx
 - `mv`: Move or rename files or directories on device.
 - `rm`: Remove files or directories on device.
 - `mkdir`: Create directories on device.
-- `touch`: Create an empty file or update timestamps.
+- `touch`: Create a file if missing; preserve existing contents.
 
 ### Device management
 
@@ -74,6 +77,8 @@ pip install replx
 - `uart`: Open, write, read, and monitor UART.
 - `spi`: Open, write, read, and transfer SPI data.
 - `i2c`: Scan, read, write, and dump I2C devices.
+- `i2s`: Play I2S tones and capture or monitor an I2S microphone.
+- `ws2812`: Write pixels and regions on WS2812 LED matrices.
 
 ### Connectivity
 

{replx-1.22.2 → replx-1.30.3}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=70", "wheel"]
+requires = ["setuptools>=77.0.3"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -23,18 +23,17 @@ classifiers = [
 ]
 
 dependencies = [
-  "click>=8.4.2",
-  "typer>=0.27.0",
-  "rich>=13.0",
+  "click>=8.5.0",
+  "typer>=0.27.3",
+  "rich>=15.0.0",
   "pyserial>=3.5",
-  "mpy-cross>=1.27.0",
+  "mpy-cross>=1.29.0",
   "psutil>=7.2.2",
+  "esptool>=5.6.0,<6",
 ]
 
-[project.optional-dependencies]
-
 [project.urls]
-Homepage = "https://github.com/PlanXLab/replx"
+Homepage = "https://planxlab.com"
 Repository = "https://github.com/PlanXLab/replx"
 Issues = "https://github.com/PlanXLab/replx/issues"
 

{replx-1.22.2 → replx-1.30.3}/replx/__init__.py

@@ -1,5 +1,5 @@
 __all__ = ["__version__", "get_version", "__description__"]
-__version__ = "1.22.2"
+__version__ = "1.30.3"
 __description__ = "Fast, modern MicroPython CLI with REPL, file sync, install, and smart port detection."
 __author__ = "PlanX Lab Development Team"
 
@@ -8,4 +8,4 @@ def get_version() -> str:
         from importlib.metadata import version as _v  # Python 3.10+
         return _v("replx")
     except Exception:
-        return __version__
+        return __version__

{replx-1.22.2 → replx-1.30.3}/replx/cli/agent/__init__.py

@@ -1,6 +1,7 @@
 
+from importlib import import_module
+
 from .protocol import AgentProtocol
-from .client import AgentClient, get_session_id, get_cached_session_id, clear_session_cache
 
 __all__ = [
     'AgentProtocol',
@@ -14,8 +15,14 @@ __all__ = [
 
 
 def __getattr__(name):
-    # The server stack pulls in ``replx.terminal`` (~150ms) plus all command
-    # handlers; CLI clients never need it. Defer until something actually asks.
+    if name in {
+        'AgentClient',
+        'get_session_id',
+        'get_cached_session_id',
+        'clear_session_cache',
+    }:
+        return getattr(import_module('.client', __name__), name)
+
     if name == 'AgentServer':
         from .server import AgentServer
 

{replx-1.22.2 → replx-1.30.3}/replx/cli/agent/client/core.py

@@ -26,14 +26,14 @@ class AgentClient:
 
         self._ppid = get_cached_session_id()
         self._atexit_registered = False
+        # Set only when Ctrl+C interrupts a request the agent may still be
+        # executing. A normal CLI exit must keep the agent's board connection.
+        self._release_on_exit = False
 
     def connect(self):
         if not self.sock:
             self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
             self.sock.settimeout(self.TIMEOUT)
-        # M7: ensure the agent releases the device port if the CLI process
-        # exits abnormally (Ctrl-C, unhandled exception, parent terminated)
-        # without its normal teardown path running.
         if not self._atexit_registered and self.device_port:
             try:
                 atexit.register(self._atexit_release)
@@ -43,9 +43,8 @@ class AgentClient:
 
     def _atexit_release(self) -> None:
         try:
-            if self.sock is None:
-                return
-            self._release_device_port_safe()
+            self._release_on_exit = False
+            self.disconnect()
         except Exception:
             pass
 
@@ -92,8 +91,22 @@ class AgentClient:
         except Exception:
             pass
 
+    @staticmethod
+    def _print_notifications(response: Dict[str, Any]) -> None:
+        for notification in response.get('notifications', ()):
+            if notification:
+                print(f"replx: {notification}", file=sys.stderr)
+
     def send_command(self, command: str, timeout: float = None, max_retries: int = None,
                      wait_on_busy: float = 30.0, **args) -> Dict[str, Any]:
+        try:
+            return self._send_command(command, timeout, max_retries, wait_on_busy, **args)
+        except KeyboardInterrupt:
+            self._release_on_exit = True
+            raise
+
+    def _send_command(self, command: str, timeout: float = None, max_retries: int = None,
+                      wait_on_busy: float = 30.0, **args) -> Dict[str, Any]:
         if not self.sock:
             self.connect()
 
@@ -161,6 +174,7 @@ class AgentClient:
             if not response:
                 raise RuntimeError("No response from agent")
 
+            self._print_notifications(response)
             error = response.get('error', '')
 
             # Retry only for transient "Another command" busy — not REPL/detached.
@@ -178,7 +192,8 @@ class AgentClient:
                         output_callback: Callable[[bytes, str], None] = None,
                         input_provider: Callable[[], Optional[bytes]] = None,
                         stop_check: Callable[[], bool] = None,
-                        ctrl_c_grace_s: float = 3.0) -> Dict[str, Any]:
+                        ctrl_c_grace_s: float = 3.0,
+                        reset: bool = True) -> Dict[str, Any]:
         if not self.sock:
             self.connect()
 
@@ -191,7 +206,8 @@ class AgentClient:
             port=self.device_port,
             script_path=script_path,
             script_content=script_content,
-            echo=echo
+            echo=echo,
+            reset=reset,
         )
         seq = request['seq']
         request_data = AgentProtocol.encode_message(request)
@@ -324,9 +340,10 @@ class AgentClient:
 
                 # Check for stream reception timeout (connection loss detection)
                 if now - last_stream_time > stream_timeout:
-                    # Release the device port on the agent so subsequent
-                    # commands don't operate on a stale serial connection.
-                    self._release_device_port_safe()
+                    try:
+                        self.send_command(Cmd.RUN_STOP, timeout=1.0)
+                    except Exception:
+                        pass
                     raise RuntimeError("Connection lost - no data from board for {}s".format(stream_timeout))
 
                 if now - last_input_time >= input_interval:
@@ -394,6 +411,15 @@ class AgentClient:
     def send_command_streaming(self, command: str, timeout: float = None,
                                 progress_callback: Callable[[Dict[str, Any]], None] = None,
                                 **args) -> Dict[str, Any]:
+        try:
+            return self._send_command_streaming(command, timeout, progress_callback, **args)
+        except KeyboardInterrupt:
+            self._release_on_exit = True
+            raise
+
+    def _send_command_streaming(self, command: str, timeout: float = None,
+                                progress_callback: Callable[[Dict[str, Any]], None] = None,
+                                **args) -> Dict[str, Any]:
         if not self.sock:
             self.connect()
 
@@ -458,6 +484,7 @@ class AgentClient:
         if not response:
             raise RuntimeError("No response from agent (timeout)")
 
+        self._print_notifications(response)
         if response.get('error'):
             raise RuntimeError(response['error'])
 
@@ -519,7 +546,7 @@ class AgentClient:
 
                 proc = subprocess.Popen(
                     cmd,
-                    creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS,
+                    creationflags=subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW,
                     stdout=subprocess.DEVNULL,
                     stderr=stderr_file if stderr_file else subprocess.DEVNULL,
                     startupinfo=startupinfo

{replx-1.22.2 → replx-1.30.3}/replx/cli/agent/protocol.py

@@ -9,6 +9,7 @@ from replx.utils.constants import MAX_PAYLOAD_SIZE
 
 _MAGIC = b'RPLX'
 _VERSION = 1
+_HEADER = struct.Struct('!4sBI')
 
 _seq_lock = threading.Lock()
 _seq_counter = int(time.time() * 1000000) & 0xFFFFFFFE  # even start
@@ -24,38 +25,32 @@ def _next_seq() -> int:
 class AgentProtocol:
     @staticmethod
     def encode_message(msg: Dict[str, Any]) -> bytes:
-        payload = json.dumps(msg).encode('utf-8')
+        payload = json.dumps(msg, separators=(',', ':')).encode('utf-8')
 
         if len(payload) > MAX_PAYLOAD_SIZE:
             raise ValueError(f"Message too large: {len(payload)} bytes")
 
-        header = (
-            _MAGIC +
-            struct.pack('!B', _VERSION) +
-            struct.pack('!I', len(payload))
-        )
+        header = _HEADER.pack(_MAGIC, _VERSION, len(payload))
 
         return header + payload
 
     @staticmethod
     def decode_message(data: bytes) -> Optional[Dict[str, Any]]:
-        if len(data) < 9:
+        if len(data) < _HEADER.size:
             return None
 
-        if data[:4] != _MAGIC:
+        magic, version, length = _HEADER.unpack_from(data)
+        if magic != _MAGIC:
             return None
 
-        version = struct.unpack('!B', data[4:5])[0]
         if version != _VERSION:
             return None
 
-        length = struct.unpack('!I', data[5:9])[0]
-
-        if len(data) < 9 + length:
+        payload_end = _HEADER.size + length
+        if len(data) < payload_end:
             return None
 
-        payload = data[9:9+length]
-        return json.loads(payload.decode('utf-8'))
+        return json.loads(data[_HEADER.size:payload_end])
 
     @staticmethod
     def create_request(command: str, seq: int = None, ppid: int = None, port: str = None, **args) -> Dict[str, Any]:

{replx-1.22.2 → replx-1.30.3}/replx/cli/agent/server/connection_manager.py

@@ -2,14 +2,18 @@ import re
 import sys
 import time
 import threading
+from collections import deque
 from concurrent.futures import Future as ConcurrentFuture
 from dataclasses import dataclass, field
-from typing import Optional, Dict, Any, List, Tuple
+from typing import Optional, Dict, Any, Deque, List, Tuple
 
 from replx.protocol import ReplProtocol, create_storage
 from replx.utils import parse_device_banner, canon_port as _shared_canon_port
-from replx.utils.constants import CTRL_B, CTRL_C
+from replx.utils.constants import (
+    CTRL_B, CTRL_C, CONNECT_DETECT_ROUNDS, CONNECT_DETECT_RETRY_DELAY,
+)
 from replx.utils.exceptions import TransportError
+from replx.utils.device_info import get_root_fs_for_core
 
 
 def _detect_device_info(transport, core: str, device: str = None) -> Tuple[str, str, str, str]:
@@ -58,7 +62,7 @@ class InteractiveSessionState:
     seq: int = 0
     client_addr: Optional[tuple] = None
     echo: bool = True
-    input_queue: List[Any] = field(default_factory=list)
+    input_queue: Deque[bytes] = field(default_factory=deque)
     stop_requested: bool = False
     thread: Optional[threading.Thread] = None
     error: Optional[str] = None
@@ -71,7 +75,7 @@ class InteractiveSessionState:
             self.seq = seq
             self.client_addr = client_addr
             self.echo = echo
-            self.input_queue = []
+            self.input_queue.clear()
             self.stop_requested = False
             self.error = None
 
@@ -82,7 +86,7 @@ class InteractiveSessionState:
             self.ppid = None
             self.seq = 0
             self.client_addr = None
-            self.input_queue = []
+            self.input_queue.clear()
             self.stop_requested = False
             thread_to_join = self.thread
             self.thread = None
@@ -104,14 +108,14 @@ class ReplSessionState:
     ppid: Optional[int] = None
     reader_future: Optional[ConcurrentFuture] = None
     reader_thread: Optional[threading.Thread] = None
-    output_buffer: bytes = b""
+    output_buffer: bytearray = field(default_factory=bytearray)
     buffer_lock: threading.Lock = field(default_factory=threading.Lock)
 
     def start(self, ppid: int):
         self.active = True
         self.ppid = ppid
         with self.buffer_lock:
-            self.output_buffer = b""
+            self.output_buffer.clear()
 
     def stop(self):
         self.active = False
@@ -123,7 +127,7 @@ class ReplSessionState:
             self.reader_thread.join(timeout=1)
             self.reader_thread = None
         with self.buffer_lock:
-            self.output_buffer = b""
+            self.output_buffer.clear()
 
     def is_owner(self, ppid: int) -> bool:
         if ppid is None:
@@ -134,13 +138,13 @@ class ReplSessionState:
 
     def append_output(self, data: bytes):
         with self.buffer_lock:
-            self.output_buffer += data
+            self.output_buffer.extend(data)
 
     def read_output(self) -> bytes:
         with self.buffer_lock:
             data = self.output_buffer
-            self.output_buffer = b""
-            return data
+            self.output_buffer = bytearray()
+        return bytes(data)
 
 @dataclass
 class BoardConnection:
@@ -236,12 +240,26 @@ class BoardConnection:
             self.last_command_time = time.time()
             return True
 
-    def release(self):
+    def acquire_for_heartbeat(self) -> bool:
+        with self._busy_lock:
+            if self.busy or self.detached_running or self.repl.active or self.interactive.active:
+                return False
+            self.busy = True
+            self.busy_session = self.HEARTBEAT_SESSION_ID
+            self.busy_command = 'heartbeat'
+            self.busy_client = None
+            return True
+
+    def release(self, *, reset_liveness: bool = True, update_last_command_time: bool = True):
         with self._busy_lock:
             self.busy = False
             self.busy_session = None
             self.busy_command = None
             self.busy_client = None
+            if update_last_command_time:
+                self.last_command_time = time.time()
+            if reset_liveness:
+                self._liveness_fail_count = 0
 
     def set_busy_state(self, busy: bool, command: str = None, session: int = None,
                        client_addr: tuple = None) -> None:
@@ -292,6 +310,7 @@ class ConnectionManager:
         # Per-port events used to serialize concurrent create_serial_connection
         # calls for the same port (prevents double serial-open race).
         self._port_creating: Dict[str, threading.Event] = {}
+        self._scan_lock = threading.Lock()
         self._default_port: Optional[str] = None
 
     @property
@@ -355,54 +374,89 @@ class ConnectionManager:
         with self._connections_lock:
             return len(self._connections)
 
+    @property
+    def scan_lock(self) -> threading.Lock:
+        return self._scan_lock
+
+    def reserve_probe_port(self, port: str) -> Optional[Tuple[str, threading.Event]]:
+        port_key = self._canon_port(port)
+        if not port_key:
+            return None
+        with self._connections_lock:
+            if port_key in self._connections or port_key in self._port_creating:
+                return None
+            event = threading.Event()
+            self._port_creating[port_key] = event
+            return port_key, event
+
+    def release_probe_port(self, reservation: Tuple[str, threading.Event]) -> None:
+        port_key, event = reservation
+        with self._connections_lock:
+            if self._port_creating.get(port_key) is event:
+                self._port_creating.pop(port_key, None)
+        event.set()
+
     def create_serial_connection(
         self,
         port: str,
         core: str = "RP2350",
         device: str = None,
-        baudrate: int = 115200
+        baudrate: Optional[int] = None
     ) -> Tuple[BoardConnection, Optional[str]]:
         original_port = str(port).strip() if port is not None else ""
         port_key = self._canon_port(original_port)
 
-        # --- Phase 1: fast check + race serialisation ---
-        with self._connections_lock:
-            if port_key in self._connections:
-                conn = self._connections[port_key]
-                if conn.is_connected():
-                    return conn, None
-            # If another thread is already opening this port, get its event so
-            # we can wait for it instead of opening the same serial port twice.
-            if port_key in self._port_creating:
-                wait_event = self._port_creating[port_key]
-                our_event = None
-            else:
-                our_event = threading.Event()
-                self._port_creating[port_key] = our_event
-                wait_event = None
-
-        if wait_event is not None:
-            # Another thread is opening this port; wait then return its result.
-            wait_event.wait(timeout=30)
+        # --- Phase 1: serialize opens and scan probes for this port ---
+        deadline = time.monotonic() + 30.0
+        while True:
             with self._connections_lock:
                 conn = self._connections.get(port_key)
                 if conn and conn.is_connected():
                     return conn, None
-            return None, "Connection creation timed out (concurrent attempt)"
+                wait_event = self._port_creating.get(port_key)
+                if wait_event is None:
+                    our_event = threading.Event()
+                    self._port_creating[port_key] = our_event
+                    break
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0 or not wait_event.wait(timeout=remaining):
+                return None, "Connection creation timed out (concurrent attempt)"
 
         # --- Phase 2: we are the creator ---
         try:
-            from replx.transport import create_transport
-
-            transport = create_transport(f"serial:{original_port}", baudrate=baudrate)
+            from replx.transport import create_transport, repl_baud_candidates
+
+            rates = [baudrate] if baudrate else repl_baud_candidates()
+            transport = create_transport(f"serial:{original_port}", baudrate=rates[0])
+
+            # A board that was just reset (e.g. by esptool or a USB-UART bridge's
+            # DTR/RTS lines) may still be booting, so a failed sweep is retried.
+            version = "?"
+            current_rate = rates[0]
+            for attempt in range(CONNECT_DETECT_ROUNDS):
+                if attempt:
+                    time.sleep(CONNECT_DETECT_RETRY_DELAY)
+                for rate in rates:
+                    if rate != current_rate:
+                        transport.set_baudrate(rate)
+                        current_rate = rate
+                    version, detected_core, detected_device, manufacturer = _detect_device_info(
+                        transport, core, device
+                    )
+                    if version != "?":
+                        break
+                if version != "?":
+                    break
+            else:
+                # No rate produced a recognisable REPL; keep the primary rate as before.
+                if current_rate != rates[0]:
+                    transport.set_baudrate(rates[0])
 
-            version, detected_core, detected_device, manufacturer = _detect_device_info(
-                transport, core, device
+            device_root_fs = get_root_fs_for_core(detected_core)
+            repl_protocol = ReplProtocol(
+                transport, core=detected_core, device_root_fs=device_root_fs
             )
-
-            repl_protocol = ReplProtocol(transport)
-
-            device_root_fs = "/"
             if version != "?":
                 try:
                     result = repl_protocol.exec("import os; print(os.getcwd())")
@@ -412,14 +466,16 @@ class ConnectionManager:
                         cwd = result.strip() if result else "/"
                     else:
                         cwd = "/"
-                    if cwd.startswith('/flash'):
+                    if cwd == '/flash' or cwd.startswith('/flash/'):
                         device_root_fs = '/flash/'
-                    elif cwd.startswith('/'):
-                        parts = cwd.split('/')
-                        if len(parts) > 1 and parts[1]:
-                            device_root_fs = f'/{parts[1]}/'
-                except Exception:
-                    pass
+                except Exception as exc:
+                    print(
+                        f"Could not query filesystem root on {original_port}; "
+                        f"using {device_root_fs} from the {detected_core} profile: {exc}",
+                        file=sys.stderr,
+                    )
+
+            repl_protocol.device_root_fs = device_root_fs
 
             file_system = create_storage(
                 repl_protocol,