replx 1.0.0__tar.gz

replx-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 chanmin.park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

replx-1.0.0/PKG-INFO

@@ -0,0 +1,421 @@
+Metadata-Version: 2.4
+Name: replx
+Version: 1.0.0
+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@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 chanmin.park
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/PlanXLab/replx
+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
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware :: Universal Serial Bus (USB)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: genlib>=0.6
+Requires-Dist: mpy-cross>=1.26
+Dynamic: license-file
+
+# replx User Manual
+
+## Overview
+**replx** is a powerful command-line tool designed for interacting with MicroPython REPL over serial connections. It provides a unified interface for managing files, running scripts, inspecting device status, and maintaining synchronized development environments in VS Code.
+
+This manual guides you through all available commands, usage patterns, and workflow integration strategies.
+
+---
+
+## Installation & Setup
+
+### Requirements
+- Python 3.10 or newer
+- `pyserial`, `click`, `mpy-cross` and `genlib` Python packages
+- Supported OS: Windows, Linux, macOS
+
+### Installation
+```bash
+pip install replx
+```
+
+### Connecting Your Board
+Before any command can run, ensure your MicroPython device is connected via USB and note the serial port name (e.g., `COM3`, `/dev/ttyACM0`).
+
+You can verify available boards:
+```bash
+replx scan
+```
+
+### Setting Up the VSCode Environment
+To initialize a VSCode workspace for a connected device:
+```bash
+replx -p <port> env
+```
+This creates `.vscode/.env` with your serial configuration, along with default `tasks.json`, `settings.json`, and `launch.json`.
+
+You can force regeneration with:
+```bash
+replx -p <port> env <device_name>
+```
+
+### Command Syntax
+
+```
+replx [OPTIONS] COMMAND [ARGS]...
+```
+
+### Globla Options
+
+Option | Description
+-------|-------------------
+-p, --port	| Serial port name of the connected device
+-c, --command	| Execute a raw command directly on the device
+-v, --version	| Show version and exit
+--help	| Show help message and exit
+
+---
+
+## Commands
+
+### `scan`
+Scan for connected MicroPython boards.
+
+```bash
+replx scan
+```
+
+**Options:**
+- `--raw` – show raw firmware info (full MicroPython banner)
+
+**Example Output:**
+```
+COM10    1.25  2025-01-15  ticle
+```
+
+---
+
+### `port`
+View or set the serial port used by replx.
+
+```bash
+replx port [PORT_NAME]
+```
+
+If no argument is given, displays the current configured port.
+
+**Examples:**
+```bash
+replx port
+replx port COM9
+```
+
+---
+
+### `get`
+Download a file from the device.
+
+```bash
+replx get <remote> [local]
+```
+
+**Example:**
+```bash
+replx get /main.py ./backup_main.py
+```
+
+---
+
+### `put`
+Upload files or directories to the device.
+
+```bash
+replx put <local> [remote]
+```
+Automatically creates directories if missing.
+
+**Examples:**
+```bash
+replx put main.py
+replx put foo.py lib/
+```
+
+---
+
+### `ls`
+List files and directories on the device.
+
+```bash
+replx ls [path]
+```
+Shows detailed file information including size and icons.
+
+---
+
+### `mkdir`
+Create a directory on the device.
+
+```bash
+replx mkdir <remote_dir>
+```
+
+---
+
+### `rm`
+Remove a file or directory (recursively).
+
+```bash
+replx rm <remote_path>
+```
+
+---
+
+### `df`
+Display filesystem usage (total, used, free, percentage).
+
+```bash
+replx df
+```
+
+---
+
+### `mem`
+Display MicroPython memory statistics.
+
+```bash
+replx mem
+```
+Shows `free`, `allocated`, `total`, and usage percent.
+
+---
+
+### `run`
+Execute a local Python script on the device.
+
+```bash
+replx run <file.py> [options]
+```
+**Options:**
+- `-n`, `--non-interactive`: Run without REPL interaction
+- `-e`, `--echo`: Enable local echo for interactive mode
+
+**Example:**
+```bash
+replx run test_led.py -e
+```
+
+> **Shortcut:** Simply typing `myscript.py` automatically invokes `run`.
+
+---
+
+### `repl`
+Enter device REPL interactively.
+
+```bash
+replx repl
+```
+
+Exit with **Ctrl+C**.
+
+---
+
+### `format`
+Format the device’s filesystem.
+
+```bash
+replx format
+```
+
+Shows a progress indicator until completion.
+
+---
+
+### `reset`
+Perform a soft reset on the device.
+
+```bash
+replx reset
+```
+
+---
+
+### `shell`
+Interactive command-line shell for device management.
+
+```bash
+replx shell
+```
+
+Inside the shell, you can use commands like:
+
+```
+ls, cd, get, put, rm, mkdir, df, pwd, repl, clear, exit
+```
+
+Example session:
+```
+📟 ticle:/ > ls
+📁 lib
+📄 main.py
+📟 ticle:/ > get main.py
+```
+
+---
+
+### `update`
+Update local library cache from GitHub.
+
+```bash
+replx update [device] [--owner <org>] [--repo <name>] [--ref <branch>]
+```
+Downloads and synchronizes `.py` sources for both `core` and `device` components.
+
+---
+
+### `install`
+Install libraries or files onto the device.
+
+```bash
+replx install [SPEC]
+```
+
+**SPEC Examples:**
+| SPEC | Description |
+|------|--------------|
+| *(empty)* | Install all core/device libs |
+| `core/` | Install only core libraries |
+| `device/` | Install only device-specific libraries |
+| `./foo.py` | Upload and compile a single file |
+| `https://.../file.py` | Download and install from URL |
+
+---
+
+### `search`
+Search for libraries in the remote registry.
+
+```bash
+replx search [lib_name] [--owner] [--repo] [--ref]
+```
+
+**Example:**
+```bash
+replx search BME68x
+```
+Shows available library versions and update status (`*` marks newer remote versions).
+
+---
+
+## Automatic Update Check
+On startup, replx checks PyPI for new releases and offers in-place upgrade:
+```bash
+A newer version (1.2.0) is available. Update now? (y/n):
+```
+
+---
+
+## Error Handling
+When a MicroPython traceback occurs, replx automatically reformats and maps `<stdin>` references to your local file paths for clarity.
+
+Example error output:
+```
+--------------------------------Traceback--------------------------------
+File "C:\project\main.py", line 22
+  sensor.read()
+ValueError: I2C bus error
+```
+
+---
+
+## Environment Integration
+
+### `.vscode/.env` Example
+```
+SERIAL_PORT=COM10
+```
+
+### File Mappings
+| Type | Target on Device |
+|------|------------------|
+| `main.py` | `/main.mpy` |
+| `boot.py` | `/boot.mpy` |
+| Libraries | `/lib/...` |
+
+---
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|----------|--------|-----------|
+| `Device not found` | Incorrect serial port | Run `scan` and verify port |
+| `could not enter raw repl` | Board busy or sleeping | Reset the board and retry |
+| `Download incomplete` | Serial timeout | Check cable and reduce baud rate |
+
+---
+
+## Versioning & Licensing
+- **Author:** PlanX Lab Development Team  
+- **License:** MIT License  
+- **Version:** Displayed via `--version`
+
+---
+
+## Quick Reference Table
+
+| Command | Description |
+|----------|-------------|
+| `scan` | Detect connected boards |
+| `port` | Show/set current serial port |
+| `get` | Download file from device |
+| `put` | Upload file or folder |
+| `ls` | List directory contents |
+| `run` | Execute a local script |
+| `repl` | Open interactive REPL |
+| `mem` | Show memory usage |
+| `df` | Show filesystem usage |
+| `mkdir` | Create directory |
+| `rm` | Delete file/folder |
+| `update` | Sync libraries from GitHub |
+| `install` | Install libraries/files |
+| `shell` | Interactive management shell |
+| `format` | Format filesystem |
+| `env` | Setup VSCode environment |
+| `reset` | Soft reset the device |
+
+---
+
+## Notes
+- All commands automatically load `.vscode/.env` if present.
+- Serial interruption (Ctrl+C) is supported on both Windows and POSIX systems.
+- Batch upload/download operations display progress bars.
+
+---
+
+**End of Manual**
+