OpenShock-AutoFlasher 0.0.1__py3-none-any.whl

openshock_autoflasher-0.0.1.dist-info/METADATA

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: OpenShock-AutoFlasher
+Version: 0.0.1
+Summary: Automatically flash OpenShock firmware to ESP32 devices
+Author: NanashiTheNameless
+Author-email: NanashiTheNameless <NanashiTheNameless@NamelessNanashi.dev>
+Maintainer: NanashiTheNameless
+Maintainer-email: NanashiTheNameless <NanashiTheNameless@NamelessNanashi.dev>
+License: AGPL-3.0
+Project-URL: Repository, https://github.com/NanashiTheNameless/OpenShock-AutoFlasher
+Project-URL: Issues, https://github.com/NanashiTheNameless/OpenShock-AutoFlasher/issues
+Project-URL: GitHub Sponsor, https://github.com/sponsors/NanashiTheNameless
+Project-URL: Buy Me a Coffee, https://buymeacoffee.com/NamelessNanashi
+Keywords: openshock,esp32,firmware,flasher
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: esptool>=5.1.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
+Requires-Dist: black>=26.1.0; extra == "dev"
+Requires-Dist: flake8>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Dynamic: license-file
+
+# OpenShock Auto-Flasher
+
+[![PyPI version](https://img.shields.io/pypi/v/OpenShock-AutoFlasher.svg)](https://pypi.org/project/OpenShock-AutoFlasher/)
+[![Python versions](https://img.shields.io/pypi/pyversions/OpenShock-AutoFlasher.svg)](https://pypi.org/project/OpenShock-AutoFlasher/)
+![Tests](https://github.com/NanashiTheNameless/OpenShock-AutoFlasher/workflows/Tests/badge.svg)
+[![License](https://img.shields.io/github/license/NanashiTheNameless/OpenShock-AutoFlasher)](LICENSE)
+
+Automatically flash OpenShock firmware to ESP32 devices when they are plugged in. Features color-coded terminal backgrounds to indicate the current status at a glance.
+
+## Features
+
+- **Automatic detection** of newly connected devices
+- **Color-coded status** with background colors:
+  - **Blue** - Waiting for device
+  - **Yellow** - Flashing in progress
+  - **Green** - Flash complete
+  - **Red** - Error occurred
+- **Firmware verification** using SHA256 checksums
+- **Multiple channels** - stable, beta, or develop
+- **Post-flash commands** - Send serial commands to device after flashing
+- **Continuous mode** - flash multiple devices in sequence
+- **Optional flash erase** before flashing
+- **Smart text wrapping** - Long messages wrap cleanly without cutting words
+- **Dynamic boards list** - View available boards for any channel via `--help`
+
+## Requirements
+
+- Python 3.12 or higher
+- Linux, macOS, or Windows
+- USB connection to ESP32 devices
+
+## Installation
+
+### From GitHub with pipx (Recommended)
+
+Install directly from the latest GitHub version:
+
+```bash
+pipx install --force 'OpenShock-AutoFlasher @ git+https://github.com/NanashiTheNameless/OpenShock-AutoFlasher@main'
+```
+
+This makes the `OPSH-AutoFlash` command available system-wide.
+
+### Alternative: From PyPI
+
+If you prefer a release from PyPI:
+
+```bash
+pipx install OpenShock-AutoFlasher
+```
+
+### From Source
+
+1. Clone this repository:
+
+```bash
+git clone https://github.com/NanashiTheNameless/OpenShock-AutoFlasher.git
+cd OpenShock-AutoFlasher
+```
+
+1. Install dependencies:
+
+```bash
+pip3 install -r requirements.txt
+```
+
+## Usage
+
+### Basic Usage
+
+Flash devices using the stable firmware channel:
+
+```bash
+OPSH-AutoFlash --board <board-name>
+```
+
+View available boards for different channels:
+
+```bash
+OPSH-AutoFlash --help                        # Shows boards for stable channel
+OPSH-AutoFlash --channel beta --help         # Shows boards for beta channel
+OPSH-AutoFlash -c develop --help             # Shows boards for develop channel
+```
+
+### Command-Line Options
+
+| Option         | Short | Description                                                | Default  |
+|----------------|-------|------------------------------------------------------------|----------|
+| `--channel`    | `-c`  | Firmware channel: `stable`, `beta`, or `develop`           | `stable` |
+| `--board`      | `-b`  | Board type (required)                                      | -        |
+| `--erase`      | `-e`  | Erase flash before flashing                                | `false`  |
+| `--no-auto`    | `-n`  | Disable auto-flash (just detect devices)                   | `false`  |
+| `--post-flash` | `-p`  | Serial command to send after flashing (can use multiple times) | -        |
+
+### Examples
+
+**Flash with stable firmware:**
+
+```bash
+OPSH-AutoFlash --board Wemos-D1-Mini-ESP32
+```
+
+**Flash with beta firmware and erase existing data:**
+
+```bash
+OPSH-AutoFlash --channel beta --board Wemos-D1-Mini-ESP32 --erase
+```
+
+**Flash and send post-flash commands to device:**
+
+```bash
+OPSH-AutoFlash --board Wemos-D1-Mini-ESP32 \
+  --post-flash "help" \
+  --post-flash "version" \
+  --post-flash "status"
+```
+
+**Use development firmware:**
+
+```bash
+OPSH-AutoFlash --channel develop --board Wemos-D1-Mini-ESP32
+```
+
+**Detect devices without auto-flashing:**
+
+```bash
+OPSH-AutoFlash --board Wemos-D1-Mini-ESP32 --no-auto
+```
+
+## How It Works
+
+1. **Fetches** the latest firmware version from firmware.openshock.org
+2. **Validates** the specified board type
+3. **Monitors** USB ports for newly connected devices
+4. **Downloads** firmware binary and checksum in parallel
+5. **Verifies** firmware integrity using SHA256
+6. **Flashes** the device using esptool
+7. **Verifies** the flash was successful
+8. **Executes** post-flash commands over serial (if specified)
+9. **Repeats** for additional devices (continuous mode)
+
+The tool uses esptool with optimized settings and can send serial commands to the device after flashing for automated configuration or testing.
+
+## Supported Boards
+
+The tool supports multiple ESP32-based boards. To view the current list of available boards, run:
+
+```bash
+OPSH-AutoFlash --help                        # Stable channel boards
+OPSH-AutoFlash --channel beta --help         # Beta channel boards
+OPSH-AutoFlash -c develop --help             # Develop channel boards
+```
+
+Common board types include:
+
+- `Wemos-D1-Mini-ESP32`
+- `Wemos-Lolin-S2-Mini`
+- `Wemos-Lolin-S3`
+- `Wemos-Lolin-S3-Mini`
+- `Waveshare_esp32_s3_zero`
+- `Pishock-2023`
+- `Pishock-Lite-2021`
+- `Seeed-Xiao-ESP32C3`
+- `Seeed-Xiao-ESP32S3`
+- `DFRobot-Firebeetle2-ESP32E`
+- `OpenShock-Core-V1`
+- `OpenShock-Core-V2`
+
+**Note:** Different channels may have different board support. Always check the help output for your selected channel.
+
+## Permissions (Linux)
+
+On Linux, you may need to add your user to the `dialout` group to access serial ports:
+
+```bash
+sudo usermod -a -G dialout $USER
+```
+
+Then log out and log back in for the changes to take effect.
+
+## Troubleshooting
+
+**Device not detected:**
+
+- Ensure the device is in bootloader mode
+- Check USB cable connection
+- Verify device appears in system (check `dmesg` on Linux or Device Manager on Windows)
+
+**Permission errors:**
+
+- Add user to dialout/uucp group (Linux)
+- Run with appropriate permissions
+- Check USB cable supports data transfer (not charge-only)
+
+**Verification fails:**
+
+- Try using `--erase` flag to erase flash first
+- Check for hardware issues
+- Try a different USB port or cable
+
+## Development
+
+### Running Tests
+
+The project includes a comprehensive test suite using pytest. To run the tests:
+
+1. Install development dependencies:
+
+```bash
+pip install -e .[dev]
+```
+
+1. Run the test suite:
+
+```bash
+pytest tests/ -v
+```
+
+1. Run tests with coverage:
+
+```bash
+pytest tests/ -v --cov=openshock_autoflasher --cov-report=term-missing
+```
+
+### Code Quality
+
+The project uses several tools for code quality:
+
+- **Black** - Code formatting
+- **Flake8** - Linting
+- **Mypy** - Type checking
+
+Run code quality checks:
+
+```bash
+# Format code
+black openshock_autoflasher/ tests/
+
+# Lint code
+flake8 openshock_autoflasher/ tests/
+
+# Type check
+mypy openshock_autoflasher/
+```
+
+### Project Structure
+
+The codebase is modular and organized as follows:
+
+- `openshock_autoflasher/` - Main package
+  - `constants.py` - Configuration constants
+  - `styles.py` - Terminal styling and colors
+  - `flasher.py` - Core AutoFlasher class with flashing logic
+  - `cli.py` - Command-line interface and argument parsing
+  - `__init__.py` - Package initialization
+  - `__main__.py` - Module entry point
+- `tests/` - Test suite
+  - `test_constants.py` - Tests for constants module
+  - `test_styles.py` - Tests for styles module
+  - `test_flasher.py` - Tests for flasher module
+  - `test_cli.py` - Tests for CLI module
+
+### Continuous Integration
+
+The project uses GitHub Actions for CI/CD:
+
+- **Tests Workflow** - Runs tests on Ubuntu, Windows, and macOS with Python 3.12-3.13
+- **Publish Workflow** - Publishes to PyPI on release
+
+## License
+
+This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+## Disclaimer
+
+This tool is provided as-is. Use at your own risk. Always ensure you have backups of any important configurations before flashing firmware.

openshock_autoflasher-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+openshock_autoflasher/__init__.py,sha256=FK4y7lR1R4vaqFus8l28cDBvYxEH9MyqUZb-sO-sJDI,343
+openshock_autoflasher/__main__.py,sha256=LSvt_hNE1414S5WNTP21ykNU-xZ3hWUxgeXShf1rlIo,188
+openshock_autoflasher/cli.py,sha256=ubjLXqu3lRsYtREhsp3lXnH4NPOTojO_meXqW5YfqzA,3646
+openshock_autoflasher/constants.py,sha256=FVj6Tk_kKzubEi7wpL-rpKWpgPHDkvRM-HjRn2towV8,553
+openshock_autoflasher/flasher.py,sha256=3DBAEQjLvfJFlHqP1KEmUmkiZ2tLXbexphwOlSHomhE,16089
+openshock_autoflasher/py.typed,sha256=kO13kg6OXApIRwKRcPpEOL09GZHx2Pk8Rp2KZpxv0lw,63
+openshock_autoflasher/styles.py,sha256=JLvtptGk6h3aVoD5iYVkfGmID3zt6PU3lBZaMdSOHnI,575
+openshock_autoflasher-0.0.1.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+openshock_autoflasher-0.0.1.dist-info/METADATA,sha256=Lly_UDZYpXQpLMbfyedM5r5UVeBO7ttziegZ-O0MK4k,9464
+openshock_autoflasher-0.0.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+openshock_autoflasher-0.0.1.dist-info/entry_points.txt,sha256=o7sTGRS_1IwYCne-CL5lAkB6QUNW7PWOsp42nWiW0cw,66
+openshock_autoflasher-0.0.1.dist-info/top_level.txt,sha256=T3qrJ7CtQqm7FAh_kHzlDcVEkNeYlB4Q6NUoSjPZNF0,22
+openshock_autoflasher-0.0.1.dist-info/RECORD,,

openshock_autoflasher-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openshock_autoflasher-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+OPSH-AutoFlash = openshock_autoflasher.cli:main